Composio 安全接入 AI Agent 工具教程：OAuth、权限、审批与回滚

这篇教程会完成什么

这份教程不只演示一次成功调用，而是把 Composio 接入多租户 AI Agent 时容易遗漏的生产环节补齐。完成后，你会得到一条可审计的执行链：用户身份稳定映射；开发与生产连接隔离；OAuth scopes 最小化；Agent 只能看到允许的工具；高风险写操作必须批准；重复请求不会重复执行；连接失效能重新授权；日志不会无边界保存敏感内容；团队知道如何暂停和回滚。

示例是一款客户支持 Agent。它可以读取工单、查询 CRM、搜索知识库、起草回复，并在人工批准后发送邮件或更新 CRM。Composio 负责工具目录、连接、认证和调用；你的应用仍负责租户权限、业务授权、审批、幂等、成本和最终审计。先把这条责任边界写进架构文档。

开始前需要准备

至少准备 development 和 production 两个完全独立的 Composio 项目。每个环境使用不同 API key、OAuth 回调地址、webhook、日志目标、测试账户和模型预算。不要让开发 Agent 连接真实客户邮箱，也不要把生产密钥放入本地共享配置。

应用数据库需要保存以下稳定字段：

• tenant_id：企业或组织的不可变主键。
• member_id：成员的不可变主键。
• agent_id：执行动作的 Agent 角色与版本。
• composio_user_id：传给 Composio 的稳定标识。
• connection_policy_version：用户接受的权限策略版本。
• disabled_at：用户、租户或连接被停用的时间。

不要用邮箱作为永久 user ID。邮箱会修改、复用，也可能出现在多个租户中。使用内部 UUID，或者用 tenant 与 member 主键生成不包含个人信息的稳定标识。

再准备动作风险表。读取公开状态属于低风险；读取邮件正文和客户备注属于敏感只读；创建草稿或内部标签属于可逆写入；发送邮件、更新 CRM、创建公开内容属于外部影响；删除、付款、改权限和批量群发属于高风险。风险越高，工具暴露越窄，审批越严格。

第一步：建立稳定用户映射

创建 Session 或连接前，先从当前登录会话解析 tenant 与 member。应用数据库是身份真相来源，Composio user ID 只是外部映射，不能反过来决定业务权限。

映射记录至少包含 tenant、member、agent、composio user、environment、status 和 policy version。每次执行工具前重新确认成员仍属于该租户、角色仍允许动作、Agent 版本仍启用。不要因为连接一周前创建过，就跳过当前授权。

删除成员时，不只停用应用账户。还要禁用其 connected accounts、终止排队任务、取消未执行审批、轮换必要的共享密钥，并按隐私政策删除连接映射。依法需要保留的审计记录只保留最小事件、时间、操作者和哈希。

第二步：真正隔离开发与生产

每套环境都应拥有自己的 Composio 项目、API key、OAuth auth config、callback URL、connected accounts、webhook signing secret、日志索引和下游 SaaS 测试账户。不要只在同一个项目里增加一个 environment 字段来假装隔离。

隔离目标是：开发密钥无法读取生产连接；测试 webhook 无法触发生产写操作；测试成员不会占用真实客户身份；清理测试数据不会影响线上。OAuth 供应商支持 sandbox 时优先使用 sandbox，不支持时创建明确标记的测试组织和服务账号。

密钥放进 secret manager，不写入仓库、提示词、浏览器或日志。轮换时允许短暂双密钥窗口，验证新 key 生效后再撤销旧 key，并记录操作人、时间和受影响服务。

第三步：选择托管认证还是自定义认证

Composio managed auth 适合原型、内部测试和长尾 toolkit。平台维护 OAuth 应用，用户通过 Connect Link 授权，token 保存与刷新由 Composio 处理。它能缩短首次接入时间。

以下情况优先使用自己的 OAuth 应用和 auth config：

• 用户需要在 consent screen 看见你的产品名。
• 需要比默认配置更精确的 scopes。
• 需要独立供应商配额和限流。
• 客户要求明确的凭据所有权。
• 开发、预发布和生产必须使用不同回调。
• 核心连接需要专门的安全与合规审查。

不必一次把所有 toolkit 都切换。可以让 Gmail、Google Drive、GitHub、Slack 等核心高流量连接使用自己的 auth config，让低使用量长尾服务暂时保留 managed auth。每个 toolkit 记录负责人、scopes、回调、供应商审核状态和应急联系人。

切换认证方式前，确认现有用户是否需要重新授权。不要假设 managed app 创建的 token 可以迁移到自己的 OAuth app。准备分批迁移、用户提醒和失败回退。

第四步：把 OAuth scopes 缩到任务所需

先列任务，再选 scopes。客户支持 Agent 需要读取指定工单相关邮件，并在批准后发送回复，不等于需要读取全部邮箱、删除邮件或修改转发规则。

建立 scope 矩阵，列出 toolkit、动作、所需权限、是否写入、是否审批。例如邮件搜索只申请必要读权限并限制时间窗口；发送回复需要发送权限和人工批准；CRM 查询只开放指定对象；更新工单状态必须校验资源属于当前 tenant。

如果供应商 scope 粒度过粗，把限制下沉到执行网关：只允许特定资源、字段、时间窗口和目标。不能把“供应商只提供全量 scope”理解为 Agent 可以自由使用全量权限。

权限升级必须触发重新授权和解释。记录旧 scopes、新 scopes、原因、批准人和生效时间。定期扫描长期未使用连接和过宽权限，发起重新确认或撤销。

第五步：限制 Session 能看到的工具

不要默认暴露完整 toolkit 目录。根据 Agent 角色生成 allowlist。支持 Agent 可以看到工单查询、CRM 查询、知识库搜索、邮件搜索和草稿工具，但发送邮件应通过自家的受控工具执行。

受控发送工具只接受 approval ID。后端从数据库读取已批准的收件人、主题和正文，重新计算参数哈希，再通过 Composio 调用实际发送动作。这样模型不能在用户批准后偷偷修改参数。

工具 schema 应严格定义类型、长度和枚举。邮箱地址、资源 ID、URL、金额和日期都要验证，未知字段直接拒绝。工具搜索结果也要限制数量，让 Agent 在少量相关工具中选择，而不是从上千项中自由搜索。

记录搜索词、候选工具、最终选择、参数摘要和模型版本。模型选错工具时，团队才能知道是 allowlist 太宽、描述含糊，还是提示与模型行为问题。

第六步：设计安全连接流程

连接入口只来自已登录页面。后端确认 tenant、member 和 CSRF 状态后生成授权链接，不能让前端提交任意 user ID。callback 返回后，由后端查询连接状态并保存 connected account 与内部映射。

授权页面应清楚说明要连接的服务、申请 scopes、Agent 会执行的动作、哪些动作需要批准、数据经过哪些处理方、如何撤销和日志保留多久。

Connect Link 不应永久保存在数据库或日志。它是短期授权入口，应尽快过期。callback 使用 HTTPS、校验 state，并限制允许域名。

同一用户连接多个 Gmail 或 Slack 时，不要自动取第一个。保存账户别名、用途和默认状态；高风险动作再次展示目标账户。工作与个人账户必须清晰区分。

第七步：所有调用经过统一执行网关

不要让模型在任意代码路径直接调用 Composio。建立统一 execution gateway，顺序固定：

1. 验证登录用户、tenant、member 和 Agent 状态。
2. 解析工具名与参数。
3. 查询动作风险和 allowlist。
4. 校验资源所有权、字段、目标与速率。
5. 对写操作计算参数哈希与幂等键。
6. 检查人工批准。
7. 创建执行记录和 trace ID。
8. 调用 Composio。
9. 规范化结果并删除不必要敏感字段。
10. 更新状态、费用、错误与审计事件。

执行记录保存 trace、tenant、member、agent、tool、risk、parameter hash、idempotency key、approval ID 和 status。不要保存原始 token。Composio 返回的大 payload 也不要直接塞回模型，只保留任务需要的字段，并设置大小上限。

第八步：强制人工审批

审批不能只存在于提示词。模型说“我会先询问”不构成安全边界。审批必须由后端状态机执行。

Agent 先生成完整参数；后端规范化并计算哈希；界面展示账户、目标、影响范围和不可逆后果；审批人登录并明确同意；后端保存审批人、时间、参数哈希和过期时间；执行时重新计算哈希。只要参数变化，批准立即失效。

approval ID 一次使用。批量动作展示数量和样本，并设置硬上限。发送 2 封邮件与发送 2,000 封不能复用同一审批语义。删除、付款、权限变更最好走专用业务服务，不直接暴露通用工具。

第九步：处理幂等、重试和部分成功

网络超时不代表动作失败。下游可能已经发送邮件，只是响应丢失。立即重试会产生重复外部影响。

每个写操作生成稳定幂等键，例如 tenant、工单、动作类型和版本的组合，并在业务数据库建立唯一约束。相同键再次到达时返回已有状态。下游支持原生 idempotency key 时同时传递；不支持时，用业务对象查询确认结果。

错误分类处理：

• 401 或 403：停止重试，检查 scopes、连接或重新授权。
• 400 或 422：参数错误，交回校验或人工修正。
• 429：遵循 Retry-After 并设置最大等待。
• 5xx 或 timeout：指数退避；写操作先查询是否成功。
• 部分成功：记录已完成对象，只补偿未完成部分。
• schema 变化：冻结受影响工具版本或进入人工队列。

每个任务设置最大尝试次数和总时限。超限进入 dead-letter queue 并通知负责人。不要让 Agent 在模型循环中无限“再试一次”。

第十步：日志、隐私与数据保留

日志应足以调查问题，又不能成为新的敏感数据库。建议保存 trace ID、tenant、member、Agent 与模型版本、toolkit、工具名、连接内部引用、风险、审批 ID、参数哈希、时间、状态、错误分类和成本。

默认不保存 token、API key、完整邮件正文、附件、密码、支付信息或大段客户记录。调试时临时提高日志级别，要有工单、批准、自动过期和访问审计。

Composio 套餐可能提供不同日志保留、零数据保留、KMS、IP allowlist 或合规附加项。购买这些功能前先画完整数据流：你的服务、模型提供商、Composio、目标 SaaS、监控和仓库都可能保留副本。只在一层启用零保留不等于端到端零保留。

用户撤销连接后，立即停止新调用；在政策时间内删除映射和缓存；依法保留必要审计时只留最小事件。给用户提供清晰连接列表和撤销入口。

第十一步：连接失效与人员离职

OAuth refresh token 会过期，也可能被供应商或用户撤销。监控 connected account 状态，为 expired 或 invalid 连接提供重新授权入口。连续失败时暂停相关队列，避免无效调用和费用。

重新授权不能自动扩大 scopes。再次展示权限和原因，完成后更新策略版本。人员离职时停用内部账号、撤销个人连接、转移服务账号流程、取消审批、轮换共享 secret，并检查最近高风险动作。

第十二步：成本预算与暂停开关

为每个 tenant、Agent 和工具设置日/月预算。记录 tool calls、trigger events、premium tools、模型 tokens 和第三方 API 成本。在预算 70%、90% 和 100% 时分别告警、降级和暂停高成本能力。

工具搜索结果可以短期缓存，但版本变化后失效。批量读取用分页和服务端过滤；确定性步骤直接调用指定工具，不必每次让模型搜索。

截至 2026 年 9 月，Composio 新价格页对 Free、Pro、Enterprise、managed apps 和 add-ons 有不同规则，新旧账户可能处于过渡期。成本模型要可配置，每月与 Billing 对账，不要把当前价格硬编码进业务授权。

第十三步：上线前故障演练

必须完成这些测试：

• 用户 A 引用用户 B 的连接，系统拒绝。
• 同一用户连接两个 Gmail，明确选择目标账户。
• token 在任务中途过期，任务暂停并引导授权。
• webhook 重复投递三次，只产生一次写入。
• 下游成功但客户端超时，重试前查询并复用结果。
• 模型把读工具换成写工具，网关阻止。
• 审批后参数变化，旧 approval ID 失效。
• 日预算耗尽，高风险和 premium 工具停止。
• 管理员撤销 toolkit，排队任务不能继续。
• 日志导出没有 token、完整正文和附件。
• 供应商返回 429，队列退避并最终告警。
• 人员离职后，连接、审批、队列和共享密钥全部处理。

每个演练记录预期、实际、负责人和修复时间。失败用例未关闭前不要发布。“不会遇到”不是风险控制。

常见错误

把托管认证当完整业务授权，是最常见错误。Composio 能证明 user ID 有连接，但你的应用仍要证明请求者属于租户并有权执行动作。

第二个错误是开放整个 toolkit。工具越多，误选和越权面越大。只开放任务需要的动作，对写操作提供更窄包装。

第三个错误是记录原始 payload。短期排错方便，长期会让日志系统积累邮件、客户资料和附件。优先保存哈希、摘要和必要字段。

第四个错误是所有错误都自动重试。认证与参数错误不会因重试变好，写操作超时可能已经成功。重试必须按错误和幂等分类。

第五个错误是忽略许可证与合同。Composio SDK 或仓库的开源许可证，不代表托管服务、第三方 toolkit、品牌和供应商 API 可以任意复制或转售。商业上线前要分别审查。

什么时候该换别的工具

团队主要是业务用户、只想搭内部自动化时，Zapier Agents 更快。事件、代码和长工作流是中心时，Pipedream 更自然。必须自托管并想查看每个节点时，评估 n8n 或 Activepieces。

如果只有少数稳定 API，而且团队已有成熟 OAuth、secret manager、队列和审计，自建窄工具网关可能更简单。平台价值来自覆盖广度、连接生命周期和持续维护；规模太小时不一定划算。

上线检查清单

• 开发、预发布、生产项目和密钥隔离。
• user ID 来自不可变内部主键。
• tenant、member、Agent 与连接映射可审计。
• managed 或 custom auth 决策有记录。
• scopes 经过最小权限审查。
• Session 只暴露允许的 toolkit 和工具。
• 所有调用经过 execution gateway。
• 高风险写操作由后端强制审批。
• 写操作有幂等键和部分成功处理。
• 不同错误有不同重试策略。
• 日志脱敏、保留、访问和删除已验证。
• 连接撤销和人员离职流程已演练。
• 成本预算、告警和暂停开关已启用。
• 能在十分钟内禁用某个 Agent、toolkit 或租户。
• 能从业务数据库恢复审批与执行状态。

最终建议

先用一个只读工具和一个需要批准的写工具做小流量试点，不要一开始开放全部 toolkit。连续观察两周的连接失败、模型误选、重试、审批放弃率、调用成本和人工处理时间，再扩大范围。

Composio 能减少 OAuth、连接和工具维护工作，但生产安全来自清晰责任边界和应用侧控制。把 Session 当作受限运行上下文，把 connected account 当作高价值凭据，把每次写操作当作需要可证明授权的事务，才能让 Agent 从 demo 进入可维护系统。