Composio Platform 集成指南：为你的应用接入用户账户连接、会话与工具执行

Composio Platform 集成指南为你的应用接入用户账户连接、会话与工具执行【免费下载链接】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 Platform 的集成路线图展开从建立项目凭证、创建用户级会话Session、选择工具与认证行为到处理高级产品工作、验证集成成果。面向正在构建由最终用户连接自己账户的 Agent、应用或后端的开发者读完你将掌握一条可复现的最小集成路径以及如何用运行时发现代替猜测工具 slug如何用 Connect Link 替代自建 OAuth 流程。本指南对应的完整技能说明与配套排错参考位于 skills/composio/SKILL.md 与 skills/composio/references/errors.md本文默认读者已了解该技能的产品分流原则For You 面向个人自有账户Platform 面向开发者构建的多用户产品。先明确任务类型在动手之前先判断本次请求属于哪一类任务不同任务对应完全不同的处理深度解释或调研Explain or discover直接基于本文档与当前文档回答不修改任何代码。首次搭建First-time setup建立项目访问凭证并走通最小的可用 SDK 路径。集成或扩展Integrate or extend检查现有代码库把 Composio 接入已有的 Agent 架构。运行操作Operate为应用当前用户发现、授权并执行工具。调试或迁移Debug or migrate在改动凭证或架构之前先查看日志 ID 与现有实现。当需要修改代码时先确认语言、包管理器、Agent/LLM 框架、稳定的用户或租户 ID、密钥加载机制以及代码库中已有的最小执行路径然后把 Composio 工具放进这条路径而不是另起炉灶创建一个并行的演示 Agent。凡是未提供或未观察到的文件名、框架选择、环境行为、身份字段一律不得臆测。采用渐进式披露progressive disclosure原则基础路径只包含项目访问、核心 SDK、一个用户级会话和现有 Agent 的工具接口。除非请求或已检查的代码明确要求否则不要引入 toolkit 过滤、标签策略、沙箱改动、自定义认证、Provider 适配器或生产环境加固。若关键仓库上下文缺失给出最小稳定大纲并只追问缺失的那一个细节而不是用占位符填满一个大示例。建立项目访问凭证路径的三种场景凭证是 Platform 集成的第一道关口核心原则是从上下文里选择恰好一条凭证路径不要混用。场景一已有 Dashboard 或仓库凭证如果COMPOSIO_API_KEY已经存在或者开发者从 Dashboard 的 Getting Started 复制了ak_*项目密钥就直接使用仓库现有环境变量或密钥机制中的这份凭证。在此路径下绝不运行composio dev init也不要切换到其他项目绝不在聊天中创建、轮换、替换、打印、回显、记录或索取密钥只检查环境变量是否存在、是否明显被掩码或类似占位符若凭证存放在文件中只检查该文件是否被版本控制忽略不打印匹配行让首次 SDK 请求去校验凭证——密钥长度不等于有效性。如果 Dashboard 交接缺失或被掩码引导开发者回到 Platform → 项目 → Getting Started → Step 1不要悄悄切换到预置流程。场景二通用首次搭建没有现成项目凭证、也没有 Dashboard 交接时使用当前首次搭建路径curl -fsSL https://composio.dev/install | bash composio login composio dev initcomposio dev init会把COMPOSIO_API_KEY和COMPOSIO_TEST_USER_ID写入.env.local。注意 Python 的 dotenv 默认不会加载.env.local所以要么显式传入该路径要么把变量迁移到项目常规的密钥机制中。不存在裸的composio init命令。验证印记上述命令在 2026-08-06 于 CLI 0.2.32 和 0.3.1 上实际演练过。如果安装版本不同或行为冲突以composio dev --help和当前文档为准不要强行套用该印记。场景三安装代码库所需的 SDKnpm install composio/core pip install composio只有当现有框架确实需要时才添加 Provider 适配器。命名某个包之前先获取当前的 Provider 索引见https://docs.composio.dev/docs/providers.md。不要为了演示 Composio 而引入另一个 LLM 框架。从源码看Python SDK 的Composio类会在初始化时从环境读取 API 密钥api_key kwargs.get(api_key, os.environ.get(COMPOSIO_API_KEY))未提供密钥时直接抛出ApiKeyNotProvidedError见 python/composio/sdk.py。因此在 SDK 代码中不应内联传入密钥。同时SDK 还支持通过COMPOSIO_BASE_URL指定自定义基址以及environment、timeout、max_retries等配置python/composio/sdk.py生产环境可按需调整。集成会话用户身份与工具的作用域会话是什么一个会话session就是一个应用用户的运行时上下文它承载身份、连接、工具作用域和沙箱配置。集成时应追踪应用现有的已认证用户或租户 ID 并使用这个稳定标识符不要新增一套并行的用户体系也不要用一个占位身份跨用户共享。最小会话示例TypeScriptimport { Composio } from composio/core; const composio new Composio(); const session await composio.create(existingUserId); const tools await session.tools();Pythonfrom composio import Composio composio Composio() session composio.create(user_idexisting_user_id) tools session.tools()两个 SDK 都暴露composio.sessions.create(...)不要制造人为的 TypeScript/Python 不对称。SDK 从环境读取COMPOSIO_API_KEY不要内联传密钥。从源码结构看Python 侧composio.create与composio.use是composio.sessions.create/composio.sessions.use的顶层快捷方式composio.tool_router是已被标记弃用的旧别名自 0.17.0 起它返回同一个对象新代码不应再对着它生成见 python/composio/sdk.py。TypeScript 侧同样如此composio.create(...)是composio.sessions.create(...)的别名composio.toolRouter仅为向后兼容保留见 ts/packages/core/src/composio.ts。文档中Tool Router 是 sessions 的旧称这一表述与两套 SDK 源码中tool_router/toolRouter 为弃用别名的实现完全一致。多轮对话与会话复用对于多轮对话要持久化返回的会话 ID 并在后续轮次中恢复它而不是每条消息都新建会话。写生产代码前务必对照configuring-sessions.md确认当前的方法名。然后把会话工具通过仓库现有模型或 Agent 的原生工具集成接口接入除非工具要求定向改动否则保留当前提示词、模型、流式与请求生命周期。选择工具与认证行为默认元工具让 Agent 在运行时自发现会话默认暴露一组数量有限的元工具使 Agent 能够在运行时发现集成并完成认证COMPOSIO_SEARCH_TOOLSCOMPOSIO_GET_TOOL_SCHEMASCOMPOSIO_MULTI_EXECUTE_TOOLCOMPOSIO_MANAGE_CONNECTIONSCOMPOSIO_WAIT_FOR_CONNECTIONSCOMPOSIO_REMOTE_WORKBENCHCOMPOSIO_REMOTE_BASH_TOOL对交互式 Agent 应保持连接管理connection management开启当用户需要授权某个应用时它会返回一个 Connect Link不要自行构建 Provider OAuth 流程。从源码结构可以印证会话配置里COMPOSIO_REMOTE_WORKBENCH与COMPOSIO_REMOTE_BASH_TOOL受沙箱开关控制当沙箱被禁用时这两个代码执行工具不再可用、相关的提示行被剥离、直接的沙箱调用会被拒绝此外还有enable_proxy_execution用于控制沙箱内是否允许代理执行调用见 python/composio/core/models/tool_router.py。这解释了为什么keep or disable the sandbox deliberately有意保留或禁用沙箱会直接改变会话暴露的工具面。direct-tools 预设的适用边界direct_tools预设只适用于狭窄、确定性、带固定允许列表的 Agent。它默认移除元工具。如果用户必须在 Agent 内认证就要重新启用连接管理沙箱要刻意保留或关闭。实现前务必先取回configuring-sessions.md确认当前预设与选项语法。自带连接 UI 的应用如果应用有自己的连接界面应使用会话授权与会话连接状态方法并抑制聊天内的连接提示。认证方面默认使用托管认证managed auth只有应用需要自定义 OAuth 品牌、附加 scope、独立 Provider 配额或有自托管/区域化需求时才创建自定义认证配置。参考 python/composio/sdk.pyPython SDK 同时暴露auth_configs与connected_accounts两个模块用于此类管理。处理高级产品工作按需路由到当前文档不要硬把高级需求塞进首次搭建流程而是路由到当前文档会话作用域、账户选择、回调、直接工具、沙箱控制configuring-sessions.md自定义连接 UImanually-authenticating.md触发器和 Webhooktriggers.md与 setting-up-triggers 系列指南自定义 MCP 服务器、工具、toolkit 或代理执行extending-sessions系列指南旧版直接执行、MCP 服务器或 Tool Router 迁移migration 与会话相关指南白标与自定义 OAuth 应用white-labeling-authentication.md需要再次强调Tool Router 是 sessions 的旧名称。直接执行direct execution应被视为迁移路径而不是新 Agent 集成的默认方案。验证集成什么才算真正成功对首次搭建或集成类请求成功的定义是从开发者真实执行路径发出的一次程序化、安全、只读的工具调用返回了真实的 Provider 结果和非空的 Composio 日志 ID。除非应用已经明确了要试哪个集成否则先问开发者想尝试哪个集成。真实 toolkit 与工具应在运行时发现。如果当前用户未连接返回 Connect Link等待授权后重试。以下情况都不算证明了集成mock、Playground 运行、工具搜索、schema 抓取、会话创建或单独一个 Connect Link。如果仓库没有可运行的 Agent 循环只添加与现有 Provider 兼容的最小入口不要额外要求一个托管模型。成功后应报告代码位置、身份与会话映射、集成与工具、安全的结果摘要、日志 ID以及有用的 Dashboard 目的地。对于解释、迁移计划或窄范围 bug 修复使用该任务自身的完成条件而不是强行触发一次新的工具调用。失败时的排错入口集成验证失败时先从 skills/composio/references/errors.md 定位认证边界项目或会话 401发生在 Provider 工具调用成功之前通常是项目凭证缺失、被掩码、无效或属于其他项目。重新执行 Platform 指南中的无输出凭证检查不要打印、轮换、替换或索取密钥也不要运行composio dev init。Provider 已连接账户 401出现在真实工具执行阶段可能是用户侧 Provider token 被吊销、过期或因密码/2FA/同意/管理员策略变更而失效。保持相同的项目密钥与应用用户 ID为该集成生成一个新的 Connect Link重连 Provider 账户后重试安全调用链接过期就再申请一个。常见 Provider 约束还包括Google App is blocked 需要移除多余 scope 或使用已验证的自定义 OAuth 应用Google API 未启用需要在拥有自定义凭证的 GCP 项目中启用对应 APISlack 429 说明托管应用共享 Provider 配额需要时可换自定义 Slack 应用获得独立配额Microsoft 403 可能要求租户管理员同意GitHub App 的 OAuth 凭证与仓库安装是相互独立的两个步骤。使用权威文档在给出版本敏感的命令或修改 SDK 集成代码之前先获取当前的 Markdown 文档https://docs.composio.dev/llms.txt https://docs.composio.dev/docs/page.md https://docs.composio.dev/toolkits/toolkit.md跨产品共用的失败可阅读 Errors and provider gotchas。当各来源冲突时以当前 API 参考和线上端点行为为准并显式命名 REST API 版本。红线清单这些事不要做不要用通用搭建流程替换 Dashboard 提供的凭证用户要求实现时不要停在文档层面不要猜测 toolkit 或工具 slug用运行时发现或 CLI 查询不要把创建认证配置当作万能前置条件不要替换应用的身份模型或 Agent 架构在请求的证明成功之前不要声称某个集成已经可用。【免费下载链接】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），仅供参考