数据截至 2026-08-19(上游 commit 9fe68b96f0a7)

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」。你会撞上三堵墙:

手脚问题 —— LLM 只会输出文字,你得自己写代码把「调用 Gmail API」这件事接上。
鉴权问题 —— Gmail 要 OAuth 登录,每个终端用户一套 token,你得自己存、自己刷新、自己处理过期。
格式问题 —— 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、挂载所有 model	`ts/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:134`
`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/client`	Stainless 生成的 HTTP 客户端,发实际 API 请求	外部 npm 依赖,非本仓库源码(`core/package.json` 里 `"@composio/client": "catalog:"`,源码 `import ComposioClient from '@composio/client'`)

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

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

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

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

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

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

01 工具与执行主线 —— 先把脊梁搞清楚:tools.get / tools.execute 端到端,以及 before/after modifier 管线在哪插入。所有人先读这章。
02 Provider 适配器 —— Composio 最优雅的设计:同一份工具数据怎么用一个 wrapTool 方法适配 N 个 agent 框架;agentic 与 non-agentic provider 的本质差别。
03 鉴权与连接账户 —— authConfig / connectedAccount / connectionRequest 三层模型,OAuth 授权与轮询等待。想接真实的有鉴权 toolkit 必读。
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.ts`	`Composio`、`ComposioConfig`
工具主线	`ts/packages/core/src/models/Tools.ts`	`Tools.get`、`Tools.execute`、`Tools.getRawComposioTools`
Provider 基类	`ts/packages/core/src/provider/BaseProvider.ts`	`BaseNonAgenticProvider`、`BaseAgenticProvider`、`executeTool`
默认 Provider	`ts/packages/core/src/provider/OpenAIProvider.ts`	`OpenAIProvider.wrapTool`、`handleToolCalls`
鉴权连接	`ts/packages/core/src/models/ConnectedAccounts.ts`	`ConnectedAccounts.list`、`ConnectedAccounts.initiate`
OAuth 轮询	`ts/packages/core/src/models/ConnectionRequest.ts`	`createConnectionRequest`、`waitForConnection`
Tool Router	`ts/packages/core/src/models/ToolRouter.ts`	`ToolRouter.create`、`ToolRouter.use`
Router 会话	`ts/packages/core/src/models/ToolRouterSession.ts`	`ToolRouterSession.search`、`execute`、`authorize`
Python 入口	`python/composio/sdk.py`	`Composio`(Python)

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

一句话定义​

解决什么问题 / 给谁用​

它能做什么(功能)​

用起来什么样​

一句话直觉 / 类比​

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

怎么读下面这张图​

部件一句话职责​

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

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

4. 仓库结构速览​

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