Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 245 lines 19.4 KB
Rendered Raw
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.