用 Composio Skill 給 Agent 接上 1000+ 外部應用

大模型Skills Composio Agent Skill AI Agent OAuth Tool Router 2026-08-16 59 閱讀

前言

寫 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 構造函數，而不是隻裝核心包卻按另一套框架的工具格式去調。

典型用法

下面命令來自 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

相關文章

騰訊 CubeSandbox 開源：60ms 冷啓動的硬件級 AI Agent 執行環境 2026-07-29 MCP 最大版本更新：無狀態核心如何讓 AI Agent 真正上生產 2026-07-30 騰訊開源 CubeSandbox：60ms 冷啓動、硬件隔離的 AI Agent 執行沙箱 2026-07-30 OpenCode 未認證 HTTP 服務致 RCE：開源 AI 編碼 Agent 的安全紅線 2026-07-30 Google 發佈 Gemini 3.6 Flash：Token 效率提升 17%、Agent 默認模型的性價比之戰 2026-07-30
羽毛球分组比赛记分
小程序二维码

欢迎使用《羽毛球分组比赛记分》微信小程序

小夜