Composio × Claude Agent SDK:用 `@composio/claude-agent-sdk` 将 Composio 工具以进程内 MCP 形式接入 Claude 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)是整条链路的枢纽,它做四件事:
- JSON Schema → Zod:把工具声明里的
inputParameters(JSON Schema)先经dereferenceJsonSchema解引用内部$ref/$defs,再交给jsonSchemaToZodSchema转换为 Zod 对象模式。若工具没有输入参数,则使用"封闭"的兜底模式:{ type: 'object', properties: {}, additionalProperties: false }——即不允许任何未声明键。 - 调用 SDK 的
tool():以composioTool.slug作为工具名、composioTool.description ?? \Execute ${composioTool.slug}`` 作为描述(缺省时自动补全),注册完整 Zod 模式与异步 handler。 - handler 内执行:handler 收到模型参数后,先经
normalizeToolArguments归一化,再调用executeTool(composioTool.slug, args)把执行路由回 Composio,返回值统一序列化为 MCP 的content: [{ type: 'text', text }]文本块——typeof result === 'string'时原样透传,否则JSON.stringify。 - 异常兜底: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 的整体架构。