5 分钟搭好 Tool Router 隔离会话：为每个用户精准管控工具与授权

5 分钟搭好 Tool Router 隔离会话为每个用户精准管控工具与授权【免费下载链接】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做多用户 Agent 时最头疼的是一套工具和连接被所有人共享A 能翻到 B 的邮件工具列表也爆炸增长。Tool Router 按用户创建隔离的 MCP 会话让你在每个会话里精细管控可用的 Toolkit、单个工具和授权流程。10 分钟内你能完成创建会话、收窄工具范围、接入自己的 AI 框架。它解决什么问题Composio 把 1000 toolkit 接到 Agent但多用户产品还差两件事每个用户要有自己的账户连接且不该看到全量工具。Tool Router 把工具变成会话维度composio.create()为用户建一个隔离会话会话自带独立的 MCP 端点、连接状态和工具白名单工具调用都在会话上下文里执行。类比酒店房卡——每间房有自己的钥匙用户连接和设施清单工具范围入住创建会话时就配好。代价是会话的生命周期要你自己存和管。5 分钟上手npm install composio/coreimport { Composio } from composio/core; const composio new Composio(); // 为用户创建隔离会话只暴露 Gmail const session await composio.create(user_123, { toolkits: [gmail], mcp: true, }); console.log(session.sessionId); // 存起来之后用 composio.use() 复用 console.log(session.mcp.url); // 任意 MCP 客户端都能接拿到两样东西sessionId复用的钥匙和 MCP URL接入点。注意mcp: true它是类型层面的显式开关传了返回类型才暴露session.mcp不传时运行时端点仍在但 TS 查不到。构造Composio时传了apiKey的话SDK 会自动把它注入mcp.headers的x-api-keyMCP 客户端直接带上即可。按场景配置按用户隔离连接与配置create(userId, config)的第一个参数就是隔离边界配置、连接、文件挂载都绑定到这个 userId 的会话上。生产里推荐把sessionId存进 Redis 之类的存储下次请求用composio.use(sessionId)取回别每次重建——重建会丢连接状态。一个取舍会话绑定了自定义工具时复用必须重传配置见后文踩坑所以use()的入参和你的存储设计要配套。收窄工具范围Toolkit 级和工具级可以叠着用覆盖三种常见诉求const session await composio.create(user_123, { toolkits: { disable: [calendar] }, // 黑名单白名单直接写 [gmail, slack] tools: { gmail: [gmail_fetch_emails, gmail_send_email], // 数组等价于 enable slack: { disable: [slack_delete_message] }, }, tags: [readOnlyHint], // 全局只保留只读工具 });toolkits支持白名单数组、{ enable }、{ disable }三种形态。tools按 toolkit slug 逐工具控制其中enable/disable/tags每个 toolkit 只能出现一个Zod 联合类型强制三选一。全局tags可在单个 toolkit 上用{ tags: [...] }覆盖比如只让 Slack 走只读、Gmail 放开写操作。四个可用 tagreadOnlyHint、destructiveHint、idempotentHint、openWorldHint。锁定认证配置与既有连接多租户场景下同一个 toolkit 可能对应多个认证配置比如企业版 Gmail 和个人 Gmail用authConfigs和connectedAccounts显式钉死const session await composio.create(user_123, { toolkits: [gmail, github], authConfigs: { gmail: ac_gmail_work }, // 钉到指定认证配置 connectedAccounts: { github: ca_abc123 }, // 直接复用已有连接 manageConnections: { enable: true, callbackUrl: https://your-app.com/callback, waitForConnections: true, // v0.4.0 新增等用户完成认证再继续 }, });authConfigs决定用哪套认证走connectedAccounts决定用哪个已连好的账户非多账户模式下每个 toolkit 只允许一个。manageConnections默认开启由 meta tools 引导用户完成连接设为false时连接完全归你管需要手动authorize()。接入你的 AI 框架两条路走session.tools()要传 provider 换取框架格式化的工具对象走 MCP 客户端则只要 URL headers不需要 provider。框架接入方式需要 provider关键差异Vercel AI SDKsession.tools()或 MCP clienttools() 路径要MCP 路径不要streamText直接接 toolsLangChainMultiServerMCPClient不要httptransport mcp.headersOpenAI AgentshostedMcpTool不要托管 MCP传serverUrl headersClaude Agent SDKmcpServers配置不要原生type: http支持最主流的 Vercel AI SDK 走 provider 路径import { openai } from ai-sdk/openai; import { Composio } from composio/core; import { VercelProvider } from composio/vercel; import { streamText } from ai; const composio new Composio({ provider: new VercelProvider() }); const session await composio.create(user_123, { toolkits: [gmail] }); const tools await session.tools(); const { text } await streamText({ model: openai(gpt-4o-mini), prompt: Find my last email from gmail, tools, });其余框架都是把session.mcp.url和session.mcp.headers填进各自的 MCP 配置即可headers 里已经带了认证信息不要自己拼。授权与连接管理调用时机看场景manageConnections开启时 meta tools 会自己引导连接一般不用手动调关闭时或在 UI 里提供连接账户按钮的场景由你发起const req await session.authorize(gmail, { callbackUrl: https://your-app.com/auth/callback, }); console.log(req.redirectUrl); // 把用户重定向到这里完成授权 const connected await req.waitForConnection(); // 用户完成后 resolvecallbackUrl是 OAuth 流程完成后 provider 回跳的地址会话级配置会覆盖认证配置里的默认值。 v0.4.0 新增的waitForConnections: true改变的是阻塞语义会话在执行工具前会先触发一步等待连接直到所有必需连接建立才继续——适合先连好账户再干活的流程纯只读场景没必要开。授权后随时可以用session.toolkits()查各 toolkit 的isActive与连接账户状态也支持toolkits、isConnected、search过滤和分页。进阶修饰器、自定义工具、沙箱会话级修饰器v0.4.0 起 modifiers 带上sessionId跨用户跟踪工具执行const tools await session.tools({ beforeExecute: ({ toolSlug, sessionId, params }) { console.log([${sessionId}] 执行 ${toolSlug}); return params; }, });modifySchema改发给模型的 schema和afterExecute改执行结果同理适合加审计日志、参数校验和遥测。进程内自定义工具import { experimental_createTool } from composio/core; import { z } from zod/v3; const grep experimental_createTool(GREP, { name: Grep, description: Search files, inputParams: z.object({ pattern: z.string() }), execute: async () ({ matches: [] }), }); const session await composio.create(user_123, { toolkits: [gmail], experimental: { customTools: [grep] }, });自定义工具自动参与search()索引LLM 调用时在进程内执行同批远程工具并行发后端后按原序合并。想复用 Composio 的认证就用扩展工具声明extendsToolkit: gmailexecute里通过ctx.execute调远程工具。多个无认证工具可以用experimental_createToolkit打包后放customToolkits。沙箱开关与规格不想让会话跑代码就sandbox: { enable: false }代码执行类工具REMOTE_WORKBENCH、BASH会被整体移除。需要跑重活时sandbox: { sandboxSize: large }升到 4 vCPU / 4 GB默认 standard 是 1 vCPU / 1 GB另有 medium 和 xlarge 两档。注意换规格会重建沙箱内存文件系统清空只有/mnt/files/目录保留。另外autoOffloadThreshold可设大响应自动卸载进沙箱的字符阈值。容易踩的坑⚠️ 没传 provider 就调session.tools()——它要靠 provider 把工具格式化成你的框架能吃的形状不传会直接抛错。不想引 provider 就走 MCP 客户端路径那是零 provider 的。⚠️sandbox和workbench同时传——二者是同一配置的新旧别名SDK 在边界直接抛ValidationErrorresolveToolRouterSandboxConfig强制二选一。新代码用sandbox。create()不传{ mcp: true }返回类型变成SessionWithoutMcp编辑器里session.mcp全是红的。端点本身在运行时存在但类型检查过不去属于白忙一场。同一个 toolkit 的tools配置里同时写enable和disable——三选一不是建议而是硬校验多传一个字段create()就失败。要启用 A 禁用 B拆成两个 toolkit 配置或用 tags 覆盖。composio.use(sessionId)复用会话时忘了重传customTools——自定义工具是内联在会话配置里的use()不携带就挂不回去自定义工具悄悄消失远端工具一切正常很难排查。延伸阅读会话实现execute / search / authorize / routeMultiExecute 本地远程分流ToolRouterSession.ts全部配置字段的 Zod schema 与默认值toolRouter.types.ts官方 API 文档tool-router.md可直接运行的示例工程authorize、preload、custom-tools、多框架接入tool-router 示例【免费下载链接】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），仅供参考