Composio TypeScript SDK 会话管理Session Management完全指南createSession 配置继承与请求头隔离【免费下载链接】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 官方 TypeScript SDK 文档 ts/docs/advanced/session-management.md 为骨架系统讲解基于createSession的会话管理机制如何在保留父实例全部配置apiKey、baseURL、provider 等的前提下为特定操作创建携带独立请求头的新 SDK 实例实现请求追踪、多租户上下文隔离与请求行为定制。读完本文你将掌握Composio构造器全部可选参数、createSession的底层实现原理含会话头合并规则与冲突优先级并能在多用户、多租户的 Agent 应用场景中正确落地会话隔离模式。一、会话管理解决什么问题在真实的多租户 AI Agent 应用中同一个后端服务往往同时服务大量用户、租户或业务上下文。如果所有请求都共享同一个 SDK 实例和同一组请求头服务端就无法区分这次工具调用来自哪个用户、这条链路属于哪次业务请求日志与监控也就失去了可观测性。Composio SDK 的会话管理能力正是为此设计通过createSession方法你可以在不重新配置 API Key、baseURL、provider 的前提下派生出一个带自定义请求头的新 Composio 实例。该派生实例会继承父实例的全部配置apiKey、baseURL、provider、allowTracking 等叠加自定义请求头并自动与 SDK 内置的会话标识头合并与其它会话相互隔离从而支持不同上下文下的并行操作。这一机制在 ts/packages/core/src/composio.ts 的源码注释中有明确定位它适用于为特定请求添加自定义请求头、用唯一标识追踪请求上下文以及为某一部分操作覆盖默认请求行为三类场景。二、Composio 构造器选项全解会话管理的前提是正确初始化父实例。以下为Composio构造函数支持的完整配置项源自官方文档并结合 ts/packages/core/src/composio.ts 构造器实现验证const composio new Composio({ apiKey: your-api-key, // 必填Composio API 密钥 baseURL: https://api.composio.dev, // 可选自定义 API 端点 allowTracking: true, // 可选默认 true是否开启遥测 allowTracing: true, // 可选默认 true是否开启追踪 provider: new OpenAIProvider(), // 可选工具提供方默认 OpenAIProvider telemetryTransport: customTransport, // 可选自定义遥测传输 defaultHeaders: { x-request-id: global-id }, // 可选全局默认请求头作用于所有请求 });各参数说明参数必填默认值说明apiKey是—Composio API 密钥用于鉴权baseURL否生产环境 URL自定义 API 端点便于自托管或走代理allowTracking否true是否启用匿名使用遥测allowTracing否true是否启用请求追踪provider否OpenAIProvider工具提供方控制x-framework等会话头telemetryTransport否内置传输自定义遥测上报通道defaultHeaders否—全局默认请求头作用于所有请求含会话外从构造器实现看apiKey与baseURL会经过getSDKConfig归一化toolkitVersions会合并环境变量如COMPOSIO_TOOLKIT_VERSION_GITHUB20250902_00fileUploadDirs/fileDownloadDir会做~展开——这些细节说明构造器在初始化阶段就完成了一整套配置快照snapshot会话正是基于这份快照派生的。三、createSession 工作原理与源码解析3.1 核心实现createSession的完整实现位于 ts/packages/core/src/composio.tscreateSession(options?: { headers?: ComposioRequestHeaders }): ComposioTProvider { const sessionHeaders getDefaultHeaders(options?.headers, this.provider); return new Composio({ ...this.config, defaultHeaders: sessionHeaders, }); }其本质是一次浅复制构造将父实例的this.config全部展开作为新实例的配置基底——这保证了 apiKey、baseURL、provider 等全部继承调用getDefaultHeaders将调用方传入的自定义 headers 与 SDK 内置会话头合并合并结果作为新实例的defaultHeaders传入构造函数完成派生。从源码结构看createSession在 JSDoc 中被标记为deprecatedSDK 官方建议未来直接用new Composio({ ...existingConfig, defaultHeaders })构造新实例或对单次调用使用 per-callrequestOptions如AbortSignal取消见 ts/packages/core/src/types/requestOptions.types.ts。当前版本仍完全可用本文示例依然有效。3.2 会话头合并规则getDefaultHeaders合并逻辑实现在 ts/packages/core/src/utils/session.tsexport function getSessionHeaders(provider) { return { x-framework: provider?.name || unknown, x-source: TYPESCRIPT_SDK, x-runtime: RUNTIME_ENV, // 在模块加载时通过 UA 探测一次 x-sdk-version: version, }; } export const getDefaultHeaders (headers, provider) { const sessionHeaders getSessionHeaders(provider); return { ...(headers || {}), ...sessionHeaders, // 内置会话头后展开优先级更高 }; };这里揭示了一个关键事实你的自定义 headers 会与 SDK 内置的x-framework、x-source、x-runtime、x-sdk-version四个会话标识头自动合并且当 key 冲突时内置会话头优先见 ts/packages/core/test/core/session.test.ts 的测试用例 should prioritize session headers over custom headers when keys conflict。x-runtime通过运行时环境探测得出NODE/BROWSER/UNKNOWNx-framework则由 provider 名称如openai决定。四、基础用法创建带自定义请求头的会话官方文档给出的最小可用示例// 创建基础 Composio 实例 const composio new Composio({ apiKey: your-api-key, }); // 创建携带自定义请求头的会话 const sessionWithHeaders composio.createSession({ headers: { x-request-id: 1234567890, x-correlation-id: session-abc-123, x-custom-header: custom-value, }, }); // 使用会话发起 API 调用 await sessionWithHeaders.tools.list();sessionWithHeaders发出的所有 API 请求都会自动携带上述三个自定义头外加 SDK 自动注入的x-source: TYPESCRIPT_SDK、x-sdk-version等会话标识头。服务端只需读取这些头即可实现链路追踪与请求归因。五、进阶用法多会话并行与上下文隔离会话之间相互独立最适合一个会话对应一个用户/租户的模式。官方文档示例// 用户 A 的会话 const userASession composio.createSession({ headers: { x-user-id: user-a, x-tenant-id: tenant-1, }, }); // 用户 B 的会话 const userBSession composio.createSession({ headers: { x-user-id: user-b, x-tenant-id: tenant-2, }, }); // 每个会话维护各自独立的上下文 await Promise.all([ userASession.tools.get(a), // 携带用户 A 的请求头 userBSession.tools.list(b), // 携带用户 B 的请求头 ]);两个会话虽然共享父实例的 apiKey 与 baseURL但请求头互不干扰因此可以安全地放入Promise.all并行执行。测试 ts/packages/core/test/core/session.test.ts 验证了这一点sessionA与sessionB各自config.defaultHeaders中仅包含自己的自定义头与公共会话头彼此完全隔离。六、全局默认头与请求头优先级如果你希望某些头对所有请求包括会话外的请求生效应在主构造器中使用defaultHeadersconst composio new Composio({ apiKey: your-api-key, defaultHeaders: { x-global-header: global-value, }, });值得注意的优先级规则测试 ts/packages/core/test/core/session.test.ts 有专门用例 should properly merge headers when both parent and session have custom headers会话自定义头覆盖父实例defaultHeaders中同名字段SDK 内置会话头x-source、x-runtime等优先级最高会覆盖自定义的同名头未冲突的字段全部共存于最终请求头中。实际请求时最终头 父实例 defaultHeaders ∪ 会话 headers ∪ SDK 内置会话头后者胜出。七、最佳实践7.1 会话生命周期会话应按上下文或操作批次创建用完即弃不要长期复用不同上下文不同用户/租户/业务线之间不要共享会话上下文一旦变化如用户切换、租户切换立即创建新会话避免请求头串号导致数据隔离失效。7.2 请求头规范采用一致的命名约定建议统一使用x-前缀扩展头尽量携带追踪 IDx-request-id、关联 IDx-correlation-id与业务维度标识x-user-id、x-tenant-id在团队内部文档中登记自定义头的含义与取值范围避免同名不同义。7.3 错误处理会话继承父实例的错误处理行为无需重复配置需要上下文级差异化处理时如对特定用户的重试策略可在会话外层包裹 try/catch 或重试逻辑单次调用如需取消可优先使用 per-callrequestOptions.signalts/packages/core/src/types/requestOptions.types.ts例如AbortSignal.timeout(5_000)SDK 会抛出可被instanceof识别的ComposioRequestCancelledError。八、局限性与注意事项会话不可变会话一旦创建其配置含请求头即固定无法在运行时修改需要变更时必须新建会话或直接构造新实例。每次派生都是全新实例createSession返回的是独立的Composio实例拥有自己的 client、tools 等模型对象因此会带来相应的初始化开销。会话头作用于该会话的全部 API 调用包括 tools、toolkits、connectedAccounts、triggers 等所有通过该实例发出的请求。内置会话头不可被覆盖x-source、x-framework、x-runtime、x-sdk-version由 SDK 强制注入自定义同名头会被覆盖见 ts/packages/core/src/utils/session.ts。九、未来迁移方向根据 ts/packages/core/src/composio.ts 的 deprecation 注释createSession将在未来版本中移除官方推荐的替代方案为// 方案一直接构造携带 defaultHeaders 的新实例 const existingConfig composio.getConfig(); // 获取冻结的配置快照 const session new Composio({ ...existingConfig, defaultHeaders: { x-user-id: user-a }, }); // 方案二单次调用覆盖使用 per-call requestOptions await composio.tools.execute(TOOL, body, { signal: AbortSignal.timeout(10_000), });其中getConfig()返回冻结Object.freeze的配置快照ts/packages/core/src/composio.ts防止误改已快照进内部模型的配置值。在新代码中建议优先采用方案一保证对未来的 SDK 升级平滑兼容。十、相关主题错误处理Error Handling自定义 ProviderCustom Providers遥测Telemetry延伸阅读仓库内可深入研究的参考核心实现ts/packages/core/src/composio.tscreateSession与getConfig会话头工具ts/packages/core/src/utils/session.tsgetSessionHeaders/getDefaultHeaders单次请求取消选项ts/packages/core/src/types/requestOptions.types.ts会话行为验证测试ts/packages/core/test/core/session.test.ts继承、隔离、合并、冲突优先级共 10 个用例官方文档原文ts/docs/advanced/session-management.md【免费下载链接】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），仅供参考