composio

Composio

Hub skill for Composio-managed third-party app access from the swarm. Three call surfaces are available when the deployment has enabled them:

• CLI: agent-swarm x composio <METHOD> <path> [--body '<json>']
• MCP: swarm_x with target: "composio"
• Script connection: ctx.api.composio.<operationId>(args) inside a swarm script

COMPOSIO_API_KEY is deployment-scoped and injected by the CLI/API process — you never pass or see it. All paths are relative Composio REST paths.

Per-app playbooks (verified slugs + argument shapes + gotchas): [[composio-gmail]] · [[composio-google-calendar]] · [[composio-google-docs]]. Read the sibling skill for the app you're touching — it lists the verified tool slugs so you don't have to /search blind.

Core Model

• user_id is the app user whose connected accounts are used. A deployment commonly uses the person's email as user_id (for example, <connected-account-email>). Resolve it with the procedure below. There is no explicit "create user" call — a user is created implicitly the first time you reference its user_id (e.g. when you create a Connect Link). Don't look for a POST /users endpoint; it doesn't exist in this flow.
• Auth config (ac_…) = a project-level OAuth app config (one per toolkit, set up in the Composio dashboard). A project can have several.
• Connected account (ca_…) = a specific user's authorized connection to a toolkit. Persists across sessions under that user_id.
• Connect Link = the short-lived URL the user clicks to authorize OAuth.
• Tool Router session = a task/conversation runtime context that auto-resolves the right connected account for a toolkit set. Reuse its session_id; create a new one if the user, toolkit set, auth config, or pinned account changes.

Resolve the user and connected account

Do this before substituting any user_id or connected_account_id placeholder:

1. Read the current task details and take its requestedByUserId.
2. Call resolve-user with userId: "<requestedByUserId>". Inspect the returned externalIds for kind: "composio"; that entry's externalId is the Composio user_id.
3. List connected accounts filtered by that resolved value: GET /connected_accounts?user_id=<resolved-composio-user-id>. Select the requested toolkit's ACTIVE row and use its id as connected_account_id.
4. If the task has no requester, the requester has no Composio identity, or the filtered result is ambiguous, run GET /connected_accounts without a filter and compare the returned toolkit and user identity fields. If more than one account is still plausible, ask which identity/account to use. Never guess from another task's example.