Composio

Composio gives Agent Swarm a managed connection layer for third-party apps such as Gmail, GitHub, Slack, Notion, HubSpot, and similar tools. The current Agent Swarm integration is intentionally small: use the x command or the swarm_x MCP tool to route requests to Composio's Tool Router API.

What it does

• Creates Tool Router sessions. A session is Composio's runtime context for one user and a set of available toolkits.
• Uses connected accounts. Gmail, GitHub, and other app credentials live in Composio under the provided user_id, not in Agent Swarm.
• Generates Connect Links. If a user has not connected a toolkit yet, COMPOSIO_MANAGE_CONNECTIONS returns a hosted link at connect.composio.dev.
• Executes app tools. After a connection is active, the session can execute app tools such as GMAIL_FETCH_EMAILS.
• Works from CLI and MCP. Humans can run agent-swarm x composio ...; agents can call swarm_x with target: "composio".

Setup

Add a Composio project API key to the process running the CLI or swarm API:

COMPOSIO_API_KEY=your-project-api-key

Optional:

COMPOSIO_BASE_URL=https://backend.composio.dev/api/v3.1
COMPOSIO_ORG_API_KEY=your-org-api-key

The CLI sends COMPOSIO_API_KEY as x-api-key. With --org, it sends COMPOSIO_ORG_API_KEY as x-org-api-key.

How it works

1. Create a user-scoped session

agent-swarm x composio POST /tool_router/session \
  --body '{"user_id":"swarm-user-id","toolkits":{"enable":["gmail"]},"workbench":{"enable":false}}'

Store the returned session_id. Sessions persist on Composio's server and do not expire, but they should still be treated as task or conversation context in Agent Swarm.

2. Search for tools before executing

agent-swarm x composio POST /tool_router/session/$SESSION_ID/search \
  --body '{"queries":[{"use_case":"Check recent emails in Gmail and return metadata only."}]}'

Search returns the current tool slugs, schemas, recommended plan, pitfalls, and connection status. Do not invent tool slugs.

3. Connect the toolkit if needed

If search reports no active Gmail connection:

agent-swarm x composio POST /tool_router/session/$SESSION_ID/execute \
  --body '{"tool_slug":"COMPOSIO_MANAGE_CONNECTIONS","arguments":{"toolkits":["gmail"]}}'

Composio returns a Connect Link for the user. Incomplete connection attempts expire quickly, so generate a fresh link if the user misses the window.

4. Execute the app tool

agent-swarm x composio POST /tool_router/session/$SESSION_ID/execute \
  --body '{"tool_slug":"GMAIL_FETCH_EMAILS","arguments":{"user_id":"me","max_results":5,"include_payload":false,"verbose":false}}'

Prefer metadata-first reads unless the task explicitly needs message bodies, attachments, or destructive operations.

Session and account scoping

If a user has multiple accounts for the same toolkit, pin the desired account when creating the session or pass the account identifier when executing a tool. Without an explicit account, Composio uses its default account-selection behavior.

MCP tool

Agents can call swarm_x instead of shelling out:

{
  "target": "composio",
  "method": "POST",
  "path": "/tool_router/session/$SESSION_ID/execute",
  "body": {
    "tool_slug": "GMAIL_FETCH_EMAILS",
    "arguments": {
      "user_id": "me",
      "max_results": 5,
      "include_payload": false,
      "verbose": false
    }
  }
}

swarm_x injects Composio auth server-side and rejects absolute Composio paths so the API key cannot be routed to arbitrary hosts.

Skill

The composio skill is bundled under plugin/skills/composio. Use it when an agent needs Composio Tool Router sessions, connected accounts, Connect Links, or Composio app tool execution.

References

• Composio users and sessions
• Create a Tool Router session
• Execute a Tool Router tool
• Connected accounts
• Managing multiple connected accounts