前言¶

写 Agent 时最常见的卡住点，往往不在模型本身，而在「怎么连上别人的软件」。发一封 Gmail、在 Slack 回一条消息、给 GitHub 提一个 Issue，每接入一个服务就要读一遍 API 文档、走一遍 OAuth、处理 token 刷新和多用户隔离。应用一多，这部分工作会把真正的业务逻辑淹没掉。

Composio 做的事情，就是把这一层收成一套统一的 CLI 和 SDK：搜索工具、连接账号、执行动作、监听事件。官方又把这套用法写成了 Agent Skill，让 Cursor、Claude Code、Codex CLI 这类支持 SKILL.md 的编程助手，在需要操作外部应用时按同一套流程来，而不是每次重新翻文档。

本文介绍的是 ComposioHQ 维护的 composio Skill：它是什么、仓库里有什么、怎么装、怎么用 CLI 直接调工具，以及怎么在自己的 Agent 里用 SDK 接第三方应用。文中命令和配置均来自官方 Skill 原文、仓库 README，以及 docs.composio.dev 的交叉核对。

这是什么¶

composio 是 Composio 官方发布的 Agent Skill，仓库在 ComposioHQ/skills，协议为 MIT。Skill 目录位于 skills/composio/，入口文件 SKILL.md 的定位是：

Use 1000+ external apps via Composio - either directly through the CLI or by building AI agents and apps with the SDK

一句话：通过 Composio 使用 1000+ 外部应用，两条路并行——终端里用 CLI 直接执行，或者在自己的 Agent / 应用里用 SDK 集成。

Composio 本身是一个 Agent 执行平台。官方文档和 SDK 仓库都写明：它提供 1000+ 预认证 toolkit、按用户隔离的 session、托管 OAuth、Triggers，以及给编码 Agent 用的本地 CLI。Gmail、Slack、GitHub、Notion、Linear 这类服务，在 Composio 里被称作 toolkit；具体动作（例如创建 GitHub Issue）被称作 tool，slug 类似 GITHUB_CREATE_ISSUE。

Skill 仓库不只放了一份简介，结构如下：

skills/
└── composio/
    ├── SKILL.md           # 主入口：何时启用、CLI / SDK 两条路径
    ├── AGENTS.md          # 由规则文件自动合并的完整版
    └── rules/             # 分主题规则（CLI、Tool Router、Triggers 等）

SKILL.md 负责路由：先判断用户是「直接操作外部应用」还是「写代码做集成」，再指向对应规则。AGENTS.md 把各条规则拼成单文件，方便一次性读完。仓库 README 写明当前有 14+ 条规则，覆盖 Tool Router 与 Triggers，示例同时提供 TypeScript 和 Python。

核心功能¶

根据 SKILL.md 的「When to Apply」，这个 Skill 会在下面几类任务里被启用：访问 Gmail / Slack / GitHub / Notion 等外部应用；用外部服务做自动化（发邮件、建 Issue、发消息）；给 AI Agent 或应用接第三方工具；多用户应用需要按用户分别连接账号。

核实后，能力可以分成四块。

1. CLI 直接执行，不必先写集成代码

Skill 给出的主流程是 search → link → execute：先按自然语言搜工具，必要时把用户账号连上对应应用，再按 tool slug 执行。官方 CLI 文档同样把 composio search、composio execute、composio link 列成最常用的三条命令。CLI 还支持 composio proxy（用已托管的鉴权去调服务商原生 API）和 composio run（用内联 TypeScript 写多步工作流）。

2. SDK 给 Agent 做按用户隔离的 session

写代码时，官方推荐入口是 composio.create(user_id)（Python 侧也写作 composio.sessions.create(user_id=...)）。每个用户一个 session，连接和工具调用都绑在这个 ID 上。session.tools() 交给 Agent 的是一小撮用于发现、连接、执行的 meta tools，而不是一次把上千个工具 schema 塞进上下文。同一 session 还可以通过 session.mcp.url 暴露成 MCP 端点，给 Cursor、Claude Desktop 等 MCP 客户端用。

3. 托管 OAuth 与按用户连接

官方文档的默认路径是 Composio 托管鉴权：Agent 在运行时需要某个 toolkit 时再发起连接，用户打开 Connect Link 完成授权。OAuth 跳转、换 token、刷新由平台处理；连过一次之后，后续 session 可以复用已连接账号。多租户场景下，Skill 的 Tool Router 规则明确要求：不要多个用户共用一个 session。

4. Triggers：用外部事件驱动工作流

Skill 覆盖创建 trigger 实例、开发阶段订阅事件、生产环境校验 webhook、以及启用 / 停用生命周期。CLI 侧可以监听实时事件。当前官方 CLI 文档把事件流放在 composio dev listen 下；Skill 规则文件里仍写着顶层的 composio listen。以当前 CLI 文档为准更稳妥，命令以本机 composio --help 为准。

安装与启用¶

这里要分清两件事：把 Skill 装进 AI 编程工具，以及把 Composio CLI（以及可选的官方插件）装到本机。前者教 Agent「怎么用 Composio」，后者才是真正发请求、走 OAuth 的运行时。

1、安装 composio Skill¶

仓库 README 给出的安装命令是：

npx skills add composiohq/skills

officialskills.sh 上的等价写法是指定仓库和 skill 名：

npx skills add https://github.com/ComposioHQ/skills --skill composio

两条都指向同一仓库。npx skills add 是 Agent Skills 生态里的通用安装器，可以把 SKILL.md 链到各工具的 skills 目录。按 Cursor 文档与 skills CLI 的约定，常见落盘位置如下（以各工具官方说明为准）：

Cursor：项目级 .cursor/skills/ 或 .agents/skills/，用户级 ~/.cursor/skills/ 或 ~/.agents/skills/
Claude Code：项目级 .claude/skills/，用户级 ~/.claude/skills/
Codex CLI：项目级 .agents/skills/，用户级 ~/.codex/skills/

装完后重启 Agent，或按所用工具的说明重新加载 skills。也可以把 skills/composio/ 整目录拷到上述路径，保证目录名与 SKILL.md 里的 name: composio 一致。

2、安装并登录 Composio CLI¶

Skill 和官方 CLI 文档都要求：本机要有 CLI，并且已经登录。官方安装命令是：

curl -fsSL https://composio.dev/install | sh

SKILL.md 里写的是 | bash，安装脚本地址相同。安装器会把发行包放到 ~/.composio，在 ~/.local/bin/composio 建立入口，并改 shell 启动文件把 CLI 加进 PATH。支持 Linux x64 / ARM64、macOS Intel / Apple Silicon；Windows 需在 WSL 中安装。装完后开一个新终端，再登录：

composio login
composio whoami
composio --version

composio login 走 OAuth，登录后会有交互式的组织 / 项目选择；加 -y 可跳过选择器、用会话默认值。whoami 用来确认 org_id、project_id、user_id，官方说明 API key 不会显示在这里，也不要把这些值写死进代码。

Agent 没法直接打开浏览器时，Skill 给出两步登录：

composio login --no-wait | jq
# 把输出里的登录 URL 发给用户，对方在浏览器完成授权后：
composio login --key "<cli_key>" --no-wait

官方文档还提供面向 Codex / Claude Code 的原生插件安装：

composio setup --target auto

auto 会检测本机已安装的 Agent。只要其中一个时，可以用 --target codex 或 --target claude。非交互环境要加 --yes。这套插件和 ComposioHQ/skills 里的 composio Skill 是两条线：插件教 Agent 调本机 CLI；仓库里的 Skill 额外包含 SDK、Tool Router、Triggers 的完整规则。需要时可以两套一起用。

3、在项目里初始化 SDK¶

走 SDK 路径时，先在项目目录执行：

composio init

当前官方 CLI 文档把项目上下文初始化写在 composio dev init。以本机 CLI 帮助为准。API key 从 Composio Dashboard 获取，本地用环境变量：

COMPOSIO_API_KEY=your_composio_api_key

TypeScript SDK 需要 Node.js 22.22.3 或更高，且是 ESM-only，用 import 而不是 require()。Python SDK 需要 Python 3.10 或更高。

# TypeScript
pnpm install @composio/core@latest

# Python
pip install composio

按所用 Agent 框架再装对应 provider。TypeScript 常见包名：@composio/vercel、@composio/openai-agents、@composio/langchain、@composio/claude-agent-sdk。Python 常见包名：composio-openai-agents、composio-langchain、composio-langgraph、composio-crewai、composio-claude-agent-sdk。把 provider 传进 Composio 构造函数，而不是只装核心包却按另一套框架的工具格式去调。

典型用法¶

1、CLI：search → link → execute¶

下面命令来自 Skill 的 CLI 规则和官方 CLI 文档，可以在已登录的终端里直接跑。

先按用途搜工具。搜索结果里带连接状态，能看出账号是否已经连上对应应用。不要把 composio search 的输出用 head 截断，截断可能把更合适的匹配藏掉：

composio search "send an email"
composio search "create github issue"
composio search "summarize my unread gmail"

没有连接时再 link。默认会打开浏览器并等到账号变成 ACTIVE；Agent 或脚本场景加 --no-wait，打印 JSON（含 redirect_url）后立即退出：

composio link gmail
composio link github
composio link slack

执行前可以看参数 schema，再带上 JSON 数据调用。Skill 规则里长选项写成 --data，官方 CLI 文档和 SKILL.md 使用 -d：

composio execute GMAIL_SEND_EMAIL --help
composio execute GMAIL_FETCH_EMAILS --get-schema

composio execute GMAIL_SEND_EMAIL -d '{"recipient_email":"you@example.com","subject":"Hello","body":"Test"}'
composio execute GITHUB_CREATE_AN_ISSUE -d '{"owner":"acme","repo":"my-repo","title":"Bug report"}'

composio execute GMAIL_FETCH_EMAILS \
  -d '{ query: "is:unread newer_than:1d", max_results: 10 }'

代表某个用户执行时，加上 --user-id（CLI 默认用户上下文是项目的 test_user_id）：

composio execute GMAIL_SEND_EMAIL --user-id "user_123" -d '{"recipient_email":"them@example.com","subject":"Hi"}'

不确定 slug 时，先查 toolkit / tool，不要自己编名字：

composio manage toolkits info "gmail"
composio manage tools info "GMAIL_SEND_EMAIL"
composio search "send email"

当前官方 CLI 文档里，同类查询也出现在 composio dev toolkits ... 下。以本机帮助文本为准。

多步、可并行的工作流可以用 composio run，官方文档给过一个并行拉取邮件和 Issue 的例子：

composio run '
const [emails, issues] = await Promise.all([
  execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),
  execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "composiohq", repo: "composio", state: "open" }),
]);
console.log({ emails: emails.data, issues: issues.data });
'

2、SDK：按用户创建 session，把工具交给 Agent¶

Skill 的 Tool Router 规则强调：每个用户单独建 session，并显式限定 toolkit。TypeScript 示例如下（来自 tr-session-basic.md）：

import { Composio } from '@composio/core';

const composio = new Composio();

const session = await composio.create('user_123', {
  toolkits: ['gmail', 'slack']
});

console.log('Session ID:', session.sessionId);
console.log('MCP URL:', session.mcp.url);

Python 对应写法：

from composio import Composio

composio = Composio()

session = composio.create(
    user_id="user_123",
    toolkits=["gmail", "slack"]
)

print(f"Session ID: {session.session_id}")
print(f"MCP URL: {session.mcp.url}")

多轮对话不要每次 create()。官方 Quickstart 的做法是把 session.session_id（TS 为 session.sessionId）存进自己的数据库，下次用 composio.use(session_id) 恢复。生产环境里的 user_id 应换成应用数据库里的稳定用户 ID，示例里的 user_123 只适合本地试验。

接 OpenAI Agents 时，要用专门的 provider 包，不要误用面向 Chat Completions 的 @composio/openai / composio-openai。官方 README 的最小例子：

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

const composio = new Composio({ provider: new OpenAIAgentsProvider() });
const session = await composio.create("user_123");
const tools = await session.tools();

const agent = new Agent({
  name: "Personal Assistant",
  instructions: "You are a helpful assistant. Use Composio tools to take action.",
  tools,
});

const result = await run(agent, "Summarize my emails from today");
console.log(result.finalOutput);

需要走 MCP、又不想装框架 provider 时，把客户端指到 session.mcp.url（以及文档要求的 headers）即可。

3、在对话里直接让编码 Agent 办事¶

官方 Agent 插件文档给的提示词不依赖事先记住 slug，例如：

List the open GitHub issues assigned to me.
Summarize the unread Gmail messages I received today.
Create a Linear issue from these release notes: ...

Agent 会先 composio search，需要授权时走 composio link 并给出 Connect Link，批准后再 composio execute。本机已装 composio Skill 时，同类自然语言任务也会按 Skill 里的 CLI / SDK 规则处理。

适用场景与注意事项¶

比较适合下面几类工作：

个人或编码 Agent 在终端里直接操作已连接的 SaaS，不想为一次性任务写集成代码
要做多用户 Agent：每个终端用户连自己的 Slack / Gmail / GitHub，而不是共用一个机器人账号
用 OpenAI Agents、Claude Agent SDK、Vercel AI SDK、LangChain、CrewAI 等框架写 Agent，希望工具发现和鉴权由 session 托管
已有 MCP 客户端，希望通过 session 的 MCP 端点接到 Composio 的 toolkit
需要 Gmail 新邮件、GitHub 事件这类外部触发来驱动后续流程

使用时有几处需要留心。

不要编造 tool / toolkit 名称。 Skill 写得很明确：只用 composio search 返回的结果；应用名用 composio manage toolkits info 或 composio manage tools info 核对。写错 slug 会在运行时报错。

多用户必须按 user 隔离 session。 规则文件把「所有人共用一个 default session」标成错误示例。连接和调用都挂在 user_id 上，共用会串数据和权限。

生产集成走 SDK / API，不要把 CLI 当运行时合同。 官方 CLI 文档写明：CLI 仍在持续变动，没有作为应用运行时的 SLA。个人知识工作、编码 Agent、内部自动化可以用 CLI；对外产品应基于 SDK 和 REST API（当前文档推荐 https://backend.composio.dev/api/v3.1）。

CLI 命令有两套命名并存。 Skill 规则里常见 composio listen、composio manage ...、composio init；当前 CLI 文档把开发者命令收在 composio dev ... 下（例如 composio dev listen、composio dev init）。以本机 composio --help / composio --help full 为准。

直连执行和 session 不是同一条路。 composio.tools.get() / composio.tools.execute() 适合脚本里参数已确定的调用，且需要指定 toolkit 版本；Agent 在运行时自己选工具，用 session。两者取舍见官方 sessions vs direct execution。

Skill 规则里出现过「200+」的表述（building-with-composio.md），与 SKILL.md 前言、composio.dev、SDK 仓库 README 中的「1000+」不一致。以后者以及 toolkit 目录为准。

小结¶

composio Skill 把「Agent 要操作外部 SaaS」收成可复用的说明书：CLI 侧是 search、link、execute；SDK 侧是按用户建 session，把工具交给框架，OAuth 交给 Composio。它解决的不是某个单一 API，而是把鉴权、工具发现和多用户隔离从每个集成里抽出来。

官方地址：

Skill 仓库：https://github.com/ComposioHQ/skills/tree/main/skills/composio
Skill 说明页：https://officialskills.sh/composiohq/skills/composio
产品文档：https://docs.composio.dev
CLI：https://docs.composio.dev/docs/cli
SDK 仓库：https://github.com/ComposioHQ/composio

用 Composio Skill 给 Agent 接上 1000+ 外部应用

前言¶

这是什么¶

核心功能¶

安装与启用¶

1、安装 composio Skill¶

2、安装并登录 Composio CLI¶

3、在项目里初始化 SDK¶

典型用法¶

1、CLI：search → link → execute¶

2、SDK：按用户创建 session，把工具交给 Agent¶

3、在对话里直接让编码 Agent 办事¶

适用场景与注意事项¶

小结¶

精选优惠券

用 Composio Skill 给 Agent 接上 1000+ 外部应用

前言¶

这是什么¶

核心功能¶

安装与启用¶

1、安装 composio Skill¶

2、安装并登录 Composio CLI¶

3、在项目里初始化 SDK¶

典型用法¶

1、CLI：search → link → execute¶

2、SDK：按用户创建 session，把工具交给 Agent¶

3、在对话里直接让编码 Agent 办事¶

适用场景与注意事项¶

小结¶

精选优惠券

相关文章