企业官网建设流程全解析

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 init

composio 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和当前文档为准，不要强行套用该印记。

场景三：安装代码库所需的 SDK

npm 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 并使用这个稳定标识符，不要新增一套并行的用户体系，也不要用一个占位身份跨用户共享。

最小会话示例

TypeScript：

import { Composio } from "@composio/core"; const composio = new Composio(); const session = await composio.create(existingUserId); const tools = await session.tools();

Python：

from composio import Composio composio = Composio() session = composio.create(user_id=existing_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_TOOLS
• COMPOSIO_GET_TOOL_SCHEMAS
• COMPOSIO_MULTI_EXECUTE_TOOL
• COMPOSIO_MANAGE_CONNECTIONS
• COMPOSIO_WAIT_FOR_CONNECTIONS
• COMPOSIO_REMOTE_WORKBENCH
• COMPOSIO_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.py，Python SDK 同时暴露auth_configs与connected_accounts两个模块用于此类管理。

处理高级产品工作：按需路由到当前文档

不要硬把高级需求塞进首次搭建流程，而是路由到当前文档：

• 会话作用域、账户选择、回调、直接工具、沙箱控制：configuring-sessions.md
• 自定义连接 UI：manually-authenticating.md
• 触发器和 Webhook：triggers.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 项目中启用对应 API；Slack 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