Composio × Claude Agent SDK:用 `@composio/claude-agent-sdk` 将 Composio 工具以进程内 MCP 形式接入 Claude Agent

原创2026-09-11 19:23:541,969 阅读
文章标签:人工智能AI Agent工具调用MCP 服务认证鉴权CLIAI 技能Agent 沙箱

Composio × Claude Agent SDK:用 @composio/claude-agent-sdk 将 Composio 工具以进程内 MCP 形式接入 Claude Agent

Composio 的 Claude Agent SDK 提供器(provider)位于 ts/packages/providers/claude-agent-sdk,它的职责是把 Composio 的 1000+ 工具包装成 Claude Agent SDK(@anthropic-ai/claude-agent-sdk)可直接调用的 MCP 工具,让 Claude 智能体在无需启动独立 MCP 服务进程的前提下,通过 createSdkMcpServer 在进程内消费这些工具。读完本文,你将掌握该提供器的安装配置、单轮/多轮会话用法、工具包装与执行回调的底层机制,以及它在参数归一化、JSON Schema 根级约束保留和 $ref 解引用等边界场景下的源码级实现与测试验证方式。

提供器定位:Composio 工具如何进入 Claude Agent SDK

Claude Agent SDK 通过 MCP(Model Context Protocol)服务器向智能体暴露工具。@composio/claude-agent-sdk 的核心思路是:提供器把每个 Composio 工具定义转换为一个 MCP 工具,并把执行回调路由回 Composio,这样 createSdkMcpServer 就可以直接进程内(in-process)提供服务,无需单独运行一个 MCP 服务进程,也不需要额外的网络配置。

从源码看,这一角色由 ClaudeAgentSDKProvider 类承担,其定义于 src/index.ts:

  • 它继承自 @composio/core 的 BaseAgenticProvider<TToolCollection, TTool, McpServerGetResponse>(见 ts/packages/core/src/provider/BaseProvider.ts),并声明 readonly name = 'claude-agent-sdk';
  • BaseAgenticProvider 设置了 override readonly _isAgentic = true,测试 claude-agent-sdk.test.ts 也断言了这一点,说明它属于"智能体式(agentic)"提供器家族,与直接返回结构化响应的非智能体提供器不同;
  • 提供器的抽象契约要求实现两个核心方法:wrapTool(tool, executeTool) 将单个工具包装成 SDK 格式,wrapTools(tools, executeTool) 批量包装,另有 wrapMcpServerResponse 用于将 MCP URL 响应转换为标准格式。

package.json(package.json)显示该包以 @anthropic-ai/claude-agent-sdk(^0.3.199 起)与 @composio/core(>=0.10.0)为 peerDependencies,自身仅直接依赖 zod,其构建产物是 ESM-only(dist/index.mjs + dist/index.d.mts),要求 Node.js 22.22.3 及以上版本。

安装与前置配置

安装三个包:Composio 核心、本提供器、以及 Anthropic 官方的 Claude Agent SDK。

npm install @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk

随后设置两个环境变量:

  • COMPOSIO_API_KEY:从 Composio 控制台获取;
  • ANTHROPIC_API_KEY:从 Anthropic Console 获取。

COMPOSIO_API_KEY 用于在 new Composio({ provider: new ClaudeAgentSDKProvider() }) 时完成对 Composio 平台的认证(也可显式传入 apiKey 选项,见源码 JSDoc 示例);ANTHROPIC_API_KEY 则由 Claude Agent SDK 的 query() 在调用 Claude 模型时使用。从 CHANGELOG.md 可知,该包自 0.10.0 起已移除 CommonJS 入口,只发布 ESM 产物,因此运行环境需为 Node.js 22.22.3 或更新版本(0.11.1 将其声明为所有 TypeScript 包的最低支持运行时)。

Quickstart:创建会话、包装工具、查询 Claude

单轮查询

核心流程分三步:创建会话 → 获取会话工具并包装为 SDK MCP 工具 → 通过 query() 发起对话。

import { Composio } from '@composio/core';
import { ClaudeAgentSDKProvider } from '@composio/claude-agent-sdk';
import { createSdkMcpServer, query } from '@anthropic-ai/claude-agent-sdk';

const composio = new Composio({ provider: new ClaudeAgentSDKProvider() });

// 每个会话(session)都归属于你的某一个用户
const session = await composio.create('user_123');
const tools = await session.tools();

const customServer = createSdkMcpServer({
  name: 'composio',
  version: '1.0.0',
  tools,
});

for await (const stream of query({
  prompt: 'Summarize my emails from today',
  options: {
    mcpServers: { composio: customServer },
    permissionMode: 'bypassPermissions',
  },
})) {
  if (stream.type === 'assistant') {
    for (const block of stream.message.content) {
      if (block.type === 'text') process.stdout.write(block.text);
    }
  }
}

关键点拆解:

  • composio.create('user_123'):以用户标识创建会话,返回的 session 已绑定该用户的认证上下文;session.tools() 拉取该会话可用工具集合。
  • createSdkMcpServer 接受 name、version 与 tools 三个参数,其中 tools 正是由提供器包装后的 SDK MCP 工具数组。
  • query() 的 options.mcpServers 以 { composio: customServer } 的形式挂载进程内 MCP 服务器;permissionMode: 'bypassPermissions' 跳过工具调用权限确认(适用于自动化脚本,生产环境应评估权限策略)。
  • 响应流中仅输出 assistant 类型的文本块,工具调用与文本交替会以流式块形式陆续到达。

也可以不使用 session.tools(),而用更细粒度 API 直接取工具并手动包装:

const tools = await composio.tools.get('default', 'GMAIL_SEND_EMAIL');
const mcpServer = createSdkMcpServer({
  name: 'composio',
  version: '1.0.0',
  tools,
});

多轮会话:复用 sessionId

对于多轮对话,不要每轮都新建会话,而是保存 session.sessionId,之后用 composio.use(sessionId) 恢复该会话:

// 第一轮
const session = await composio.create('user_123');
const sessionId = session.sessionId;

// 之后的每一轮
const resumed = composio.use(sessionId);
const tools = await resumed.tools();
// ... 再次 createSdkMcpServer 并 query

这样工具所携带的认证与上下文(如已连接的 Gmail 账户)可以跨轮次延续,避免重复授权。

工作原理:从 Composio 工具到 MCP 工具再到执行回调

ClaudeAgentSDKProvider.wrapTool(src/index.ts)是整条链路的枢纽,它做四件事:

  1. JSON Schema → Zod:把工具声明里的 inputParameters(JSON Schema)先经 dereferenceJsonSchema 解引用内部 $ref/$defs,再交给 jsonSchemaToZodSchema 转换为 Zod 对象模式。若工具没有输入参数,则使用"封闭"的兜底模式:{ type: 'object', properties: {}, additionalProperties: false }——即不允许任何未声明键。
  2. 调用 SDK 的 tool():以 composioTool.slug 作为工具名、composioTool.description ?? \Execute ${composioTool.slug}`` 作为描述(缺省时自动补全),注册完整 Zod 模式与异步 handler。
  3. handler 内执行:handler 收到模型参数后,先经 normalizeToolArguments 归一化,再调用 executeTool(composioTool.slug, args) 把执行路由回 Composio,返回值统一序列化为 MCP 的 content: [{ type: 'text', text }] 文本块——typeof result === 'string' 时原样透传,否则 JSON.stringify。
  4. 异常兜底:handler 内部 try/catch,任何执行错误都被格式化为 { successful: false, error, data: null } 的 JSON 文本返回,而不是让 MCP 调用直接失败,模型仍能看到结构化错误信息并自行修正。

wrapTools 则是 tools.map(t => this.wrapTool(t, executeTool)) 的简单批处理(见 src/index.ts),测试 claude-agent-sdk.test.ts 验证了多工具包装与空数组返回空数组两个分支。

为什么注册"完整模式"而非"原始属性形状"

源码注释与 CHANGELOG 0.11.0(CHANGELOG.md)记录了一次关键行为修正:旧实现只注册原始属性形状(raw property shape),而它只是"属性名 → 属性"的映射,无法表达根级约束——additionalProperties(布尔或 schema 形式)与 patternProperties 在注册阶段就被丢弃。后果有二:

  • 自由形式的对象参数(free-form object)会丢失内容:根级 additionalProperties 约束消失后,SDK 会静默剥离未声明键,导致工具以残缺参数运行;
  • 模型幻觉出的未声明键会被悄悄删除而不是被拒绝。

现在的实现注册完整对象 schema,使根级规则能到达 SDK:additionalProperties: false 让未声明键被拒绝(rejects an unknown key instead of silently dropping it),schema 形式的 additionalProperties(如 { type: 'number' })和 patternProperties(如 '^meta_' 键)也能被保留与校验。完整行为由 claude-agent-sdk.registration.test.ts 通过真实的 SDK + 内存 MCP 传输(InMemoryTransport.createLinkedPair() + MCP Client)验证:既断言模型看到的 inputSchema(如 additionalProperties 是否为 false),也断言真实 tools/call 结果(合法键被透传执行、非法键返回 isError: true 且不触发执行)。

$ref/$defs 解引用与参数归一化

  • 解引用(dereference):若工具 schema 内部含 $ref/$defs 引用而未经解引用,$ref 类型的属性会退化为 z.any() 从而静默接受任意值。0.12.0(CHANGELOG.md)引入 dereferenceJsonSchema(..., { onUnresolved: 'sentinel' }) 先解析内部引用再转 Zod。回归测试 claude-agent-sdk-ref.test.ts 覆盖了三种情况:正常 $defs 描述的形状能通过校验({ message: { subject, body } } 合法、{ message: 42 } 非法)、悬空引用($ref 指向未声明的 $defs)不抛异常、自引用(递归 $defs)schema 也不抛异常。
  • 参数归一化(normalizeToolArguments):模型偶尔会把工具入参以 JSON 字符串而非对象发出(如 COMPOSIO_MULTI_EXECUTE_TOOL 场景,对应 issue #2406)。提供器在 handler 内统一走 @composio/core 的 normalizeToolArguments(实现见 ts/packages/core/src/utils/toolArguments.ts):null/undefined → {};纯对象原样返回;字符串做 JSON.parse(空/纯空白字符串 → {});解析不出纯对象时抛出类型化的 ComposioInvalidToolArgumentsError。测试 claude-agent-sdk.test.ts 分别验证了"字符串化 JSON 输入被解析为对象后执行"与"畸形 JSON 字符串返回 successful: false 且不执行"两个分支。

handler 返回值与错误格式

执行结果的三种形态都被测试覆盖(claude-agent-sdk.test.ts):

执行结果 handler 输出
对象(如 ToolExecuteResponse) content[0].text = JSON.stringify(result)
字符串 原样透传为 content[0].text
undefined content[0].text = ''(保证永远是字符串)
抛错 content[0].text = JSON.stringify({ successful: false, error, data: null })

无论何种情况,返回给 SDK/MCP 的都是 { type: 'text', text: string } 形式的文本内容块,符合 MCP 工具调用的内容协议。

版本与运行前提小结

  • 当前包版本 0.12.0,peerDependencies 要求 @anthropic-ai/claude-agent-sdk >= 0.3.199、@composio/core >= 0.10.0、zod ^4(见 package.json);
  • 包为 ESM-only,需 Node.js ≥ 22.22.3(CHANGELOG 0.10.0 / 0.11.1);
  • 运行测试使用 vitest run(npm test),仓库中 ts/packages/providers/claude-agent-sdk/test 目录下的三组测试分别覆盖单元包装、真实 SDK 注册边界与 $ref 回归场景;
  • 依赖图:本包依赖 @composio/core 的 BaseAgenticProvider、dereferenceJsonSchema、jsonSchemaToZodSchema、normalizeToolArguments 与 Tool/ExecuteToolFn 等类型;运行时无独立服务进程,工具执行始终回调 Composio 平台完成认证与调度。

在此基础上,若要接入更多框架,可参考仓库内其他提供器(如 @composio/vercel、@composio/langchain、@composio/llamaindex,CHANGELOG 0.11.0 指出它们早已采用"注册完整 schema"策略);若要查看完整接入流程,可继续阅读仓库根目录 README.md 与 ts/README.md 了解 Composio 的整体架构。

登录后查看全文
composio