Composio TypeScript 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本文以仓库中 TypeScript Provider 技能的规范文档 SKILL.md 及其引用的工作流文档 provider-workflow.md 为主体系统讲解在ts/packages/providers/目录下实现、修改、测试和文档化 TypeScript Provider 包的完整工作流。读完后你可以掌握如何用pnpm create:provider一键脚手架一个新的 Provider 包、理解 agentic 与 non-agentic 两类 Provider 的抽象差异、遵循实现规则避免破坏框架原生工具格式以及用 typecheck/test/build 三步完成验证。1. 技能定位与适用范围SKILL.md 在 frontmatter 中给出了该技能skill的明确定位名称typescript-providers描述Implement, modify, test, or document TypeScript provider packages underts/packages/providers覆盖 OpenAI、Anthropic、Google、LangChain、Mastra、Vercel、LlamaIndex、Cloudflare 和 Claude Agent SDK 等框架适配器边界约束用于 Provider 专属的 TS 工作仅涉及 core 包的改动不适用本技能技能正文只有一条硬性要求在修改任何 TypeScript Provider 之前先阅读 references/provider-workflow.md。这体现了该仓库的技能路由设计——ts/packages/providers/AGENTS.md 进一步补充了路由规则Provider 实现与文档/示例走typescript-providers包级测试走typescript-testing存在 Python 对应实现时走cross-sdk-parity。从仓库结构看ts/packages/providers/下现有 10 个 Provider 包anthropic、claude-agent-sdk、cloudflare、google、langchain、llamaindex、mastra、openai、openai-agents、vercel与技能描述所列框架一一对应可参见 ts/packages/providers/README.md 中的包清单表。2. 创建或定位 Provider脚手架命令工作流文档的第一步是创建或定位Provider 包pnpm create:provider provider-name [--agentic]所有 Provider 统一存放在ts/packages/providers/目录下。该命令最终由脚本 ts/scripts/create-provider.sh 实现从源码可以看到它做了以下事情参数校验未提供 provider 名时直接报错退出用法为npm run create-provider provider-name [--agentic]--agentic标志决定生成 agentic 还是 non-agentic 骨架。创建目录ts/packages/providers/name/src。生成 package.json包名固定为composio/nametype: module入口src/index.ts发布产物dist/index.mjs 类型声明dist/index.d.mtscomposio/core同时出现在peerDependencies^0.1.0和devDependenciesworkspace:*构建脚本使用tsdown测试使用vitest run。生成 tsconfig.json继承仓库根的tsconfig.base.jsontarget: es2022、module: esnext、strict: true、moduleResolution: bundler。生成 tsdown.config.ts复用 tsdown.config.base.ts 中的baseConfig。生成 src/index.ts 骨架骨架代码按--agentic分支生成两种基类继承——agentic 版继承BaseAgenticProvider且wrapTool接收(tool, executeTool)两个参数non-agentic 版继承BaseNonAgenticProvider且wrapTool只接收tool。生成 README.md并在目录内执行pnpm install。生成的 Provider 类骨架以 non-agentic 为例形如import { BaseNonAgenticProvider, Tool } from composio/core; interface MyframeworkTool { // Add your tool type here } type MyframeworkToolCollection ArrayMyframeworkTool; export class MyframeworkProvider extends BaseNonAgenticProvider MyframeworkToolCollection, MyframeworkTool { readonly name myframework; /** * Wrap a tool in the myframework format. */ wrapTool(tool: Tool): MyframeworkTool { return { // Implement your tool wrapping logic here } as MyframeworkTool; } wrapTools(tools: Tool[]): MyframeworkToolCollection { return tools.map(tool this.wrapTool(tool)); } }注意脚手架生成的两个泛型TToolCollection, TTool分别约束工具集合与单个工具的类型Provider 需要为所选框架定义对应的原生工具类型。3. 两类 Provider 的抽象基础理解实现规则之前需要先理解 core 暴露的两个基类定义在 ts/packages/core/src/provider/BaseProvider.tsBaseNonAgenticProviderTToolCollection, TTool, TMcpResponseL134-L153_isAgentic false要求实现wrapTool(tool: Tool): TTool与wrapTools(tools: Tool[]): TToolCollection。适用于你自己在应用代码中跑工具循环的裸模型 API 场景OpenAI、Anthropic、Cloudflare运行时通过executeToolCall/handleToolCalls等辅助方法执行工具。BaseAgenticProviderTToolCollection, TTool, TMcpResponseL160-L181_isAgentic truewrapTool与wrapTools均额外接收一个executeTool: ExecuteToolFn参数即把执行函数烘焙进工具本身LangChain、LlamaIndex、Mastra、Vercel、OpenAI Agents 这类由框架自身驱动工具循环的场景。两者共同继承的内部基类BaseProviderL17-L127提供了executeTool(toolSlug, body, modifiers?)通过 core 注入的_globalExecuteToolFn执行工具若未注入则抛出ComposioGlobalExecuteToolFnNotSetErrorL55-L66executeToolForTargetL85-L113统一的执行入口target 是字符串 userId 时走 direct tools APIexecuteTool是 Tool Router session 时调用target.execute——并且通过assertToolCallExecutionOptionsL69-L79拒绝在 session 执行时混用 direct-only 的 options/modifiers。这意味着 Provider 包本身不直接发 HTTP 请求执行能力由 core 注入这也正是工作流文档中避免把 provider 专属依赖泄漏进 core这条规则反向成立的原因core 对 Provider 的依赖被约束在抽象基类层面。4. 实现规则Implementation Rulesprovider-workflow.md 列出了五条实现规则逐条结合仓库佐证保持框架原生工具格式Preserve framework-native tool formats。每个 Provider 输出的是所选框架 API 所要求的工具形状如 Anthropic 的input_schema、OpenAI 的parameters、LangChain 的工具结构不做跨框架统一改写。ts/packages/providers/AGENTS.md 进一步强调Preserve framework-native tool shapes and naming conventions。Provider 专属代码留在 Provider 包内Keep provider-specific code in the provider package。脚手架把composio/core声明为workspace:*的开发依赖、发布时仅为 peer 依赖保证了依赖方向是provider - core单向的。不要向 core 泄漏 Provider 专属依赖Avoid leaking provider-only dependencies into core。框架 SDK如anthropic-ai/sdk、langchain只应出现在各 Provider 包自己的依赖里。setup 或公开用法变化时同步更新文档/示例Update docs/examples。脚手架生成的 README 已包含安装、Quick Start、API Reference 三个区块修改公开 API 后需要维护这些内容。有 Python 对应实现的 Provider 使用cross-sdk-parity技能保证跨 SDK 行为对齐例如仓库中存在python/providers/anthropic/、python/providers/langchain/等 Python 侧对应包以及 parity-variance.json 记录 parity 差异。此外ts/packages/providers/AGENTS.md 补充了一条 schema 处理细则凡接收 rawTool的 Provider在输出 vendor JSON Schema 之前、且在 Provider 自身的 schema 变换之后必须调用composio/core的deduplicateJsonSchemaRequiredArrays已通过ToolSchema归一化的 API 工具除非后续又被变换否则无需重复调用。5. 验证流程Verification工作流文档给出的三步验证命令均在仓库根目录执行pnpm --filter composio/provider typecheck # 类型检查 pnpm --filter composio/provider test # vitest run pnpm build:packages # 全量打包构建其中单包的test脚本即脚手架写入的vitest run。工作流还明确了测试覆盖要求Add tests for wrapping, tool-call handling, schema conversion, and framework version compatibility when relevant即按需覆盖四类场景——工具包装、工具调用处理、schema 转换、框架版本兼容性。pnpm --filter composio/provider是 pnpm workspace 的包过滤语法provider即包名去掉composio/前缀部分如--filter composio/openai testpnpm build:packages则触发 monorepo 级别的全量构建用于在单包验证通过后确认没有破坏 workspace 其他包尤其是 core。6. 实操小结新增一个 Provider 的完整路径综合技能文档与工作流一次完整的 Provider 开发可按以下路径执行示例以名为myframework的 agentic Provider 为例在仓库根目录执行pnpm create:provider myframework --agentic得到ts/packages/providers/myframework/骨架在src/index.ts中实现wrapTool(tool, executeTool)与wrapTools(tools, executeTool)把Tool转成该框架原生工具形状若涉及 schema 变换按 AGENTS.md 要求在输出 vendor JSON Schema 前调用deduplicateJsonSchemaRequiredArrays补充覆盖 wrapping / tool-call handling / schema conversion / 框架版本兼容性的 vitest 用例依次运行pnpm --filter composio/myframework typecheck、pnpm --filter composio/myframework test、pnpm build:packages完成验证若该 Provider 有 Python 对应实现走cross-sdk-parity流程做跨 SDK 对齐setup 或公开用法有变化时更新 README 与示例。适用前提与限制以上流程基于当前仓库的 pnpm workspace tsdown vitest 工具链见 ts/packages/providers/README.md 与 ts/scripts/create-provider.shProvider 必须依赖 workspace 内的composio/core仓库为只读本文仅说明查看、安装、运行与配置方式。若要在本仓库之外构建自有适配器可参考 core 中BaseNonAgenticProvider/BaseAgenticProvider的公开接口自行扩展。【免费下载链接】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），仅供参考