ComposioHQ/composio · 上手攻略

• 仓库：ComposioHQ/composio
• 链接：https://github.com/ComposioHQ/composio
• 分类：ai / agent
• 作者：Jay
• 更新：2026-07-10

🎯 是什么

Composio 是一个 AI Agent 工具集成平台，为 AI Agent 提供 1000+ 预认证工具包（Toolkit），覆盖 GitHub、Gmail、Slack、Linear、Notion、Salesforce 等主流 SaaS。它解决的问题是：让 Agent 不只是"聊天"，而是真正"执行操作"——创建 issue、发送邮件、管理日历、查询数据库。

核心抽象是 Session（会话）——每个终端用户有一个独立会话，Composio 在该会话内统一管理工具发现、身份认证和执行上下文。你不需要预先加载数百个工具定义，Agent 通过 Meta Tools 在运行时动态发现和调用需要的工具。

类似于给 AI Agent 装上"插拔式工具底座"，开发者只需写一次集成，Agent 就能操作几乎所有主流应用。

关键数字：1000+ 工具包、支持 9+ Agent 框架、Stars 29,157、周增 +63（2026-07）

🧩 解决什么问题

⚡ 快速安装

TypeScript

npm install @composio/core @composio/openai-agents @openai/agents

Python

pip install composio composio-openai-agents openai-agents

获取 API Key

1. 访问 https://dashboard.composio.dev/settings 注册账号
2. 创建 COMPOSIO_API_KEY
3. 配置 .env：

# .env
COMPOSIO_API_KEY=your_composio_api_key_here
OPENAI_API_KEY=your_openai_api_key_here   # 若使用 OpenAI Agents
ANTHROPIC_API_KEY=your_anthropic_key_here  # 若使用 Claude

🔧 核心用法

1. 基本使用：OpenAI Agents（Python）

from dotenv import load_dotenv
from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider
from agents import Agent, Runner, SQLiteSession

load_dotenv()

# 初始化 Composio，绑定 OpenAI Agents Provider
composio = Composio(provider=OpenAIAgentsProvider())

# 为终端用户创建会话（user_id 建议用数据库主键，不要用 email）
session = composio.create(user_id="user_123")
tools = session.tools()

# 构建 Agent
agent = Agent(
    name="Personal Assistant",
    instructions="You are a helpful personal assistant. Use Composio tools to take action.",
    model="gpt-5.2",
    tools=tools,
)

# 多轮对话持久化（SQLite）
memory = SQLiteSession("conversation")

# 运行
result = Runner.run_sync(starting_agent=agent, input="Summarize my emails from today", session=memory)
print(result.final_output)

2. 会话持久化（多轮）

# 保存 session_id 到数据库，下次直接复用
session_id = session.session_id
# ...
session = composio.use(session_id)
tools = session.tools()  # 不需要重新创建

3. 限制工具包范围（减少噪音）

session = composio.create(
    user_id="user_123",
    toolkits=["gmail", "github"],  # 只暴露这两个工具包
)

4. MCP 协议接入（不用 Provider 包）

# 创建带 MCP 端点的 Session
session = composio.create(user_id="user_123", mcp=True)
print(session.mcp.url)   # 托管 MCP 服务器 URL
print(session.mcp.headers)  # 认证 Header，给 Cursor / Claude Desktop 用

5. Direct Tools 模式（不用 Meta Tools，直接列出工具）

from composio import Composio, SESSION_PRESET_DIRECT_TOOLS

session = composio.create(
    user_id="user_123",
    toolkits=["gmail"],
    tools={"gmail": {"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"]}},
    session_preset=SESSION_PRESET_DIRECT_TOOLS,
    mcp=True,
)
# 生成固定 URL，只暴露这两个工具

6. 支持的 Provider（框架）

7. CLI 工具

# 安装 CLI
curl -fsSL https://composio.dev/install | bash
composio login

# 搜索工具
composio search "github issue"

# 执行工具
composio execute github_create_issue --repo owner/repo --title "Bug fix"

# 连接账户
composio link --toolkit gmail

🏷 典型适用场景

1. 个人效率助手——在 Telegram/Discord 里发一条消息，让 Agent 查邮件、整理 GitHub issues、预约日历
2. 多租户 SaaS Agent——为每个终端用户在 Composio 建立独立 Session，Agent 以该用户身份操作数据
3. 跨平台工作流自动化——把 GitHub + Linear + Slack 串起来：issue 关闭 → 通知 Slack → 更新 Linear 状态
4. 快速验证 Agent 创意——不需要自己写 OAuth 逻辑，直接用现成工具包跑 MVP
5. MCP 协议接入——用 Claude Desktop 或 Cursor 时，直接把 Composio Session 作为 MCP Server 使用

⚠️ 坑与注意

1. API Key 必须启用工具调用——Composio 依赖 Agent 框架的 function calling 能力，基础 ChatGPT 模型（不支持工具调用）不可用
2. 每个 Session 的 Meta Tools 会动态发现——默认加载所有工具包的元工具（搜索、认证、执行），如果你只需要特定工具，请用 SESSION_PRESET_DIRECT_TOOLS 避免噪音
3. OAuth 连接需要用户操作——每个工具包的首次授权需要终端用户点击授权链接，Agent 在需要时会暂停并返回授权链接
4. 免费额度有限——Composio 有免费调用次数，超出需要付费（具体价格见 dashboard.composio.dev）
5. TypeScript 包包含源码——@composio/core 故意打包了 TypeScript 源码以方便 Coding Agent 检查；如果只需要运行时体积小，用 @composio/slim
6. Session 不要用 default user_id——生产环境不要用 default，否则所有用户共享认证和会话数据
7. MCP 端点由 Composio 托管——不是本地 MCP Server，URL 指向 Composio 平台，需要网络连通性

🔄 与同类对比

Composio 最大优势：开箱即用的 1000+ OAuth 认证工具包 + 多框架适配层，是目前接入工具最全的方案。缺点是需要平台账号（部分能力付费），不适合完全自托管场景。

✅ 一句话推荐

如果你正在构建需要"操作真实应用"的 AI Agent，而不是只做 RAG 问答，Composio 是目前最完整的工具集成底座——1000+ 工具包、9+ 框架适配、MCP 协议支持，一次接入即可跨所有主流 SaaS 行动。