Composio

Composio — External App Integration via Gateway

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.

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

Gateway Base URL

GATEWAY = "http://composio-gateway.flycast"

All requests use plain HTTP over Fly internal network (flycast). No JWT needed.

CRITICAL — never route the gateway through sc-proxy:

• Use curl (as in the examples below) or plain requests / http.client with no proxy.
• Do not use proxied_get / proxied_post for this host (even though PROTOCOL says “always proxied” for external APIs — flycast is the documented exception; core.http_client also auto-bypasses *.flycast).
• Do not set HTTP_PROXY / HTTPS_PROXY or curl -x toward the gateway.
• Proxying rewrites the caller identity so the gateway sees the wrong user and connections/execute fail or hit another locker.

API Reference

1. Search Tools (compact)

Find the right tool slug for a task. Returns compact tool info — just slug, description, and parameter names. Enough to pick the right tool.

curl -s -X POST $GATEWAY/internal/search \
  -H "Content-Type: application/json" \
  -d '{"query": "send email via gmail"}'

Response (compact):

{
  "results": [{"primary_tool_slugs": ["GMAIL_SEND_EMAIL"], "use_case": "send email", ...}],
  "tool_schemas": {
    "GMAIL_SEND_EMAIL": {
      "tool_slug": "GMAIL_SEND_EMAIL",
      "toolkit": "gmail",
      "description": "Send an email...",
      "parameters": ["to", "subject", "body", "cc", "bcc"],
      "required": ["to", "subject", "body"]
    }
  },
  "toolkit_connection_statuses": [...]
}

2. Get Tool Schema (full)

Get the complete parameter definitions for a specific tool — types, descriptions, enums, defaults. Use this after search when you need exact parameter formats.

curl -s -X POST $GATEWAY/internal/tool_schema \
  -H "Content-Type: application/json" \
  -d '{"tool": "GOOGLECALENDAR_EVENTS_LIST"}'

Response:

{
  "data": {
    "tool_slug": "GOOGLECALENDAR_EVENTS_LIST",
    "description": "Returns events on the specified calendar.",
    "input_parameters": {
      "properties": {
        "timeMin": {"type": "string", "description": "RFC3339 timestamp..."},
        "timeMax": {"type": "string", "description": "RFC3339 timestamp..."},
        "calendarId": {"type": "string", "default": "primary"}
      },
      "required": ["calendarId"]
    }
  },
  "error": null
}

3. Execute a Tool

Execute a Composio tool. Key name is `arguments`, not `params`.

curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GMAIL_SEND_EMAIL", "arguments": {"to": "x@example.com", "subject": "Hi", "body": "Hello!"}}'

On success:

{"data": {"messages": [...]}, "error": null}

On failure — includes tool_schema so you can self-correct:

{
  "data": null,
  "error": "Missing required parameter: calendarId",
  "tool_schema": {
    "tool_slug": "GOOGLECALENDAR_EVENTS_LIST",
    "description": "...",
    "input_parameters": {"properties": {...}, "required": [...]}
  }
}

4. List User's Connections (and confirm OAuth completion)

# Optional toolkit filter: oauth_completed_active only turns true
# when that toolkit status is ACTIVE.
curl -s "$GATEWAY/internal/connections?toolkit=gmail"

Response includes:

• connections: current deduplicated connection list
• oauth_completed_active: boolean, true only when OAuth completion is observed as ACTIVE

Cache invalidation is triggered only after ACTIVE is observed, and it targets the user's instance (fly-force-instance-id=<user container_id from user_mapping>), not composio-gateway's own instance.

5. Initiate New Connection

curl -s -X POST $GATEWAY/api/connect \
  -H "Content-Type: application/json" \
  -d '{"toolkit": "gmail"}'

Returns connect_url for the user to complete OAuth.

Zero-friction connect (MANDATORY when acting)

Trigger only when the user wants to perform an action in an external app (send/read mail, create calendar event, open GitHub issue, post, …) and that app is not connected yet.

Do not trigger for pure Q&A / explanations ("what is Gmail?", "how does Calendar work?").

1. Do not narrate connection checks, empty lists, OAuth mechanics, or ask "want me to connect?".
2. On Web (active SSE session): call the built-in tool for the one primary toolkit: `` frontend_action(action_type="composio_connect", toolkit="gmail") ` Optional: display_name="Gmail", title=..., description=.... Use the correct lowercase toolkit slug. **Do not** paste connect_url` markdown links — the frontend renders a Connect card from the action_request.
3. Visible reply: one short line about what you will do after they connect (no emoji chrome, no authorize URLs).
4. Stop and wait for the user to finish OAuth / Done, then continue the original task.
5. Never send the user to dig through the Connections page first.
6. Fallback (no SSE / non-Web channel, or frontend_action fails): ``bash curl -s -X POST $GATEWAY/api/connect \ -H "Content-Type: application/json" \ -d '{"toolkit": "gmail"}' ` Then give the bare connect_url` as plain text (still no markdown card soft-match required). If that also fails, say so in one short line and stop — do not invent alternate setup flows.

6. Disconnect

curl -s -X DELETE $GATEWAY/api/connections/{connection_id}

Instagram Posting (important slug mapping)

Composio search may return legacy Instagram slugs that are not executable in this environment. When posting to Instagram, use these working slugs:

1. Create draft container:

• INSTAGRAM_CREATE_MEDIA_CONTAINER
• Required: ig_user_id
• Typical args for photo: {"ig_user_id":"...","image_url":"https://...","content_type":"photo","caption":"..."}

1. Publish draft:

• INSTAGRAM_CREATE_POST
• Required: ig_user_id, creation_id

Two-step flow:

• Execute INSTAGRAM_CREATE_MEDIA_CONTAINER → read data.data.id as creation_id
• Execute INSTAGRAM_CREATE_POST with that creation_id

Tip: If /internal/search suggests INSTAGRAM_POST_IG_USER_MEDIA or INSTAGRAM_POST_IG_USER_MEDIA_PUBLISH but execute returns "Tool ... not found", switch to the two slugs above.

Browserbase — Hybrid Workflow (Session Management + Playwright CDP)

Composio's Browserbase tools ONLY manage session lifecycle (open/close/list). They do NOT control web pages.

To actually operate a browser (navigate, click, fill forms, scrape data), use Playwright `connect_over_cdp` to connect to the session's WebSocket URL.

Step 1: Create a Browserbase Session via Composio

curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "BROWSERBASE_TOOL_SESSIONS_CREATE", "arguments": {"projectId": "YOUR_PROJECT_ID"}}'

Response includes id (session_id), status, and timestamps.

Step 2: Build the CDP WebSocket URL

import os
session_id = "<session_id from step 1>"
api_key = os.environ.get("BROWSERBASE_API_KEY")  # stored in workspace/.env