Composio Python Provider 开发工作流：从脚手架创建到验证发布的完整指南

本指南以 Composio 仓库中 .agents/skills/python-providers/references/provider-workflow.md 为核心骨架，结合仓库内的脚手架脚本、Makefile/nox 验证链路与真实 Provider 实现，系统讲解如何为 Composio Python SDK 创建、实现、测试与打包一个框架适配 Provider。读完你将掌握：如何用一条命令生成 Provider 包骨架、Agentic 与非 Agentic 两种形态的实现差异、make chk / make tst / make type_inference 三条验证链路的底层机制，以及发布前包元数据的检查方法。

一、工作流总览：Provider 在 Composio 生态中的位置

Composio Python SDK 的核心设计是"一套工具，处处可用"：同一个工具集合可以被 Anthropic、OpenAI、LangChain、CrewAI、Google ADK 等不同 Agent 框架消费。承担这一桥接职责的模块就是 Provider——每个 Provider 是一个独立的 Python 包，位于仓库 python/providers/ 目录下，负责两件核心事情：

1. 工具格式转换（wrap）：把 Composio 内部统一的 Tool 模型转换为目标框架约定的工具格式（如 Anthropic 的 ToolParam、OpenAI 的 function schema）；
2. 工具调用执行（execute）：把目标框架发出的工具调用请求，转译为 Composio 工具执行并返回标准化结果。

从 python/providers/AGENTS.md 可以确认其定位："Each child directory is a Python provider package that adapts Composio to a framework or agent runtime." 当前仓库中已落地的 Provider 包括 anthropic、autogen、claude_agent_sdk、crewai、gemini、google、google_adk、langchain、langgraph、llamaindex、openai、openai_agents 共 12 个（见 python/providers/）。

二、创建或定位一个 Provider

2.1 一条命令生成完整骨架

Provider 工作流的第一步是创建（或定位到）目标 Provider 包。原文档给出的命令在仓库根目录的 python/ 下执行：

make create-provider name=<provider-name>
make create-provider name=<provider-name> agentic=true

其中 agentic=true 用于生成 Agentic Provider（面向自带 Agent 循环的框架，如 CrewAI、Autogen），不加该参数则生成 Non-Agentic Provider（面向纯 LLM 客户端框架，如 Anthropic、OpenAI）。

这条 Makefile 目标的真实执行链路在 python/Makefile：make create-provider 会校验 name 参数是否提供，把 agentic/output 参数拼装为命令行参数，最终转发给 python/scripts/create-provider.sh 执行。

2.2 脚手架脚本生成了什么

阅读 python/scripts/create-provider.sh 可知，脚本以 make create-provider name=myai 为例会生成以下结构（默认输出目录 python/providers/，可用 --output-dir <directory> 覆盖）：

python/providers/myai/
├── README.md              # 包说明、快速开始、API 参考
├── pyproject.toml         # 包元数据与依赖声明
├── setup.py               # 向后兼容的 setup 入口
├── myai_demo.py           # 可直接运行的演示脚本
└── composio_myai/
    ├── __init__.py        # 导出 <Name>Provider
    ├── provider.py        # Provider 实现（核心文件）
    └── py.typed           # PEP 561 类型标记，启用类型推断

几个值得注意的工程细节：

• 包命名：Python 包名统一为 composio_<provider-name>（下划线形式），而发布到 PyPI 的项目名在 pyproject.toml 中由各 Provider 自定（如 anthropic 的发布名为 composio-anthropic，见 python/providers/anthropic/pyproject.toml）；
• py.typed 文件：脚本通过 touch 创建该标记文件（create-provider.sh），配合 pyproject.toml 中的 package-data 声明即可让 mypy 等类型检查器识别包内类型，这是"类型推断"能力的前提；
• Python 版本约束：脚手架统一写入 requires-python = ">=3.10,<4"；
• Agentic 差异：agentic=true 时 provider.py 继承 AgenticProvider（python/composio/core/provider/agentic.py），wrap_tool 需要额外接收 execute_tool: AgenticProviderExecuteFn 执行回调，并定义 wrap_tools 返回工具集合；非 Agentic 形态继承 NonAgenticProvider（python/composio/core/provider/none_agentic.py），wrap_tool 只做纯格式转换，另需实现 execute_tool_call 与 handle_tool_calls 两个执行方法。

2.3 脚本自带的演示与校验逻辑

脚手架还为两种形态各生成一个可直接运行的演示脚本（<provider>_demo.py）：非 Agentic 形态演示 composio.tools.get(user_id="default", toolkits=["GITHUB"]) 获取工具并打印；Agentic 形态演示通过 Composio(provider=<Name>Provider()) 初始化并打印工具列表。脚本中以 TODO 标注了接入真实框架客户端的挂载点（如 handle_tool_calls 的执行逻辑），是快速验证 Provider 骨架可运行的最小样例。

三、实现规则：五个必须遵守的约束

原文档给出了 Provider 实现的五条规则，结合仓库源码可以进一步明确每条的落点：

1. Provider 专属依赖只进 Provider 包元数据：框架依赖（如 anthropic>=0.120.0）应声明在 python/providers/anthropic/pyproject.toml 的 dependencies 中，而不是塞进根 SDK。这与 python/noxfile.py 的设计互为印证——nox 仅将各框架库作为 type stubs 单独安装，避免把 langchain、crewai 等重依赖拖进根依赖解析，防止传递依赖冲突。

2. 保持公共导入路径稳定：外部使用者通过 from composio_anthropic import AnthropicProvider 导入（见 python/tests/test_type_inference_anthropic.py）。改名或移动包时若破坏该路径，会直接破坏所有下游用户代码。

3. 匹配框架原生约定：Provider 输出的工具格式必须与目标框架的官方类型对齐。以 Anthropic Provider 为例（python/providers/anthropic/composio_anthropic/provider.py），wrap_tool 返回的是 anthropic.types.tool_param.ToolParam，并调用 alias_tool_input_schema 处理输入 schema 别名；handle_tool_calls 直接解析 anthropic 消息对象中的 ToolUseBlock / BetaToolUseBlock。这就是"遵循框架原生惯例"的具体体现。

4. 公共用法变更必须同步更新文档与示例：SDK 的 API 变更会波及 python/examples/ 下的示例脚本，它们同时被 chk_examples 会话做类型检查（python/noxfile.py）。

5. 有 TypeScript 对应物的 Provider 使用 cross-sdk-parity 技能：仓库同时维护 ts/packages/providers/（47 个 .ts 文件），Python 与 TypeScript 双端 Provider 需保证行为与类型推断对齐，相关校验逻辑见 .agents/skills/cross-sdk-parity/SKILL.md。

四、验证链路：make chk / make tst / make type_inference

原文档要求从 python/ 目录运行以下三条命令完成验证：

make chk
make tst
make type_inference

它们的底层实现都在 python/noxfile.py 中，各自的职责边界如下：

4.1 make chk：静态检查与类型检查

对应 nox -s chk 会话（python/noxfile.py），依次执行：

• ruff check：按 config/ruff.toml 配置对 composio/、providers/、tests/、examples/、scripts/ 做 lint；
• mypy：按 config/mypy.ini 对 composio/、providers/、tests/、scripts/ 逐模块做类型检查。

注意该会话会安装 type_stubs 列表（python/noxfile.py）——包括锁定版本的 anthropic、crewai、langchain、llama-index 等库，目的仅是为 mypy 提供可解析的第三方类型，而非把它们装进运行环境。

4.2 make tst：单元测试套件

对应 nox -s tst（python/noxfile.py），默认运行 pytest tests/ -v --tb=short。其中 crewai、langchain、langgraph 三个 Provider 会被额外以本地路径安装（session.install("./providers/crewai") 等），因为这些 Provider 的测试依赖真实框架。若只想跑子集，可通过 make tst -- <test-path> 传参。另外 python/noxfile.py 提供了专门的 tst_autogen 会话，在兼容 protobuf 的环境中单独跑 Autogen 的 skip_defaults 参数一致性测试。

4.3 make type_inference：Provider 返回类型推断校验

这是 Provider 工作流最独特的验证环节。对应 nox -s type_inference（python/noxfile.py）：

• 先安装全部 12 个 Provider 包，使 mypy 能解析各 Provider 的类型；
• 再对 python/tests/test_type_inference.py 及 11 个按 Provider 命名的测试文件（如 test_type_inference_anthropic.py、test_type_inference_crewai.py 等）做 mypy 静态分析。

这些测试文件不参与运行时执行，而是让类型检查器验证：Composio(provider=XxxProvider()) 后调用 composio.tools.get(...)，返回值能否被正确推断为 list[ToolParam] / list[Function] 等框架原生类型。以 Anthropic 为例（python/tests/test_type_inference_anthropic.py）：

composio: Composio[ToolParam, list[ToolParam]] = Composio(
    provider=AnthropicProvider()
)
tools = composio.tools.get(user_id="test", toolkits=["github"])
# Type checker should infer: list[ToolParam]
assert_type(tools, list[ToolParam])

这正是 python/composio/core/provider/none_agentic.py 中泛型 BaseProvider[TTool, TToolCollection] 的设计收益：类型信息在 Composio 实例化时被固定，IDE 与静态检查器即可为下游代码提供精确补全与错误提示。

4.4 窄范围迭代：pytest 标记与直接路径

新增 Provider 时无需每次全量跑测试。原文档给出的两种窄化方式：

# 方式一：pytest 标记（-k 关键字匹配）
make tst -- -k "anthropic"

# 方式二：直接指定测试路径
make tst -- tests/test_provider.py

tst 会话支持 posargs 透传（python/noxfile.py），-- 之后的参数会原样交给 pytest。同理，type_inference 会话也可用 make type_inference -- tests/test_type_inference_anthropic.py 单独校验单个 Provider 的类型推断。

五、发布前检查：包元数据的构建验证

对于面向发布的包元数据变更，原文档要求在构建产物存在时执行：

make build          # 构建所有包（含各 Provider 的 wheel/sdist）
twine check dist/*  # 校验构建产物元数据

make build 的真实逻辑在 python/Makefile：先清理旧的 dist/、build/，用 .venv/bin/python -m build 构建根包，再遍历 providers/*/pyproject.toml 逐个构建 Provider 包，并把各 Provider 的产物拷贝到根 dist/。随后 twine check dist/* 会验证 wheel 与 sdist 的元数据完整性（如 README 渲染、classifier 合法性、许可证声明等），确保发布到 PyPI 的包不会因元数据问题被拒。

PROVIDER_DIRS 的自动发现逻辑见 python/Makefile：通过 wildcard providers/*/pyproject.toml 自动枚举所有 Provider，因此新增 Provider 后无需手工修改 Makefile 的构建列表。

六、完整开发闭环：把工作流串起来

综合原文档与仓库源码，一个完整的新 Provider 开发流程如下：

1. 脚手架：cd python && make create-provider name=<provider-name> [agentic=true]，产物位于 python/providers/<provider-name>/；
2. 实现：按目标框架约定填充 provider.py——非 Agentic 形态实现 wrap_tool / wrap_tools / execute_tool_call / handle_tool_calls；Agentic 形态继承 AgenticProvider 并实现带 execute_tool 回调的包装方法；框架依赖写入包内 pyproject.toml；
3. 注册验证：新增或重命名 Provider 包时，把该包加入 python/noxfile.py 的 type_inference 安装列表，并在 python/noxfile.py 的 mypy 检查文件列表中加入对应的 test_type_inference_<name>.py；
4. 补测试：参照 python/tests/test_type_inference_anthropic.py 新增类型推断测试，并在 python/tests/ 中补充行为测试（可参考 test_provider.py、test_tool_router.py 等既有用例的组织方式）；
5. 验证：make chk（lint + 类型检查）→ make tst（单测）→ make type_inference（类型推断校验），日常迭代用 -- -k <provider> 或直接传测试路径缩小范围；
6. 打包发布：make build && twine check dist/* 确认元数据合法后发布。

这套工作流把"创建—实现—验证—发布"固化为可重复的工程流程：脚手架保证包结构、命名、类型标记的规范性，nox 会话保证静态检查、单元测试、类型推断三层验证的完整性，而 twine check 为发布质量兜底。对希望为 Composio 贡献新框架适配（或维护既有 Provider）的开发者而言，按此流程即可获得与仓库内 12 个官方 Provider 完全一致的工程标准。