Composio Skill 完整指南面向 Agent 的产品路由、SDK/CLI/MCP 集成与故障排查【免费下载链接】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本文以仓库 skills/composio/SKILL.md 及其三个配套参考For You、Platform、Errors and provider gotchas为主体结合 Python 与 TypeScript SDK、CLI 源码系统讲解如何让 AI Agent 正确选择 Composio 产品线、完成 SDK/MCP/CLI 集成、排查连接与工具调用故障。读完本文你将掌握一套可复用的先选产品 → 再选任务 → 只加载相关指南 → 最小改动完成集成 → 用真实调用验证的 Agent 工作流并能对照源码理解 session会话与 meta tools 的底层机制。1. 技能定位一个路由器而非单点操作指南Composio 是一个面向 AI Agent 的工具接入平台仓库代码python/composio、ts/packages覆盖 Python/TypeScript SDK、CLI、MCP 与 1000 工具集。面对如此庞杂的能力面composio这个 Agent 技能Skill刻意被设计成一个路由器router它的职责不是穷举所有 API而是完成四步决策识别产品For You 还是 Platform识别任务解释、搭建、集成、运维、调试/迁移只加载相关指南for-you.md、platform.md、errors.md执行最小必要改动并用一次安全、只读的真实工具调用验证。仓库中 skills/composio 目录的结构即为该设计的具体体现SKILL.md是决策主干三个references/*.md是按产品与故障场景拆分的内容模块Agent 按需加载即可避免把解释、查文档或局部修 bug 升级成一次完整的 onboarding。2. 第一步选择产品For You 与 Platform 绝不混用SKILL.md强调的第一条纪律是不要混淆产品——二者使用完全不同的凭证与接入路径维度Composio For YouComposio Platform适用场景用户想让自己的 Agent使用自己的应用开发者正在构建一个产品其终端用户连接各自账户主要接入面MCP 或 Composio CLI应用内的 SDK session凭证客户端需要 header 时用ck_...consumer keyCOMPOSIO_API_KEY项目密钥控制台dashboard.composio.dev→ For Youdashboard.composio.dev→ Platform若上下文无法确定产品只问一个问题这是给你自己的 Agent 和账户用还是给一个由用户连接账户的产品用判定规则也很明确命名的个人 AI 客户端且无产品代码 → For You应用代码库、SDK、用户/租户身份、后端或产品 Agent → Platform。这一产品二分法在源码中同样存在。For You 侧依赖 MCP 端点与 consumer keyPlatform 侧则依赖 python/composio/sdk.py 中Composio.__init__从os.environ.get(COMPOSIO_API_KEY)读取的项目密钥二者不是同一种凭证混用必然导致鉴权失败。3. 第二步选择任务Job避免把一切当作 onboarding在动手前先明确期望产出Explain or discover解释/发现回答问题、对比方案、查找当前 APISet up搭建首次建立凭证、MCP 客户端、CLI 或 SDKBuild or change构建/修改把 Composio 集成进现有 Agent 或应用Operate运维为真实任务查找、连接并运行工具Debug or migrate调试/迁移诊断失败、升级旧集成或从 Legacy direct execution / Tool Router 迁移。关键纪律不要把一个解释、文档查询或窄幅 bug 修复升级成 onboarding。例如用户只是问Gmail 工具怎么用就不该启动完整的项目初始化流程。4. 第三步按需加载指南而不是一次读完场景应加载的指南For You 相关skills/composio/references/for-you.mdPlatform 相关skills/composio/references/platform.mdProvider/连接/执行失败追加 skills/composio/references/errors.md三个参考文档各司其职For You 讲个人 Agent 的 MCP/CLI 接入Platform 讲产品内 SDK session 集成Errors 讲跨产品共性的故障边界。这种按需加载设计使得技能在上下文受限的 Agent 场景下也能保持低 token 开销。5. Composio For You个人 Agent 接入 MCP 或 CLI5.1 稳定的产品契约For You 的接入参数是稳定的MCP 端点https://connect.composio.dev/mcp客户端需要 header 时的 consumer keyck_...Header 名x-consumer-api-key密钥位置Dashboard → For You → AI Clients → 选择客户端已被移除的mcp.composio.dev端点以及 Platform 的 MCP URL 都不能作为替代ck_...与 Platform 的COMPOSIO_API_KEY也不可互换。任何客户端相关配置变更前先以https://docs.composio.dev/docs/composio-connect.md作为当前事实来源。5.2 选择 MCP 还是 CLI默认策略桌面端与托管 AI 客户端用 MCP终端 Agent 用 CLI后者可以直接执行命令与操作工具。需要注意各接入面安装的内容是互补而非互相依赖的接入面Agent 能发现什么原始 Composio MCP 连接可调用的工具及其 schemaMCP 不会安装 Agent 技能公开composioskill本文所述的产品任务路由器需从ComposioHQ/composio显式安装Composio CLIcomposio命令 单独维护的composio-cliskillCLI 的 agent 设置流程会安装它OpenAI/Codex 插件托管的 Composio app 内置composio-runtimeskill在托管工具与本地 CLI 之间选择Claude Code 插件命令与 hooks不内置 skillCLI login/setup 会单独安装composio-cli因此一个 Agent 可能看得到 Composio 工具却看不到任何 Composio skill也可能同时拥有多个职责不同的 skillcomposio管产品选择与集成指导composio-runtime管 OpenAI 插件路由composio-cli管 CLI 操作。5.3 MCP 客户端配置Claude Desktop 与 ChatGPT 走浏览器 OAuth不需要consumer key基于 header 的客户端使用上述端点和x-consumer-api-key其他支持 MCP 的客户端配置 HTTP 传输必要时加 header且不要把凭证写进被提交的配置。5.4 终端 Agent 的 CLI 路径仅在任务确实需要时安装并认证 CLIcurl -fsSL https://composio.dev/install | bash composio login真实任务的标准操作序列composio search 用户想要什么 composio link toolkit composio execute TOOL_SLUG -d {...}当 Agent 无法打开浏览器时用composio login --no-wait | jq获取登录 URL 交给用户再用返回的 key 完成认证。CLI 帮助文本与composio link/search/execute的用法在 ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.link.cmd.ts 中有明确示例如composio link gmail --alias work、composio link github --list。CLI 安装脚本本身install/bash.sh只做 HTTPS 下载校验与临时目录清理真正的安装逻辑在下载的install.sh中且支持COMPOSIO_DEBUG1输出调试信息。5.5 按需连接应用与验证不要预先连接所有应用。从任务本身出发当某个集成需要时Composio 会返回授权链接连接建立后会为后续运行持久化。对于搭建或运维类请求在授权可用时用一次安全、真实的调用验证所选路径对于问题咨询或配置解释直接回答而不强制执行。5.6 For You 常见故障检查MCP 工具不出现 → 确认连接器已启用清除客户端缓存并重连浏览器 OAuth 反复选错账户 → 用干净浏览器 profile、只登录一个 Composio 账户重试授权链接过期 → 请求新链接不要复用旧的已连接应用返回 auth 错误 → 重连该应用并重试不要重新生成 consumer key。连接管理在 Dashboard → For You → Connect Appsconsumer key 与 MCP/CLI 会话在 Settings → Sessions API Key。6. Composio Platform在产品中集成 SDK Sessions6.1 建立项目访问二选一绝不并行路径 A已有 Dashboard 或仓库凭证。若COMPOSIO_API_KEY已存在或开发者从 Dashboard Getting Started 复制了ak_*项目密钥就直接使用仓库现有环境/密钥机制中的凭证。此路径下绝不运行composio dev init或切换项目绝不在聊天中创建、轮换、替换、打印或请求该密钥只检查环境变量是否存在且未被明显脱敏/占位密钥在文件里时只确认该文件已被源码控制忽略不打印匹配行让第一次 SDK 请求去验证凭证——长度不是验证。路径 B通用首次搭建。无现有项目凭证且无 Dashboard 交接时curl -fsSL https://composio.dev/install | bash composio login composio dev initcomposio dev init会把COMPOSIO_API_KEY与COMPOSIO_TEST_USER_ID写入.env.local对应 CLI 源码 ts/packages/cli/src/commands/init.cmd.tsupsertEnvVar幂等写入这两个变量并在.composio/下生成project.json与.gitignore。注意Python dotenv默认不会加载.env.local需显式传路径或把变量迁移到项目常规密钥机制中此外不存在裸composio init命令只有composio dev init。该命令的验证戳是 CLI 0.2.32 与 0.3.12026-08-06 实测若安装版本不同或行为冲突以composio dev --help和当前文档为准。6.2 安装代码库所需的 SDKnpm install composio/core pip install composio仅当现有框架确实需要时才添加 provider adapter如 Anthropic、LangChain、CrewAI 等参见 python/providers 各 provider 包命名包前先查https://docs.composio.dev/docs/providers.md。不要为了演示 Composio 而引入另一个 LLM 框架。6.3 会话Session集成Platform 的核心抽象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(...)——不要制造人为的 TS/Python 不对称。SDK 从环境读取COMPOSIO_API_KEY因此不要内联传密钥。这一设计在源码中有明确体现Python 侧 python/composio/sdk.py 从环境变量取api_key缺失即抛ApiKeyNotProvidedError并将self.create/self.use绑定为sessions的快捷方式composio.tool_router是已弃用别名sdk.py 标注自 0.17.0 弃用TypeScript 侧 ts/packages/core/src/composio.ts 中sessions是规范入口toolRouter同样是仅保留兼容的弃用别名composio.create(...)是别名composio.ts。对于多轮对话持久化返回的 session ID 并在后续消息中复用而不是每轮新建。编写生产代码前对照configuring-sessions.md确认当前方法名。随后把 session 工具交给仓库现有的 model/agent使用其原生工具集成方式除非工具需要定向修改否则保留现有 prompt、模型、流式与请求生命周期。6.4 会话的默认 meta tools 与 direct-tools presetSessions 默认暴露一组小型 meta tools让 Agent 能在运行时发现集成并完成认证COMPOSIO_SEARCH_TOOLS搜索工具COMPOSIO_GET_TOOL_SCHEMAS获取工具 schemaCOMPOSIO_MULTI_EXECUTE_TOOL批量执行COMPOSIO_MANAGE_CONNECTIONS管理连接COMPOSIO_WAIT_FOR_CONNECTIONS等待连接COMPOSIO_REMOTE_WORKBENCH远程工作台COMPOSIO_REMOTE_BASH_TOOL远程 Bash源码侧可印证这些工具确实存在于会话模型中TypeScript 端 ts/packages/core/src/models/ToolRouterSession.ts 定义了COMPOSIO_MULTI_EXECUTE_TOOL常量并实现其执行分发逻辑Python 端 python/composio/core/models/tool_router.py 在 sandbox 配置中明确写到当sandbox{enable: False}时COMPOSIO_REMOTE_WORKBENCH与COMPOSIO_REMOTE_BASH_TOOL将不在会话中可用。交互式 Agent 务必保持连接管理开启——当用户需要授权某应用时它会返回 Connect Link不要自己构建 provider OAuth 流。direct-tools preset 只用于工具清单固定的窄确定性 Agent它默认移除 meta tools需要用户在 Agent 内认证时需重新启用连接管理并审慎决定沙箱开关。实现前对照configuring-sessions.md获取当前 preset 与选项语法。如果应用有自己的连接 UI应使用 session 的授权与连接状态方法并抑制聊天内连接提示初始阶段使用 managed auth仅为应用的 OAuth 品牌、额外 scope、专属 provider 配额或自托管/区域需求创建自定义 auth config。6.5 session 创建的完整参数面源码级从 python/composio/core/models/tool_router.py 的ToolRouter.create文档可见会话配置的完整参数参数说明与示例user_id会话归属的用户 ID必填toolkits启用/禁用 toolkit[github,slack]或{enable: [...]}/{disable: [...]}tools按 toolkit 配置工具{gmail: [GMAIL_SEND_EMAIL,GMAIL_SEARCH]}或{enable:...}/{disable:...}/{tags:...}tags全局 MCP 标签过滤[readOnlyHint,idempotentHint,destructiveHint,openWorldHint]或{enable:..., disable:...}manage_connectionsTrue/False或{enable: True, callback_url: ..., wait_for_connections: True}auth_configstoolkit slug → auth config ID如{github: ac_xxx}connected_accountstoolkit slug → 已连接账户 ID如{github: ca_xxx}支持多账户列表sandbox{enable: bool}、{enable_proxy_execution: bool}、{auto_offload_threshold: int}、{sandbox_size: ...}multi_account{enable: True, max_accounts_per_toolkit: 3, require_explicit_selection: True}preload{tools: [GMAIL_FETCH_EMAILS]}或all把工具直接暴露在session.tools()中session_presetSESSION_PRESET_DIRECT_TOOLSdirect-tools 模式见 tool_router_constants.pyexperimental实验特性如{assistive_prompt: {user_timezone: America/New_York}}mcpTrue返回带托管 MCP 端点session.mcp.url/session.mcp.headers的会话类型sandbox 计算档位在源码中以注释表形式给出tool_router.pystandard1 vCPU / 1 GB默认、medium2 vCPU / 2 GB、large4 vCPU / 4 GB、xlarge8 vCPU / 8 GB。6.6 高级产品工作与迁移不要把高级请求硬塞进首次搭建流程按主题路由到对应文档会话作用域/直接工具/沙箱控制 →configuring-sessions.md自定义连接 UI →manually-authenticating.md触发器与 webhook →triggers.md与 setting-up-triggers 指南自定义 MCP 服务器/工具/toolkit/代理执行 →extending-sessions指南Legacy direct execution/MCP 服务器/Tool Router 迁移 → migration 与 sessions 指南白标与自定义 OAuth →white-labeling-authentication.md。需要特别记住的术语变更Tool Router 是 sessions 的旧称direct execution 是迁移路径而非新集成默认。这与 SDK 源码中tool_router/toolRouter弃用别名的处理完全一致。6.7 验证标准成功 真实工具调用 非空日志 ID首次搭建或集成请求的成功标准是从开发者真实执行路径发起的一次程序化、安全、只读的工具调用返回了实际的 provider 结果和非空的 Composio 日志 ID。需要明确的是——mock、Playground 运行、工具搜索、schema 获取、session 创建或仅生成 Connect Link都不算集成成功。若当前用户未连接返回 Connect Link、等待授权后重试。成功后报告代码位置、身份与会话映射、集成与工具、安全结果摘要、日志 ID 及有用的 Dashboard 目的地。7. 跨产品错误处理与 Provider 注意事项7.1 先取证再改代码获得 Composio 日志或 request ID 并检查 Dashboard Logs不要在改凭证或代码前跳过这一步Agent 框架常会包裹底层 provider 错误。CLI 已安装并认证时可用composio dev logs tools composio dev logs triggers composio connections list但不要仅为诊断一个已包含失败信息的 Dashboard 日志而安装或重新初始化 CLI。7.2 工具不存在绝不猜 slug在 Platform session 中通过会话 meta tools 发现工具在 CLI 工作流中用composio search再检查返回的工具。Legacy 手动执行时缺失工具可能是 toolkit 版本问题——先取当前 migration 与执行文档而非假设 provider 缺少该操作。新 session 集成应使用运行时发现。7.3 定位认证边界Composio 项目/session 401发生在任何 provider 工具调用成功之前项目凭证缺失、被脱敏、无效或属于别的项目。重跑 Platform 指南中的无输出凭证检查若来自 Dashboard Getting Started引导回该项目 Step 1而不是运行composio dev init。Provider connected-account 401出现在真实工具执行时所选用户的 provider token 可能因密码、2FA、consent 或管理员策略变更而失效。保持同一项目密钥与应用用户 ID为集成生成新的 Connect Link重连 provider 账户后重试安全调用链接过期就申请新链接。For You 客户端认证失败核对 For You 指南中的 consumer 端点、OAuth 会话或ck_...header 路径不要用 Platform 项目密钥替代。7.4 常见 Provider 约束速查Google App is blocked移除多余 scope 或改用已验证的自定义 OAuth appGoogle API disabled在持有自定义凭证的 Google Cloud 项目中启用所需 APISlack 429托管 app 共享 provider 配额需要专属配额时使用自定义 Slack appMicrosoft 403租户可能需要管理员 consentGitHub App 访问OAuth 凭证与仓库安装是两步独立操作Payment toolkit 会话限制属 surface 策略限制不是套餐或连接失败。7.5 品牌与生产级认证Managed auth 用于让初期开发变简单。上线前把需要应用品牌、额外 scope 或专属配额的集成迁移到自己的 OAuth app。涉及移除 Composio 品牌时先定位 surfaceConnect Link 页、provider 同意屏、secured 徽章、回调域名还是成功页不同 surface 修法不同实施前取white-labeling-authentication.md。7.6 触发器与 Webhook变更触发器前先检查 Composio 状态页与触发器日志事件名、轮询限制与连接状态验证以当前触发器文档为准不要承诺静态出站 IP应使用文档化的 webhook 签名验证。8. 十条稳定规则Agent 行为红线先确定产品再选凭证、URL、SDK 与命令Dashboard onboarding 只是上下文不是技能的身份开发者带着现有COMPOSIO_API_KEY到达时直接使用绝不在聊天中创建/轮换/替换/打印/请求它也不运行composio dev init无 Dashboard 凭证交接的通用 Platform 首次搭建遵循 Platform 指南当前搭建路径绝不发明 toolkit/tool slug运行时或用 CLI 发现不构建 provider OAuth 流——需要认证时 Composio 返回 Connect Link新 Platform 集成使用 sessions保留应用现有用户身份与 Agent 架构凭证不进入源码控制、URL、日志、聊天与命令输出诊断失败工具调用前先拿日志或 request ID优先最小配置toolkit 过滤、标签策略、沙箱控制、自定义认证、provider 加固等高级选项不进首条路径不虚构仓库事实文件、框架、环境加载器、身份字段、Agent 路径或依赖未提供或未检查前不得断言存在代码库上下文不可用时就说明未知并请求访问或一个必要细节。9. 权威信息来源与引用纪律对于版本、provider adapter、客户端配置、toolkit 行为或可能变化的 API回答前以当前权威文档与 CLI/工具 schema 为主https://docs.composio.dev/llms.txt https://docs.composio.dev/docs/page.md https://docs.composio.dev/toolkits/toolkit.md若这些主来源无法解答再查询公开统一知识搜索https://docs.composio.dev/api/knowledge-search?qquestion。引用证据时引用结果返回的canonicalUrl相对路径则前缀https://docs.composio.dev而不是搜索 API URL只有当 excerpt 或页面直接回答问题时才作为证据没有任何公开来源直接记载某个确切错误时如实说明并索要日志/request ID而不是用相邻结果猜测诊断来源冲突时优先当前 API reference 与线上端点行为标记 Legacy 的页面次之并明确命名 REST API 版本用文档完成任务不要用户只问链接就只丢链接。10. 从仓库源码理解技能背后的 SDK 契约技能文档的诸多规则其实都能在仓库源码中找到契约级对应理解这些对应能让 Agent 与开发者都少踩坑凭证从环境读取Python SDK 在 python/composio/sdk.py 中默认api_key os.environ.get(COMPOSIO_API_KEY)无密钥即抛ApiKeyNotProvidedError这正是不要在代码内联传 key的底层原因sessions 是规范入口tool_router 是弃用别名Python 侧 sdk.py 与 TS 侧 composio.ts 一致TS 端composio.create/composio.use直接绑定sessionscomposio.ts会话参数即产品能力边界toolkits/tools/tags/manage_connections/sandbox/session_preset等参数的完整语义都写在 python/composio/core/models/tool_router.py 的 create 文档中是编写 session 配置的一手依据composio dev init的产物可预期它幂等写入.env.local的COMPOSIO_API_KEY/COMPOSIO_TEST_USER_ID并在.composio/生成project.json与.gitignorets/packages/cli/src/commands/init.cmd.tsCLI 操作三件套有官方帮助文本composio search/link/execute的用法与别名选项如--alias、--list见 connected-accounts.link.cmd.ts。将技能决策树与这些源码契约结合起来就构成了一套会选产品、会按需加载、会用最小改动完成集成、会用真实调用验证的完整 Agent 工作流——这也是本技能希望 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），仅供参考