Composio 与 Claude 深度集成composio/anthropic 非 Agentic 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 TypeScript SDK 中的composio/anthropic包展开讲解如何将 Composio 托管的 1000 工具集适配到 Anthropic Claude Messages API 的tools协议中并自主执行 Claude 返回的tool_use调用。读完本文你将掌握完整的工具调用循环tool-call loop写法、cacheTools提示词缓存配置、工具 Schema 键名自动净化与还原机制、会话Session与直接执行两条执行路径以及流式输出与 MCP 接入等进阶用法。一、包定位什么是非 Agentic Provider在 Composio SDK 的 provider 体系里provider 是把 Composio 工具格式转换成目标 AI 平台所需格式的适配层。ts/packages/core/src/provider/BaseProvider.ts 中定义了两种基类BaseNonAgenticProvider不拥有自主循环只负责wrapTool/wrapTools的格式转换并由你的代码驱动循环_isAgentic falseBaseAgenticProvider自行维护 Agent 循环_isAgentic true。AnthropicProvider继承自BaseNonAgenticProvider其name属性为anthropic核心职责是把 Composio 工具定义包装wrap成 Anthropic Messages API 认可的input_schema格式解析 Claude 返回的tool_use内容块执行对应工具并把结果打包成可直接追加的tool_result消息。整体调用链可概括为Composio 工具 → wrapTool 包装 →client.messages.create({ tools })→ Claude 返回tool_use→ handleToolCalls 执行 → 追加tool_result回传 → 循环直到模型输出文本。二、安装与环境准备在package.json中composio/anthropic声明了对anthropic-ai/sdk^0.110.0 || ^0.120.0 || ^0.124.0和composio/core0.10.0 1.0.0的 peer 依赖。安装命令与包说明文档一致npm install composio/core composio/anthropic anthropic-ai/sdk需要特别留意两点运行时前提依据 package.json 的engines字段Node.js 版本该包已发布为 ESM-onlytype: module产物为dist/index.mjs要求 Node.js 22.22.3环境变量设置COMPOSIO_API_KEY在 Composio 控制台的 Settings 页面创建和ANTHROPIC_API_KEY在 Anthropic 控制台的 API Keys 页面创建。仓库自带的可运行示例位于 ts/examples/anthropic/src/index.ts它会通过dotenv读取环境变量并演示完整流程可作为本地调试的起点。三、快速开始完整的工具调用循环下面这段代码直接来自包 README 的 Quickstart是使用AnthropicProvider的最小完整骨架。它完成四件事创建用户会话、把会话工具传给 Messages API、循环执行所有tool_use块、直到 Claude 以纯文本回复。import Anthropic from anthropic-ai/sdk; import { Composio } from composio/core; import { AnthropicProvider } from composio/anthropic; const composio new Composio({ provider: new AnthropicProvider(), }); const client new Anthropic(); // Create a session for your user const session await composio.create(user_123); const tools await session.tools(); const messages: Anthropic.MessageParam[] [ { role: user, content: Send an email to johnexample.com with the subject Hello and body Hello from Composio!, }, ]; let response await client.messages.create({ model: claude-opus-4-6, max_tokens: 4096, tools, messages, }); // Agentic loop: keep executing tool calls until the model responds with text while (response.stop_reason tool_use) { const toolResults await composio.provider.handleToolCalls(session, response); messages.push({ role: assistant, content: response.content }); messages.push(...toolResults); response await client.messages.create({ model: claude-opus-4-6, max_tokens: 4096, tools, messages, }); } // Print final response for (const block of response.content) { if (block.type text) { console.log(block.text); } }要点拆解composio.create(user_123)以外部用户 ID 创建 Tool Router 会话session.tools()返回该会话可见的工具默认包含会话级 meta 工具tools数组直接传给client.messages.create的tools字段——它已经是 Anthropic 格式循环的退出条件是stop_reason tool_use只要模型还想调用工具就把assistant轮次和tool_result结果依次入栈继续请求把assistant消息整体response.content推入历史是 Anthropic 多轮工具调用的硬性要求handleToolCalls返回的tool_result块则负责回答模型上一次的工具意图。四、核心 API 逐个拆解AnthropicProvider的公开方法定义在 src/index.ts。我们逐一分析其行为与底层实现。4.1 wrapToolComposio 工具 → Anthropic 工具wrapTool(tool)把一个 ComposioTool转成AnthropicTool。转换结果结构由 src/types.ts 定义{ name: tool.slug, // 模型调用时使用的工具名 description: tool.description || , input_schema: schema, // JSON Schemadraft 2020-12格式的输入定义 cache_control: this.cacheTools ? { type: ephemeral } : undefined, }在产出input_schema之前wrapTool内部会按顺序执行三步预处理dereferenceJsonSchema内联$ref/$defs把只通过引用可达的键变成普通值位置保证后续净化与还原都能覆盖。采用 lenient 模式onUnresolved: sentinel遇到悬空引用时降级为宽松对象而非抛错sanitizeSchemaPropertyKeys键名净化重写违反 Anthropic 约束的键详见第六节deduplicateJsonSchemaRequiredArrays去重required去除同一层级required数组中的重复条目——测试 test/anthropic.test.ts 中deduplicates required entries at every object-schema level用例专门验证了顶层与嵌套对象都会去重。wrapTools(tools)则是tools.map(tool this.wrapTool(tool))的批量版本。测试还覆盖了无inputParameters的工具自动补{ type: object, properties: {}, required: [] }与空数组返回空数组等边界。4.2 handleToolCalls执行一批工具调用并打包结果handleToolCalls(executionTarget, message, options?, modifiers?)接收 Anthropic 返回的Message从中过滤出所有tool_use内容块逐个执行后返回Anthropic.Messages.MessageParam[]——注意它不是返回原始字符串而是一条可直接push进消息列表的user消息内容为tool_result块数组[ { role: user, content: [ { type: tool_result, tool_use_id: tu_123, content: {result:success} }, // ...每个 tool_use 对应一个 tool_result ], } ]没有tool_use块时返回空数组[]不会污染消息历史。每个tool_result的content字段是executeToolCall序列化后的 JSON 字符串当cacheTools: true时tool_result块同样会携带cache_control: { type: ephemeral }从而把工具结果也纳入提示词缓存。4.3 executeToolCall执行单个 tool_use 块executeToolCall有两个重载签名对应两种执行目标传SessionexecuteToolCall(session, toolUse)通过会话的execute方法执行传userIdexecuteToolCall(userId, toolUse, options?, modifiers?)走直连执行可携带connectedAccountId、customAuthParams等选项以及beforeExecute/afterExecute修饰器。单块执行的内部顺序是对应 src/index.ts 第 275-312 行normalizeToolArguments归一化参数若模型把input以 JSON 字符串而非对象发出先解析为对象依据toolKeyMappings还原被净化的键名详见第六节通过executeToolForTarget分发到会话或直连执行返回JSON.stringify(result.error null ? result.data : { error: result.error })——成功时返回数据本身失败时返回{ error }对象错误文本会被保留而不是悄悄吞掉这一点在 CHANGELOG 0.11.0 中有明确说明。五、Provider 选项cacheTools 与提示词缓存AnthropicProvider目前只有一个构造选项new AnthropicProvider({ cacheTools: true })当cacheTools: true时provider 会给每个工具定义wrapTool产出的cache_control: { type: ephemeral }和每个tool_result块都挂上 Anthropic 的临时缓存标记。效果是当你在每一轮请求中都发送同一大批工具时Claude 可以复用已缓存的工具 Schema从而削减重复的提示词成本——这对每轮都传全套工具的典型 Agent 场景收益明显。实现层面该开关在构造函数中被记录src/index.ts 第 122-126 行随后同时作用于wrapTool工具定义与handleToolCalls结果块两处形成覆盖输入 Schema 输出结果的完整缓存断点。仓库示例 ts/examples/anthropic/src/index.ts 中即使用了new AnthropicProvider({ cacheTools: true })组合composio.tools.get(default, HACKERNEWS_GET_USER)获取指定工具的写法展示了缓存选项与按需取工具的配合方式。六、工具 Schema 键名净化与还原让任何工具都能通过 Anthropic 校验这是本包最有技术含量、也最值得展开的部分。Anthropic Messages API 对工具input_schema的每个属性键有严格约束^[a-zA-Z0-9_.-]{1,64}$任何单个违规键都会导致整个tools数组被 HTTP 400 拒绝同请求中的其他工具全部陪葬。而 Composio 生态的真实工具常踩到两个雷区OData 参数如 OneDrive / Microsoft Graph 工具的$top、$filter、microsoft.graph.conflictBehavior其中$与非法超长扁平化键如 Zoom 等工具中超过 64 字符的__连接长键。该约束与重写策略定义在 src/sanitize-keys.ts具体规则如下表场景处理方式$字符替换为dollar_如$top→dollar_top字符替换为at_如odata.type→at_odata.type其他非法字符替换为_键长度 64截断并追加确定性哈希后缀djb2 哈希转 base-36取前 7 位空键 / 全部字符被剥离生成key_hash形式非空别名别名冲突追加哈希后缀仍冲突则再追加递增计数器保证算法必然收敛已合规的键原样保留不产生映射净化的作用域是递归全遍历不仅覆盖顶层properties与数组items还覆盖allOf/anyOf/oneOf、not/if/then/else、prefixItems元组、additionalProperties/patternProperties、$defs/definitions等组合关键字这些在 test/sanitize-keys.test.ts 中有大量针对用例。唯一的例外是additionalProperties这类动态键位置为保证 Schema 能被 Anthropic 接受仍会净化但动态键值无法一一还原注释明确记录了这一设计取舍。6.1 还原模型看到别名后端收到原名净化只是上半场。如果只改键名后端工具执行时收到的将是dollar_top而非$top导致工具调用失败。因此 provider 在wrapTool时会把每个工具的重写映射记录进内部的toolKeyMappingssanitized - original按工具 slug 索引并在executeToolCall执行前通过restoreOriginalKeys把参数键还原回原名。测试 test/sanitize-keys.test.ts 中的端到端用例展示了这一往返模型发出input: { dollar_top: 25 }provider 最终以{ $top: 25 }调用后端执行函数。需要记住的契约与边界源码注释中明确说明同一个 provider 实例上先 wrap 后 execute还原依赖 wrap 阶段注册的映射。若某工具在从未包装过它的实例上执行参数将原样透传模型发出的别名会直达后端此时会有debug日志可诊断重新 wrap 同一 slug 会刷新映射若新 Schema 无需重写旧的映射会被清除避免残留映射误伤原型污染防护还原映射与重建的结果对象均无原型prototype-free参数中出现__proto__、constructor、toString等Object.prototype成员名时不会抛错、不会污染全局原型深度上限Schema 净化与参数还原都限定了递归深度病态深嵌套会抛出明确错误而非栈溢出。七、参数归一化防御模型把 JSON 当字符串发Claude 偶尔会把tool_use的input以JSON 字符串而不是对象发出COMPOSIO_MULTI_EXECUTE_TOOL与 Vercel AI SDK 流式场景最容易触发对应 issue #2406。若把原始字符串直接转发给执行层会出现tool_use.input: Input should be a valid dictionary这类难以排查的错误。composio/core提供了统一的normalizeToolArguments帮助函数见 ts/packages/core/src/utils/toolArguments.ts其规则为null/undefined→{}某些模型对无参工具不发送参数普通对象 → 原样返回字符串 →JSON.parse空串 / 纯空白串 →{}无法解析为对象的输入数组、原始值、非法 JSON→ 抛出带工具名的类型化错误ComposioInvalidToolArgumentsError。AnthropicProvider在executeToolCall中先归一化、后还原键名——这个顺序是刻意设计的对原始字符串做键还原是无效操作必须先解析成对象才能遍历重写。测试normalizes a JSON-string input before restoring sanitized keys专门守护了这一顺序。八、会话执行与直连执行两条执行路径的取舍executeToolCall/handleToolCalls的第一个参数可以是Session或userId 字符串底层由executeToolForTarget定义于 ts/packages/core/src/provider/BaseProvider.ts分流目标类型执行方式适用场景Sessiontarget.execute(toolSlug, args)走 Tool Router 会话会话保留了工具上下文、历史与 meta 工具适合需要状态的多轮对话userId字符串直连executeTool(toolSlug, body, modifiers)携带userId、connectedAccountId、customAuthParams、customConnectionData配合tools.get()拉取的工具无会话状态适合一次性调用两条路径的选择规则源码assertToolCallExecutionOptions与测试均有体现使用 Session 时不允许传options或modifiers会抛出TypeError因为会话执行与直连专属配置互斥Session 执行结果中的error字段会保留在{ error }结果里测试exposes session execution errors without changing successful results验证了成功结果不变、失败保留错误文本的行为直连执行时connectedAccountId用于指定已连接的第三方账号如{ connectedAccountId: conn_xyz456 }customAuthParams可注入自定义认证参数测试中展示了 header 类型的 token 注入。九、MCP 接入把会话暴露为 Anthropic MCP 客户端除了手工工具循环AnthropicProvider还支持通过 MCP 接入。它实现了wrapMcpServerResponse把 Composio 的 MCP URL 响应转换为 Anthropic 认可的{ url, name, type: url }格式测试覆盖了 URL 原样保留、空数组、单元素数组等场景。仓库示例 ts/examples/anthropic/src/mcp.ts 展示了完整玩法先用composio.sessions.create(externalUserId, { toolkits: [gmail], mcp: true })创建带托管 MCP 端点的会话再让 Anthropic 原生 MCP 客户端直连该端点const session await composio.sessions.create(externalUserId, { toolkits: [gmail], mcp: true, }); const stream anthropic.beta.messages.stream({ model: claude-sonnet-5, max_tokens: 64_000, mcp_servers: [ { type: url, url: session.mcp.url, name: composio-gmail, authorization_token: process.env.COMPOSIO_API_KEY, }, ], messages: [ { role: user, content: Please fetch the latest 2 emails and provide a detailed summary with sender, subject, date, and brief content overview for each email..., }, ], betas: [mcp-client-2025-04-04], });这条路径把工具发现与执行完全交给 Anthropic 的 MCP 客户端处理无需在业务代码里维护工具调用循环。注意示例中session.mcp.url来自sessions.create(..., { mcp: true })的会话对象。十、流式输出边生成边打印如果希望文本输出流式到达可改用client.messages.stream()。示例 ts/examples/anthropic/src/streaming.ts 展示了与工具调用结合的写法on(text)实时写出文本finalMessage()拿到完整消息后再统一处理tool_use块第二轮请求时需要把tool_use块拼进assistant内容再追加toolResultsmessages: [ { role: user, content: Fetch the details of the user pg ... }, { role: assistant, content: [ { type: text, text: Ill fetch the details ... }, ...toolUseBlocks, ], }, ...toolResults, ]十一、与 Claude Agent SDK 的选型对比包 README 明确指出如果已经在用 Claude Agent SDK应改用composio/claude-agent-sdk。两条路线的分工是composio/anthropic本文主角把工具适配到 Messages API 格式由你的代码驱动工具调用循环适合需要对循环有完全控制权的场景composio/claude-agent-sdk把 Composio 工具包装为进程内 MCP 服务器交由 Claude Agent SDK 自己跑循环createSdkMcpServerquery业务代码只需定义 prompt 与权限模式。判断标准很简单你是否需要手写while (stop_reason tool_use)循环。需要精细控制如逐轮插入修饰器、自定义重试选本文方案希望框架代管循环、少写胶水代码则选 Claude Agent SDK 方案。十二、质量保障测试如何覆盖这些行为该包的测试位于 test/anthropic.test.ts 与 test/sanitize-keys.test.ts通过 vitest mockanthropic-ai/sdk完成覆盖的关键契约包括wrapTool的格式正确性、无参工具兜底、required去重executeToolCall的参数透传、JSON 字符串归一化含非法 JSON 抛类型化错误、options/modifiers透传、会话执行错误保留handleToolCalls的单块 / 多块 / 无工具调用场景以及tool_result打包结构键名净化OData 键重写、64 字符截断且确定性、别名冲突保持区分、嵌套对象 / 数组 items / 元组 /anyOf/oneOf/allOf/prefixItems/$defs全覆盖、additionalProperties只净不还原、原型污染防护、深度上限还原的端到端行为模型发dollar_top后端收到$topre-wrap 清理陈旧映射$ref嵌套非法键的往返。这些测试文件既是行为契约也是排查问题时的最佳参照——若你在接入某个具体工具时遇到 400 校验失败可以对照测试中的 sanitize 用例检查该工具的 Schema 键名。十三、注意事项与边界运行时与模块格式ESM-only Node ≥ 22.22.3CommonJS 调用方只能依赖 Node 原生require(esm)互操作同一个实例先 wrap 后 execute键名还原依赖实例内的映射表混用不同实例可能产生别名透传可用debug日志定位additionalProperties/patternProperties等动态键位置只净化、不还原若后端工具依赖这些动态键上的原始 OData 名称需要额外处理会话目标不接受options/modifiers混用会抛出TypeError请根据工具来源会话 vs 直连选择正确的调用形态模型与参数名文中模型名claude-opus-4-6、claude-sonnet-5与示例代码取自当前仓库请按你实际可用的 Anthropic 模型版本替换。至此从安装、快速开始、核心 API、缓存优化、键名净化原理到会话/直连双路径、MCP 与流式接入composio/anthropic的完整能力已全部覆盖。你可以直接以本文第三节的代码为骨架替换为实际工具集与业务提示词快速搭建一个由 Claude 驱动、由 Composio 提供工具执行能力的 Agent 应用。【免费下载链接】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），仅供参考