Composio SDK 工具修饰器Modifiers实战用 modifySchema / beforeExecute / afterExecute 精确掌控 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工具修饰器Modifiers是 Composio SDK 提供给开发者的一组生命周期钩子让你能够在工具被 LLM 使用之前、执行之中与执行之后分别改写其Schema定义、入参params与执行结果result。本文以仓库中的 ts/examples/modifiers 示例为骨架结合 modifiers.types.ts 的类型定义与 Tools.ts 的底层实现完整讲解如何通过这三种修饰器对 HackerNews 等工具进行细粒度定制读完即可在非 Agentic 与 AgenticVercel AI SDK两种模式下落地使用。一、示例定位Composio 工具修饰器的最小可运行演示ts/examples/modifiers/README.md 将本示例定位为“Composio SDK Vercel AI SDK”的集成演示核心诉求是让 AI 应用能够调用 HackerNews 数据。不过与仓库中其他示例不同该目录真正落地的 src/index.ts 是一份修饰器modifiers专题演示它没有实现流式聊天界面而是聚焦展示modifySchema、beforeExecute、afterExecute三个钩子在“非 Agentic”与“Agentic”两种 Provider 模式下的用法并以console.log(tools)输出最终装配好的工具对象供开发者直接观察。目录结构非常精简ts/examples/modifiers/ ├── README.md # 示例说明本文所述关联文档 ├── package.json # 依赖与运行脚本 ├── tsconfig.json # TypeScript 配置 └── src/index.ts # 修饰器演示源码从 package.json 可以看到示例依赖composio/core核心 SDK与composio/vercelVercel 集成并通过catalog:引用 workspace 中的ai与ai-sdk/openai运行脚本为bun src/index.tsBun 运行时类型检查脚本为tsc --noEmit -p ./tsconfig.json。二、环境准备与快速运行按照 README 的 Getting Started 章节需要准备前置条件说明Node.js建议使用最新 LTS 版本pnpmv10.8.0 及以上若使用bun src/index.ts则需 Bun 运行时Composio API Key用于初始化Composio客户端OpenAI API KeyAgentic 模式下供 Vercel AI SDK 调用 GPT-4 等模型启动步骤在当前仓库根目录下执行# 1. 进入示例目录 cd ts/examples/modifiers # 2. 安装依赖 pnpm install # 3. 复制环境变量模板 cp .env.example .env注意当前仓库中该示例目录没有随附.env.example文件README 中的.env配置项COMPOSIO_API_KEY、OPENAI_API_KEY需要你自行创建COMPOSIO_API_KEYyour_composio_api_key OPENAI_API_KEYyour_openai_api_key随后即可运行bun src/index.ts # 或 pnpm start pnpm typecheck # 仅做类型检查不输出产物三、两种 Provider 模式非 Agentic 与 Agentic 的修饰器差异src/index.ts 的核心价值在于用同一把工具HACKERNEWS_GET_USER对比展示了两种获取工具的方式1. 非 Agentic 模式—— 直接使用Composio客户端只能传入modifySchemaconst composio new Composio({ apiKey: process.env.COMPOSIO_API_KEY, }); const tools await composio.tools.get(default, HACKERNEWS_GET_USER, { modifySchema: ({ toolSlug, toolkitSlug, schema }) { if (toolSlug HACKERNEWS_GET_USER) { schema { ...schema, inputParameters: { type: object, properties: { ...schema.inputParameters?.properties, userId: { type: string, description: The user ID to get the user for, }, }, }, }; } return schema; }, }); console.log(tools);2. Agentic 模式—— 传入provider: new VercelProvider()后三种修饰器全部可用const vercel new Composio({ apiKey: process.env.COMPOSIO_API_KEY, provider: new VercelProvider(), // 将工具包装为 Vercel AI SDK 的 Tool }); const agenticTools await vercel.tools.get( default, { tools: [HACKERNEWS_GET_USER] }, { afterExecute: ({ toolSlug, toolkitSlug, result }) { // 修改执行结果 return result; }, beforeExecute: ({ toolSlug, toolkitSlug, params }) { // 修改执行参数 return params; }, modifySchema: ({ toolSlug, toolkitSlug, schema }) { // 修改工具 schema return schema; }, } ); console.log(agenticTools);注意两处关键差异源码中注释亦明确标注获取方式非 Agentic 模式第二个参数直接传工具 slug 字符串Agentic 模式则传{ tools: [HACKERNEWS_GET_USER] }对象能力边界非 Agentic 模式ToolOptions只支持modifySchema以及beforeFileUploadAgentic 模式AgenticToolOptions额外支持beforeExecute与afterExecute。这种差异并非人为约定而是由类型系统强制保证的详见下文第五节。四、modifySchema在工具暴露给 LLM 之前改写其定义modifySchema是TransformToolSchemaModifier类型的回调签名定义于 modifiers.types.tsexport type TransformToolSchemaModifier (context: { toolSlug: string; toolkitSlug: string; schema: Tool; }) Tool | PromiseTool;它的用途包括自定义输入/输出参数的描述、增删改参数以满足业务需求、改写工具名称与描述使其更贴合应用上下文、实现 Schema 的版本化或特性开关等。类型注释中给出了比示例更完整的改造样例例如为HACKERNEWS_GET_USER补充带校验约束的userId参数、includeSubmissions布尔开关与submissionLimit数值范围const modifySchema ({ schema, toolSlug, toolkitSlug }) { if (toolSlug HACKERNEWS_GET_USER) { return { ...schema, name: Get HackerNews User Profile, description: Retrieve detailed user information from HackerNews, inputParameters: { ...schema.inputParameters, userId: { type: string, description: The HackerNews username to retrieve information for, required: true, minLength: 2, maxLength: 15, pattern: ^[a-zA-Z0-9_-]$ }, submissionLimit: { type: number, description: Maximum number of submissions to return, default: 10, minimum: 1, maximum: 100 } } }; } return schema; };底层实现在 Tools.ts 中get、getRawComposioToolBySlug、getRawComposioTools等方法都会在拿到后端返回的原始工具后调用applySchemaModifiers将用户提供的modifySchema逐工具应用参见 Tools.ts 与 Tools.ts。测试 modifiers.test.ts 验证了两点单个工具获取时修饰器恰好被调用一次且回调收到的上下文包含toolSlug、toolkitSlug与schema批量获取多个工具TOOL1、TOOL2时修饰器会被逐个调用并分别改写name字段。五、beforeExecute / afterExecute拦截执行前后的请求与响应5.1 签名与参数两个执行期修饰器定义于 modifiers.types.tsexport type beforeExecuteModifier (context: { toolSlug: string; toolkitSlug: string; params: ToolExecuteParams; }) PromiseToolExecuteParams | ToolExecuteParams; export type afterExecuteModifier (context: { toolSlug: string; toolkitSlug: string; result: ToolExecuteResponse; }) PromiseToolExecuteResponse | ToolExecuteResponse;beforeExecute在工具真正执行前拿到即将发送的参数params典型场景包括注入认证参数/请求头、转换输入数据格式、追加上下文信息、做请求校验与归一化。类型注释给出了为所有请求追加X-API-Key、X-Request-ID等头部的完整示例。afterExecute在工具执行完成后拿到响应result含data、error、successful、logId等字段典型场景包括把响应转换为更便于下游消费的结构、统一错误处理与日志/埋点、为成功响应补充派生数据。5.2 底层调用链以 Session 执行为例在 Tools.ts 中可以看到beforeExecute的插入位置它在文件上传预处理applyFileUploadModifiers之后才被调用因此回调中看到的params与真正发送到 Tool Router 的参数完全一致修改后的参数会写入executePayload.arguments发出。执行完成后Tools.ts 再调用afterExecute将修饰器返回的结果作为最终ToolExecuteResponse返回给调用方。两条钩子均支持返回 Promise也支持抛错中断流程非函数类型的修饰器会触发ComposioInvalidModifierError见 Tools.ts 与 Tools.ts。5.3 测试佐证modifiers.test.ts 的 Execution Modifiers 用例验证了完整行为beforeExecute把参数{ limit: 5 }改写为{ limit: 10 }后mockClient.tools.execute收到的实际参数即为改写后的值L72-L104afterExecute在响应data上追加{ enhanced: true }最终result.data确认包含该字段L106-L131Combined Modifiers 用例L134-L296同时注入三种修饰器验证modifySchema改写描述与标签、beforeExecute触发埋点并注入tracking参数、afterExecute在成功结果上追加processed字段且不触发错误日志。六、类型体系修饰器如何随 Provider 自动区分能力修饰器能力的差异由 modifiers.types.ts 中的类型组合精确建模类型包含的钩子适用场景ToolOptionsL377-L383modifySchema、beforeFileUpload非 Agentic ProviderExecuteToolModifiersL412-L424beforeExecute、afterExecute、beforeFileUpload单次工具执行AgenticToolOptionsL587ToolOptions ExecuteToolModifiersAgentic ProviderOpenAI、Vercel 等SessionExecuteMetaModifiersL537-L549会话版beforeExecute/afterExecuteTool Router 会话执行SessionMetaToolOptionsL628ToolOptions SessionExecuteMetaModifiers会话工具获取其中的ProviderOptionsTProviderL658-L663利用条件类型当 Provider 是BaseAgenticProvider的子类如VercelProvider时自动解析为AgenticToolOptions否则解析为ToolOptions。这正是示例源码中“非 Agentic 只能传modifySchemaAgentic 可以传三个钩子”这一行为在编译期的保证——写错配置会直接得到类型错误示例源码注释中也留下了// what is the type error i am getting here?这类排查提示。七、进阶能力会话上下文修饰器与文件上传钩子除示例展示的三个钩子外同一类型文件中还定义了面向更复杂场景的修饰器1. 会话上下文修饰器beforeExecuteMetaModifier/afterExecuteMetaModifierL459-L498专用于 Tool Router 会话执行回调额外携带sessionId且params类型为MetaToolArguments非空的工具参数见 L431。helper 工具使用composiotoolkit slug预加载的应用工具使用各自 toolkit slug。典型用法是为会话内工具注入sessionMetadata、统计startTime或在结果上附加sessionInfo。2. 文件上传钩子beforeFileUploadModifierL204-L209在 SDK 读取并上传file_uploadable值之前触发context.source区分三种输入——path本地文件系统路径、urlhttp(s)://链接、fileFile对象此时path仅为文件名。返回字符串可替换上传输入重写路径、重定向 URL、把File换成本地路径上传返回false或抛错则中止上传并抛出ComposioFileUploadAbortedError。八、Agentic 模式内部机制VercelProvider 如何包装工具在 Agentic 模式下provider: new VercelProvider()负责把 Composio 工具翻译成 Vercel AI SDK 的tool()格式其核心逻辑在 ts/packages/providers/vercel/src/index.ts 的wrapTool方法L113-L169中Schema 规范化先通过deduplicateJsonSchemaRequiredArrays去重required数组若构造时开启strict: true再用toStrictJsonSchema将 JSON Schema 重写为结构化输出所需的严格形态——所有属性必填可选参数变为可空无法表达的构造会保留原 Schema 并输出警告日志Zod 转换jsonSchemaToZodSchema(dereferenceJsonSchema(...))把展开$ref后的 Schema 转为 Vercel AI SDK 所需的 Zod SchemaZod 转换器不跟随$ref因此需预先内联定义执行桥接execute回调里先用normalizeToolArguments处理模型偶尔把工具入参输出成 JSON 字符串的情况再调用composio.tools.executestrict 模式下还会用omitNullToolArguments剔除“值为 null 表示省略”的可选参数。wrapToolsL234-L239则把多个工具按 slug 组装成ToolSet字典返回。也就是说示例中vercel.tools.get(...)返回的agenticTools本质上就是可以直接喂给 Vercel AI SDK 的tools参数。九、最佳实践与注意事项综合示例、类型注释与源码实现总结以下实践要点按 Provider 类型选择钩子非 Agentic 场景如直接用 SDK 调用工具只有modifySchema需要beforeExecute/afterExecute时使用VercelProvider等 Agentic Provider编译期类型会给出正确约束。modifySchema是纯定义变换它发生在工具暴露给消费者之前不影响后端工具本身适合做参数裁剪、描述增强、命名定制注意保持返回对象为合法 JSON SchemainputParameters需为type: object结构。beforeExecute看到的是最终参数文件上传预处理先于它执行Tools.ts因此不要在前置钩子里重复处理文件上传逻辑。afterExecute的返回值即最终结果无论成功失败都会进入该钩子可统一在此处做日志埋点与错误增强修改data时建议基于result.data展开合并避免丢失successful、logId等字段。异步与错误处理三个修饰器都支持返回PromisebeforeExecute抛错会中止执行afterExecute抛错则中断结果返回可据此实现校验失败、鉴权刷新等分支逻辑。示例为最小演示README 中描述的 HackerNews 头条摘要GPT-4 流式响应属于该示例的设计目标实际 src/index.ts 以console.log输出装配后的工具对象为主用于快速验证修饰器链路落地完整 Agent 应用时可在其基础上接入ai与ai-sdk/openai构建流式对话接口。十、延伸阅读示例入口与运行脚本ts/examples/modifiers/src/index.ts、ts/examples/modifiers/package.json修饰器全部类型定义与示例代码ts/packages/core/src/types/modifiers.types.ts修饰器底层调用链实现ts/packages/core/src/models/Tools.ts修饰器单元测试ts/packages/core/test/tools/modifiers.test.tsVercel Provider 工具包装实现ts/packages/providers/vercel/src/index.ts【免费下载链接】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），仅供参考