Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | # Composio Platform |
| 2 | |
| 3 | Use this product when a developer is building an agent, application, or backend whose users connect their own accounts. Route by task instead of assuming every request is onboarding. |
| 4 | |
| 5 | ## Contents |
| 6 | |
| 7 | 1. [Choose the task](#choose-the-task) |
| 8 | 2. [Establish project access](#establish-project-access) |
| 9 | 3. [Integrate sessions](#integrate-sessions) |
| 10 | 4. [Choose tools and authentication behavior](#choose-tools-and-authentication-behavior) |
| 11 | 5. [Handle advanced product work](#handle-advanced-product-work) |
| 12 | 6. [Verify setup when relevant](#verify-setup-when-relevant) |
| 13 | 7. [Use canonical documentation](#use-canonical-documentation) |
| 14 | |
| 15 | ## Choose the task |
| 16 | |
| 17 | - **Explain or discover:** answer from this guide and current documentation without changing code. |
| 18 | - **First-time setup:** establish project access and the smallest working SDK path. |
| 19 | - **Integrate or extend:** inspect the codebase and add Composio to the existing agent architecture. |
| 20 | - **Operate:** discover, authorize, and execute tools for the application's current user. |
| 21 | - **Debug or migrate:** inspect the log ID and current implementation before changing credentials or architecture. |
| 22 | |
| 23 | When modifying code, first inspect and identify the language, package manager, agent or LLM framework, stable user or tenant ID, secret-loading mechanism, and smallest existing execution path where Composio tools belong. Extend that path; do not create a parallel demo agent when one already exists. Never infer filenames, framework choices, environment behavior, or identity fields that were not provided or observed. |
| 24 | |
| 25 | Use progressive disclosure. The basic path is project access, the core SDK, one user-scoped session, and the existing agent's tool interface. Do not add toolkit filters, tag policies, sandbox changes, custom auth, provider adapters, or production hardening unless the request or inspected code requires them. If essential repository context is missing, give the minimum stable outline and ask only for the missing detail instead of filling a large example with placeholders. |
| 26 | |
| 27 | ## Establish project access |
| 28 | |
| 29 | Choose exactly one credential path from context. |
| 30 | |
| 31 | ### Existing dashboard or repository credential |
| 32 | |
| 33 | If `COMPOSIO_API_KEY` already exists, or the developer arrived from Dashboard Getting Started after copying an `ak_*` project key, use that credential from the repository's existing environment or secret mechanism. |
| 34 | |
| 35 | In this path: |
| 36 | |
| 37 | - Never run `composio dev init` or select another project. |
| 38 | - Never create, rotate, replace, print, echo, log, or request the key in chat. |
| 39 | - Check only whether the environment variable exists and is not visibly masked or placeholder-like. |
| 40 | - When it lives in a file, check that the file is ignored by source control without printing the matching line. |
| 41 | - Let the first SDK request validate the credential; length is not validation. |
| 42 | |
| 43 | If the dashboard handoff is missing or masked, direct the developer back to Platform → project → Getting Started → Step 1. Do not silently switch to a provisioning flow. |
| 44 | |
| 45 | ### General first-time setup |
| 46 | |
| 47 | If there is no existing project credential and no dashboard handoff, use the current first-time setup path: |
| 48 | |
| 49 | ```bash |
| 50 | curl -fsSL https://composio.dev/install | bash |
| 51 | composio login |
| 52 | composio dev init |
| 53 | ``` |
| 54 | |
| 55 | `composio dev init` writes `COMPOSIO_API_KEY` and `COMPOSIO_TEST_USER_ID` to `.env.local`. Python dotenv does not load `.env.local` by default, so pass the path explicitly or move the variables through the project's normal secret mechanism. There is no bare `composio init` command. |
| 56 | |
| 57 | Verification stamp: these commands were exercised against CLI 0.2.32 and 0.3.1 on 2026-08-06. If the installed version differs or behavior conflicts, check `composio dev --help` and current docs rather than forcing the stamped behavior. |
| 58 | |
| 59 | ### Install the SDK the codebase needs |
| 60 | |
| 61 | ```bash |
| 62 | npm install @composio/core |
| 63 | pip install composio |
| 64 | ``` |
| 65 | |
| 66 | Add a provider adapter only when the existing framework needs one. Fetch the current provider index before naming a package: |
| 67 | |
| 68 | ```text |
| 69 | https://docs.composio.dev/docs/providers.md |
| 70 | ``` |
| 71 | |
| 72 | Do not introduce another LLM framework solely to demonstrate Composio. |
| 73 | |
| 74 | ## Integrate sessions |
| 75 | |
| 76 | If the application or MCP server already has its own tools and needs only per-user third-party authentication, follow [managed authentication for your own tools](https://docs.composio.dev/docs/authentication/managed-auth-for-custom-tools.md). Create a Connect Link with `session.authorize()`, then call provider endpoints with `composio.tools.proxyExecute()` in TypeScript or `composio.tools.proxy()` in Python. Keep the existing tool definitions and business logic. Skip `session.tools()` and catalog tool selection for this path. The proxy returns provider responses, not access or refresh tokens. Your application still authenticates its own callers. |
| 77 | |
| 78 | A session is the runtime context for one application user. It carries identity, connections, tool scope, and sandbox configuration. |
| 79 | |
| 80 | Trace the application's existing authenticated user or tenant ID and use that stable identifier. Do not add a parallel user system or share one placeholder identity across users. |
| 81 | |
| 82 | TypeScript: |
| 83 | |
| 84 | ```typescript |
| 85 | import { Composio } from "@composio/core"; |
| 86 | |
| 87 | const composio = new Composio(); |
| 88 | const session = await composio.create(existingUserId); |
| 89 | const tools = await session.tools(); |
| 90 | ``` |
| 91 | |
| 92 | Python: |
| 93 | |
| 94 | ```python |
| 95 | from composio import Composio |
| 96 | |
| 97 | composio = Composio() |
| 98 | session = composio.create(user_id=existing_user_id) |
| 99 | tools = session.tools() |
| 100 | ``` |
| 101 | |
| 102 | Both SDKs also expose `composio.sessions.create(...)`; do not teach an artificial TypeScript/Python asymmetry. The SDK reads `COMPOSIO_API_KEY` from the environment, so do not pass it inline. |
| 103 | |
| 104 | For a multi-turn conversation, persist the returned session ID and resume it instead of creating a fresh session on every message. Use the [Session API lookup](#look-up-the-session-api) below for exact method names and configuration shapes. |
| 105 | |
| 106 | Pass the session tools to the repository's existing model or agent using its native tool integration. Preserve the current prompt, model, streaming, and request lifecycle unless tools require a targeted change. |
| 107 | |
| 108 | ### Look up the Session API |
| 109 | |
| 110 | Fetch the relevant Markdown page directly when you need an exact signature, option shape, or return type. Search-result summaries can omit code: |
| 111 | |
| 112 | - [TypeScript creation and reuse](https://docs.composio.dev/reference/sdk-reference/typescript/sessions.md) |
| 113 | - [TypeScript Session methods and results](https://docs.composio.dev/reference/sdk-reference/typescript/session.md) |
| 114 | - [Python Session methods and results](https://docs.composio.dev/reference/sdk-reference/python/session.md) |
| 115 | - [Create options and configuration updates in both languages](https://docs.composio.dev/docs/configuring-sessions.md) |
| 116 | |
| 117 | Check the installed SDK version first. Prefer its bundled reference for that version when it differs from the current website. API discovery does not require constructing a client, providing an API key, or calling the backend. Public Session types can retain the former `ToolRouter` name; follow their definitions rather than guessing a renamed import. |
| 118 | |
| 119 | ## Choose tools and authentication behavior |
| 120 | |
| 121 | For Instant Tools, read https://docs.composio.dev/docs/instant-tools.md before choosing authentication or usage settings. Use that guide for current eligibility, pricing, project access, Session controls, account routing, and charge reporting. |
| 122 | |
| 123 | Sessions expose a small set of meta tools by default so the agent can discover integrations and authenticate at runtime: |
| 124 | |
| 125 | - `COMPOSIO_SEARCH_TOOLS` |
| 126 | - `COMPOSIO_GET_TOOL_SCHEMAS` |
| 127 | - `COMPOSIO_MULTI_EXECUTE_TOOL` |
| 128 | - `COMPOSIO_MANAGE_CONNECTIONS` |
| 129 | - `COMPOSIO_WAIT_FOR_CONNECTIONS` |
| 130 | - `COMPOSIO_REMOTE_WORKBENCH` |
| 131 | - `COMPOSIO_REMOTE_BASH_TOOL` |
| 132 | |
| 133 | Keep connection management enabled for interactive agents. It returns a Connect Link when a user needs to authorize an app; do not build a provider OAuth flow. |
| 134 | |
| 135 | Before you restrict a session, check whether the request names a toolkit. A capability request such as "send an email" doesn't name Gmail, Outlook, or any other toolkit. Keep the default meta tools so the agent can find the toolkit and tool with `COMPOSIO_SEARCH_TOOLS`. Restrict the session only when the user, the application's configuration, or the inspected code names the toolkit. Then enable only that toolkit and keep the meta tools. |
| 136 | |
| 137 | Use the direct-tools preset only for a narrow, deterministic agent with a fixed allowlist. It removes meta tools by default. Re-enable connection management when users must authenticate in the agent, and keep or disable the sandbox deliberately. Fetch `configuring-sessions.md` for the current preset and option syntax before implementing it. |
| 138 | |
| 139 | If the application has its own connect UI, use session authorization and connection-state methods and suppress in-chat connection prompts. Use managed auth initially. Create a custom auth config only for the application's OAuth branding, additional scopes, dedicated provider quotas, or self-hosted or regional requirements. |
| 140 | |
| 141 | ### Composio Built or Provider MCP |
| 142 | |
| 143 | Some products ship more than one toolkit grouped as one App in the catalog, for example a Composio Built toolkit (`notion`) and a Provider MCP toolkit backed by the product's own MCP server (`notion_mcp`). Use the catalog grouping; do not derive membership from names or suffixes. Different jobs or acting identities can remain separate. They are separate toolkits with separate auth configs and connected accounts. Session config takes exact slugs, never an App: enable one sibling (`toolkits: ["notion"]`), enable both (`toolkits: ["notion", "notion_mcp"]`), or use the disable list to remove the sibling the agent should not see (syntax in `configuring-sessions.md`). Enabling `notion` does not expose `notion_mcp`, and the siblings never share a connection. When the request or code names a slug, use it. Otherwise compare auth schemes, connected state, tool lists, and triggers (triggers exist only on Composio Built toolkits today), prefer the toolkit the user can authenticate, and state which one you chose. Do not assume Provider MCP means DCR OAuth: some need no auth at all, and a few use API Key or OAuth2. Read what the toolkit declares. Details: `https://docs.composio.dev/docs/apps-and-toolkits.md`. A Custom MCP server registered into the project (slug `CUSTOM_*`) is separate from both; see the `extending-sessions` guides. |
| 144 | |
| 145 | ## Handle advanced product work |
| 146 | |
| 147 | Do not force advanced requests through first-time setup. Route them to current documentation: |
| 148 | |
| 149 | - Session scoping, account selection, callbacks, direct tools, and sandbox controls: `configuring-sessions.md` |
| 150 | - Asking the user before a tool runs: `approvals.md`, covered in [Require approval before tools run](#require-approval-before-tools-run) |
| 151 | - Blocking tool calls, tool results, or prompt injection: `firewall.md`, covered in [Block calls and results with Firewall](#block-calls-and-results-with-firewall) |
| 152 | - Adding a remote MCP server as a toolkit: `extending-sessions/custom-mcp.md`, covered in [Add a remote MCP server](#add-a-remote-mcp-server) |
| 153 | - Custom tools and toolkits that run in the application, or proxy execution: the other `extending-sessions` guides |
| 154 | - Custom connection UI: `authentication/manually-authenticating.md` |
| 155 | - Triggers and webhooks: `triggers.md` and the setting-up-triggers guides |
| 156 | - Legacy direct execution, MCP servers, or Tool Router migrations: the migration and sessions guides |
| 157 | - White labeling and custom OAuth apps: `white-labeling-authentication.md` |
| 158 | |
| 159 | "Tool Router" is the former name for sessions. Treat direct execution as a migration path, not the default for new agent integrations. |
| 160 | |
| 161 | Approvals, Firewall, and Custom MCP are experimental. Fetch their current page before writing code, check the installed SDK version against the minimum the page names, and copy the documented call shape for the requested language. Add them only when the request or inspected code asks for that control. A request like "ask before sending", "confirm before writes", or "human in the loop" asks for Approvals. A request like "never let the agent email pricing" or "stop prompt injection" asks for Firewall. |
| 162 | |
| 163 | ### Require approval before tools run |
| 164 | |
| 165 | Approvals make Composio pause a tool call and ask the user before it runs. Composio doesn't run the tool. It returns an elicitation, then runs the tool when the call comes back with the user's answer. |
| 166 | |
| 167 | Choose the gated tools when you create the session: |
| 168 | |
| 169 | - By tag, session-wide: `tags={"require_approval": ["createHint", "updateHint", "destructiveHint"]}` in Python, `tags: { requireApproval: [...] }` in TypeScript. |
| 170 | - By tag, per toolkit: set `tools.<toolkit>.tags`. It replaces the session-wide `tags` for that toolkit, including blocked tags, so list everything that toolkit still needs. |
| 171 | - By tool: set `tools.<toolkit>.require_approval` (`requireApproval` in TypeScript) to exact tool slugs. Prefer explicit slugs for anything that must always be gated: Composio assigns tags on a best-effort basis. |
| 172 | |
| 173 | Handle the pause in the application's tool loop: |
| 174 | |
| 175 | 1. Run tools with `session.execute()`. The SDK's `handle_tool_calls` and framework providers don't handle approvals yet. |
| 176 | 2. Catch `ToolInputRequiredError` (Python, from `composio.exceptions`) or `ComposioToolInputRequiredError` (TypeScript). Over the API, the response has `"result_type": "input_required"`. |
| 177 | 3. Show the user each entry in `input_requests`: its `message`, and a form built from its `requested_schema`. Build the form from the schema, since choices vary. One call can return several questions, for example from `COMPOSIO_MULTI_EXECUTE_TOOL`. |
| 178 | 4. Retry the same call with `input_responses` (each `{"action": "accept", "content": {...}}`, keyed by question ID) and the returned `request_state`. |
| 179 | |
| 180 | An **Always approve** answer lasts for the rest of the session for that tool on the same connected account. |
| 181 | |
| 182 | Over MCP, clients that support elicitation ask the user themselves. Clients without elicitation support get the call denied, unless the session sets `experimental.no_elicitation_support_fallback` to `"allow"`. Only suggest that fallback when the developer accepts running those tools without approval. |
| 183 | |
| 184 | Tell the developer about the documented limits when they matter: Workbench and bash scripts can call tools the approval check misses (disable the sandbox if approval must never be skipped), and `session.proxy_execute()` is disabled for a toolkit with any approval-gated tool. |
| 185 | |
| 186 | ### Block calls and results with Firewall |
| 187 | |
| 188 | Firewall blocks tool calls the agent shouldn't make and tool results it shouldn't read. Configure it with session `hooks`. Each hook needs a unique `id`, a `type`, an `applies_to` (`appliesTo` in TypeScript) of toolkit slugs or `"all"`, and a `handler`. |
| 189 | |
| 190 | - `before_execute` with a `condition_check` handler blocks a call before it runs, such as emailing internal pricing to a customer. |
| 191 | - `after_execute` with a `condition_check` handler blocks a result before the agent reads it, such as an email that contains an API key. |
| 192 | - `after_execute` with a `prompt_injection_check` handler blocks results that contain prompt injection. It works only in `after_execute`. |
| 193 | |
| 194 | Write each `condition` as a description of what to block, not as an instruction to the agent. "Sharing internal pricing with anyone outside acme.com" works. "Don't share internal pricing" does not. |
| 195 | |
| 196 | A blocked call returns `result_type` `blocked`, the error `Blocked by session policy`, and a `block_reason` and `hook_results` naming the hook. This is a policy outcome, not a tool or auth failure. Don't retry it or reconnect the account. |
| 197 | |
| 198 | `session.update(hooks=[...])` replaces the whole hook list, so include every hook to keep. Hooks don't run on meta tools themselves, but they do check tool calls made through multi-execute, Workbench scripts, and proxy calls. Firewall is a paid-plan feature, and with Zero Data Retention the classifier judges each call without earlier session context. |
| 199 | |
| 200 | ### Add a remote MCP server |
| 201 | |
| 202 | Custom MCP adds a remote MCP server as a Composio toolkit, so its tools sit next to Composio's toolkits in a session. Use it for an MCP server on a public HTTPS URL. Use Custom Tools and Toolkits instead for functions that run inside the application. |
| 203 | |
| 204 | 1. Create the toolkit with `composio.experimental.custom_toolkits.create()` in Python or `composio.experimental.customToolkits.create()` in TypeScript. Pass `name`, the final MCP endpoint as `app_url` (no redirects, no keys in the URL), `auth_schemes`, and `user_id`. |
| 205 | 2. Store the returned `CUSTOM_*` slug. Never construct it yourself. |
| 206 | 3. If a private toolkit needs auth, send its user to the returned `connect_link.redirect_url`. `connect_link` is `null` for shared and no-auth toolkits. Tools sync on creation for no-auth servers, and when the first account connects otherwise. |
| 207 | 4. Add the slug to a session's toolkits. The agent finds the tools with `COMPOSIO_SEARCH_TOOLS`. |
| 208 | |
| 209 | Choose `user_id` deliberately: `"all"` shares the toolkit with every user in the project, and a user ID makes it private to that user. Choose `auth_schemes` mode `NO_AUTH`, `API_KEY` (a header containing `{{generic_api_key}}`), or `DCR_OAUTH` (with a `discovery_url`). `app_url`, `auth_schemes`, and `user_id` can't change later: delete and create the toolkit again. |
| 210 | |
| 211 | Know the limits before promising a design: remote servers only (no local or STDIO), at most 500 tools, OAuth only through Dynamic Client Registration, and no automatic resync. Call `sync()` when the server's tools change. `upsert()` is deprecated: new code uses `create()` and `update()`. |
| 212 | |
| 213 | ## Verify setup when relevant |
| 214 | |
| 215 | For a first-time setup or integration request, verify a safe, read-only provider request from the developer's real execution path: |
| 216 | |
| 217 | - For auth-only integrations with existing tools, call a provider endpoint through Proxy Execute using the intended user's connected account. Verify a successful HTTP status and the expected provider response. Catalog tool discovery and a Composio tool log ID are not required for this path. |
| 218 | - For catalog-tool integrations, discover the real toolkit and tool at runtime. Verify an actual provider result and a non-empty Composio log ID. If the current user is not connected, check the Instant Tools guide before assuming a connection is required. |
| 219 | |
| 220 | Ask which integration the developer wants to try unless the application already makes the choice clear. When authentication is required, return the Connect Link, wait for authorization, and retry. |
| 221 | |
| 222 | A mock, Playground run, tool search, schema fetch, session creation, or Connect Link alone does not prove the integration. If the repository has no runnable execution path, add only the smallest entrypoint compatible with its existing runtime; do not require another hosted model. |
| 223 | |
| 224 | After success, report the code location, user and account mapping, session ID when used, and safe result summary. For auth-only integrations, include the provider endpoint and HTTP status. For catalog-tool integrations, include the tool and Composio log ID. For an explanation, migration plan, or narrow bug fix, use that task's own completion condition instead of forcing a new tool call. |
| 225 | |
| 226 | ## Use canonical documentation |
| 227 | |
| 228 | Fetch current Markdown before giving version-sensitive commands or editing SDK integration code: |
| 229 | |
| 230 | ```text |
| 231 | https://docs.composio.dev/llms.txt |
| 232 | https://docs.composio.dev/docs/<page>.md |
| 233 | https://docs.composio.dev/toolkits/<toolkit>.md |
| 234 | ``` |
| 235 | |
| 236 | Read [Errors and provider gotchas](errors.md) for failures shared across products. |
| 237 | |
| 238 | ## Do not |
| 239 | |
| 240 | - Do not replace a dashboard-provided credential with a general setup flow. |
| 241 | - Do not stop at documentation when the user asked for implementation. |
| 242 | - Do not guess toolkit or tool slugs. |
| 243 | - Do not create auth configs as a universal prerequisite. |
| 244 | - Do not replace the application's identity model or agent architecture. |
| 245 | - Do not claim an integration works before the requested proof succeeds. |