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_iduser_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配置的一部分默认falsemultiAccount.maxAccountsPerToolkit默认 5、取值范围 210ts/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这是最容易踩坑的语义之一省略connectedAccountsTool Router 在执行时实时解析会话用户的当前 active 账号包括会话创建之后才新连接的账号——即活的账号发现提供connectedAccounts这是一个精确的工具包级覆盖exact toolkit overrideTool 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_iduser_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保持不变直到会话被更新或重建。示例TypeScriptconst 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 configTool 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.mdxTypeScript SDK 的会话实现见 ts/packages/core/src/models/ToolRouter.ts 与 ts/packages/core/src/models/ToolRouterSession.ts配置 schema 定义见 ts/packages/core/src/types/toolRouter.types.ts。【免费下载链接】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），仅供参考 
长河君 · 2026/9/10 0:37:35 · 阅读 1.2k 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_iduser_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配置的一部分默认falsemultiAccount.maxAccountsPerToolkit默认 5、取值范围 210ts/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这是最容易踩坑的语义之一省略connectedAccountsTool Router 在执行时实时解析会话用户的当前 active 账号包括会话创建之后才新连接的账号——即活的账号发现提供connectedAccounts这是一个精确的工具包级覆盖exact toolkit overrideTool 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_iduser_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保持不变直到会话被更新或重建。示例TypeScriptconst 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 configTool 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.mdxTypeScript SDK 的会话实现见 ts/packages/core/src/models/ToolRouter.ts 与 ts/packages/core/src/models/ToolRouterSession.ts配置 schema 定义见 ts/packages/core/src/types/toolRouter.types.ts。【免费下载链接】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），仅供参考