Composio gateway: act on 1000+ connected apps like Gmail, Slack, GitHub, Calendar. Use when the user wants to act in a connected SaaS app (e.g. send Gmail, create Notion page, add Calendar event, open a GitHub issue).

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 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 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. Response (compact): 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. Response: 3. Execute a Tool Execute a Composio tool. Key name is arguments , not params . On success: On failure — includes tool schema so you can self correct: 4. List User's Connections (and confirm OAuth completion) 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 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: 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): 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 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":"..."} 2) 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 Response includes id (session id), status , and timestamps. Step 2: Build the CDP WebSocket URL Step 3: Control the Browser with Playwright Step 4: Delete the Session (IMPORTANT — stops billing) Key Concepts Aspect Detail Composio role Session lifecycle only — create, list, delete sessions Playwright role Page control — navigate, click, fill, scrape, screenshot Memory cost ~30 50MB locally (Playwright client only); Chromium runs on Browserbase servers Anti detection Browserbase handles it server side — fingerprint masking, captcha solving, Cloudflare bypass. Playwright client does nothing special. Billing Per minute (rounded up). Always delete sessions when done. Full Example Script (Create → Control → Delete) Available Browserbase Tools via Composio Tool Slug Purpose Key Arguments BROWSERBASE TOOL SESSIONS CREATE Create a browser session projectId BROWSERBASE TOOL SESSIONS DELETE Delete a session id BROWSERBASE TOOL SESSIONS GET Get session info id BROWSERBASE TOOL SESSIONS LIST List all sessions (none) BROWSERBASE TOOL SESSIONS GET DEBUG INFO Get debug info id BROWSERBASE TOOL SESSIONS STOP Stop a session id BROWSERBASE TOOL CONTEXTS CREATE Create persistent context projectId BROWSERBASE TOOL CONTEXTS DELETE Delete context id BROWSERBASE TOOL CONTEXTS GET Get context info id BROWSERBASE TOOL CONTEXTS LIST List contexts (none) BROWSERBASE TOOL CONTEXTS UPDATE Update context labels id , labels BROWSERBASE TOOL UPLOADS CREATE Upload file to session projectId , file data BROWSERBASE TOOL UPLOADS GET Get upload info id BROWSERBASE TOOL UPLOADS LIST List uploads (none) BROWSERBASE TOOL UPLOADS DELETE Delete upload id BROWSERBASE TOOL DOWNLOADS LIST List downloads sessionId BROWSERBASE TOOL DOWNLOADS GET Get download downloadId BROWSERBASE TOOL DOWNLOADS GET STREAM Stream download downloadId BROWSERBASE TOOL KB GET KNOWLEDGE Get KB article id Browserbase / Browser Tool troubleshooting If Browserbase is connected but execution fails, check naming mismatches across connection toolkit vs tool slug : Connection may appear as toolkit browserbase tool Search may return tool slugs like BROWSER TOOL CREATE TASK Execute may still reject that slug ( Tool ... not found ) and only resolve legacy slugs under toolkit browserbase Quick diagnosis: If error says No active connection found for toolkit 'browserbase' , gateway should normalize Browserbase aliases server side ( browser / browserbase / browserbase tool ) and normalize execute slug variants ( BROWSERBASE TOOL ↔ BROWSER TOOL ) so both old/new clients work with a browserbase tool active connection. Optimal Workflow (minimize tool calls) Known tool → Direct execute (1 call) If you already know the tool slug and parameters from previous use or the Common Tools table below, skip search entirely : Unknown tool → Search + Schema + Execute (2 3 calls) 1. Search (compact) → pick the right tool slug 2. Get schema (if param details unclear) → know exact argument format 3. Execute → with correct arguments If execute fails, the error response includes the full schema — so you can retry immediately without an extra schema call. Wrap in a script for repeat use For recurring queries, write a one shot Python script: Then future calls are just: bash("python3 scripts/calendar events.py 7 Asia/Hong Kong") — 1 tool call . Common Tools Quick Reference (skip search for these) 📧 Gmail Tool Slug Purpose Key Arguments GMAIL SEND EMAIL Send email to , subject , body , cc , bcc GMAIL FETCH EMAILS Fetch emails max results (int), label ids (list), q (Gmail search syntax) GMAIL CREATE EMAIL DRAFT Create draft to , subject , body Gmail Usage Examples: Gmail Response Parsing: Email data is in data.data.messages[] , each email has id , snippet , payload.headers[] (From/Subject/Date are in headers, lookup by name). 🐦 Twitter Tool Slug Purpose Key Arguments TWITTER CREATION OF A POST Create post text (required), media media ids , reply in reply to tweet id TWITTER POST DELETE BY POST ID Delete post id TWITTER POST LOOKUP BY POST ID Get single tweet id , tweet fields TWITTER RECENT SEARCH Search last 7 days query , max results (min 10) TWITTER USER LOOKUP ME Get own profile (no params) TWITTER USER LOOKUP BY USERNAME Get user profile username Twitter Usage Examples: Twitter Response Structure: Post/create returns data.data.data (3 level nesting), contains id , text , edit history tweet ids . Twitter — Post with Image (FileUploadable flow) Key constraint: the gateway's /internal/execute is a thin wrapper over Composio v2 actions/{slug}/execute — it does NOT support version pinning or FileUploadable synthesis. Twitter media upload tools ( TWITTER UPLOAD MEDIA , TWITTER UPLOAD LARGE MEDIA ) require both , so they MUST be called via the composio client Python SDK directly, not via gateway. The gateway is intentionally generic — keep all per tool flows (like this one) here in the skill. 3 step flow (proven working): Why this works (debugging notes — don't lose this knowledge): GET /api/v3/tools/TWITTER UPLOAD MEDIA returns 404 without a version because it lives in toolkit version 20260501 00+ , not the default 00000000 00 . client.tools.execute(version=...) routes through /api/v3/tools/execute/{slug} which IS version aware. Gateway uses v2 /api/v2/actions/{slug}/execute for execute — v2 has no version routing, so it can never reach versioned tools. Don't try to "fix" the gateway for this — adding version + FileUploadable would bloat it. Keep it thin. The media param expects {name, mimetype, s3key} (FileUploadable schema), NOT base64. Passing base64 returns: "Input should be a valid dictionary or instance of FileUploadable on parameter media ". File size limit for TWITTER UPLOAD MEDIA is ~5 MB. For larger files / videos / GIFs, use TWITTER UPLOAD LARGE MEDIA (chunked, same flow but additional segment params). ⚠️ Twitter Limitations & Fallback: TWITTER RECENT SEARCH only covers last 7 days , older tweets won't appear TWITTER FULL ARCHIVE SEARCH requires Twitter API Pro access , regular OAuth App can't use it When fetching user tweet history, prefer platform native tool twitter user tweets , not limited to 7 days 📅 Google Calendar Tool Slug Purpose Key Arguments GOOGLECALENDAR EVENTS LIST List events calendarId (default: "primary"), timeMin , timeMax (RFC3339+tz), singleEvents (true), timeZone GOOGLECALENDAR CREATE EVENT Create event calendarId , summary , start ,