Creating a session
- Python
- TypeScript
- API
COMPOSIO_SEARCH_TOOLS. Use the options below to restrict or customize what’s available.
You can also attach local custom tools and custom toolkits that run in-process alongside Composio tools. See Custom tools and toolkits.
API key permissions
If you use a scoped project API key, grant permissions for the session operations your application needs:- Session management controls creating, viewing, configuring, and deleting sessions. It does not grant tool execution access.
- Session tool execution covers search, tool execution, proxy execution, and session-linked MCP access.
Using a saved Session config
To start a session from a saved access policy you build in the Composio Dashboard, see Using saved session configs.Reading and updating session configuration
In TypeScript,session.config exposes the configuration returned by the server. Call session.update() to change selected fields. It preserves omitted fields, updates session.config in place, and returns the updated configuration. See Updating a session for an example.
ToolRouterSessionConfig and ToolRouterSessionConfigHistoryConfig use the API client’s types. The SDK returns the config as sent by the API, without validating instant at runtime or removing premium_usage. instant is always present as false or a policy object. Use ToolRouterSessionConfig['instant'] when you need its TypeScript type.
When inspecting a returned config, handle toolkits and individual tools entries that contain only require_approval, without enabled or disabled. tags can also carry require_approval, and the config can include proxy_execute. These fields also appear in configurations returned by session.listConfigHistory().
In Python, session.config.instant is a model when it contains a policy. Read its fields with attribute access rather than dictionary indexing, just as you do for Instant charges.
If you implement the TypeScript
Session interface yourself, include the required config member. Sessions created by the SDK provide it automatically.Requiring tool approval
Require approval before selected session tools run by addingrequireApproval (require_approval in Python) to toolkit, tool, or tag filters. These approval settings are experimental.
You can combine an approval list with
enable or disable in the same filter object. An approval list alone does not restrict which tools are available.
When execution needs approval, catch ComposioToolInputRequiredError from @composio/core in TypeScript or ToolInputRequiredError from composio.exceptions in Python. Display inputRequests (input_requests) and wait for the person’s answers. Repeat the same tool or meta-tool call with inputResponses and requestState (input_responses and request_state), preserving the state from the error. Forward decline and cancel answers unchanged. See handling input requests for the continuation flow.
For MCP clients, configure the approval fallback if the client cannot ask for approval.
Enabling toolkits
To limit a session to specific toolkits, pass an array of toolkit slugs. The agent can only discover and use tools from these toolkits.- Python
- TypeScript
- API
Disabling toolkits
To keep every toolkit discoverable except a few, use thedisable syntax. This is useful when you want broad access but need to exclude specific toolkits.
- Python
- TypeScript
- API
Denying every app toolkit
An explicit empty allowlist means no app toolkits at all. Omittingtoolkits keeps the unrestricted default, and an empty disable list is also unrestricted. The three requests are different:
Use an empty allowlist when a session should only run custom tools or session helpers. Meta tools such as
COMPOSIO_SEARCH_TOOLS, connection management, and the sandbox keep their own enablement, so session.tools() can still return them.
- Python
- TypeScript
- API
Requires
@composio/core ≥ 0.19.1 (TypeScript) or composio ≥ 0.22.1 (Python) when you narrow an existing session with session.update(). Both SDKs send the empty allowlist as { enable: [] }; the backend previously read an empty allowlist as “allow every toolkit”, which left the session unrestricted.400 before it creates anything. A typo such as a singular toolkit fails the request instead of silently creating an unrestricted session.
Direct tools preset
The direct tools preset preloads every tool allowed by session filters into the session’s tool list and disables session meta tools by default. Use it for specialized agents with a narrow tool set that don’t need dynamic tool discovery, in-chat auth, or workbench helpers. This is not the default mode for broad agents. The default session behavior keeps meta tools available so the agent can search for relevant tools and avoid context bloat.- Python
- TypeScript
- API
Enable selected meta tools
With the direct tools preset, you can re-enable supported meta tool groups that your agent still needs. This session loads Gmail tools upfront while keeping connection management and workbench support available:- Python
- TypeScript
- API
Enabling or disabling specific tools
To control which individual tools are available within a toolkit, use thetools configuration. The key is the toolkit slug and the value specifies which tools to enable or disable.
To enable only specific tools, pass an enable list per toolkit:
- Python
- TypeScript
- API
enable:
- Python
- TypeScript
- API
disable:
- Python
- TypeScript
- API
Filtering tools by tags
Every tool has a hint for the type of action it takes:readOnlyHint, createHint, updateHint or destructiveHint. Use the tags configuration to set what happens to each type of tool:
- Allow: leave the hint out. This is the default.
- Block: add the hint to
tags.disable. The agent can’t see or call these tools. - Require approval: add the hint to
tags.require_approval. These tools wait for the user’s approval before they run. See Approvals.
- Python
- TypeScript
- API
Overriding for a toolkit
The session-widetags apply to the tools of every toolkit. To handle a toolkit’s tools differently, override them in tools.<toolkit>.tags. The override replaces the session-wide tags for that toolkit, so list everything you still want to block for it.
For example, this session blocks tools that update or delete everywhere, but overrides GitHub so only its tools that delete are blocked:
- Python
- TypeScript
- API
enable or disable, as in Enabling or disabling specific tools, also overrides the session-wide tags for that toolkit.
Preloading tools
Return a known set of tools directly fromsession.tools() and the session MCP tool list, without the agent searching for them first.
By default, sessions expose meta tools that let the agent discover app tools at runtime. Use preload.tools when you already know which tools the agent needs, so it can call them without going through search each time.
Keep the preloaded set small, generally fewer than 20 tools, to avoid context bloat.
Requires
@composio/core ≥ 0.9.0 (TypeScript) or composio ≥ 0.13.0 (Python). Older SDKs do not support preload.tools, sessionPreset / session_preset, or custom-tool preload.preload.tools is not supported when multiAccount.enable is true. See Managing multiple connected accounts.- Python
- TypeScript
- API
preload: true on the custom tool or custom toolkit. See Preloading custom tools.
To preload every tool allowed by the session filters, use the preload.tools = "all" shortcut (preload={"tools": "all"} in Python, preload: { tools: "all" } in TypeScript). The all shorthand works for both Composio tools and SDK custom tools.
Custom auth configs
Use your own OAuth credentials instead of Composio’s defaults. Pass an auth config ID per toolkit:- Python
- TypeScript
- API
Account selection
When a user has multiple connected accounts for the same toolkit, specify which one the session uses:- Python
- TypeScript
- API
Arrays are the preferred format for
connectedAccounts. A single string (e.g. "ca_work_gmail") is still accepted for backwards compatibility and is automatically coerced to a single-element array. Only one account per toolkit is allowed when multi-account mode is disabled.Precedence
When executing a tool, the session selects the connected account in this order:- The
connectedAccountsoverride, if provided in the session config. - The
authConfigsoverride, which finds or creates a connection on that config. - An auth config previously created for this toolkit.
- A new auth config created using Composio managed auth.
- Otherwise, an error if no Composio managed auth scheme exists for the toolkit.
Disabling the sandbox
By default, sessions include the sandbox, a persistent environment that providesCOMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL. If your use case doesn’t need code execution, disable it:
- Python
- TypeScript
- API
COMPOSIO_REMOTE_WORKBENCHandCOMPOSIO_REMOTE_BASH_TOOLare excluded from the session- Sandbox-related system prompt lines are stripped
- Direct sandbox calls are rejected with a 400 error
enable_proxy_execution (Python) or enableProxyExecution (TypeScript) to false. See Proxy execute for how session restrictions apply to proxy calls.
sandbox is the preferred config key. workbench still works as a fully supported alias and isn’t deprecated, so existing code keeps running unchanged.Sandbox compute tier
The sandbox runs per session. Pick a compute tier to match the workload: heavier code execution or larger in-memory data benefits from a bigger sandbox. Pass the tier viasandbox.sandbox_size (snake_case on the wire, sandboxSize in the TypeScript SDK).
Requires
@composio/core ≥ 0.8.1 (TypeScript) or composio ≥ 0.12.1 (Python). Older SDKs reject sandboxSize (TypeScript) or silently drop sandbox_size (Python). See the release notes.
Defaults to
standard when omitted.
- Python
- TypeScript
- API
Pricing: Sandboxes are not billed today. Composio plans to begin billing for sandbox usage soon (metered by tier and runtime). Pick a tier that matches your workload, but expect future pricing to track actual usage.
sandbox_size on an existing session recreates the sandbox on the next access. The sandbox’s in-memory filesystem state is lost, but the persistent /mnt/files/ mount survives the restart.
Updating a session
session.update() patches the stored configuration in place. Fields you omit are preserved, so you can widen or narrow one part of a session without restating the rest. The SDK refreshes session.config and the session’s config version only after the API accepts the change.
- Python
- TypeScript
- API
The update behavior below requires
@composio/core ≥ 0.19.1 (TypeScript) or composio ≥ 0.22.1 (Python).Maps replace, they don’t merge
Atools, authConfigs, or connectedAccounts map you send replaces the stored map entirely. The API does not merge entries, so a Slack-only tools map removes a Gmail entry that was stored before it.
Stored before the update:
- Python
- TypeScript
- API
gmail entry is gone:
{}) is stored as an explicit empty map.
The same rule applies to toolkits, tags, and preload: a value replaces the stored policy. manageConnections, sandbox, and multiAccount merge the subfields you send, and an empty object changes nothing.
Narrowing an existing session to no app toolkits
An empty allowlist on update denies every app toolkit, exactly as it does on create. The SDK sends{ "enable": [] } as-is instead of dropping it from the request.
- Python
- TypeScript
- API
Removing a callback URL
manageConnections.callbackUrl: null removes only the stored callback URL. enable and the other connection settings stay as they are. An empty string is rejected.
- Python
- TypeScript
- API
Clearing a block with null
Passingnull (None in Python) for a whole block removes the stored override and the session falls back to the default for that block. Every policy block accepts it: toolkits, tools, tags, authConfigs, connectedAccounts, preload, manageConnections, sandbox, proxyExecute, multiAccount, search, execute, and experimental.
- Python
- TypeScript
- API
toolkits: null removes the toolkit policy and restores the unrestricted default, which is the opposite of { "enable": [] }; clearing preload does the same for preloaded tools, so the agent can reach more than before the update. Send toolkits: [] when you want to deny every app toolkit. Clearing multiAccount resolves to disabled, while omitting it preserves the stored setting.
Blocks you can set only on update
search, execute, and experimental are not part of create(). Reach them with session.update() on an existing session.
- Python
- TypeScript
- API
search controls the session’s search helper, so disabling it leaves the agent with the tools you preloaded. execute.enableMultiExecute controls whether the agent can run several tool calls in one request. manageConnections.enableConnectionRemoval is update-only as well, and controls whether the session exposes the connection-removal tool.
The experimental block on update holds server-side session settings: permissions, linkUrlOverwrite, fastMode, submitFeedback, and sessionConfigId. sessionConfigId applies a saved Session config and can’t be combined with toolkits, tools, or tags. The experimental block on update is a different field from the experimental option on create(), which holds custom tools and toolkits that run in your process, so experimental: null on an update leaves those alone.
Multi-account mode after an update
The canonical disabled state is{ "enable": false, "require_explicit_selection": false } with no maximum. Sending enable: false resets a stale maximum or selection setting, and reapplying that disabled configuration is accepted. Combining enable: false with maxAccountsPerToolkit or requireExplicitSelection: true is rejected with a 400.
Preload must stay inside the policy
An update that narrowstoolkits, tools, or tags while leaving an explicitly preloaded tool outside the new policy is rejected with a 400, and nothing changes. Fix preload in the same update:
- Python
- TypeScript
- API
Concurrent updates
Every session response carries a config version (session.configVersion in TypeScript, session.config_version in Python, config_version on the wire). By default, session.update() sends no precondition, so the last writer wins. To make an update conditional, pass the version you read as expectedConfigVersion (expected_config_version in Python). The API then applies the update only when the stored version still matches. Otherwise it answers 409 and writes nothing: no config change, no history entry, no cache update. The SDK never retries that request, so a conflict is reported exactly once.
The API must support
expected_config_version. If it doesn’t, it rejects a conditional update with a 400.ComposioSessionConfigConflictError (TypeScript) or SessionConfigConflictError (Python) and leaves the session object as it was. Re-read the session with sessions.use(), reapply your change on top of the fresh config, and retry:
- Python
- TypeScript
- API
expectedConfigVersion: false (expected_config_version=False) is the same as omitting it. The API still commits only a fully validated configuration, so a losing update never leaves a half-applied session behind.
Raw HTTP callers set expected_config_version in the PATCH body themselves; without it the last writer wins.
To roll a session back, read a previous configuration from its config history (GET /api/v3.1/tool_router/session/{session_id}/config_history) and convert it into an update request. A history entry is not a request body: it carries metadata and version fields, and it names toolkits and tools as enabled and disabled, which map to enable and disable in the update.
Session methods
For framework examples, see provider-specific documentation like OpenAI or Vercel AI SDK. To connect over MCP instead, see Using sessions via MCP.tools()
Get the tools the session exposes for your AI framework. By default these are the session’s meta tools, formatted for your configured provider.- Python
- TypeScript
- API
executeMeta() / execute_meta()
Run aCOMPOSIO_* meta tool directly from your session with a slug and optional arguments:
- Python
- TypeScript
- API
ToolRouterSessionMetaToolSlug type lists the accepted slugs. The response includes resultType (result_type in Python). If execution needs input, such as approval, the SDK raises ComposioToolInputRequiredError (ToolInputRequiredError in Python). Calls are sent once without retries, so retry only when the operation is safe to repeat.
In TypeScript, the third argument holds input-response options: session.executeMeta(slug, args, { inputResponses, requestState }). Request options belong in the fourth argument. To pass only request options, use session.executeMeta(slug, args, undefined, requestOptions).
COMPOSIO_MULTI_EXECUTE_TOOL calls through this method run on the backend. Custom tools named in those calls are not executed in your process.
authorize()
Manually authenticate a user to a toolkit outside of the chat flow.- Python
- TypeScript
- API
toolkits()
List the toolkits enabled for the session and their connection status, sorted by popularity. Use it to build a UI showing which apps are connected. Each toolkit includes itsslug, name, logo, and connection status, and the call returns the first 20 by default.
- Python
- TypeScript
- API
- Python
- TypeScript
- API
limit and the returned cursor:
- Python
- TypeScript
- API
update()
Patch the session configuration in place. See Updating a session for what omitted fields, replaced maps,null, and expectedConfigVersion do.
- Python
- TypeScript
- API
Configuration history
Inspect the configurations a session has used withsession.list_config_history(limit=10) in Python or await session.listConfigHistory({ limit: 10 }) in TypeScript. Results are newest first, with the live configuration first. Each session.update() archives the previous configuration.
The response contains items with each version’s config and an is_current (Python) or isCurrent (TypeScript) flag. Pass the response’s next_cursor (Python) or nextCursor (TypeScript) as cursor to fetch another page; limit supports up to 100 items per page.
delete()
Delete a session when you’re done with it. Deleted sessions immediately stop being retrievable or executable, and the call returns the deletedsession_id. Deleting a missing or already-deleted session surfaces the backend 404.
Requires
@composio/core ≥ 0.13.1 (TypeScript) or composio ≥ 0.17.1 (Python).- Python
- TypeScript
- API
Browsing the catalog
Before configuring a session, explore the toolkits and tools available. Browse them visually at dashboard.composio.dev or in the docs catalog, or fetch them programmatically:- Python
- TypeScript
- API
getRawComposioToolBySlug:
- Python
- TypeScript
- API
composio.toolkits.get_many(["github", "slack"]) in Python or await composio.toolkits.getMany(['github', 'slack']) in TypeScript. Both return the matching toolkits.