企业官网建设流程全解析

3分钟给每个用户建一个隔离的工具会话：Composio 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 Agent 产品时，「让 Agent 碰用户自己的 Gmail 和 GitHub」是最先卡住人的功能：你不能把上千个工具全暴露给每个用户，不能把张三的凭证串到李四头上，还得有一个统一入口管理这些外部能力。Composio Tool Router 就是为此而生的会话管理能力——它为每位用户创建一套隔离的 MCP 会话（MCP 即 Model Context Protocol，大模型与外部工具之间的标准通信协议），并按用户维度精细控制工具范围、授权流程和执行入口。

三步创建你的第一个隔离 MCP 会话 🚀

先装 SDK，并设置好你的 API Key（从 Composio 控制台获取）：

npm install @composio/core export COMPOSIO_API_KEY=sk_your_key

上面两条命令分别安装核心包并把密钥放进环境变量，SDK 会默认读取它。

然后写一个最小可运行脚本（需要支持顶层 await 的运行时，如 Bun 或 Node 22+）：

import { Composio } from '@composio/core'; const composio = new Composio(); const session = await composio.create('user_123', { toolkits: ['gmail'], mcp: true, }); console.log(session.sessionId); // 会话唯一 ID，存进你的数据库 console.log(session.mcp.url); // 该会话专属的 MCP 端点 console.log(session.mcp.headers); // 预置好的认证请求头

跑通后你手里有三样东西：一个与会话绑定的sessionId、一个只暴露 Gmail 工具的 MCP 端点、以及已经塞好x-api-key请求头的认证头。任何支持 MCP 的客户端（Cursor、Claude Desktop、自研 Agent 都一样）拿这个 URL 就能连上，会话在后台控制台里对应一条可查的记录：

通过 MCP 客户端连接会话时，不需要给 Composio 构造函数传 provider；只有调用session.tools()获取框架专用工具对象时才需要传（provider 是把工具翻译成某个 AI 框架内部格式的适配器，比如 VercelProvider）。

看懂隔离机制：一个 MCP URL 如何圈出权限与凭证边界

调用create()时，SDK 先对配置做严格校验（比如tools里某些互斥选项只允许出现一个），再连同用户 ID 发给后端；后端据此创建一个与该用户绑定的会话，并分配专属 MCP 端点。此后所有操作——搜工具（search）、执行工具（execute）、发起授权（authorize）——都挂在这个会话上进行。会话就是权限边界加凭证边界：模型只能看到配置允许的工具，后端在执行时也会根据会话解析出「这个用户自己的」已连接账户，用户 A 的会话绝不会调用用户 B 的凭证。SDK 再把你的 API Key 以x-api-key头注入mcp.headers，客户端直接可用。如果会话里还绑了本地自定义工具，执行时 SDK 会自动分流：本地工具在进程内跑，远程工具并行发往后端，最后按原始顺序合并结果。

给每个用户画好权限围栏：toolkit 与 tool 两层过滤

默认会话会把搜索、批量执行等「meta tools」加上允许范围内的工具一起交给模型，工具多时既费 token 又放大风险。权限管控的思路是两层过滤：外层toolkits决定哪些应用可用，内层tools决定每个应用里哪些动作可用，另外用tags按行为特征（只读、破坏性、幂等、开放世界）做全局筛选。

const session = await composio.create('user_123', { toolkits: ['gmail', 'slack'], tools: { gmail: { enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'] }, slack: { disable: ['SLACK_DELETE_MESSAGE'] }, }, tags: ['readOnlyHint'], });

这段代码给同一用户开了 Gmail 和 Slack 两个应用：Gmail 白名单只留收发两件事，Slack 黑名单砍掉删消息，再叠加全局只读标签，模型在这个会话里基本做不出「删库」操作。

需要注意两点。第一，tools的每个 toolkit 里enable/disable/tags三选一，多传会被 SDK 的校验直接拒绝：

tools配置中每个 toolkit 只能出现 enable、disable、tags 三者之一，同时传多个会在校验阶段抛错——这是刻意的，避免「白名单里又留了个黑名单漏洞」的歧义。

第二，如果工具参数本身想裁剪（比如删掉page参数、把size改成必填），可以在拿工具时传modifySchema修饰符，在 schema 进模型前做变换，效果如下图：

创建之后权限还可以热改：session.update()只改传入的字段（如追加toolkits: { enable: ['github'] }），未传字段保持不变，无需重建会话。

让用户授权自己的账户：Gmail 连接的两条路 🔑

权限围栏解决「能用什么」，授权解决「用谁的身份」。Tool Router 提供两条路：

自动路（默认）：manageConnections默认为true，会话里自带连接管理 meta tools，用户可以在对话中被引导完成 OAuth；给它配callbackUrl指定回调地址，再加waitForConnections: true后，会话会阻塞等待，直到所有必需连接都建立成功才放行——适合「先连账户再开工」的 onboarding 流程。

手动路：关掉自动管理，自己拿authorize()串流程，拿到重定向 URL 发给用户即可：

const session = await composio.create('user_123', { toolkits: ['gmail'], manageConnections: false, }); const request = await session.authorize('gmail', { callbackUrl: 'https://example.com/auth/callback', }); console.log(request.redirectUrl); // 发给用户完成 OAuth const account = await request.waitForConnection(); console.log(account.id, account.status);

这段代码完整走了一遍手动授权：发起 Gmail 连接、把链接交给用户、挂起等待直到授权完成并拿到账户 ID 与状态。

连接后随时可用session.toolkits()核对状态，支持按 toolkit 过滤与分页：

const { items } = await session.toolkits(); for (const tk of items) { console.log(tk.slug, tk.connection?.isActive ? 'active' : 'not connected'); }

一个用户要连两个 Gmail（工作 + 个人）时，创建会话加multiAccount: { enable: true, maxAccountsPerToolkit: 3 }，execute()就能通过options.account指定用哪个账户。

交互式应用保持manageConnections: true默认值最省心；只有当你需要完全自定义授权 UI（比如自己的品牌化授权页）时，才关掉它改用authorize()。

把会话接进 AI 框架：Vercel AI SDK 的两条路

与 Vercel AI SDK 集成有两条路，差别只在「工具从哪来」，会话本身写法完全一样。

Provider 路：让 SDK 把工具翻译成 AI SDK 的原生工具对象，需要传 provider：

import { openai } from '@ai-sdk/openai'; import { Composio } from '@composio/core'; import { VercelProvider } from '@composio/vercel'; import { stepCountIs, streamText } from 'ai'; const composio = new Composio({ provider: new VercelProvider() }); const session = await composio.create('user_123', { toolkits: ['gmail'] }); const result = await streamText({ model: openai('gpt-4o-mini'), prompt: 'Summarize my latest email', stopWhen: stepCountIs(10), tools: await session.tools(), }); console.log(await result.text);

这段代码创建会话、取出框架专用工具、直接喂给streamText，模型会自主决定调 Gmail 的哪个工具并流式返回结果，与仓库示例 ts/examples/tool-router/src/index.ts 的写法一致。

MCP 客户端路：不加 provider，MCP 客户端从会话端点自己拉工具，更薄、更通用：

import { openai } from '@ai-sdk/openai'; import { createMCPClient } from '@ai-sdk/mcp'; import { stepCountIs, streamText } from 'ai'; import { Composio } from '@composio/core'; const composio = new Composio(); const session = await composio.create('user_123', { toolkits: ['gmail'], mcp: true }); const client = await createMCPClient({ transport: { type: 'http', url: session.mcp.url, headers: session.mcp.headers }, }); const result = await streamText({ model: openai('gpt-4o-mini'), prompt: 'Summarize my latest email', stopWhen: stepCountIs(10), tools: await client.tools(), }); console.log(await result.text);

这段代码把session.mcp.url和认证头交给 MCP 客户端，工具列表直接由会话端点提供，完整对照可看示例 ts/examples/tool-router/src/mcp.ts。

其余框架套路相同，都是「MCP 端点 + 头」的三句话版本：LangChain 用@langchain/mcp-adapters的MultiServerMCPClient指向会话 URL 后getTools()；OpenAI Agents SDK 用hostedMcpTool({ serverUrl, headers })；Claude Agent SDK 则直接把会话写进options.mcpServers。三条路都不需要 provider。

收尾：速查表与五条老手建议

五条建议：

1. 存 ID、复用会话：sessionId落到自己的数据库或缓存，请求进来先use()，没有再create()，别每次请求都建会话。
2. 最小权限默认值：新会话默认白名单（enable）起步，确有需要再放开destructiveHint类工具，比事后删黑名单安全。
3. MCP 路省一个依赖：能用 MCP 客户端就用 MCP 客户端，少装 provider 包，升级框架时不用动工具层。
4. 执行前查一眼连接：toolkits()里connection.isActive为 false 时，先发authorize()流程，别等工具执行报 401。
5. 多账户显式选：开了multiAccount后，execute()传options.account明确指定账户，别让后端猜。

延伸阅读（仓库内相对路径）：

• ts/docs/api/tool-router.md：Tool Router 完整 API 文档，含框架集成与授权流程
• ts/examples/tool-router/：可直接运行的示例工程，覆盖 MCP、授权、多账户、direct-tools 预置等场景
• ts/packages/core/src/models/ToolRouterSession.ts：会话类源码，本地/远程工具分流逻辑都在这
• ts/docs/api/：会话文件挂载（files）等周边文档目录

【免费下载链接】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