Composio Python Provider 开发指南：从脚手架生成到类型推断验证的完整实践-迪斯科星球

Composio Python 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

导读

本文聚焦 Composio 开源仓库中python/providers/目录的 Provider 开发体系。该目录下每个子目录都是一个独立的 Python Provider 包，负责将 Composio 的 1000+ 工具适配到 Anthropic、OpenAI、LangChain、CrewAI、Google ADK 等具体框架或 Agent 运行时。读完本文，你将掌握：如何通过make create-provider一键生成 Provider 脚手架、非 Agentic 与 Agentic 两种 Provider 的底层差异、make chk/make tst/make type_inference三套验证流程的作用，以及新增 Provider 时必须在 python/noxfile.py 中完成的注册事项。

本文主体依据 python/providers/AGENTS.md 展开，并辅以 python/Makefile、python/scripts/create-provider.sh、python/noxfile.py 及真实 Provider 实现（如 python/providers/anthropic/composio_anthropic/provider.py）作为源码级佐证。

Provider 包的定位与职责范围

从仓库目录结构可以清晰看到，python/providers/ 下目前包含 12 个 Provider 包：

anthropic/ autogen/ claude_agent_sdk/ crewai/ gemini/ google/ google_adk/ langchain/ langgraph/ llamaindex/ openai/ openai_agents/

每个子目录都是一个独立的 Python 包，遵循统一的内部结构。以anthropic为例（见 python/providers/anthropic/）：

anthropic/ ├── README.md ├── anthropic_demo.py # 独立可运行的演示脚本 ├── composio_anthropic/ # 实际 Python 包 │ ├── __init__.py │ ├── provider.py # Provider 核心实现 │ └── py.typed # PEP 561 类型标记 ├── pyproject.toml # 包元数据与依赖声明 └── setup.py # 向后兼容的安装入口

这些包的共同职责是：把 Composio 统一的Tool模型转换为目标框架原生期望的工具格式，并把目标框架返回的工具调用（tool call）转换回 Composio 的执行入口。因此它们各自以composio_<provider>命名，例如composio_anthropic、composio_openai，并在pyproject.toml中声明自己的框架依赖。

以 python/providers/anthropic/pyproject.toml 为例，依赖声明为：

dependencies = [ "anthropic>=0.120.0", "composio", ]

而composio-openai（python/providers/openai/pyproject.toml）则声明openai>=2.48.0。这正是 AGENTS.md 规则 "Keep provider dependencies in the provider package metadata unless shared tooling needs them" 的落地：每个框架的强依赖只留在各自的 Provider 包内，避免把 Anthropic、OpenAI、LlamaIndex 等互有冲突的传递依赖全部拖进根包解析。

开发工作流：四组核心命令

Provider 开发相关的命令统一从python/目录执行（即仓库下的 python/ 目录），共四组：

make create-provider name=<provider-name> make create-provider name=<provider-name> agentic=true make chk make tst make type_inference

make create-provider：脚手架生成

create-provider目标定义在 python/Makefile，它把参数转发给bash scripts/create-provider.sh。脚本 python/scripts/create-provider.sh 支持三个参数：

参数	作用	默认值
`name=<provider-name>`	必填，Provider 名称（如`myai`）	无
`agentic=true`	生成 Agentic Provider 模板	`false`
`output=<directory>`	自定义输出目录	`python/providers`

脚本的核心逻辑（python/scripts/create-provider.sh）：

将名字转换为标题大小写（myai→Myai），包名统一为composio_<provider>；
若目标目录已存在同名 Provider 则直接报错退出，防止覆盖；
生成完整的目录骨架：pyproject.toml、setup.py、README.md、<name>_demo.py、<package>/__init__.py、<package>/provider.py以及 PEP 561 类型标记py.typed；
输出uv pip install -e .的下一步安装提示。

生成的pyproject.toml声明requires-python = ">=3.10,<4"并默认只依赖composio，README 中附带pip install/uv add两种安装方式。

Agentic 与非 Agentic 模板的本质区别

agentic=true决定了provider.py中生成的基类：

非 Agentic（默认）：继承NonAgenticProvider，实现wrap_tool/wrap_tools/execute_tool_call/handle_tool_calls四个方法，面向"客户端自行调用 LLM 后把 tool call 交回执行"的场景（如 OpenAI Function Calling 风格）；
Agentic：继承AgenticProvider，只需实现wrap_tool(tool, execute_tool)/wrap_tools，由框架自身的 Agent 循环（Agent Loop）驱动执行，面向具备自主 Agent 能力的运行时（如 OpenAI Agents SDK、Google ADK）。

两者的模板差异可以从真实包中印证：以composio_anthropic为例，其 provider.py 继承NonAgenticProvider[ToolParam, list[ToolParam]]，wrap_tool把 Composio 的Tool转换为 Anthropic 的ToolParam：

def wrap_tool(self, tool: Tool) -> ToolParam: aliases = alias_tool_input_schema(tool.input_parameters or {}) self._aliases[tool.slug] = aliases return ToolParam( input_schema=aliases.schema, name=tool.slug, description=tool.description, )

其execute_tool_call还针对"模型偶尔把 tool input 输出成 JSON 字符串"的真实问题调用normalize_tool_arguments(tool_call.input)做归一化，再通过execute_tool_for_target执行——这是模板之上的成熟实现细节，值得新 Provider 参考。

验证命令链

make chk：等价于nox -s chk，执行Ruff 代码规范检查 + mypy 类型检查（见 python/noxfile.py），检查范围覆盖composio/、providers/、tests/、scripts/；
make tst：等价于nox -s tst，运行pytest 单元测试套件（python/noxfile.py），测试前会额外安装crewai、langchain、langgraph三个 Provider 包；
make type_inference：等价于nox -s type_inference，这是 Provider 特有的验证环节，详见下文。

Provider 的类型推断验证：为什么重要

type_inference会话专门验证一个关键能力：当用户调用Composio.tools.get()时，mypy 能否借助@overload签名正确推断出各 Provider 特有的返回类型。其实现见 python/noxfile.py：

安装核心 SDK、开发依赖、mypy 以及一组类型桩（type_stubs，包括anthropic、crewai、langchain、langgraph、llama-index、openai-agents、google-cloud-aiplatform等）；
逐个安装全部 12 个 Provider 包，使 mypy 能解析 Provider 类型；
对tests/test_type_inference.py及tests/test_type_inference_<provider>.py逐个运行 mypy。

仓库测试目录 python/tests/ 中每个框架都有对应的类型推断测试文件，例如test_type_inference_anthropic.py、test_type_inference_crewai.py、test_type_inference_langchain.py、test_type_inference_openai_agents.py等。这意味着：凡是改变了公共返回类型的 Provider 改动，都必须同步补充类型推断测试覆盖——这正是 AGENTS.md 规则 "Add provider tests and type-inference coverage when public return types change" 的验证入口。

新增 Provider 的两条硬性注册要求

AGENTS.md 特别强调：新 Provider 或重命名的 Provider 包，通常需要在 python/noxfile.py 的两处列表中显式登记：

type_inference会话的安装列表（python/noxfile.py）：必须把./providers/<name>加入，否则类型推断测试无法解析新包的导入；
type_inference会话的 checked-file 列表（python/noxfile.py）：必须把对应的tests/test_type_inference_<name>.py加入 mypy 检查清单。

注意：这两处列表需要显式列出，原因在 noxfile 的注释中写得很清楚——mypy.ini可能配置了 exclude 模式，而显式列出的文件即使命中 exclude 也会被强制检查。

此外还有一处隐性要求：make tst会话（python/noxfile.py）目前仅额外安装crewai、langchain、langgraph三个包——如果你的新 Provider 需要参与单元测试的完整解析，需评估是否同样需要加入该安装列表。

开发规则与质量红线

综合 python/providers/AGENTS.md 与 python/AGENTS.md（Python SDK 总则），Provider 开发需遵守以下规则：

依赖隔离：Provider 的框架依赖（anthropic、openai、crewai等）必须声明在各包自己的pyproject.toml中，除非共享工具链确实需要；
命名与导入路径：保持 Python 命名约定和公共导入路径稳定，包名统一为composio_<provider>；
测试覆盖：公共返回类型变更时，必须同步补充 pytest 测试与类型推断覆盖（test_type_inference_<provider>.py）；
元数据验证：涉及发布（release-facing）的改动前，必须验证包元数据（版本、依赖、描述等）；
信安边界：Python SDK 将 API 响应的每个字段视为不可信输入，Provider 若把 slug、ID 等不可信组件拼进文件路径，必须使用composio.utils.safe_path.secure_join等安全路径工具（参见 python/AGENTS.md 的 Trust boundary 一节）。

实战：从零创建并接入一个 Provider

综合上述脚手架与验证流程，完整的新 Provider 落地路径如下：

# 1. 在 python/ 目录下生成脚手架（非 Agentic 模板） make create-provider name=myai # 2. 如需 Agent 循环驱动型运行时，使用 Agentic 模板 make create-provider name=myai agentic=true # 3. 编辑 providers/myai/composio_myai/provider.py 实现 wrap/execute 逻辑 # 4. 将新包加入 noxfile.py 的 type_inference 安装列表与 checked-file 列表 # 5. 编写 tests/test_type_inference_myai.py 与 pytest 用例 # 6. 依次执行三阶段验证 make chk # Ruff + mypy make tst # pytest 单元测试 make type_inference # Provider 返回类型推断验证

生成的 README 与<name>_demo.py已经包含可运行的骨架代码：demo 通过composio.tools.get(user_id="default", toolkits=["GITHUB"])拉取工具列表并打印每个工具的名称与描述，是验证 Provider 接入是否成功的最快路径。

总结

python/providers/是 Composio Python SDK 的"框架适配层"，其开发规范围绕三个核心原则展开：依赖隔离（框架依赖留在各 Provider 包内）、格式双向转换（wrap_tool/execute_tool_call/handle_tool_calls）、类型安全（@overload签名 +type_inference会话验证）。无论是贡献新框架适配还是修改现有 Provider，遵循 python/providers/AGENTS.md 中"脚手架生成 → noxfile 注册 → 测试覆盖 → 三阶段验证"的流程，即可保证改动与整个 SDK 的类型推断体系保持一致。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析