Composio：把 1000+ 應用工具、使用者授權與 MCP 接進 AI Agent

很多 AI Agent 示範在模型吐出第一個 tool call 時就結束了。但只要把它放進真實產品，問題很快會從「模型會不會呼叫工具」變成「這個使用者能不能安全地呼叫正確工具，而且下一輪對話還能延續同一個連線」。

我認為 Composio 值得看的地方，不只是它列出 1000+ 個可用 toolkit，而是它把工具發現、帳號連接、每位使用者的 session、agent framework 整合與實際執行，整理成一個可以被程式重複使用的邊界。這讓 Agent 不必把所有工具定義一次塞進 context，也不必由每個應用團隊重新處理 OAuth 與 provider 格式。

本文以 GitHub 上的 Composio SDK monorepo 與官方文件為準，拆解它解決的問題、程式模型、上手方式，以及我認為導入前必須先釐清的限制。

先講結論：Composio 的價值在「工具生命週期」

Composio 官方把自己定位成給 AI agents 使用的工具與連接層，提供 1000+ 個預先整合的 toolkits、每位使用者的 sessions、authentication、triggers 與 sandbox。開源 repo 本身則是 SDK monorepo，包含 TypeScript SDK、Python SDK、Composio CLI，以及面向 OpenAI Agents、Claude Agent SDK、Vercel AI SDK、LangChain 等框架的 provider adapters。

這個定位和單純的 API wrapper 不同。API wrapper 通常只處理「如何送出請求」；Composio 還要處理「工具從哪裡找到」、「用哪個使用者身分連線」、「怎麼把工具轉成目前 agent framework 看得懂的格式」，以及「如何在後續回合重用同一個 session」。

因此，它最適合的不是一次性的函式呼叫，而是需要讓 Agent 代表不同使用者操作外部服務的產品：例如整理某位使用者的信件、更新 CRM、建立工作項目，或把一個多步驟流程交給 Agent 執行。

它把哪幾件容易失控的事放在一起？

工具發現：不要把數百個 schema 全塞進 context

官方 quickstart 說明，session 預設會取得用來 discovery、authentication 與 execution 的 meta tools。換句話說，Agent 可以在執行期間搜尋需要的應用工具，而不是在每次 prompt 一開始就攜帶一大包工具定義。

這個設計有兩個直接效果。第一，context 不會因為整合數量增加而線性膨脹。第二，工具選擇可以變成一個明確的執行步驟：先找工具，再確認連線狀態，最後執行。這不代表模型永遠會選對工具，卻讓應用程式有機會在每個階段加上限制、記錄與人工確認。

身分與 session：把「誰在操作」變成顯式參數

Composio 的 quickstart 以 user_123 建立 session，並強調每個 session 會以你的使用者為範圍。你可以保存 session.session_id，在下一輪透過 composio.use() 重用它，也可以在建立 session 時限制可用的 toolkits、auth configs 與 connected accounts。

這是導入企業流程時很重要的抽象。若把 OAuth token、工具清單與對話歷史全部散落在應用程式各處，權限邊界很容易變成隱含規則；把 session 當成邊界，至少能讓「使用者識別」、「連線狀態」與「可用工具範圍」進入同一個設計討論。

但「預先整合」不等於「使用者已授權」。正式產品仍需要設計登入、連接帳號、重新授權、撤銷權限與錯誤回報流程；Composio 負責提供這些能力的接點，產品仍要決定何時要求使用者確認。

Provider adapters：讓工具進入既有 Agent framework

repo 內的 provider adapters 對應多種框架。TypeScript 有 OpenAI、OpenAI Agents、Anthropic、Claude Agent SDK、Vercel、Google、LangChain、LlamaIndex、Mastra、Cloudflare 等整合；Python 也提供 OpenAI Agents、Anthropic、Google、LangChain、LangGraph、LlamaIndex、CrewAI 與 AutoGen 等套件。

這些 adapter 的價值不是新增一個模型，而是把 Composio session 產出的工具轉成框架原生格式。團隊可以保留既有的 Agent runner、prompt 與 tracing 方式，只替換工具取得與連接層。若框架不在清單中，官方文件也提供 custom provider 的方向；另一條路則是直接使用 MCP。

實作模型：Session → Tools → Agent

用最小模型看，流程可以拆成三步：

以你的使用者識別建立 Composio session。
從 session 取得工具，交給 agent framework。
由 Agent 根據自然語言意圖選擇工具，Composio 處理對應的連線與執行。

TypeScript 的官方 quickstart 以 OpenAI Agents 為例：

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: "Use Composio tools to take action.",
  tools,
});

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

這段程式最值得注意的不是 run，而是 session.tools()。工具不是全域常數，而是從一個使用者範圍的 session 產生。當你的產品開始支援多租戶時，這個差異會直接影響授權與快取設計。

Python 的概念相同，官方範例使用 composio、composio-openai-agents 與 openai-agents：

from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider
from agents import Agent, Runner

composio = Composio(provider=OpenAIAgentsProvider())
session = composio.create(user_id="user_123")
tools = session.tools()

agent = Agent(
    name="Personal Assistant",
    instructions="Use Composio tools to take action.",
    tools=tools,
)

result = Runner.run_sync(
    starting_agent=agent,
    input="Summarize my emails from today",
)
print(result.final_output)

真正上線前，我會在這個最小流程外再加三層：對高風險動作要求確認、在 server 端記錄 tool call 與回應摘要，以及對每個使用者保存可撤銷的連線狀態。不要因為 demo 只有一個 user_123 就把它當成全域 API key。

三種接入方式：SDK、CLI 與 MCP

SDK：適合應用程式內的細緻控制

TypeScript 與 Python SDK 都適合放進後端服務。你可以在建立 session 時處理使用者範圍，再按產品需求限制 toolkits 或 connected accounts。若應用已經選定 Agent framework，provider adapter 能減少自行轉換 tool schema 的程式碼。

SDK 路線的代價是你必須自己設計 session ID 的保存、併發控制、重試、審計紀錄與 UI。Composio 提供能力邊界，不會自動替你決定哪些外部動作必須二次確認。

CLI：把外部工具帶給 coding agent

repo README 將 composio CLI 定位成 shell 裡的工具面，提供 search、execute、link 與 run 等命令。官方安裝入口是：

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

這條路徑對 coding agent 特別有吸引力：Agent 可以先搜尋工具，再透過 CLI 執行或連接帳號。不過把能改動外部系統的 CLI 暴露給自動化 Agent 時，我會把 shell 權限、可用帳號與審計紀錄分開管理，並為破壞性動作設定明確的 allowlist。

MCP：把 session 暴露成標準工具端點

官方 README 指出，每個 session 也能提供 hosted MCP endpoint；建立 session 時傳入 mcp: true，再把 session.mcp.url 提供給 Claude、Cursor 或其他 MCP client。這讓 Composio 的連線與授權邏輯，能和支援 MCP 的客戶端分離。

MCP 的好處是整合面清楚：client 不必理解每一個應用的 OAuth 細節，只需要連到 session endpoint。代價則是你要更仔細處理 endpoint 的生命週期、權限、來源驗證與撤銷；MCP 不是把安全問題消失，而是把工具邊界搬到協定層。

我會怎麼評估它，而不是只看 toolkit 數量？

先看「你的 Agent 是否真的需要跨應用動作」

如果產品只是讀取一個內部資料庫，自己寫一個狹窄的 typed client 可能更容易測試與控權。Composio 的價值會在整合數量、使用者授權與 Agent framework 變成主要成本時放大。

再看權限是否能被限制與觀測

官方文件提供限制 toolkits、auth configs 與 connected accounts 的方向，但落地時仍要確認每個動作的權限模型、錯誤格式與回應資料是否符合你的要求。我會把下列項目列入驗收：

不同使用者建立的 session 是否真的隔離。
工具 discovery 是否只返回產品允許的範圍。
授權失效時，Agent 是否能得到可理解且不洩漏敏感資料的錯誤。
寫入、寄送、刪除等動作是否有額外確認。
每次 tool call 是否有 request ID、使用者與 session 的可追溯紀錄。

最後才看開發體驗

Composio repo 的 layout 把 TypeScript workspace、Python SDK、provider packages、CLI 與文件放在同一個 monorepo。這對想同時維護兩種語言的團隊很方便，也意味著升級時要留意 SDK、provider adapter 與 CLI 的版本配合。README 建議以 mise 管理 pinned toolchain，並以 pnpm 執行 build 與 test；Python 部分則從 python/ 目錄操作。

常見限制：它不是 Agent 的完整答案

第一，工具數量不等於任務成功率。模型仍可能選錯工具、填錯參數，或在需要多步驟確認時過早執行。你仍然需要 schema 驗證、重試策略、人工審核與 domain-specific guardrails。

第二，授權流程是產品工作，不是一次設定。你需要決定連接帳號的 UI、token 過期後的處理、使用者撤銷權限後如何讓 session 失效，以及企業客戶如何稽核操作。

第三，外部服務本身會改變。第三方 API 的配額、欄位、權限與錯誤格式都可能更新；在 production 不能只測「模型最後說了什麼」，還要測實際 tool call、外部副作用與回滾方式。

第四，Composio 的快速上手依賴 API key 與官方 dashboard。這使它更像一個開源 SDK 加上託管連線服務，而不是完全離線、只靠本機套件就能完成所有整合的工具。若你的部署要求所有憑證與執行都留在內網，應先確認架構與合規邊界。

適合誰先試？

我會建議以下團隊做一個小型 spike：

已有 Agent，但卡在多個 SaaS OAuth 與工具 schema 維護。
需要讓每位使用者以自己的帳號操作外部服務。
同時支援 TypeScript／Python，或正在比較 provider adapter 與 MCP。
想把工具 discovery 與實際執行拆成可觀測的流程。

第一個 spike 不要從「讓 Agent 控制所有應用」開始。選一個低風險、可回放的任務，例如列出今日信件摘要；完成登入、session 保存、tool call 記錄與失敗重試後，再加入寫入型動作。

相反地，如果需求只有單一 API、完全不需要每位使用者的授權，或部署環境不能接受託管連線服務，那麼直接維護一個小型 typed integration，通常更容易保持可預測。

結語：把 Agent 從「會回答」推進到「能負責任地行動」

Composio 的核心貢獻不是替模型增加一個神奇按鈕，而是把 Agent 行動時會遇到的幾個邊界集中起來：工具怎麼找、使用者是誰、連線怎麼保存、框架怎麼接，以及 MCP 如何對外暴露。

我會把它理解成一個工具生命週期層，而不是單純的工具目錄。當你的產品開始面對多使用者、多框架與多個外部應用時，這種抽象可以縮短第一個可運作版本的距離；但在正式導入前，仍要用權限隔離、審計、失敗處理與資料邊界驗證它，而不是只用 GitHub stars 或 toolkit 數量做決策。

參考資料