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/core

import { 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-key，MCP 客户端直接带上即可。

按场景配置

按用户隔离连接与配置

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 放开写操作。四个可用 tag：readOnlyHint、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。

最主流的 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(); // 用户完成后 resolve

callbackUrl是 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: 'gmail'，execute里通过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可设大响应自动卸载进沙箱的字符阈值。

容易踩的坑

1. ⚠️ 没传 provider 就调session.tools()——它要靠 provider 把工具格式化成你的框架能吃的形状，不传会直接抛错。不想引 provider 就走 MCP 客户端路径，那是零 provider 的。
2. ⚠️sandbox和workbench同时传——二者是同一配置的新旧别名，SDK 在边界直接抛ValidationError（resolveToolRouterSandboxConfig强制二选一）。新代码用sandbox。
3. create()不传{ mcp: true }，返回类型变成SessionWithoutMcp，编辑器里session.mcp全是红的。端点本身在运行时存在，但类型检查过不去，属于白忙一场。
4. 同一个 toolkit 的tools配置里同时写enable和disable——三选一不是建议而是硬校验，多传一个字段create()就失败。要"启用 A 禁用 B"，拆成两个 toolkit 配置或用 tags 覆盖。
5. 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