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_KEYsk_your_key上面两条命令分别安装核心包并把密钥放进环境变量SDK 会默认读取它。然后写一个最小可运行脚本需要支持顶层 await 的运行时如 Bun 或 Node 22import { 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 的原生工具对象需要传 providerimport { 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 客户端路不加 providerMCP 客户端从会话端点自己拉工具更薄、更通用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。收尾速查表与五条老手建议配置 / 方法作用典型使用时机composio.create(userId, config)为用户创建隔离会话新用户首次进入composio.use(sessionId)恢复已有会话对象跨请求复用避免重复创建toolkits: [...] / { enable } / { disable }应用级启用/禁用粗粒度权限tools按 toolkit 配工具白名单/黑名单/标签细粒度权限tags全局行为过滤readOnlyHint 等四种只读场景manageConnections自动连接管理可配callbackUrl、waitForConnections交互式 onboardingsession.authorize(toolkit, opts)手动发起 OAuth返回重定向 URL自定义授权 UIsession.toolkits(opts)查询连接状态支持过滤与分页执行前预检、状态展示session.execute(slug, args)会话内执行工具自定义工具进程内跑不经过 LLM 的直调session.search({ query })按语义用例搜工具返回 schema 与引导大工具集场景session.update(config)部分更新会话配置未传字段不变权限热更新session.delete()删除会话立即可检索性消失用户注销/清理connectedAccounts/authConfigs会话直接绑定指定已连接账户/认证配置多租户指定身份multiAccount多账户模式每 toolkit 2~10 个用户有多个同平台账号workbench推荐写sandbox代码执行沙箱enable、sandboxSize四档规格等需要大响应卸载/代码执行sessionPreset: direct_toolspreload跳过 meta tools直接暴露全部允许工具工具集事先已知的低延迟场景session.experimental.files会话级虚拟文件系统上传/下载/删除文档处理类 Agent五条建议存 ID、复用会话sessionId落到自己的数据库或缓存请求进来先use()没有再create()别每次请求都建会话。最小权限默认值新会话默认白名单enable起步确有需要再放开destructiveHint类工具比事后删黑名单安全。MCP 路省一个依赖能用 MCP 客户端就用 MCP 客户端少装 provider 包升级框架时不用动工具层。执行前查一眼连接toolkits()里connection.isActive为 false 时先发authorize()流程别等工具执行报 401。多账户显式选开了multiAccount后execute()传options.account明确指定账户别让后端猜。延伸阅读仓库内相对路径ts/docs/api/tool-router.mdTool 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 3分钟给每个用户建一个隔离的工具会话：Composio Tool Router 实战指南
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_KEYsk_your_key上面两条命令分别安装核心包并把密钥放进环境变量SDK 会默认读取它。然后写一个最小可运行脚本需要支持顶层 await 的运行时如 Bun 或 Node 22import { 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 的原生工具对象需要传 providerimport { 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 客户端路不加 providerMCP 客户端从会话端点自己拉工具更薄、更通用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。收尾速查表与五条老手建议配置 / 方法作用典型使用时机composio.create(userId, config)为用户创建隔离会话新用户首次进入composio.use(sessionId)恢复已有会话对象跨请求复用避免重复创建toolkits: [...] / { enable } / { disable }应用级启用/禁用粗粒度权限tools按 toolkit 配工具白名单/黑名单/标签细粒度权限tags全局行为过滤readOnlyHint 等四种只读场景manageConnections自动连接管理可配callbackUrl、waitForConnections交互式 onboardingsession.authorize(toolkit, opts)手动发起 OAuth返回重定向 URL自定义授权 UIsession.toolkits(opts)查询连接状态支持过滤与分页执行前预检、状态展示session.execute(slug, args)会话内执行工具自定义工具进程内跑不经过 LLM 的直调session.search({ query })按语义用例搜工具返回 schema 与引导大工具集场景session.update(config)部分更新会话配置未传字段不变权限热更新session.delete()删除会话立即可检索性消失用户注销/清理connectedAccounts/authConfigs会话直接绑定指定已连接账户/认证配置多租户指定身份multiAccount多账户模式每 toolkit 2~10 个用户有多个同平台账号workbench推荐写sandbox代码执行沙箱enable、sandboxSize四档规格等需要大响应卸载/代码执行sessionPreset: direct_toolspreload跳过 meta tools直接暴露全部允许工具工具集事先已知的低延迟场景session.experimental.files会话级虚拟文件系统上传/下载/删除文档处理类 Agent五条建议存 ID、复用会话sessionId落到自己的数据库或缓存请求进来先use()没有再create()别每次请求都建会话。最小权限默认值新会话默认白名单enable起步确有需要再放开destructiveHint类工具比事后删黑名单安全。MCP 路省一个依赖能用 MCP 客户端就用 MCP 客户端少装 provider 包升级框架时不用动工具层。执行前查一眼连接toolkits()里connection.isActive为 false 时先发authorize()流程别等工具执行报 401。多账户显式选开了multiAccount后execute()传options.account明确指定账户别让后端猜。延伸阅读仓库内相对路径ts/docs/api/tool-router.mdTool 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考