给每个用户一把“专属钥匙“：Composio Tool Router 隔离 MCP 会话完全讲解

给每个用户一把专属钥匙Composio Tool Router 隔离 MCP 会话完全讲解【免费下载链接】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 应用的人都遇到过这个麻烦模型想调用外部工具但工具背后连着真实账户。A 用户的邮件工具绝不能让 B 用户碰到每个用户能用哪些功能、授权走到哪一步都得有人管。Composio 的 Tool Router 就是干这件事的——它帮你为每个用户开一个隔离的 MCPModel Context Protocol会话在会话级别精细圈定可用的 Toolkit 和 Tool并把多套 OAuth 授权流程统一收口。先建立心智模型会话就是一次性保险柜把 Tool Router 想成酒店前台每位客人用户登记时领一张房卡房卡只能开自己的房间房间里能用什么电器、能不能用保险柜都在入住登记时写死。一张房卡 一个 session。你调用composio.create(userId, config)时config 就是入住登记表哪些 Toolkit 能进房间、哪些工具拔掉插头、账户用谁的授权全部在这里定。而每个会话自带一个 MCP 服务器 URL任何 MCP 客户端拿 URL 加请求头就能把房间里的工具搬进自己的 AI 框架。5 行代码拿到第一个隔离会话先装包npm install composio/core0.4.0然后是最小可运行示例import { Composio } from composio/core; const composio new Composio(); const session await composio.create(user_123, { toolkits: [gmail], }); console.log(session.mcp.url);拿到session.mcp.url后把它连同session.mcp.headers交给任意 MCP 客户端这个用户就能访问 Gmail 工具了。注意两点一是toolkits传的是 slug 字符串数组等价于只允许这些 Toolkit 进会话二是走 MCP 路径时不需要给Composio构造函数传 provider。场景一精确圈定这个用户能碰哪些工具create()的配置里控制工具范围的主要是三个字段。Toolkit 级开关——toolkits支持三种写法toolkits: [gmail, slack] // 只启用这些 toolkits: { enable: [gmail] } // 显式启用 toolkits: { disable: [calendar] } // 全开唯独禁掉日历Tool 级开关——tools以 Toolkit slug 为 key细化到单个工具const session await composio.create(user_123, { toolkits: [gmail, slack], tools: { gmail: [gmail_fetch_emails, gmail_send_email], // 白名单 // 也可以写成 { disable: [gmail_delete_email] } 黑名单 }, });行为标签——tags用行为提示过滤工具全局生效也可在单个 Toolkit 下覆盖。可用值只有四个readOnlyHint只读、destructiveHint会改数据、idempotentHint可重试、openWorldHint开放世界。字段控制粒度常见坑toolkits整个 Toolkit数组形式 enable 白名单toolsToolkit 内单个工具enable/disable/tags三选一同时传多个会在 Zod 校验时直接报错tags跨 Toolkit 的行为维度适合这个用户只做只读操作这类需求另外两个绑定字段值得知道authConfigs把 Toolkit 钉到某个认证配置 ID例如公司邮箱和个人邮箱用不同的ac_xxxconnectedAccounts把 Toolkit 钉到某个已连接账户 ID。看源码可知connectedAccounts的值传字符串会被 SDK 自动包成单元素数组再发给后端。场景二用户还没授权会话怎么不卡死这是 Tool Router 相比自己拼 OAuth最大的省心点。默认做法manageConnections默认开启传true或不传都行会话会带上管理连接的 meta tools由模型在对话中自动引导用户完成授权const session await composio.create(user_123, { toolkits: [gmail, slack], manageConnections: { enable: true, callbackUrl: https://your-app.com/auth/callback, waitForConnections: true, // 等待用户完成认证后再继续 }, });waitForConnections是 v0.4.0 新加的会话会阻塞执行直到所有必需连接建立完成。适合授权没走完就别开始干活的批处理或定时任务场景。手动做法如果关闭manageConnections或就是想自己控制时序用authorize()串联const request await session.authorize(gmail, { callbackUrl: https://your-app.com/auth/callback, }); console.log(request.redirectUrl); // 把用户导向这个 URL const account await request.waitForConnection(); // 阻塞到连接成功授权完可以用session.toolkits()轮询状态返回每个 Toolkit 的connection.isActive、授权配置 ID、账户状态支持按 slug 过滤和 cursor 分页。场景三把会话接到你正在用的 AI 框架接入分两条路选哪条取决于你要不要框架原生工具对象。MCP 路径多数框架推荐客户端直接连session.mcp.url零 provider。以 Vercel AI SDK 为例import { experimental_createMCPClient as createMCPClient } from ai-sdk/mcp; const client await createMCPClient({ transport: { type: http, url: session.mcp.url, headers: session.mcp.headers, // 已含 x-api-key 认证头 }, }); const tools await client.tools(); // 直接喂给 streamTextLangChainMultiServerMCPClient、OpenAI Agents SDKhostedMcpTool、Claude Agent SDKmcpServers选项都是同样的套路URL headers。可运行的完整示例在 ts/examples/tool-router/ 目录里。Provider 路径只有当你想调用session.tools()拿到框架格式化的工具对象时才需要 provider构造Composio时传入即可。仓库在 ts/packages/providers/ 下提供了 vercel、openai、openai-agents、langchain、claude-agent-sdk、anthropic、mastra、llamaindex 等十余种实现import { Composio } from composio/core; import { VercelProvider } from composio/vercel; const composio new Composio({ provider: new VercelProvider() }); const session await composio.create(user_123, { toolkits: [gmail] }); const tools await session.tools(); // Vercel AI SDK 格式mcp.headers里会自动注入构造时传入的apiKey作为x-api-key请求头类型限定为http | sse两种。场景四往会话里塞自己的本地工具experimental.customTools允许你把进程内工具注册进会话和 Composio 远程工具混编。三种形态独立工具无认证experimental_createTool(GREP, { inputParams: z.object({...}), execute })扩展工具加extendsToolkit: gmail继承 Gmail 的认证execute的第二个参数ctx提供ctx.execute()复用远程工具自定义工具箱用experimental_createToolkit把多个无认证工具打包。const session await composio.create(user_123, { toolkits: [gmail], experimental: { customTools: [grepTool, importantEmailsTool], }, }); await session.execute(GREP, { pattern: TODO, path: /src });两个硬约束绑定了自定义工具的会话必须传 userId否则构造器直接抛错自定义工具也会参与session.search()的语义搜索不用你手动注册。如果你想深入底层本地/远程分流是怎么工作的模型一次批量调多个工具时SDK 的routeMultiExecute()会解析COMPOSIO_MULTI_EXECUTE_TOOL的tools[]数组本地工具在进程内并行跑远程工具并行发后端最后按原始顺序合并结果并给出total_count/success_count/error_count统计。execute()对两种工具返回完全相同的{ data, error, logId }结构你的代码不用关心工具住在哪。沙箱workbench是什么每个会话默认带一个远程代码执行沙箱对应workbench配置源码里新别名是sandbox两者不能同时传。关键开关enable: false会整体关闭COMPOSIO_REMOTE_WORKBENCH与COMPOSIO_REMOTE_BASH_TOOLautoOffloadThreshold控制响应超过多少字符自动卸载进沙箱sandboxSize提供 standard1 vCPU/1GB默认、medium、large、xlarge 四档算力。注意改sandboxSize会重建沙箱内存文件系统清空但/mnt/files/持久目录保留。会话还能后补货。session.update()支持部分更新只改传入字段。三个进阶配置值得一知sessionPreset: direct_tools把所有通过过滤的工具直接平铺进session.tools()和 MCP 列表并默认关掉 search 等 meta tools工具集合固定、想省搜索步数时很好用preload: { tools: [...] }预加载指定工具免去搜索multiAccount开启多账户模式每 Toolkit 最多 10 个账户之后execute()可传options.account指定账户。执行前后加钩子。v0.4.0 的会话级 modifiers 携带sessionId上下文modifySchema改发给模型的 schemabeforeExecute改参数afterExecute改结果。下图是afterExecute的典型用法——把完整响应裁剪成模型只需要的小字段会话自带虚拟文件系统。session.experimental.files提供upload支持路径、URL、File、buffer、list、download、delete适合让 Agent 在会话内存取中间产物。完整的挂载说明见 ts/docs/api/ 下的 Tool Router Session Files 文档。常见坑位 FAQQMCP 路径为什么不用 providersession.tools()却报需要 provider两条路设计如此MCP 客户端自己从服务器拉工具定义tools()要在本地生成框架格式的工具对象必须由 provider 的wrapTools()完成。只走 MCP 就永远不用装 provider 包。Qtools里给同一个 Toolkit 同时写了enable和tags会怎样直接抛校验错误。每个 Toolkit 的 tools 配置里enable/disable/tags只能出现一个——这是 schema 的superRefine强制的不是静默忽略。Q重启服务后会话还在吗在只要保存session.sessionId。用composio.use(sessionId)拿回会话MCP URL 可继续用composio.create和composio.use分别是sessions.create/sessions.use的别名。删会话用session.delete()或composio.sessions.delete()删不存在的会话会拿到后端 404。QmanageConnections: false和true差在哪true默认时模型可通过 meta tools 自己发起并管理连接false时 SDK 完全不代管你必须自己调authorize()并处理回调适合把授权流程嵌进自家产品页面的团队。Q改sandboxSize后会丢数据吗内存文件系统会丢沙箱整体重建但/mnt/files/下的持久化文件保留。重要产物记得落在持久目录。速查表create()配置项一览配置项默认值一句话说明toolkits不限数组 白名单{enable}/{disable}显式控制tools不限按 Toolkit 细管单个工具enable/disable/tags 三选一tags无按行为标签过滤四个 Hint 可选可被 tools 覆盖authConfigs默认认证Toolkit → 认证配置 ID 的映射connectedAccounts自动选Toolkit → 已连接账户 ID字符串会自动包成数组manageConnectionstrue含callbackUrl与 v0.4.0 新增的waitForConnectionsworkbench/sandbox沙箱开启二者互斥可关、调 offload 阈值、选算力档位sessionPreset默认 meta toolsdirect_tools平铺全部工具、关闭辅助 meta toolspreload无预加载工具 slug 列表或allmultiAccount关闭开启后每 Toolkit 可绑 2~10 个账户experimental.assistivePrompt无传 IANA 时区生成时区感知提示词experimental.customTools无本地工具/扩展工具会话必须有 userId会话方法一览方法用途session.tools(modifiers?)获取框架格式化工具需 providersession.execute(slug, args)执行工具本地与远程统一返回{ data, error, logId }session.search({ query })按用例语义搜工具含自定义工具session.authorize(toolkit, opts?)发起授权支持 callbackUrl、SHARED 连接session.toolkits(opts?)查连接状态支持过滤与分页session.proxyExecute(params)借会话账户代理调第三方 APIsession.update(partial)部分更新会话配置session.experimental.files会话虚拟文件系统的上传/下载/列表/删除写在最后Tool Router 的本质是把谁能用什么、用谁的授权从散落的 if-else 收敛成一张会话配置表create()定规则MCP URL 发钥匙execute()/search()/authorize()管日常update()管变通。对新手建议路径是——先跑通最小示例拿到 MCP URL接进你现有的 AI 框架再按业务收紧toolkitstools白名单最后才碰沙箱、预加载、自定义工具这些进阶项。仓库里 ts/examples/tool-router/ 下的示例脚本MCP、preload、direct-tools 各一套和 ts/docs/api/tool-router.md 的完整 API 文档可以直接对着继续往下挖。【免费下载链接】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），仅供参考