Composio Python Providers 开发指南：创建、实现与验证框架适配器的完整工作流

Composio Python Providers 开发指南创建、实现与验证框架适配器的完整工作流【免费下载链接】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 开源仓库中.agents/skills/python-providers技能文档SKILL.md 与 provider-workflow.md为核心骨架系统讲解如何在python/providers/目录下创建、实现、测试与打包 Python Provider 适配器。读完本文你将掌握make create-provider脚手架的使用、Agentic 与 Non-Agentic 两类 Provider 的基类契约与实现差异、make chk / tst / type_inference三条验证命令背后的 nox 会话原理以及新 Provider 接入仓库时需要在哪些元数据与测试清单中登记。一、Provider 在 Composio Python SDK 中的定位Composio Python SDK 的核心能力是把 1000 工具统一包装成任意 AI 框架原生的工具格式。实现这一能力的关键抽象就是Provider每个 Provider 是一个框架适配器负责把 Composio 的工具描述转换为目标框架如 Anthropic、OpenAI、LangChain、CrewAI 等期望的工具结构并在模型发起工具调用时把调用翻译回 Composio 执行层。从仓库结构看所有 Provider 包都位于 python/providers/每个子目录是一个独立可发布的 Python 包命名遵循composio_provider如composio_anthropic、composio_openai并随附pyproject.toml、setup.py、py.typedPEP 561 类型标记和 demo 脚本。当前仓库内置了 anthropic、autogen、claude_agent_sdk、crewai、gemini、google、google_adk、langchain、langgraph、llamaindex、openai、openai_agents 等 Provider见 python/noxfile.py 的完整安装列表。注意技能文档的边界约定Provider 包相关改动使用python-providers技能核心 SDKpython/composio/下代码的改动则使用python-sdk技能见 python/AGENTS.md。二、创建 Providermake create-provider 脚手架技能文档给出的创建入口是一条 Make 目标从python/目录执行# 创建普通Non-AgenticProvider make create-provider nameprovider-name # 创建 Agentic Provider面向自带 Agent 执行循环的框架 make create-provider nameprovider-name agentictruename参数必填缺省时 Makefile 会报错提示。此外还可传入outputdirectory自定义输出目录见 python/Makefile 的create-provider目标它最终调用bash scripts/create-provider.sh name [--agentic] [--output-dir dir]。2.1 脚手架生成的目录结构以namemyai为例python/scripts/create-provider.sh 会生成python/providers/myai/ ├── README.md # 包说明、安装方式、Quick Start、API 参考、开发指引 ├── pyproject.toml # 现代打包元数据dependencies 至少包含 composio ├── setup.py # 向后兼容的安装入口 ├── myai_demo.py # 可运行的 demo 脚本 └── composio_myai/ # 实际 Python 包 ├── __init__.py # 导出 XProvider ├── provider.py # Provider 实现主体 └── py.typed # PEP 561 类型标记文件脚手架还会做三件关键事包名与类名自动规范化PACKAGE_NAMEcomposio_$PROVIDER_NAME类名转为首字母大写myai - MyaiProvider重复创建保护若目标目录已存在脚本直接报错退出❌ Provider myai already exists依赖声明默认化生成的pyproject.toml中dependencies [composio]requires-python 3.10,4——与现有 Provider 包保持一致例如 python/providers/openai/pyproject.toml 声明openai2.48.0与composio两个依赖。2.2 生成后的下一步脚本结束时会输出后续操作清单cd python/providers/provider-name # 1. 按目标框架补齐 provider.py 中的实现 # 2. 开发模式安装 uv pip install -e . # 3. 运行 demo 验证 python provider-name_demo.py脚手架生成的 demo 已演示了标准用法——Composio(providerXProvider())初始化再通过composio.tools.get(user_iddefault, toolkits[GITHUB])或tools[...]获取工具Agentic 模板中还预留了Agent(...)/Runner.run(...)的接入占位。三、Provider 基类体系Non-Agentic 与 Agentic 两条契约要正确实现 Provider必须先理解仓库中 python/composio/core/provider/ 下的基类层次。3.1 BaseProvider公共骨架python/composio/core/provider/base.py 定义了最底层约定泛型参数TTool/TToolCollection即包装后的单个工具与工具集合类型name: str类属性用于标识 Providerexecute_tool: ExecuteToolFn——由核心 SDK 通过set_execute_tool_fn()自动注入的执行函数签名(slug, arguments, *, modifiers, user_id) - ToolExecutionResponseschema_config.skip_defaults配置__schema_skip_defaults__类属性控制是否在工具 schema 中跳过默认值resolve_tool_call_execution_target()与execute_tool_for_target()统一处理直接执行user_id与Tool Router 会话执行session两种目标且强制要求二选一——两者同时提供或都不提供会抛出ValueError。3.2 NonAgenticProvider面向纯 LLM 工具调用框架python/composio/core/provider/none_agentic.py 适用于只把工具作为函数参数传给模型、由开发者自己驱动执行循环的框架如 OpenAI Function Calling、Anthropic Messages API、Google Gemini。它只要求实现两个方法def wrap_tool(self, tool: Tool) - TTool: ... def wrap_tools(self, tools: t.Sequence[Tool]) - TToolCollection: ...wrap_tool负责把 Composio 的Tool转换为框架原生工具参数结构。以 Anthropic 为例python/providers/anthropic/composio_anthropic/provider.py 返回anthropic.types.tool_param.ToolParam并额外用alias_tool_input_schema处理 schema 别名如枚举重命名以备调用时还原。3.3 AgenticProvider面向自带 Agent 执行循环的框架python/composio/core/provider/agentic.py 适用于框架自带 Agent 与 Runner 的生态如 OpenAI Agents SDK、CrewAI、Autogen、LangGraph 等。与 Non-Agentic 的关键区别在于wrap_tool/wrap_tools额外接收execute_tool: AgenticProviderExecuteFn参数包装出来的工具自带execute可调用对象Agent 框架可直接调用由内部execute_wrapper调用execute_tool(tool.slug, kwargs)完成执行并在result.get(successful)为假时抛出异常。3.4 两类 Provider 的通用执行方法无论哪类 Provider通常还需实现两个执行辅助方法基类在 base.py 提供了目标解析与分发的通用逻辑execute_tool_call(user_id, tool_call, modifiersNone)执行单次工具调用tool_call包含name与argumentshandle_tool_calls(user_id, response, modifiersNone)从模型响应对象中抽取全部工具调用并逐个执行。Anthropic Provider 的 handle_tool_calls 是很好的参考它接受dict或ToolsBetaMessage遍历response.content中类型为ToolUseBlock/BetaToolUseBlock的内容块逐个执行并汇总ToolExecutionResponse列表。它还处理了一个真实细节——模型偶尔会把工具入参输出成 JSON 字符串而非 dict因此先经normalize_tool_arguments归一化再执行对应代码注释中 issue #2406。四、实现规则技能文档的六条红线provider-workflow.md 明确列出了实现 Provider 时必须遵守的规则逐条解读如下依赖归属框架相关的依赖如anthropic、openai必须声明在 Provider 包的pyproject.toml中而非核心 SDK——除非共享工具确实需要。核心 SDK 保持框架无关这是 Provider 包独立发布的前提。保留公共导入路径composio_provider包的公开导入面如from composio_openai import OpenAIProvider不得随意变更避免破坏下游用户代码。匹配框架原生约定包装出的工具结构应与目标框架官方 SDK 的类型定义一致。这也是 python/tests/test_type_inference.py 用assert_type校验的正是返回类型精确等于框架原生类型如 OpenAI 场景推断为list[ChatCompletionToolParam]。公共用法变更须同步更新文档与示例改wrap_tool等公开行为时需同步维护 python/docs/ 与 python/examples/ 中的相关示例。有 TypeScript 对应版本的 Provider 使用cross-sdk-parity技能确保 Python 与 TypeScript SDK 行为对齐见 .agents/skills/cross-sdk-parity/SKILL.md。登记 noxfile.py 清单新建 Provider 或重命名 Provider 包时通常需要在 python/noxfile.py 的type_inference会话中把新包加入provider 安装列表session.install(./providers/name, ...)以及mypy 检查文件列表如tests/test_type_inference_name.py。这一步漏掉会导致类型推断验证无法覆盖新 Provider。五、验证工作流make chk / tst / type_inference技能文档要求从python/依次执行三条验证命令make chk # 静态检查Ruff lint mypy 类型检查 make tst # 运行单元测试套件 make type_inference # 验证 Provider 返回类型推断三者分别对应 python/noxfile.py 中的 nox 会话chk会话noxfile.py安装核心包与 dev 依赖、mypy 及类型 stub 后依次执行ruff check与按模块循环的mypy --config-file config/mypy.ini统一走 python/config/ruff.toml 与 python/config/mypy.ini 配置tst会话noxfile.py安装 dev 依赖并单独安装 crewai、langchain、langgraph 等 Provider 后运行 pytesttype_inference会话noxfile.py与chk不同它会把全部 12 个 Provider 包逐一安装然后对tests/test_type_inference*.py全部文件运行 mypy。会话 docstring 解释得很清楚只有安装了 Provider 包mypy 才能解析出各 Provider 的真实类型进而验证Composio.tools.get()的overload签名推断是否成立。注意这些测试文件不在运行时执行只被类型检查器静态分析。对于局部迭代技能文档建议用 pytest marker 或直接指定测试路径缩小范围例如# 只跑某个 Provider 的类型推断测试 pytest tests/test_type_inference_anthropic.py -v此外 python/Makefile 还提供make sntsanity快速运行tests/test_imports.py与tests/test_sdk.py的导入/SDK 初始化冒烟测试作为更轻量的前置检查make fmt负责 Ruff 格式化与 import 排序。六、类型推断测试为什么 Provider 要写 test_type_inference_ .pypython/tests/test_type_inference.py 的模式值得新 Provider 复制测试函数体内用if TYPE_CHECKING:包裹assert_type断言验证Composio(providerXProvider()).tools.get(...)的静态返回类型def test_openai_provider_explicit() - None: composio: Composio[OpenAITool, OpenAIToolCollection] Composio( providerOpenAIProvider() ) tools composio.tools.get(user_idtest, toolkits[github]) if TYPE_CHECKING: assert_type(tools, list[ChatCompletionToolParam])文件覆盖了toolkits、slug、tools、search四种取参方式以及显式泛型与类型推断两种写法并验证默认 ProviderOpenAI行为。这类测试把包装结果类型是否与框架原生类型一致固化为可回归的静态断言正是技能文档要求新 Provider 注册对应测试文件的根本原因。七、发布前检查构建与 twine 校验技能文档最后一步针对面向发布的包元数据make build # 构建核心包与全部 Provider 包产物汇总到 python/dist/ twine check dist/* # 校验分发文件元数据其中make build在 python/Makefile 中定义先清空旧构建产物用.venv/bin/python -m build构建核心包再遍历PROVIDER_DIRS即所有含pyproject.toml的 Provider 目录逐一构建并复制产物到python/dist/。twine check用于确认打包后的元数据长描述渲染、字段合法性等可正常发布。八、完整实操清单综合以上内容从零接入一个新 Python Provider 的完整流程为# 1. 创建脚手架在 python/ 下 make create-provider namemyai # 或 agentictrue # 2. 实现 provider.py按 3.1~3.4 的基类契约补全 wrap_tool/wrap_tools # Agentic 还需实现 execute_wrapper可选实现 execute_tool_call/handle_tool_calls cd python/providers/myai uv pip install -e . # 3. 跑 demo 冒烟验证 python myai_demo.py # 4. 注册到 noxfile.pytype_inference 的 provider 安装列表 检查文件列表 # 5. 新增 tests/test_type_inference_myai.py复制 test_type_inference.py 的 assert_type 模式 # 6. 完整验证在 python/ 下 make chk make tst make type_inference # 7. 发布前构建与元数据校验 make build twine check dist/*若你的 Provider 在 TypeScript SDK 中有对应实现如 ts/packages/providers/ 中的同名包实现前务必先阅读 cross-sdk-parity 技能文档保证两侧行为一致。【免费下载链接】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），仅供参考