跳到主要内容

Composio — 架构与原理

30 秒导读: LLM 自己只会「说」,不会「做」。Composio 是给 agent 装「手脚」的一层:它把 GitHub、Gmail、Slack 等上千个外部服务的 API 包装成 LLM 能调用的 tool,替你管好 OAuth 登录态,还能把同一份工具数据塞进任何 agent 框架(OpenAI、LangChain、Vercel AI SDK…)。本仓库是它的 SDK v3 monorepo,TypeScript 与 Python 双语言。

1. 这是什么(零基础也能懂)​

一句话定义​

Composio 是一个 agent 工具层 + 鉴权层:把「第三方 API」变成「LLM 工具(function calling)」,并替你处理每个用户对每个服务的登录授权。

解决什么问题 / 给谁用​

假设你在写一个 AI 助理,想让它「读我的 Gmail 未读邮件,在 GitHub 上开个 issue」。你会撞上三堵墙:

  1. 手脚问题 —— LLM 只会输出文字,你得自己写代码把「调用 Gmail API」这件事接上。
  2. 鉴权问题 —— Gmail 要 OAuth 登录,每个终端用户一套 token,你得自己存、自己刷新、自己处理过期。
  3. 格式问题 —— OpenAI 的 tool 格式、LangChain 的 tool 格式、Vercel AI SDK 的 tool 格式两两不同,换框架就得重写一遍工具定义。

Composio 把这三件事一次性接管。你只写「我要 GitHub 和 Gmail 的工具,给用户 user@acme.org」,剩下的它办。

它能做什么(功能)​

  • 拉工具:按 toolkit(如 GITHUB)或按工具 slug(如 GITHUB_CREATE_ISSUE)取回 LLM 可用的工具定义。
  • 执行工具:把 LLM 选好的工具 + 参数发到 Composio 后端,真正调用那个第三方 API,拿回结果。
  • 管鉴权:为每个用户发起 OAuth / API-Key 授权,保存「连接账户(connected account)」,执行时自动带上正确的凭据。
  • 适配框架:用「Provider」把同一份工具数据 wrap 成任意框架的格式。
  • Tool Router:工具太多(几千个)时,不把全部塞进上下文,而是给 agent 一个「搜工具 + 执行工具」的元工具,让它按需检索。

用起来什么样​

下面是 README 里的最小真实示例(README.md:54-79,TypeScript):

import { Composio } from '@composio/core';
import { OpenAIAgentsProvider } from '@composio/openai-agents';
import { Agent, run } from '@openai/agents';

const composio = new Composio({
  provider: new OpenAIAgentsProvider(),   // 选一个 agent 框架适配器
});

const userId = 'user@acme.org';

// 拉 HACKERNEWS 这个 toolkit 的工具,已经是 OpenAI Agents 能直接吃的格式
const tools = await composio.tools.get(userId, { toolkits: ['HACKERNEWS'] });

const agent = new Agent({ name: 'Hackernews assistant', tools });
const result = await run(agent, 'What is the latest hackernews post about?');

关键就一行 composio.tools.get(...):它去后端取工具 schema,套上 provider 格式,返回的工具里已经绑好了「执行函数」——agent 一旦选中某个工具,执行就自动打回 Composio 后端真正调用 HackerNews API。

一句话直觉 / 类比​

把 Composio 当成 agent 的「应用商店 + 单点登录(SSO)」。应用商店给你成千上万个「能力」(每个第三方 API 一套工具);SSO 替你和每个用户记住「他登录过哪些 app、凭据是什么」。你的 agent 只管说「我要用 GitHub」,不用关心 GitHub 的 OAuth 细节。

本节到此不碰任何底层代码。下一节看「大盘」。

2. 顶层全景(它大概怎么转)​

怎么读下面这张图​

从上到下是一次工具调用的生命周期:你的代码 → SDK 的几个 model → Composio 后端 → 第三方 API。SDK 本身几乎不实现业务逻辑,真正调 GitHub/Gmail 的活在 Composio 的云端后端;SDK 是一层「取 schema + 套格式 + 转发执行 + 跑 modifier」的客户端。

  你的 agent 代码
        │  composio.tools.get(userId, {toolkits:['GITHUB']})
        ▼
  ┌─────────────────────────────────────────────┐
  │            Composio (顶层门面类)              │   composio.ts
  │  持有 client + 一组 model:                    │
  │  tools / toolkits / triggers / authConfigs /  │
  │  connectedAccounts / sessions(ToolRouter)    │
  └───────┬───────────────────────────────┬───────┘
          │                               │
   ① 拉工具 + 套格式               ② 执行工具
          │                               │
  ┌───────▼─────────┐            ┌────────▼─────────┐
  │   Tools model   │            │  Provider 适配器  │
  │ get / execute   │◀──绑定───▶ │ wrapTool 把工具    │
  │ + modifier 管线 │  执行函数   │ 转成框架格式        │
  └───────┬─────────┘            └──────────────────┘
          │ HTTP (@composio/client)
          ▼
  ┌─────────────────────────────────────────────┐
  │           Composio 云端后端 (Apollo)          │
  │  真正调用第三方 API,管 OAuth token,版本化工具 │
  └───────┬─────────────────────────────────────┘
          ▼
   GitHub / Gmail / Slack / … 真实第三方 API

部件一句话职责​

部件干什么在哪个文件
Composio顶层门面:读配置、建 client、挂载所有 modelts/packages/core/src/composio.ts:165
Tools列举 / 取 / 执行工具,跑 modifier 管线ts/packages/core/src/models/Tools.ts:95
Provider(Base/OpenAI/…)把 Composio 工具 wrap 成某框架格式,注入执行函数ts/packages/core/src/provider/BaseProvider.ts:82
ConnectedAccounts / ConnectionRequest管「用户 × 服务」的授权连接,轮询等待 OAuth 完成ts/packages/core/src/models/ConnectedAccounts.ts:71
AuthConfigs管「某 toolkit 用哪套 OAuth app / 鉴权方式」ts/packages/core/src/models/AuthConfigs.ts
ToolRouter / ToolRouterSession工具太多时,创建一个会话,用 search + execute 元工具按需检索ts/packages/core/src/models/ToolRouter.ts:121
@composio/clientStainless 生成的 HTTP 客户端,发实际 API 请求外部 npm 依赖,非本仓库源码(core/package.json 里 "@composio/client": "catalog:",源码 import ComposioClient from '@composio/client')

主线走一遍(高层,不进代码)​

以「拉 GitHub 工具并执行一次」为例:

  1. composio.tools.get(userId, {toolkits:['GITHUB']}) → Tools 向后端要 GitHub 的工具 schema 列表。
  2. 拿到原始 schema(snake_case)→ Tools 转成 camelCase、跑「默认 schema modifier」(如文件上传字段处理)。
  3. Tools 把每个工具交给当前 Provider,wrapTool 套成框架格式,并把一个绑好 userId 的执行函数塞进去。
  4. agent 跑起来,模型选中某个工具 → 框架回调那个执行函数 → 最终走到 tools.execute(slug, {userId, arguments})。
  5. execute 跑 beforeExecute modifier → 发 HTTP 给后端 → 后端用该用户的 connected account 凭据真正调 GitHub → 返回结果 → 跑 afterExecute modifier → 还给 agent。

这条「get → wrap → execute → modifier」主线是整个 SDK 的脊梁。详见 01-tools-and-execute.md。

3. 阅读地图(建议顺序)​

这是个复杂项目,按下面顺序由浅入深读:

  1. 01 工具与执行主线 —— 先把脊梁搞清楚:tools.get / tools.execute 端到端,以及 before/after modifier 管线在哪插入。所有人先读这章。
  2. 02 Provider 适配器 —— Composio 最优雅的设计:同一份工具数据怎么用一个 wrapTool 方法适配 N 个 agent 框架;agentic 与 non-agentic provider 的本质差别。
  3. 03 鉴权与连接账户 —— authConfig / connectedAccount / connectionRequest 三层模型,OAuth 授权与轮询等待。想接真实的有鉴权 toolkit 必读。
  4. 04 Tool Router 与自定义工具 —— 工具规模化的杀手锏:用 search+execute 元工具收敛上下文;以及本地自定义工具的 in-process 执行。

4. 仓库结构速览​

Composio 是 TS + Python 双 SDK 的 monorepo,两边 API 设计刻意对齐(见 AGENTS.md 的 cross-sdk-parity skill)。

路径内容
ts/packages/core/@composio/core,主 SDK,本系列文档以它为准
ts/packages/providers/各框架适配器(openai / langchain / vercel / mastra / …)
ts/packages/cli/基于 Effect 的 CLI
python/composio/Python SDK,结构与 TS 一一对应
python/providers/Python 侧的框架适配器

TS 与 Python 的对应:composio.ts ↔ python/composio/sdk.py;models/Tools.ts ↔ python/composio/core/models/tools.py;provider 基类 BaseProvider.ts ↔ python/composio/core/provider/base.py。本文档主要引 TS,涉及双语言差异处会点明。

5. 代码地图(导航索引)​

主题文件关键符号
顶层门面 / 配置ts/packages/core/src/composio.tsComposio、ComposioConfig
工具主线ts/packages/core/src/models/Tools.tsTools.get、Tools.execute、Tools.getRawComposioTools
Provider 基类ts/packages/core/src/provider/BaseProvider.tsBaseNonAgenticProvider、BaseAgenticProvider、executeTool
默认 Providerts/packages/core/src/provider/OpenAIProvider.tsOpenAIProvider.wrapTool、handleToolCalls
鉴权连接ts/packages/core/src/models/ConnectedAccounts.tsConnectedAccounts.list、ConnectedAccounts.initiate
OAuth 轮询ts/packages/core/src/models/ConnectionRequest.tscreateConnectionRequest、waitForConnection
Tool Routerts/packages/core/src/models/ToolRouter.tsToolRouter.create、ToolRouter.use
Router 会话ts/packages/core/src/models/ToolRouterSession.tsToolRouterSession.search、execute、authorize
Python 入口python/composio/sdk.pyComposio(Python)