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 | ## Create Tool Router sessions through the SDK or API |
| 2 | |
| 3 | There is no normal dashboard toggle required to enable Tool Router. Create a session through the SDK or the REST API. |
| 4 | |
| 5 | - [Quickstart](https://docs.composio.dev/docs/quickstart) |
| 6 | - [Configuring sessions](https://docs.composio.dev/docs/configuring-sessions) |
| 7 | - [Create a Tool Router session API](https://docs.composio.dev/reference/api-reference/tool-router/postToolRouterSession) |
| 8 | |
| 9 | If you receive an actual 403 or an error saying Tool Router is not enabled for the account, do not keep repeating the setup steps. Contact Composio support for account-level checking and include the exact error body plus the request or code snippet. |
| 10 | |
| 11 | ## Session lifetime and deletion |
| 12 | |
| 13 | Tool Router sessions are long-lived records and do not currently have a time-based expiration. This is separate from temporary workbench files, live sandbox retention, and short response-cache lifetimes. |
| 14 | |
| 15 | Reuse an existing session with `composio.use(sessionId)` in TypeScript or `composio.use(session_id)` in Python. Delete it with `session.delete()`, or delete by ID: |
| 16 | |
| 17 | ### Python |
| 18 | |
| 19 | ```python |
| 20 | composio.sessions.delete("trs_1a2b3c4d5e6f") |
| 21 | ``` |
| 22 | |
| 23 | ### TypeScript |
| 24 | |
| 25 | ```typescript |
| 26 | import { Composio } from "@composio/core"; |
| 27 | |
| 28 | const composio = new Composio(); |
| 29 | await composio.sessions.delete("trs_1a2b3c4d5e6f"); |
| 30 | ``` |
| 31 | |
| 32 | ### API |
| 33 | |
| 34 | ```bash |
| 35 | curl -X DELETE https://backend.composio.dev/api/v3.1/tool_router/session/trs_1a2b3c4d5e6f \ |
| 36 | -H "x-api-key: $COMPOSIO_API_KEY" |
| 37 | ``` |
| 38 | |
| 39 | <!-- end-languages --> |
| 40 | |
| 41 | Deletion takes effect immediately. A deleted, missing, or inaccessible session returns 404 when retrieved; deleting a session does not delete its users, auth configs, or connected accounts. |
| 42 | |
| 43 | ## Select among multiple accounts with an alias or account ID |
| 44 | |
| 45 | When a toolkit has multiple connected accounts, assign clear aliases such as `work`, `personal`, or `primary`, then pass the alias as the execution `account`. Without an alias, use the generated account ID returned by connection discovery. |
| 46 | |
| 47 | Do not rely on fuzzy phrases such as “office email” unless a matching alias exists. If explicit account selection is disabled and no `account` is supplied, the session can fall back to its first/default account. |
| 48 | |
| 49 | ## The session user must match the connected-account user |
| 50 | |
| 51 | An account can be active in the dashboard but unavailable to Tool Router when the session uses a different `user_id`. Private accounts resolve for their owning user; explicitly shared or pinned accounts follow the session configuration. |
| 52 | |
| 53 | Create the session and connection with the same stable user ID. If a particular account must be used, pass its allowed connected-account override in the session configuration. |
| 54 | |
| 55 | ## Connected-account selection is live unless pinned |
| 56 | |
| 57 | When `connectedAccounts` is omitted, Tool Router resolves currently active accounts for the session user at execution time, including accounts connected after session creation. When `connectedAccounts` is supplied, it is an exact toolkit override and Tool Router does not fall back to another active account for that toolkit. |
| 58 | |
| 59 | Adding another account later does not change an explicit pin. Update or recreate the session when the pinned account should change; omit the override when you want live account discovery. |
| 60 | |
| 61 | ## Toolkit allowlists are enforced before connection lookup |
| 62 | |
| 63 | When a session has a non-empty `toolkits.enabled` list, every other toolkit is blocked. A `toolkits.disabled` list does the inverse: listed toolkits are blocked while the rest remain eligible. This restriction is checked before auth configs and connected accounts. |
| 64 | |
| 65 | If Tool Router reports `[Session Restriction] Toolkit '<name>' is not allowed`, update or recreate the session's toolkit configuration first. Only then debug whether that toolkit has an auth config and connection. |
| 66 | |
| 67 | ## A fresh task context is a new session runtime, not model memory |
| 68 | |
| 69 | Every `create()` call returns a new session ID. A session scopes the user, |
| 70 | toolkit and tool access, auth and account selection, and session runtime |
| 71 | resources such as sandbox files. It is not the model's conversation memory. |
| 72 | |
| 73 | Reuse a stored session with `composio.use(sessionId)` when a conversation or |
| 74 | workflow should retain the same session configuration and runtime context. |
| 75 | Create a new session for a different user or materially different setup. A new |
| 76 | session for the same user can still resolve that user's eligible connected |
| 77 | accounts, but it does not inherit the old session's sandbox state. |
| 78 | |
| 79 | ## Auth links create project- and user-scoped connected accounts |
| 80 | |
| 81 | `session.authorize()` and `COMPOSIO_MANAGE_CONNECTIONS` create a Connect Link |
| 82 | for the session user and selected auth config. After authentication, the |
| 83 | connected account belongs to that project/user rather than only to the session |
| 84 | that produced the link. Later unpinned sessions for the same stable user can |
| 85 | resolve it; an explicit connected-account pin remains unchanged until the |
| 86 | session is updated or recreated. |
| 87 | |
| 88 | ## Toolkit filters do not preload every matching tool |
| 89 | |
| 90 | By default, a session exposes meta tools that discover and load app tools at |
| 91 | runtime. Enabling a toolkit limits what the session can discover and execute; |
| 92 | it does not put every tool from that toolkit into the initial schema set. |
| 93 | |
| 94 | Use an explicit `preload.tools` list when the agent must receive known tools |
| 95 | directly. Use the direct-tools preset or `preload.tools = "all"` only with a |
| 96 | narrow positive filter; broad preload sets are capped and increase agent |
| 97 | context. |
| 98 | |
| 99 | ## SDK custom tools and Custom MCP toolkits have different runtimes |
| 100 | |
| 101 | An SDK-defined custom tool runs inside the customer's application process. Its |
| 102 | function body is not uploaded into Composio and is not automatically callable |
| 103 | from a remote session MCP URL or Remote Workbench. |
| 104 | |
| 105 | To expose customer-owned functionality remotely, host it as an MCP server and |
| 106 | register it as a Custom MCP toolkit. The resulting remote tools remain subject |
| 107 | to the session's toolkit and connection restrictions. |
| 108 | |
| 109 | ## Enhanced Control requires client support for MCP elicitation |
| 110 | |
| 111 | For You's Enhanced Control approval flow relies on MCP elicitation. It works |
| 112 | only with clients that advertise and implement that capability. If a client |
| 113 | does not support elicitation, use a supported client, set an applicable |
| 114 | **Always Allow** policy, or disable Enhanced Control under **For You → Settings |
| 115 | → General** and reconnect the client. |
| 116 | |
| 117 | ## Pin the intended auth config when a toolkit has multiple auth schemes |
| 118 | |
| 119 | Tool Router first uses the auth config explicitly mapped in the session. When |
| 120 | the toolkit supports multiple schemes, map the intended `ac_...` ID rather than |
| 121 | depending on automatic selection. The selected config must belong to the same |
| 122 | project and be enabled for Tool Router. An explicit connected-account override |
| 123 | is an exact toolkit selection and does not fall back to another active account. |