Back to Details

composio

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Composio — External App Integration via Gateway

Composio — 通过网关实现外部应用集成

Composio lets users connect 1000+ external apps (Gmail, Slack, GitHub, Google Calendar, Notion, etc.) to their Starchild agent. All operations go through the Composio Gateway (
composio-gateway.fly.dev
), which handles auth and API key management.
Composio支持用户将1000+外部应用（Gmail、Slack、GitHub、Google日历、Notion等）连接到他们的Starchild Agent。所有操作都通过Composio网关（
composio-gateway.fly.dev
）进行，由网关负责处理身份验证和API密钥管理。

Architecture

架构

Agent (Fly 6PN network)
    ↓  HTTP (auto-authenticated by IPv6)
Composio Gateway (composio-gateway.fly.dev)
    ↓  Composio SDK
Composio Cloud → Target API (Gmail, Slack, etc.)
  • You never touch the COMPOSIO_API_KEY — the gateway holds it
  • You never call Composio SDK directly — use the gateway HTTP API
  • Authentication is automatic — your Fly 6PN IPv6 resolves to a user_id via the billing DB
  • No env vars needed — the gateway is always accessible from any agent container
Agent (Fly 6PN network)
    ↓  HTTP (auto-authenticated by IPv6)
Composio Gateway (composio-gateway.fly.dev)
    ↓  Composio SDK
Composio Cloud → Target API (Gmail, Slack, etc.)
  • 你完全不需要接触COMPOSIO_API_KEY——由网关保管
  • 你不需要直接调用Composio SDK——使用网关的HTTP API即可
  • 身份认证自动完成——你的Fly 6PN IPv6地址会通过计费数据库关联到对应的user_id
  • 无需配置环境变量——所有Agent容器都可以直接访问网关

When to Use Composio

何时使用Composio

Use this skill when the user wants to:
  • Send/read emails (Gmail, Outlook)
  • Manage calendar (Google Calendar, Outlook Calendar)
  • Interact with code repos (GitHub, GitLab)
  • Send messages (Slack, Discord, Telegram)
  • Manage documents (Notion, Google Docs)
  • Any external SaaS integration
How to know if a user has connections: Check the system prompt — it includes a 
## Composio Connections
section listing active app connections. If the section is absent or empty, the user has no connections yet.
当用户需要执行以下操作时使用该技能：
  • 发送/读取邮件（Gmail、Outlook）
  • 管理日历（Google日历、Outlook日历）
  • 与代码仓库交互（GitHub、GitLab）
  • 发送消息（Slack、Discord、Telegram）
  • 管理文档（Notion、Google Docs）
  • 任何外部SaaS集成需求
如何判断用户是否已有连接？ 查看系统提示——其中包含
## Composio Connections
部分，列出了已激活的应用连接。如果该部分不存在或为空，说明用户还没有任何连接。

Gateway Base URL

网关基础URL

GATEWAY = "http://composio-gateway.flycast"
All requests use plain HTTP over Fly internal network (flycast). No JWT needed — the gateway identifies the agent by its 6PN IPv6 address.
GATEWAY = "http://composio-gateway.flycast"
所有请求都通过**Fly内部网络的纯HTTP协议（flycast）**发起。不需要JWT——网关通过Agent的6PN IPv6地址识别身份。

API Reference

API参考

1. List User's Connections

1. 列出用户的连接

Check what apps the user has already connected.
bash
curl -s http://composio-gateway.flycast/internal/connections | python3 -m json.tool
Response:
json
{
  "user_id": "554",
  "connections": [
    {"id": "ca_xxx", "toolkit": "gmail", "status": "ACTIVE", "created_at": "2025-03-19..."}
  ]
}
查看用户已经连接的应用。
bash
curl -s http://composio-gateway.flycast/internal/connections | python3 -m json.tool
响应：
json
{
  "user_id": "554",
  "connections": [
    {"id": "ca_xxx", "toolkit": "gmail", "status": "ACTIVE", "created_at": "2025-03-19..."}
  ]
}

2. Search Tools

2. 搜索工具

Find the right tool slug for a task using natural language.
bash
curl -s -X POST http://composio-gateway.flycast/internal/search \
  -H "Content-Type: application/json" \
  -d '{"query": "send email via gmail"}' | python3 -m json.tool
通过自然语言找到对应任务的工具slug。
bash
curl -s -X POST http://composio-gateway.flycast/internal/search \
  -H "Content-Type: application/json" \
  -d '{"query": "send email via gmail"}' | python3 -m json.tool

3. Execute a Tool

3. 执行工具

Execute a Composio tool on behalf of the user.
bash
curl -s -X POST http://composio-gateway.flycast/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GMAIL_SEND_EMAIL", "arguments": {"to": "x@example.com", "subject": "Hi", "body": "Hello!"}}' \
  | python3 -m json.tool
Response:
json
{"data": {"messages": [...]}, "error": null}
代表用户执行指定的Composio工具。
bash
curl -s -X POST http://composio-gateway.flycast/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GMAIL_SEND_EMAIL", "arguments": {"to": "x@example.com", "subject": "Hi", "body": "Hello!"}}' \
  | python3 -m json.tool
响应：
json
{"data": {"messages": [...]}, "error": null}

4. Initiate New Connection

4. 初始化新连接

When the user wants to connect a new app.
bash
curl -s -X POST http://composio-gateway.flycast/api/connect \
  -H "Content-Type: application/json" \
  -d '{"toolkit": "gmail"}' | python3 -m json.tool
Response:
json
{"connect_url": "https://connect.composio.dev/link/lk_xxx", "connection_id": "ca_xxx"}
Give 
connect_url
to the user — they click it to complete OAuth.
当用户需要连接新应用时使用。
bash
curl -s -X POST http://composio-gateway.flycast/api/connect \
  -H "Content-Type: application/json" \
  -d '{"toolkit": "gmail"}' | python3 -m json.tool
响应：
json
{"connect_url": "https://connect.composio.dev/link/lk_xxx", "connection_id": "ca_xxx"}
将
connect_url
提供给用户——用户点击链接即可完成OAuth授权。

5. Disconnect (Delete) a Connection

5. 断开（删除）连接

bash
curl -s -X DELETE http://composio-gateway.flycast/api/connections/{connection_id} \
  | python3 -m json.tool
Response:
json
{"status": "disconnected", "connection_id": "ca_xxx"}
bash
curl -s -X DELETE http://composio-gateway.flycast/api/connections/{connection_id} \
  | python3 -m json.tool
响应：
json
{"status": "disconnected", "connection_id": "ca_xxx"}

6. List Available Toolkits

6. 列出可用工具集

bash
curl -s http://composio-gateway.flycast/api/toolkits?limit=200 | python3 -m json.tool
bash
curl -s http://composio-gateway.flycast/api/toolkits?limit=200 | python3 -m json.tool

Workflows

工作流程

User wants to use an app (e.g. "send an email")

用户想要使用某个应用（例如“发送邮件”）

  1. Check system prompt for 
    ## Composio Connections
    section
  2. If Gmail is listed → skip to step 5
  3. If not connected → call 
    /api/connect
    with 
    {"toolkit": "gmail"}
  4. Give the user the 
    connect_url
    link. Wait for them to confirm they've authorized.
  5. Call 
    /internal/search
    with 
    {"query": "send email gmail"}
    to find the right tool slug
  6. Call 
    /internal/execute
    with the tool slug and arguments
  1. 检查系统提示中的
    ## Composio Connections
    部分
  2. 如果Gmail已在列表中 → 直接跳到第5步
  3. 如果未连接 → 调用
    /api/connect
    接口，传入参数
    {"toolkit": "gmail"}
  4. 将
    connect_url
    链接提供给用户，等待用户确认已完成授权
  5. 调用
    /internal/search
    接口，传入参数
    {"query": "send email gmail"}
    找到对应的工具slug
  6. 调用
    /internal/execute
    接口，传入工具slug和对应的参数

User asks "what apps can I connect?"

用户询问“我可以连接哪些应用？”

  1. Call 
    /api/toolkits
    to get the full list
  2. Present a curated summary (there are 1000+, so filter to popular ones)
  1. 调用
    /api/toolkits
    接口获取完整列表
  2. 向用户展示筛选后的精选列表（总共有1000+个，所以优先展示热门应用）

User asks "what apps do I have connected?"

用户询问“我已经连接了哪些应用？”

  1. Call 
    /internal/connections
  2. Show the list with status
  1. 调用
    /internal/connections
    接口
  2. 向用户展示带状态的连接列表

Common Tool Slugs

常用工具slug

AppToolDescription
Gmail
GMAIL_SEND_EMAIL
Send an email
Gmail
GMAIL_FETCH_EMAILS
Fetch recent emails
Gmail
GMAIL_GET_EMAIL
Get a specific email
Google Calendar
GOOGLECALENDAR_EVENTS_LIST
List events
Google Calendar
GOOGLECALENDAR_CREATE_EVENT
Create an event
GitHub
GITHUB_CREATE_ISSUE
Create an issue
GitHub
GITHUB_LIST_REPOS
List repositories
Slack
SLACK_SEND_MESSAGE
Send a message
Notion
NOTION_CREATE_PAGE
Create a page
When unsure of tool slug, always use 
/internal/search
first — it supports semantic search.
应用工具描述
Gmail
GMAIL_SEND_EMAIL
发送邮件
Gmail
GMAIL_FETCH_EMAILS
获取最近的邮件
Gmail
GMAIL_GET_EMAIL
获取指定邮件
Google Calendar
GOOGLECALENDAR_EVENTS_LIST
列出日程
Google Calendar
GOOGLECALENDAR_CREATE_EVENT
创建日程
GitHub
GITHUB_CREATE_ISSUE
创建Issue
GitHub
GITHUB_LIST_REPOS
列出仓库
Slack
SLACK_SEND_MESSAGE
发送消息
Notion
NOTION_CREATE_PAGE
创建页面
如果不确定工具slug，优先使用
/internal/search
接口——它支持语义搜索。

Important Notes

重要注意事项

  • Tool slugs are UPPERCASE: 
    GMAIL_SEND_EMAIL
    , 
    GITHUB_CREATE_ISSUE
  • Toolkit slugs are lowercase: 
    gmail
    , 
    github
    , 
    slack
  • Errors from Composio are returned as 
    {"data": null, "error": "..."}
    — show the error to the user
  • OAuth tokens are managed by Composio — they auto-refresh expired tokens
  • Data flows through Composio cloud — be mindful of sensitive data
  • 工具slug为全大写格式：
    GMAIL_SEND_EMAIL
    、
    GITHUB_CREATE_ISSUE
  • 工具集slug为全小写格式：
    gmail
    、
    github
    、
    slack
  • Composio返回的错误格式为
    {"data": null, "error": "..."}
    ——请将错误信息展示给用户
  • OAuth令牌由Composio管理——过期令牌会自动刷新
  • 数据会经过Composio云——处理敏感数据时请注意