Composio Python SDK 开发指南环境搭建、Provider 插件架构与测试体系详解【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio导读本指南以 python/docs/development.md 为骨架完整讲解 Composio Python SDK 的本地开发全流程从一条命令创建隔离开发环境到理解以composio_PROVIDER命名的插件式 Provider 架构再到用自动化会话运行核心包与各框架插件的测试。读完本文你将能独立在 Composio 仓库的python/目录下搭建可复现的开发环境、定位插件代码、运行与排查测试并顺着源码链路理解这套多 Provider 工程的设计动机。一、开发环境搭建从make env到可用的隔离环境原文档指出安装 pipenv 后运行make env即可创建全新环境且该命令可反复用于清理并重建环境。需要说明的是当前仓库的 python/Makefile 已将环境管理从 pipenv 迁移至uv仓库根目录同时存在 python/uv.lock 与 python/pyproject.toml 的[dependency-groups]声明但入口命令与文档保持一致make env。查看env目标的真实实现python/Makefile可以看到它并非简单地创建一个虚拟环境而是一条完整的环境装配流水线env: echo * creating new environment if [ -z $$VIRTUAL_ENV ]; \ then \ uv venv --seed --prompt composio --python 3.12; \ uv sync; \ uv sync --dev; \ make provider; \ uv pip install -e .; \ echo * enter virtual environment with all development dependencies now; \ else \ uv sync; \ uv pip install -e .; \ echo * already in a virtual environment (exit first (deactivate) to create a new environment); \ fi echo * run source .venv/bin/activate to enter the development environment.逐步拆解这条流水线能清晰理解每个环节的作用步骤命令作用1uv venv --seed --prompt composio --python 3.12以 Python 3.12 创建全新虚拟环境shell 提示符标记为composio与requires-python 3.10,4兼容见 python/pyproject.toml2uv sync按锁定文件安装运行时依赖pydantic、composio-client、openai 等见 python/pyproject.toml3uv sync --dev追加安装[dependency-groups].dev中的开发依赖包括 nox、pytest、ruff、mypy、hypothesis 等见 python/pyproject.toml4make provider遍历providers/*/pyproject.toml并逐个uv pip install装上全部框架插件5uv pip install -e .以可编辑editable模式安装核心 SDK源码改动即时生效关键设计有两个幂等与可重建make env的注释明确写着enter virtual environment with all development dependencies now。当环境已激活$VIRTUAL_ENV非空时它只做增量uv sync不会重新建环境文档所说每次用它清理环境对应的是先deactivate退出再运行从而从零重建。这让make env既适合首次克隆后的一次性初始化也适合依赖漂移时的重置。插件单独安装make provider依赖PROVIDER_DIRS : $(patsubst %/,%,$(sort $(dir $(wildcard providers/*/pyproject.toml))))动态发现所有插件包。之所以不把它们放进根pyproject.toml原因在 python/noxfile.py 的注释中写得很明确crewai、langchain、llama-index 等框架库会引入互相冲突的传递依赖必须与核心包解耦。完成make env后按输出提示执行source .venv/bin/activate即可进入开发环境。二、Provider 插件架构composio_PROVIDER命名空间与插件目录原文档指出插件位于plugins/文件夹并以composio_PROVIDER命名空间组织。对照当前仓库该目录已更名为providers/python/providers包含 13 个框架插件anthropic/ autogen/ claude_agent_sdk/ crewai/ gemini/ google/ google_adk/ langchain/ langgraph/ llamaindex/ openai/ openai_agents/每个插件都是一个独立的 Python 包例如 python/providers/openai/pyproject.toml 声明了包名composio-openai依赖composio与openai。这与文档描述的命名规则一致——导入时即composio_openai、composio_anthropic、composio_langchain等。插件目录中还提供了 python/providers/AGENTS.md 供插件开发者参考。这种插件化设计要解决的核心问题是依赖冲突隔离核心 SDK 不依赖任何第三方 Agent 框架而每个框架插件各自锁定自己所需的框架版本。你在使用时会选择性地安装一个或几个插件例如# 仅核心 SDK OpenAI 插件 uv pip install composio composio-openai # 核心 SDK LangChain 插件LangChain 插件另依赖 langchain_openai见 dev 组声明 uv pip install composio composio-langchain新插件脚手架make create-provider除了手工创建目录Makefile 提供了脚手架命令make create-provider nameprovider-namepython/Makefile底层调用 python/scripts/create-provider.sh# 生成标准 Provider 插件骨架 make create-provider namemyframework # 生成支持 agentic 调用的 Provider 插件 make create-provider namemyframework agentictrue # 指定输出目录 make create-provider namemyframework outputpython/providers从源码结构看生成的插件遵循统一约定独立的pyproject.toml命名composio-name、provider 类实现、对应的类型推断测试文件见下文测试章节。这也是为什么 python/noxfile.py 中type_inference会话需要按名称逐个安装全部插件。Provider 与核心 SDK 的分工从 python/composio/sdk.py 等核心模块的结构可以推断核心包负责 SDK 初始化、工具获取与执行、认证等通用逻辑插件包如composio_openai负责把通用工具转换成特定框架的函数调用格式。使用者通过Composio(provider...)传入对应 Provider 实例即可让同一套工具适配不同 Agent 框架——这正是插件体系在运行时层的落点。三、测试体系多 Provider 依赖冲突下的测试隔离3.1 为什么用 tox / nox 这类工具跑测试原文档给出了关键设计理由可选插件之间可能互相冲突因此不能在一个共享环境里一次性安装全部插件来跑测试。tox以及当前仓库实际使用的 nox为每个测试环境创建独立隔离环境从而把核心包与各插件的测试彻底分开。这是一个从依赖图推导出的必然选择把 crewai、langchain、llama-index 装进同一环境会引发传递依赖冲突python/noxfile.py 明确点名了这一点。因此 python/pyproject.toml 的dev组只放通用测试/静态检查工具nox、pytest、ruff、mypy、hypothesis、fastapi、semver 等框架库则留在各自插件包内。3.2 原文档的 tox 命令与当前仓库的 nox 实现原文档给出的命令是tox -r -e core/tox -r -e openai/tox -r -e langchain。需要说明的是这是文档记录的历史用法当前仓库已将测试执行器从 tox 迁移到nox uv。搜索仓库可见 tox 字样仅残留在 python/docs/development.md 与 python/scripts/bump.py用于跳过.tox目录实际的测试会话全部定义在 python/noxfile.py且 python/noxfile.py 设置了nox.options.default_venv_backend uv即每个会话默认用 uv 创建独立虚拟环境。两者理念一致都是多环境、隔离跑测。当前仓库对应的命令映射如下均为make别名见 python/Makefile原文档 tox 命令当前等价命令执行内容tox -r -e coremake tst即nox -s tst安装核心 SDK dev 组 crewai/langchain/langgraph 插件运行 python/tests 全套单元测试tox -r -e openainox -s type_inference中的 openai 部分安装全部插件后对tests/test_type_inference_openai_agents.py等做 mypy 类型推断校验tox -r -e langchainnox -s type_inference中的 langchain 部分同上校验 LangChain 插件的返回类型推断3.3 各 nox 会话详解python/noxfile.py 定义了 8 个会话它们是日常开发的核心工作流测试类tstmake test安装. dev 组再额外安装crewai、langchain、langgraph三个插件python/noxfile.py默认以pytest tests/ -v --tbshort运行全部单元测试支持--传参指定测试路径。之所以只额外装这三个插件是因为其余插件要么无框架测试、要么在独立会话中覆盖。sntmake sanity快速冒烟测试默认只跑tests/test_imports.py与tests/test_sdk.py验证导入与 SDK 初始化无碍python/noxfile.py适合改动后秒级反馈。tst_autogenAutogen 插件因 protobuf 版本敏感单独在一个隔离环境里跑test_provider.py中两个与skip_defaults相关的签名测试python/noxfile.py——这是依赖冲突必须隔离原则的典型例证。静态检查类fmtmake format运行ruff check --select I --fix修复导入排序再ruff format格式化全部源码模块python/noxfile.py扫描范围包括composio/、providers/、tests/、examples/、scripts/。chkmake check先ruff check配置见 python/config/ruff.toml再对composio/、providers/、tests/、scripts/逐个跑mypy --config-file config/mypy.inipython/noxfile.py。为让 mypy 能解析插件与测试中的框架导入该会话会安装一组仅用于类型解析的 type stubs 与固定版本库types-requests、types-protobuf、anthropic、crewai、langchain、llama-index等见 python/noxfile.py。chk_examples对 python/examples 下每个.py示例单独跑一次 mypy避免同名模块冲突并开启--check-untyped-defs强制检查未注解函数体python/noxfile.py。type_inference安装全部 12 个插件后对tests/test_type_inference*.py系列文件做 mypy 校验验证Composio.tools.get()的overload签名能否为不同框架正确推断返回类型python/noxfile.py。对应测试文件见 python/tests/test_type_inference.py 及各框架的test_type_inference_framework.py。dead_code用 vulture 以 80% 置信度扫描composio/与providers/报告可能未使用的函数/类/变量采用报告不阻断策略success_codes[0, 3]确认误报后可将符号加入 python/config/vulture_allowlist.pypython/noxfile.py。3.4 测试文件布局与 pytest 配置测试全部位于 python/tests数量超过 60 个覆盖认证配置、连接账户、工具执行、Schema 转换、文件上传、类型推断、URL 安全等多个领域。常见模式包括Schema/类型相关test_schema_converter.py、test_strict_schema_corpus.py、test_json_schema.py、test_type_inference_*.py系列安全相关test_url_safety.py、test_url_safety_pinning.py、test_sensitive_file_upload_paths.py、test_path_join_guardrail.pyProvider 相关test_provider.py、test_crewai_provider.py、test_gemini_provider.py、test_google_provider.py等。python/pytest.ini 的关键配置[pytest] testpaths tests python_files test_*.py python_classes Test* python_functions test_* addopts -v --tbshort --ignore-globtests/test_type_inference*.py markers slow: marks tests as slow (deselect with -m not slow) integration: marks tests as integration tests unit: marks tests as unit tests schema: marks tests as schema-related tests值得注意的两点addopts默认用--ignore-glob排除test_type_inference*.py这些文件只由type_inference会话驱动避免常规 pytest 因缺少插件类型而失败markers定义了slow/integration/unit/schema四类标记例如可以用pytest -m not slow快速跳过慢测试。3.5 只跑某一插件的测试最小复现路径当只想验证某个插件时可结合tst会话的posargs与 pytest 路径过滤或直接激活环境后指定测试文件# 方式一走 nox 会话只跑 provider 相关测试 nox -s tst -- tests/test_provider.py # 方式二进入 make env 创建的环境后直接跑 source .venv/bin/activate pytest tests/test_provider.py tests/test_schema_converter.py -v若修改涉及返回类型推断务必补跑nox -s type_inference这是保证各框架插件类型契约不被破坏的专门门禁。四、代码规范与发布流程的衔接开发文档未展开的部分可在仓库配套文档中找到闭环代码格式与类型规范make fmt/make chk是提交前的第一道关卡分别对应 ruff 与 mypy 检查配置见 python/config/ruff.toml 与 python/config/mypy.ini。发布流程python/docs/release.md 描述了完整的 Python 包发布流程运行python scripts/bump.pypython/scripts/bump.py交互式选择各包的下一版本major/minor/patch/pre/post/skip创建 release PR合并后发布 GitHub Release。该脚本会扫描**/pyproject.toml与**/setup.py自动跳过.venv、.nox、.tox等目录python/scripts/bump.py因此上文提到的所有插件包会一并纳入版本管理。发布前的完整性校验make clean-build清理 dist 目录、make build使用.venv/bin/python -m build逐个构建核心包与所有插件包并合并 distpython/Makefile 与 python/Makefile。一个典型的开发闭环是make env建环境 →make snt冒烟 →make fmt make chk静态检查 → 修改代码 →make tst全量单测 →nox -s type_inference校验插件类型推断 → 按需make dead-code清理死代码 → 发布前make bump make build。五、实践建议与注意事项环境重建要彻底make env在已激活环境内只会增量同步需要从零重建时先deactivate再运行或删除.venv后重新执行以保证--seed的 Python 3.12 基线一致。插件依赖别装进根项目新增框架依赖请放在对应插件的providers/name/pyproject.toml而不是根 python/pyproject.toml否则会重新引入依赖冲突——这正是本仓库插件架构的初衷。新增插件记得补类型推断测试参照现有test_type_inference_framework.py的写法并确认type_inference会话中加入了对应安装与检查条目python/noxfile.py。区分两套测试入口常规pytest tests/默认排除类型推断测试涉及插件返回类型时必须显式运行nox -s type_inference二者互补而非替代。遵循测试标记约定为耗时用例标注pytest.mark.slow或integration便于pytest -m not slow快速迭代。通过本文梳理你应该已经掌握 Composio Python SDK 的开发环境装配原理、composio_PROVIDER插件架构的组织方式以及从 tox 演进到 nox 的多环境测试体系。在此基础上深入阅读 python/Makefile、python/noxfile.py 与 python/tests 下的具体用例即可完全上手该仓库的日常开发。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
