Composio:给 Agent 的每次外部操作绑定用户、账号和工具范围

新工具猫目发布于 来源:Composio 官方仓库及文档
session 负责发现、授权和执行的上下文;接入时要分清账号范围、结果状态,以及 SDK 与远程 MCP 的差别。
Composio:给 Agent 的每次外部操作绑定用户、账号和工具范围

为什么值得关注

外部动作可以沿同一用户session发现、完成账号连接并执行;应用能明确选择账号并检查真正的调用状态。

适合谁:已有Agent,需要按用户连接GitHub等外部服务并跨多轮保留操作上下文的开发者。

这次有哪些亮点

  • session 绑定稳定用户ID、工具范围、认证及已连接账号。
  • 默认元工具按需发现;固定职责可改用受限的直接工具列表。
  • 结果信封明确区分业务data、执行状态、日志ID与错误文字。

使用前需要知道

依赖Composio账户/API key、所选模型及用户服务授权。SDK代码MIT不代表托管平台可离线自托管;MCP会绕过SDK执行钩子与进程内自定义工具。配置更新须匹配当前SDK,服务网络与账号条件另核。

给研发助手接一个“创建 GitHub issue”的动作,真正要解决的往往还有两件事:这次代表哪个用户操作,用他的哪个账号?Composio 的当前 SDK 围绕 session 组织工具,把用户、可用工具、认证和已连接账号收进同一个运行上下文。它适合已有 Agent、想让应用按用户连接外部服务的开发者,尤其是需要把一次动作接到后续多轮任务时。官方仓库

一个用户的一次任务,先有明确的上下文

官方将用户 ID 定义为你自己应用中的稳定标识,例如数据库 ID,而不是会变化的昵称。应用先为这个用户创建 session,再将 session.tools() 交给 Agent;服务中的连接会保留在用户名下,后续任务可以再次使用已完成的授权。用户有多个同类账号时,还能在 session 中选择具体的 connected account。session 的定义

可以用一个未执行的教学情境理解:同事提交故障描述,请助手在工作账号对应的 GitHub 中建立 issue。输入是复现步骤与目标仓库,预期输出是创建结果及 issue 链接。模型组织参数,应用提供用户和账号范围,Composio 负责发现、授权与执行工具的连接流程。本文没有连接账号或创建 issue;用户在你应用里是谁,仍要由自己的登录系统映射,不能让模型临时编一个用户 ID。

封面截自官方文档,四个范围分别是用户、工具访问、认证和执行状态。它展示的是接口设计,不是上述故障任务的运行记录。

工具先发现,缺连接时再完成授权

默认 session 给 Agent 的是一小组元工具,先搜索相关能力,再管理连接、执行动作,避免把整个服务目录的所有工具定义都塞进提示词。需要连接账号时,可以由应用调用 session.authorize() 取得 Connect Link,也可以通过连接管理工具引导用户完成 OAuth;Composio 处理跳转、令牌交换与刷新。用户还没有完成授权时,“能发现工具”并不意味着已经可以操作账号。工具与认证流程

知道任务只需要很少几个工具,也可以采用 direct tools preset,直接提供限定后的工具列表。这个取舍与业务有关:探索式助手适合边找边用,固定职责的应用则可以先定义好范围。官方配置文档明确,省略 toolkits 默认开放目录发现,而显式空允许列表表示不提供任何 app toolkit;两种写法含义相反。原先 session 的更新也有版本条件,不能拿旧 SDK 套当前配置语义。范围配置

执行结束,要读结果状态而不只看错误文字

本篇认为最值得接入者记住的是返回值。session.execute() 返回的是信封:实际业务输出位于 data,另有执行状态、日志 ID 与错误信息。当前 Python 文档要求检查 result_type,TypeScript 对应 resultType;失败时错误文字可能为空,所以只判断 error 是否存在,会误把某些失败当成功。工具自身输出中偶尔有的 successful 字段,也不能替代通用执行状态。结果读取约定

对创建 issue 的应用,这意味着先确认调用完成,再从工具输出取链接;如果失败,应保留日志线索并反馈给用户,而不是让模型自行补一个“已创建”。同一轮对话继续工作时,可保存 session ID,再通过 composio.use() 复用,保留该任务的工具、认证与工作区上下文。创建新 session 与继续旧任务,是两个不同决定。

SDK 与托管服务分开判断

开始需要 Composio dashboard 的 API key、可用的模型与用户愿意连接的服务。当前仓库给出 Python 与 TypeScript 两套 SDK,Python 支持 3.10 及以上,TypeScript 路线测试 Node 22 及以上。所选 GitHub 等服务、OAuth 账号策略及实际网络可达性,仍需在自己的使用环境确认。

如果通过 MCP 接入,可创建带 MCP 的 session,将官方返回的 URL 与 headers 交给客户端。它与直接 SDK 路线共享账号和工具范围,但 SDK 中的执行钩子、schema 变换及进程内自定义工具不会自动随这条远程路径生效。已有应用依赖这些拦截逻辑时,应先评估传输路线。MCP 的具体取舍

仓库的 MIT 许可适用于 SDK 代码;本篇介绍的连接、session 和远程执行依赖托管服务,账户、额度和数据条件需另看,不能由 MIT 推导成整个平台可离线自托管。已经有 Agent、愿意管理用户映射与服务授权的开发者值得继续看;只接一个内部函数,或要求所有工具运行与数据都留在本地时,应先核对这条服务路线是否符合条件。

原始资料:Composio 官方仓库及文档

以上为编辑整理,功能、许可与使用条件以官方说明为准。

返回每日分享