Composio Tool Router 会话完整指南：创建、账号选择、生命周期与故障排查-二趣网

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

导读

本文以 Composio 知识库文章 docs/kb/articles/mcp-tool-router-sessions.md 为核心骨架，系统讲解 Tool Router 会话（Session）这一核心抽象：它是用户身份、工具与工具包访问、认证与账号选择、以及沙箱运行时资源（如沙箱文件）的作用域边界。你会掌握通过 SDK 或 REST API 创建会话、复用与删除会话、在多个连接账号间做精确选择、用工具包白名单/黑名单约束工具集、区分"会话运行时"与"模型记忆"等关键概念，并理解配置会话文档与 TypeScript SDK 源码（ts/packages/core/src/models/ToolRouter.ts）背后的实现机制，从而在生产环境中少踩 404、403 与账号错配的坑。

一、通过 SDK 或 API 创建 Tool Router 会话

Tool Router 不需要在控制台（Dashboard）中开启任何开关——会话只能通过 SDK 或 REST API 创建。TypeScript 侧的标准入口是composio.sessions.create(userId, config)，顶层composio.create(...)只是其向后兼容别名；这一点在 ts/packages/core/src/models/Sessions.ts 的类注释中有明确说明。

import { Composio } from '@composio/core'; const composio = new Composio({ apiKey: 'your_api_key' }); const session = await composio.sessions.create('user_123', { toolkits: ['gmail', 'github'], manageConnections: true, });

Python 侧等价写法为composio.sessions.create(user_id="user_123")。更多创建选项（工具包启停、工具级过滤、标签过滤、预加载、认证配置、账号选择、沙箱与计算规格）可参考 docs/content/docs/configuring-sessions.mdx。

从源码看，create()内部会解析ToolRouterCreateSessionConfigSchema，把toolkits、tools、tags、authConfigs、connectedAccounts、manageConnections、sandbox、multiAccount、preload等字段统一序列化后调用后端toolRouter.session.create接口（ts/packages/core/src/models/ToolRouter.ts）。也就是说，SDK 只是 REST API 的类型安全封装，两者的能力完全等价。

关于 403 的处置原则

如果收到真实的 403，或报错提示"Tool Router 未对该账号启用"，不要反复重试设置步骤。正确的做法是联系 Composio 支持进行账号级排查，并附上精确的错误响应体以及对应的请求或代码片段——这能显著加快问题定位。

二、会话生命周期：长期记录、复用与删除

2.1 会话是长期记录

Tool Router 会话是长期存在的记录，目前没有基于时间的过期机制。这与以下资源是相互独立、彼此不混淆的：

临时的 workbench 文件；
实时沙箱（live sandbox）的保留时长；
短暂的响应缓存（response-cache）生命周期。

也就是说，一个会话只要不被显式删除，就会一直保留其配置并可用于执行。

2.2 复用已有会话

复用已存储的 TypeScript 会话使用composio.use(sessionId)（即composio.sessions.use(id)，源码见 ts/packages/core/src/models/ToolRouter.ts）。use()对无自定义工具的会话走session.retrieve，对附带自定义工具的会话走session.attach，并返回与create()同构的ToolRouterSession对象。

const session = await composio.use('session_123'); // 或 composio.sessions.use('session_123')

2.3 删除会话

删除会话有两种等价方式：通过会话实例删除，或直接按 ID 删除。

await session.delete(); // 方式一：实例方法 await composio.sessions.delete(sessionId); // 方式二：按 ID 删除

删除立即生效。一个已被删除、不存在或不可访问的会话，在检索时返回404。需要特别注意的是：删除会话不会删除其关联的用户、认证配置（auth configs）或连接账号（connected accounts）——这些是项目/用户级资源，与会话相互独立。

三、多账号选择：用别名（alias）或账号 ID

当一个工具包（toolkit）下有多个连接账号时，建议为账号设置清晰、明确的别名，例如work、personal、primary，然后在执行时把别名作为account参数传入：

const result = await session.execute('GMAIL_SEND_EMAIL', { ... }, { account: 'work', // 对应连接账号的别名 });

如果没有别名，则使用连接发现（connection discovery）返回的系统生成账号 ID。SDK 层面，execute()的options.account会原样传递到后端执行参数中（ts/packages/core/src/models/ToolRouterSession.ts），仅用于直接执行 app 工具，helper/meta 工具会忽略该顶层字段或定义自己的账号选择字段。

两条纪律：

不要依赖模糊短语（如"office email"）去匹配账号，除非确实存在同名字的别名；
如果显式账号选择被禁用（requireExplicitSelection: false）且未提供account，会话会回退到第一个/默认账号。

注意：requireExplicitSelection是multiAccount配置的一部分，默认false；multiAccount.maxAccountsPerToolkit默认 5、取值范围 2～10（ts/packages/core/src/types/toolRouter.types.ts）。

四、会话用户必须与连接账号的用户一致

一个账号即使在控制台显示为 active，也可能在 Tool Router 中不可用——最常见的原因是会话使用的user_id与连接账号的归属用户不一致。

私有（PRIVATE）账号只对其拥有者用户解析；
显式共享（SHARED）或固定（pinned）的账号则遵循会话配置。

因此最佳实践是：创建会话与创建连接时使用同一个稳定用户 ID。如果某个账号必须被使用，请在会话配置中传入其允许的连接账号覆盖（connected-account override）。会话创建时通过connectedAccounts字段指定：

const session = await composio.create('user_123', { connectedAccounts: { gmail: ['ca_work_gmail'], github: ['ca_personal_github'], }, });

字符串形式的账号 ID 会被自动强制转换为单元素数组，向后兼容；多账号模式未启用时，每个工具包只允许一个账号（详见 docs/content/docs/configuring-sessions.mdx 的 Account selection 一节）。

五、连接账号选择是"活的"，除非被固定（pinned）

这是最容易踩坑的语义之一：

省略connectedAccounts：Tool Router 在执行时实时解析会话用户的当前 active 账号，包括会话创建之后才新连接的账号——即"活的"账号发现；
提供connectedAccounts：这是一个精确的工具包级覆盖（exact toolkit override），Tool Router不会为该工具包回退到其他 active 账号。

关键推论：会话创建之后新增的账号不会改变已经固定的选择。当固定账号需要更换时，必须更新（update/patch）或重建会话；想要实时账号发现，就省略该覆盖。

后端账号选择的完整优先级（来自 docs/content/docs/configuring-sessions.mdx）：

会话配置中的connectedAccounts覆盖；
authConfigs覆盖（在对应配置上查找或创建连接）；
之前为该工具包创建的 auth config；
使用 Composio 托管认证新建的 auth config；
否则报错（该工具包不存在 Composio 托管认证方案）。

在未显式选择且存在多个连接账号时，会话默认使用最近连接的那个账号。

六、工具包白名单/黑名单在连接查找之前强制执行

会话支持toolkits.enabled与toolkits.disabled两种过滤语义：

非空toolkits.enabled列表：除列表内工具包外，其余全部被拦截（白名单）；
toolkits.disabled列表：列表内工具包被拦截，其余保持可用（黑名单）。

关键点是这条限制在认证配置和连接账号查找之前检查——也就是说，工具包级别不通过，根本不会进入认证/连接的解析阶段。Python 侧写法：

session = composio.sessions.create( user_id="user_123", toolkits={"disable": ["exa", "firecrawl"]} # 或 {"enable": ["github", "gmail", "slack"]} )

TypeScript 侧等价于toolkits: { enable: [...] }/toolkits: { disable: [...] }，数组简写toolkits: ["github"]等价于enable。

遇到`[Session Restriction] Toolkit '<name>' is not allowed`怎么办

当 Tool Router 报出该错误时，优先修正会话的工具包配置（更新或重建会话），然后再去排查该工具包是否缺少 auth config 或连接账号。顺序不能反，否则会白费力气。

七、每次`create()`都是新会话运行时，不是模型记忆

每一次create()调用都会返回一个新的会话 ID。一个会话作用域内包含：

用户（user）；
工具包与工具的访问权限；
认证与账号选择；
会话运行时资源，例如沙箱文件。

但它不是模型的对话记忆（conversation memory）。

当对话或工作流需要保持相同的会话配置与运行时上下文时，用composio.use(sessionId)复用已存储的会话；
当面向不同用户或实质不同的配置时，应创建新会话；
同一用户的新会话仍可解析该用户符合条件的连接账号，但不会继承旧会话的沙箱状态。

// 会话 A：用户甲的沙箱与配置 const sessionA = await composio.create('user_a', { toolkits: ['gmail'] }); // 会话 B：同一用户，全新运行时——沙箱状态不继承 const sessionB = await composio.create('user_a', { toolkits: ['gmail'] });

八、Auth Links 创建的是项目级、用户级连接账号

session.authorize()与COMPOSIO_MANAGE_CONNECTIONS会为会话用户 + 所选 auth config创建一个 Connect Link。认证完成后：

该连接账号归属于该项目/用户，而不是仅归属于产生该链接的会话；
之后同一稳定用户的其他未固定账号的会话可以解析到它；
显式的连接账号固定（pin）保持不变，直到会话被更新或重建。

示例（TypeScript）：

const connectionRequest = await session.authorize('github', { callbackUrl: 'https://myapp.com/callback', }); console.log(connectionRequest.redirectUrl); const connectedAccount = await connectionRequest.waitForConnection();

从源码看，authorize()内部调用后端toolRouter.session.link，支持callbackUrl、alias以及实验性的accountType: 'SHARED'+ 每用户 ACL 配置；默认行为是创建 PRIVATE 连接（ts/packages/core/src/models/ToolRouterSession.ts）。

九、工具包过滤不会预加载全部匹配工具

默认情况下，会话暴露的是meta 工具（如COMPOSIO_SEARCH_TOOLS），由 Agent 在运行时动态发现并加载 app 工具。启用某个工具包只是限制了会话可以发现和执行的范围，并不会把该工具包的每个工具都放进初始 schema 集合。

何时需要显式预加载：

当 Agent 必须直接拿到已知工具时，使用显式的preload.tools列表：

const session = await composio.create('user_123', { toolkits: ['gmail'], preload: { tools: ['GMAIL_FETCH_EMAILS', 'GMAIL_CREATE_EMAIL_DRAFT'] }, }); const tools = await session.tools(); // GMAIL_FETCH_EMAILS, GMAIL_CREATE_EMAIL_DRAFT, COMPOSIO_SEARCH_TOOLS, ...

preload.tools = "all"（或 direct-tools 预设SessionPreset.DIRECT_TOOLS）只应在窄的正向过滤下使用（如toolkits/tools/tags组合收窄范围）；宽泛的全量预加载会被后端封顶（capped），并显著增加 Agent 上下文体积。

实践建议：预加载集合保持精简，一般少于 20 个工具，避免上下文膨胀（docs/content/docs/configuring-sessions.mdx）。direct-tools 预设默认会禁用 search、multi-execute、manage-connections 与 workbench，适合工具集确定、不需要动态发现与工作台辅助的专用 Agent。

十、SDK 自定义工具与 Custom MCP 工具包运行在不同运行时

这是一个容易被误解的差异：

SDK 定义的自定义工具运行在客户自己的应用进程内。其函数体不会上传到 Composio，也不能从远程会话 MCP URL 或 Remote Workbench 自动调用——它天生是"本地/进程内"的。
若要在远端暴露客户自有功能，应将其托管为 MCP 服务器，并注册为Custom MCP 工具包。注册后的远端工具仍受会话的工具包与连接限制约束。

从 ts/packages/core/src/models/ToolRouterSession.ts 可以看到执行时的分流逻辑：SDK 自定义工具通过executeCustomTool在进程内执行（本地工具），其余工具发送到 Composio 后端执行（远端工具）；COMPOSIO_MULTI_EXECUTE_TOOL会把本地与远端工具拆分并行执行后再按原顺序合并结果。

十一、Enhanced Control 依赖客户端的 MCP 引导（elicitation）能力

For You 的 Enhanced Control 审批流依赖MCP elicitation能力，因此只有声明并实现了该能力的客户端才能正常工作。

如果当前客户端不支持 elicitation，可选的处置路径：

换用支持该能力的客户端；
设置适用的Always Allow策略；
或在For You → Settings → General中关闭 Enhanced Control，然后重新连接客户端。

十二、工具包存在多种认证方案时，固定目标 auth config

Tool Router 会优先使用会话中显式映射的 auth config。当一个工具包支持多种认证方案（scheme）时：

应把预期的ac_...ID显式映射到会话中，而不是依赖自动选择；
所选 auth config 必须属于同一项目，并且已为 Tool Router 启用；
显式的连接账号覆盖是精确的工具包级选择，不会回退到其他 active 账号。

const session = await composio.create('user_123', { authConfigs: { github: 'ac_your_github_config', slack: 'ac_your_slack_config', }, });

Python 等价为auth_configs={"github": "ac_your_github_config"}。当工具包存在多认证方案而你又没有显式映射时，会话会依次尝试connectedAccounts覆盖 →authConfigs覆盖 → 已有配置 → 托管认证新建 → 报错（见第五节优先级）。

结语

Tool Router 会话是 Composio 中"为单个用户隔离工具、认证与运行时"的核心边界。抓住三条主线即可用好它：会话配置决定工具与账号边界（白名单/黑名单、auth config、connected accounts）；账号选择是"活的"除非显式固定；会话生命周期独立于用户、认证配置与连接账号。遇到 403 或[Session Restriction]报错时，先修正会话配置、再排查账号级问题，并把精确错误体提交给 Composio 支持团队，即可快速收敛问题。

进一步阅读：会话配置的完整参数与沙箱计算规格见 docs/content/docs/configuring-sessions.mdx；TypeScript SDK 的会话实现见 ts/packages/core/src/models/ToolRouter.ts 与 ts/packages/core/src/models/ToolRouterSession.ts；配置 schema 定义见 ts/packages/core/src/types/toolRouter.types.ts。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析