@composio/mastra 集成指南：将 Composio 工具无缝接入 Mastra Agent

composio/mastra 集成指南将 Composio 工具无缝接入 Mastra 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导读本文面向使用 Mastra 为核心骨架结合 ts/packages/providers/mastra/src/index.ts 源码与测试用例进行深度展开。一、包定位与安装composio/mastra是 Composio TypeScript SDK 的 Mastra Provider 包。它的职责非常单一把 Composio 工具转换成 Mastra 的工具格式createTool的产物并在工具被调用时执行真正的 Composio 工具调用——也就是说包装后的工具自带执行能力可以直接传给 Mastra 的Agent使用无需再手动编写execute逻辑。安装命令npm install composio/core composio/mastra mastra/core ai-sdk/openai四个包的分工如下包作用composio/coreComposio 核心 SDK提供Composio客户端、会话模型与工具枚举能力composio/mastra本 Provider负责工具格式转换与执行绑定mastra/coreMastra 核心框架提供Agent与createToolai-sdk/openaiAI SDK 的 OpenAI 模型接入也可换成你自己的 LLM Provider从 package.json 可以看到该包的版本与依赖约束composio/core要求0.10.0 1.0.0 || 1.0.0-beta.0 1.0.0peer dependencymastra/core要求^1.46.0zod要求^3.25 || ^4运行时依赖仅一个mastra/schema-compat ^1.3.8用于把 JSON Schema 转换成 Mastra 内部使用的 Zod 模型Node 环境要求22.22.3。环境变量安装完成后需要配置两个密钥COMPOSIO_API_KEY在 Composio 控制台的 Settings 页面获取OPENAI_API_KEY或你所用 LLM Provider 的密钥。这两个密钥分别用于鉴权 Composio 后端与驱动 Agent 的模型推理。二、快速开始五步接入 Mastra AgentREADME 给出的 Quickstart 是理解整个 Provider 的最小完整示例下面逐段拆解import { Composio } from composio/core; import { MastraProvider } from composio/mastra; import { Agent } from mastra/core/agent; import { openai } from ai-sdk/openai; const composio new Composio({ provider: new MastraProvider(), }); // Create a session for your user const session await composio.create(user_123); const tools await session.tools(); const agent new Agent({ id: my-agent, name: My Agent, instructions: You are a helpful assistant., model: openai(gpt-5.2), tools, }); const { text } await agent.generate([ { role: user, content: Send an email to johnexample.com with the subject Hello and body Hello from Composio!, }, ]); console.log(text);第 1 步实例化 Composio 客户端。new Composio({ provider: new MastraProvider() })把 Provider 注入核心 SDK此后 SDK 中所有获取工具的入口都会走这个 Provider 做格式转换。第 2 步为用户创建会话。composio.create(user_123)会创建一个绑定到该用户的 Composio 会话Session。会话是工具执行上下文的载体包括身份、连接账户与沙箱等配置。第 3 步拉取会话工具。session.tools()从 Composio 后端拉取该会话可用的工具列表并返回已经是 Mastra 格式的工具集合。从源码看这个方法位于 ts/packages/core/src/models/ToolRouterSession.ts 的async tools()其返回类型正是ReturnTypeTProvider[wrapTools]——也就是说格式转换的时机发生在tools()内部由 Provider 的wrapTools完成。第 4 步注入 Agent。转换后的工具集合直接作为tools字段传给 Mastra 的Agent。此后 Agent 在规划时就能看到这些工具的id、description、输入输出 Schema并在需要时自动调用。第 5 步生成。agent.generate()触发一次完整的思考→调用工具→汇总结果循环。上面示例让 Agent 给johnexample.com发送一封主题为 Hello 的邮件实际执行时 Agent 会选择对应的邮件工具例如 Gmail 发信工具由包装后的execute完成真实调用并返回结果。README 特别强调每个工具都被同时赋予了输入 Schema 和输出 Schema因此 Mastra 既能校验模型生成的参数也能校验工具返回的结果。这一点是 Mastra 工具模型与普通函数调用的关键差异也是下文两套 Schema 处理机制存在的原因。三、工具包装机制wrapTool 源码解析要理解 Provider 的能力边界需要深入 src/index.ts 的MastraProvider实现。它继承自BaseAgenticProvider定义于 ts/packages/core/src/provider/BaseProvider.ts核心转换逻辑集中在wrapTool与wrapTools两个方法。wrapTools把工具数组按 slug 归并为键值集合wrapTools(tools: Tool[], executeTool: ExecuteToolFn): MastraToolCollection { return tools.reduce((acc, tool) { acc[tool.slug] this.wrapTool(tool, executeTool); return acc; }, {} as MastraToolCollection); }对应的测试test/mastra.test.ts验证了集合的键是工具 slug、空数组返回空对象、重复 slug 后者覆盖前者等行为。wrapTool则完成单个工具的四件事构造输入 Schema可能经过严格模式规范化见第四节构造输出 Schema先解引用$ref再执行宽松化见第五节两者统一交给applyCompatLayer来自mastra/schema-compat编译成 Mastra 可用的 Schema用createTool生成 Mastra 工具execute闭包内完成参数归一化与真实执行execute: async (inputData, _context) { // Models occasionally emit tool input as a JSON string rather than an object (issue #2406). const normalized normalizeToolArguments(inputData, tool.slug); const result await executeTool( tool.slug, strictSource ? omitNullToolArguments(normalized, strictSource) : normalized ); return result; }normalizeToolArguments处理一个真实世界的高频问题对应 issue #2406LLM 偶尔会把工具入参以 JSON 字符串而非对象的形式输出。测试用例覆盖了字符串化输入被还原为对象、畸形 JSON 抛出带类型信息的错误、缺失入参被规范化为空对象等场景保证无论模型如何抽风真实执行时拿到的都是结构正确的参数对象。四、输出 Schema 宽松化让第三方 API 的真实响应通过校验这是 Provider 中最值得展开的工程细节对应 src/relax-output-schema.ts。背景是Mastra 会用工具的outputSchema校验每次工具执行结果校验不通过就丢弃数据并替换为错误。而 Composio 后端下发的输出 Schema 是严格风格的可选字段被声明为非空原始类型{ type: string }对象带有additionalProperties: false。但真实第三方 APILinear、Notion、Jira、Slack……经常为未设置的字段返回null偶尔还会多返回键。于是严格校验会拒绝完全正常的响应导致模型看到的工具输出被截断对应 issue #3047。因此 Provider 在把输出 Schema 交给mastra/schema-compat之前会先递归执行四类只放宽only-widen的转换转换说明类型节点可空化type: string→type: [string, null]已有数组则追加null且不重复允许额外键对象上的additionalProperties: false或未声明改为trueenum/const放宽向enum追加nullconst变成双成员可空enum删除required真实 API 会整个省略未设置的字段要求任何字段都会误伤合法响应这四类改动只会扩大可校验通过的范围原本能通过的载荷转换后依然通过因此对已合法的输出没有任何行为改变。实现上对items、anyOf、oneOf、allOf、prefixItems、properties、$defs等子 Schema 位置会递归处理且刻意不触碰not关键字——not否定其子 Schema放宽内部 Schema 反而会缩小父级接受范围违背只放宽的不变式。完整的逐条断言见 test/relax-output-schema.test.ts其中还包括输入 Schema 不被原地修改的不可变性测试。五、严格模式Strict mode对齐 OpenAI 结构化输出README 中单独成节的功能是严格模式一行开关即可启用const composio new Composio({ provider: new MastraProvider({ strict: true }), });从源码看strict是构造函数可选参数默认false对应测试new MastraProvider()时strict false。开启后wrapTool会对每个工具的输入 Schema 调用toStrictJsonSchema来自composio/core做规范化以适配 OpenAI 的结构化输出约束所有属性都进入required可选属性也保留在列表中但类型被拓宽为可接受null如type: [string, null]对象是封闭的additionalProperties: false执行前的null清理严格模式下可选参数以必填但可空的形式出现所以模型补的null表示省略。执行前通过omitNullToolArguments把工具自身 Schema 不接受null的参数剔除而工具 Schema 本身就接受null的字段则原样保留显式的null——测试用例验证了cfg.note: null被剔除、clearable: nullSchema 接受 null被保留的行为无法表达的工具保持原样接受任意键的对象如additionalProperties为 Schema 的 map 类型、allOf、prefixItems、未解析的$ref等无法用严格结构化输出表达的 Schema会保留原始 Schema 并打印一条警告日志警告内容包含工具 slug 与不支持原因。测试test/mastra.test.ts 的 strict mode 分组对可选属性变必填可空、map 类型保留原 Schema、严格模式下的批量包装等行为都有断言。六、$ref 容错悬空引用不崩溃JSON Schema 中常见的$ref指向#/$defs/...Provider 会在交给 schema-compat 之前先调用dereferenceJsonSchema内联这些内部引用。原因是上游的mastra/schema-compat依赖 AJV 编译 Schema遇到未解析的$ref会直接拒绝编译而 JSON Schema → Zod 转换器会把$ref类型的属性静默降级成宽容的anyOf丢失$defs中的类型信息。现实中的坑更隐蔽部分 Composio 后端下发的工具如GMAIL_FETCH_EMAILS会在输出 Schema 里引用#/$defs/...却从未声明$defs块对应 issue #3307。严格解引用在这种悬空引用上会抛异常导致tools.get直接崩溃。Provider 的处理方式是解引用时使用onUnresolved: sentinel悬空分支被替换为宽容的对象 Schema{ type: object, additionalProperties: true }工具照常可用每个(toolSlug, ref)组合只记录一次警告避免同一 SDK 会话内反复包装同一工具刷爆日志警告中的 slug、toolkit、ref 全部经过JSON.stringify转义中性化换行、ANSI 转义与控制字节防止伪造日志行或污染终端CWE-117 缓解同时通过telemetry.sendMetric发送一条聚合信号函数名composio.mastra.wrapTool.danglingRef用于向维护团队反馈上游 API 修复的优先级COMPOSIO_DISABLE_TELEMETRYtrue可关闭网络错误会被静默吞掉。对应的回归测试 test/mastra-dangling-defs.test.ts 覆盖了悬空输出/输入$ref不抛异常、去重后的单次警告、恶意转义字节被清理、遥测事件按(toolSlug, ref)去重、可解析的$ref保留真实类型信息等场景test/mastra-ref.test.ts 则使用真实mastra/schema-compat验证$defs与 Draft-7definitions中的类型信息不被降级、最终 Schema 中不残留$ref。七、MCP 支持与扩展接口MastraProvider还实现了 MCPModel Context Protocol相关接口。wrapMcpServerResponse把 MCP URL 响应转换为 Mastra 期望的服务名 → URL映射wrapMcpServerResponse(data: McpUrlResponse): MastraUrlMap { return data.reduce((acc, item) { acc[item.name] { url: item.url }; return acc; }, {}); }对应测试覆盖了空数组、单元素、重复服务名后者覆盖前者、URL 原样保留含端口、查询串、片段等边界。这意味着你可以在 Mastra 应用中把 Composio 会话内的 MCP 服务统一接入由 Provider 负责格式适配。八、测试体系与验证方式该包内置了完整的 vitest 测试套件test/README.md 有总览覆盖 Provider 属性、wrapTool/wrapTools各种边界缺描述、缺入参、缺出参、空上下文、畸形 Schema、executeTool与 modifiers、严格模式、MCP 转换与错误处理。运行方式# 在包目录内 npm test # 在工作区根目录pnpm monorepo pnpm test --filtercomposio/mastra两个关键测试文件刻意不 mockmastra/schema-compat而是用真实依赖验证 AJV 编译与$ref解引用行为这正是悬空引用不崩溃、可解析引用不降级两项保证能长期成立的底气。九、实战要点与注意事项综合 README、源码与测试在实际项目中建议留意以下几点密钥安全COMPOSIO_API_KEY与 LLM 密钥只应在服务端使用切勿写入前端代码或提交到版本库。按用户建会话composio.create(user_123)中的用户标识用于隔离连接账户与执行上下文多用户应用务必使用各自独立的标识避免工具权限串号。默认非严格、按需开启严格默认行为下可选参数保持非必填对大多数 LLM 兼容性最好只有当你的模型使用 OpenAI 结构化输出且需要强约束参数形状时才开启strict: true。注意严格模式无法表达的 Schemamap 类型、allOf、悬空$ref等会自动回退到原始 Schema 并打警告属预期行为。输出 Schema 已内置宽松化无需自己放宽输出校验——Provider 已经处理了第三方 API 返回null和多余键的问题保证合法响应不被截断。模型输入容错即使模型把工具入参输出成 JSON 字符串Provider 也会自动归一化后再执行无需在 Agent 层做额外防御。依赖版本确保composio/core、mastra/core、zod满足 package.json 中的 peer 约束Node 运行时不低于 22.22.3。至此从安装配置、最小示例到 Schema 双通道处理、$ref容错与 MCP 适配composio/mastra的完整工作方式已经清晰。你可以基于本指南在自己的 Mastra 应用中把 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），仅供参考