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 | --- |
| 2 | title: Configuring Sessions |
| 3 | description: Enable toolkits, set auth configs, and select connected accounts |
| 4 | keywords: [session, toolkits, auth configs, connected accounts] |
| 5 | --- |
| 6 | |
| 7 | ## Creating a session |
| 8 | |
| 9 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 10 | <Tab value="Python"> |
| 11 | ```python |
| 12 | session = composio.sessions.create(user_id="user_123") |
| 13 | ``` |
| 14 | </Tab> |
| 15 | <Tab value="TypeScript"> |
| 16 | ```typescript |
| 17 | import { Composio } from '@composio/core'; |
| 18 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 19 | // ---cut--- |
| 20 | const session = await composio.create("user_123"); |
| 21 | ``` |
| 22 | </Tab> |
| 23 | <Tab value="API"> |
| 24 | ```bash |
| 25 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 26 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 27 | -H "Content-Type: application/json" \ |
| 28 | -d '{"user_id": "user_123"}' |
| 29 | ``` |
| 30 | </Tab> |
| 31 | </Tabs> |
| 32 | |
| 33 | By default, a session has access to every toolkit in the Composio catalog. Your agent can discover and use any of them through `COMPOSIO_SEARCH_TOOLS`. Use the options below to restrict or customize what's available. |
| 34 | |
| 35 | You can also attach local tools and local toolkits that run in-process alongside Composio tools. See [Local tools and toolkits](/docs/extending-sessions/local-tools-and-toolkits). |
| 36 | |
| 37 | <Callout type="warn"> |
| 38 | Both SDKs pass product and runtime identity through the API client's `identity` option. If you configure custom default or request headers, remove identity headers such as `x-source`, `x-framework`, `x-sdk-version`, and `x-client-*`. The client rejects attempts to override them. |
| 39 | </Callout> |
| 40 | |
| 41 | ### API key permissions |
| 42 | |
| 43 | If you use a [scoped project API key](/reference/authenticating-to-composio/project-api-key-permissions), grant permissions for the session operations your application needs: |
| 44 | |
| 45 | - **Session management** controls creating, viewing, configuring, and deleting sessions. It does not grant tool execution access. |
| 46 | - **Session tool execution** covers search, tool execution, proxy execution, and session-linked MCP access. |
| 47 | |
| 48 | Enable both permissions if your application manages sessions and executes tools through them. |
| 49 | |
| 50 | ## Using a saved Session config |
| 51 | |
| 52 | To start a session from a saved access policy you build in the Composio Dashboard, see [Using saved session configs](/docs/session-configs). |
| 53 | |
| 54 | ## Reading and updating session configuration |
| 55 | |
| 56 | 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](/docs/how-composio-works#how-sessions-behave) for an example. |
| 57 | |
| 58 | `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. |
| 59 | |
| 60 | 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()`. |
| 61 | |
| 62 | 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](/docs/instant-tools#return-the-charge-with-a-call). |
| 63 | |
| 64 | <Callout> |
| 65 | If you implement the TypeScript `Session` interface yourself, include the required `config` member. Sessions created by the SDK provide it automatically. |
| 66 | </Callout> |
| 67 | |
| 68 | ## Requiring tool approval |
| 69 | |
| 70 | Require approval before selected session tools run by adding `requireApproval` (`require_approval` in Python) to toolkit, tool, or tag filters. These approval settings are experimental. |
| 71 | |
| 72 | | Scope | TypeScript session option | Python session option | |
| 73 | | --- | --- | --- | |
| 74 | | All tools in a toolkit | `toolkits: { requireApproval: ["gmail"] }` | `toolkits={"require_approval": ["gmail"]}` | |
| 75 | | Specific tools in a toolkit | `tools: { gmail: { requireApproval: ["GMAIL_SEND_EMAIL"] } }` | `tools={"gmail": {"require_approval": ["GMAIL_SEND_EMAIL"]}}` | |
| 76 | | Tools with matching tags | `tags: { requireApproval: ["destructiveHint"] }` | `tags={"require_approval": ["destructiveHint"]}` | |
| 77 | |
| 78 | 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. |
| 79 | |
| 80 | 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](/docs/how-composio-works#handling-requests-for-user-input) for the continuation flow. |
| 81 | |
| 82 | For MCP clients, configure the [approval fallback](/docs/sessions-via-mcp#approval-without-elicitation-support) if the client cannot ask for approval. |
| 83 | |
| 84 | ## Enabling toolkits |
| 85 | |
| 86 | To limit a session to specific toolkits, pass an array of toolkit slugs. The agent can only discover and use tools from these toolkits. |
| 87 | |
| 88 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 89 | <Tab value="Python"> |
| 90 | ```python |
| 91 | # Using array format |
| 92 | session = composio.sessions.create( |
| 93 | user_id="user_123", |
| 94 | toolkits=["github", "gmail", "slack"] |
| 95 | ) |
| 96 | |
| 97 | # Using object format with enable key |
| 98 | session = composio.sessions.create( |
| 99 | user_id="user_123", |
| 100 | toolkits={"enable": ["github", "gmail", "slack"]} |
| 101 | ) |
| 102 | ``` |
| 103 | </Tab> |
| 104 | <Tab value="TypeScript"> |
| 105 | ```typescript |
| 106 | import { Composio } from '@composio/core'; |
| 107 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 108 | // ---cut--- |
| 109 | // Using array format |
| 110 | const session = await composio.create("user_123", { |
| 111 | toolkits: ["github", "gmail", "slack"], |
| 112 | }); |
| 113 | |
| 114 | // Using object format with enable key |
| 115 | const session2 = await composio.create("user_123", { |
| 116 | toolkits: { enable: ["github", "gmail", "slack"] }, |
| 117 | }); |
| 118 | ``` |
| 119 | </Tab> |
| 120 | <Tab value="API"> |
| 121 | ```bash |
| 122 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 123 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 124 | -H "Content-Type: application/json" \ |
| 125 | -d '{"user_id": "user_123", "toolkits": {"enable": ["github", "gmail", "slack"]}}' |
| 126 | ``` |
| 127 | </Tab> |
| 128 | </Tabs> |
| 129 | |
| 130 | ## Disabling toolkits |
| 131 | |
| 132 | To keep every toolkit discoverable except a few, use the `disable` syntax. This is useful when you want broad access but need to exclude specific toolkits. |
| 133 | |
| 134 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 135 | <Tab value="Python"> |
| 136 | ```python |
| 137 | session = composio.sessions.create( |
| 138 | user_id="user_123", |
| 139 | toolkits={"disable": ["exa", "firecrawl"]} |
| 140 | ) |
| 141 | ``` |
| 142 | </Tab> |
| 143 | <Tab value="TypeScript"> |
| 144 | ```typescript |
| 145 | import { Composio } from '@composio/core'; |
| 146 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 147 | // ---cut--- |
| 148 | const session = await composio.create("user_123", { |
| 149 | toolkits: { disable: ["exa", "firecrawl"] }, |
| 150 | }); |
| 151 | ``` |
| 152 | </Tab> |
| 153 | <Tab value="API"> |
| 154 | ```bash |
| 155 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 156 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 157 | -H "Content-Type: application/json" \ |
| 158 | -d '{"user_id": "user_123", "toolkits": {"disable": ["exa", "firecrawl"]}}' |
| 159 | ``` |
| 160 | </Tab> |
| 161 | </Tabs> |
| 162 | |
| 163 | ## Denying every app toolkit |
| 164 | |
| 165 | An explicit empty allowlist means no app toolkits at all. Omitting `toolkits` keeps the unrestricted default, and an empty `disable` list is also unrestricted. The three requests are different: |
| 166 | |
| 167 | | Toolkit config | Effect | |
| 168 | |---|---| |
| 169 | | Omitted | Every toolkit in the catalog is available | |
| 170 | | `{ enable: [] }` | No app toolkit is listed, searchable, executable, or served over MCP | |
| 171 | | `{ disable: [] }` | Every toolkit in the catalog is available | |
| 172 | |
| 173 | Use an empty allowlist when a session should only run [local tools](/docs/extending-sessions/local-tools-and-toolkits) 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. |
| 174 | |
| 175 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 176 | <Tab value="Python"> |
| 177 | ```python |
| 178 | session = composio.sessions.create( |
| 179 | user_id="user_123", |
| 180 | toolkits={"enable": []}, |
| 181 | ) |
| 182 | ``` |
| 183 | </Tab> |
| 184 | <Tab value="TypeScript"> |
| 185 | ```typescript |
| 186 | import { Composio } from '@composio/core'; |
| 187 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 188 | // ---cut--- |
| 189 | const session = await composio.create("user_123", { |
| 190 | toolkits: { enable: [] }, |
| 191 | }); |
| 192 | ``` |
| 193 | </Tab> |
| 194 | <Tab value="API"> |
| 195 | ```bash |
| 196 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 197 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 198 | -H "Content-Type: application/json" \ |
| 199 | -d '{"user_id": "user_123", "toolkits": {"enable": []}}' |
| 200 | ``` |
| 201 | </Tab> |
| 202 | </Tabs> |
| 203 | |
| 204 | <Callout type="info"> |
| 205 | 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. |
| 206 | </Callout> |
| 207 | |
| 208 | The session API rejects unknown root keys with a `400` before it creates anything. A typo such as a singular `toolkit` fails the request instead of silently creating an unrestricted session. |
| 209 | |
| 210 | ## Direct tools preset |
| 211 | |
| 212 | 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. |
| 213 | |
| 214 | 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. |
| 215 | |
| 216 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 217 | <Tab value="Python"> |
| 218 | ```python |
| 219 | from composio import Composio, SESSION_PRESET_DIRECT_TOOLS |
| 220 | from composio_openai_agents import OpenAIAgentsProvider |
| 221 | |
| 222 | composio = Composio( |
| 223 | api_key="your_api_key", |
| 224 | provider=OpenAIAgentsProvider(), |
| 225 | ) |
| 226 | |
| 227 | session = composio.sessions.create( |
| 228 | user_id="user_123", |
| 229 | toolkits=["gmail"], |
| 230 | tools={ |
| 231 | "gmail": { |
| 232 | "enable": [ |
| 233 | "GMAIL_FETCH_EMAILS", |
| 234 | "GMAIL_CREATE_EMAIL_DRAFT", |
| 235 | ], |
| 236 | }, |
| 237 | }, |
| 238 | session_preset=SESSION_PRESET_DIRECT_TOOLS, |
| 239 | ) |
| 240 | |
| 241 | tools = session.tools() |
| 242 | print([tool.name for tool in tools]) |
| 243 | # GMAIL_FETCH_EMAILS |
| 244 | # GMAIL_CREATE_EMAIL_DRAFT |
| 245 | ``` |
| 246 | </Tab> |
| 247 | <Tab value="TypeScript"> |
| 248 | ```typescript |
| 249 | import { Composio, SessionPreset } from '@composio/core'; |
| 250 | import { OpenAIAgentsProvider } from '@composio/openai-agents'; |
| 251 | |
| 252 | const composio = new Composio({ |
| 253 | apiKey: 'your_api_key', |
| 254 | provider: new OpenAIAgentsProvider(), |
| 255 | }); |
| 256 | // ---cut--- |
| 257 | const session = await composio.create("user_123", { |
| 258 | toolkits: ["gmail"], |
| 259 | tools: { |
| 260 | gmail: { |
| 261 | enable: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"], |
| 262 | }, |
| 263 | }, |
| 264 | sessionPreset: SessionPreset.DIRECT_TOOLS, |
| 265 | }); |
| 266 | |
| 267 | const tools = await session.tools(); |
| 268 | console.log(tools.map((tool) => tool.name)); |
| 269 | // GMAIL_FETCH_EMAILS |
| 270 | // GMAIL_CREATE_EMAIL_DRAFT |
| 271 | ``` |
| 272 | </Tab> |
| 273 | <Tab value="API"> |
| 274 | ```bash |
| 275 | # The direct tools preset turns off meta tools, preloads every allowed tool, and disables search and multi-execute |
| 276 | SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 277 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 278 | -H "Content-Type: application/json" \ |
| 279 | -d '{ |
| 280 | "user_id": "user_123", |
| 281 | "toolkits": {"enable": ["gmail"]}, |
| 282 | "tools": {"gmail": {"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"]}}, |
| 283 | "manage_connections": {"enable": false}, |
| 284 | "workbench": {"enable": false}, |
| 285 | "preload": {"tools": "all"}, |
| 286 | "search": {"enable": false}, |
| 287 | "execute": {"enable_multi_execute": false} |
| 288 | }' | jq -r '.session_id') |
| 289 | |
| 290 | curl -s -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools \ |
| 291 | -H "x-api-key: $COMPOSIO_API_KEY" | jq -r '.items[].slug' |
| 292 | ``` |
| 293 | </Tab> |
| 294 | </Tabs> |
| 295 | |
| 296 | ### Enable selected meta tools |
| 297 | |
| 298 | 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: |
| 299 | |
| 300 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 301 | <Tab value="Python"> |
| 302 | ```python |
| 303 | from composio import Composio, SESSION_PRESET_DIRECT_TOOLS |
| 304 | from composio_openai_agents import OpenAIAgentsProvider |
| 305 | |
| 306 | composio = Composio( |
| 307 | api_key="your_api_key", |
| 308 | provider=OpenAIAgentsProvider(), |
| 309 | ) |
| 310 | |
| 311 | session = composio.sessions.create( |
| 312 | user_id="user_123", |
| 313 | toolkits=["gmail"], |
| 314 | tools={ |
| 315 | "gmail": { |
| 316 | "enable": [ |
| 317 | "GMAIL_FETCH_EMAILS", |
| 318 | "GMAIL_CREATE_EMAIL_DRAFT", |
| 319 | ], |
| 320 | }, |
| 321 | }, |
| 322 | session_preset=SESSION_PRESET_DIRECT_TOOLS, |
| 323 | manage_connections={ |
| 324 | "enable": True, |
| 325 | }, |
| 326 | sandbox={ |
| 327 | "enable": True, |
| 328 | }, |
| 329 | ) |
| 330 | |
| 331 | tools = session.tools() |
| 332 | print([tool.name for tool in tools]) |
| 333 | # GMAIL_FETCH_EMAILS |
| 334 | # GMAIL_CREATE_EMAIL_DRAFT |
| 335 | # COMPOSIO_MANAGE_CONNECTIONS |
| 336 | # COMPOSIO_REMOTE_WORKBENCH |
| 337 | # COMPOSIO_REMOTE_BASH_TOOL |
| 338 | ``` |
| 339 | </Tab> |
| 340 | <Tab value="TypeScript"> |
| 341 | ```typescript |
| 342 | // @noErrors |
| 343 | import { Composio, SessionPreset } from '@composio/core'; |
| 344 | import { OpenAIAgentsProvider } from '@composio/openai-agents'; |
| 345 | |
| 346 | const composio = new Composio({ |
| 347 | apiKey: 'your_api_key', |
| 348 | provider: new OpenAIAgentsProvider(), |
| 349 | }); |
| 350 | // ---cut--- |
| 351 | const session = await composio.create("user_123", { |
| 352 | toolkits: ["gmail"], |
| 353 | tools: { |
| 354 | gmail: { |
| 355 | enable: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"], |
| 356 | }, |
| 357 | }, |
| 358 | sessionPreset: SessionPreset.DIRECT_TOOLS, |
| 359 | manageConnections: { |
| 360 | enable: true, |
| 361 | }, |
| 362 | sandbox: { |
| 363 | enable: true, |
| 364 | }, |
| 365 | }); |
| 366 | |
| 367 | const tools = await session.tools(); |
| 368 | console.log(tools.map((tool) => tool.name)); |
| 369 | // GMAIL_FETCH_EMAILS |
| 370 | // GMAIL_CREATE_EMAIL_DRAFT |
| 371 | // COMPOSIO_MANAGE_CONNECTIONS |
| 372 | // COMPOSIO_REMOTE_WORKBENCH |
| 373 | // COMPOSIO_REMOTE_BASH_TOOL |
| 374 | ``` |
| 375 | </Tab> |
| 376 | <Tab value="API"> |
| 377 | ```bash |
| 378 | SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 379 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 380 | -H "Content-Type: application/json" \ |
| 381 | -d '{ |
| 382 | "user_id": "user_123", |
| 383 | "toolkits": {"enable": ["gmail"]}, |
| 384 | "tools": {"gmail": {"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"]}}, |
| 385 | "manage_connections": {"enable": true}, |
| 386 | "workbench": {"enable": true}, |
| 387 | "preload": {"tools": "all"}, |
| 388 | "search": {"enable": false}, |
| 389 | "execute": {"enable_multi_execute": false} |
| 390 | }' | jq -r '.session_id') |
| 391 | |
| 392 | curl -s -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools \ |
| 393 | -H "x-api-key: $COMPOSIO_API_KEY" | jq -r '.items[].slug' |
| 394 | ``` |
| 395 | </Tab> |
| 396 | </Tabs> |
| 397 | |
| 398 | ## Enabling or disabling specific tools |
| 399 | |
| 400 | To control which individual tools are available within a toolkit, use the `tools` configuration. The key is the toolkit slug and the value specifies which tools to enable or disable. |
| 401 | |
| 402 | Composio enforces these filters on every session execution path, including multi-execute, the sandbox, and MCP. See [Per-action permissions](/docs/governance/action-permissions) for allow and deny examples and the paths the filters don't cover. |
| 403 | |
| 404 | To enable only specific tools, pass an `enable` list per toolkit: |
| 405 | |
| 406 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 407 | <Tab value="Python"> |
| 408 | ```python |
| 409 | session = composio.sessions.create( |
| 410 | user_id="user_123", |
| 411 | tools={ |
| 412 | # Only these Gmail tools will be available |
| 413 | "gmail": {"enable": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"]}, |
| 414 | # Only issue-related GitHub tools |
| 415 | "github": {"enable": ["GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_ISSUE"]} |
| 416 | } |
| 417 | ) |
| 418 | ``` |
| 419 | </Tab> |
| 420 | <Tab value="TypeScript"> |
| 421 | ```typescript |
| 422 | import { Composio } from '@composio/core'; |
| 423 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 424 | // ---cut--- |
| 425 | const session = await composio.create("user_123", { |
| 426 | tools: { |
| 427 | // Only these Gmail tools will be available |
| 428 | gmail: { enable: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"] }, |
| 429 | // Only issue-related GitHub tools |
| 430 | github: { enable: ["GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_ISSUE"] } |
| 431 | } |
| 432 | }); |
| 433 | ``` |
| 434 | </Tab> |
| 435 | <Tab value="API"> |
| 436 | ```bash |
| 437 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 438 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 439 | -H "Content-Type: application/json" \ |
| 440 | -d '{ |
| 441 | "user_id": "user_123", |
| 442 | "tools": { |
| 443 | "gmail": {"enable": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"]}, |
| 444 | "github": {"enable": ["GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_ISSUE"]} |
| 445 | } |
| 446 | }' |
| 447 | ``` |
| 448 | </Tab> |
| 449 | </Tabs> |
| 450 | |
| 451 | The shorthand array syntax is equivalent to `enable`: |
| 452 | |
| 453 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 454 | <Tab value="Python"> |
| 455 | ```python |
| 456 | session = composio.sessions.create( |
| 457 | user_id="user_123", |
| 458 | tools={ |
| 459 | "gmail": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"], |
| 460 | "github": ["GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_ISSUE"] |
| 461 | } |
| 462 | ) |
| 463 | ``` |
| 464 | </Tab> |
| 465 | <Tab value="TypeScript"> |
| 466 | ```typescript |
| 467 | import { Composio } from '@composio/core'; |
| 468 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 469 | // ---cut--- |
| 470 | const session = await composio.create("user_123", { |
| 471 | tools: { |
| 472 | gmail: ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"], |
| 473 | github: ["GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_ISSUE"] |
| 474 | } |
| 475 | }); |
| 476 | ``` |
| 477 | </Tab> |
| 478 | <Tab value="API"> |
| 479 | ```bash |
| 480 | # The SDK expands the array shorthand to {"enable": [...]} |
| 481 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 482 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 483 | -H "Content-Type: application/json" \ |
| 484 | -d '{ |
| 485 | "user_id": "user_123", |
| 486 | "tools": { |
| 487 | "gmail": {"enable": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"]}, |
| 488 | "github": {"enable": ["GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_ISSUE"]} |
| 489 | } |
| 490 | }' |
| 491 | ``` |
| 492 | </Tab> |
| 493 | </Tabs> |
| 494 | |
| 495 | To keep every tool in a toolkit except a few, use `disable`: |
| 496 | |
| 497 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 498 | <Tab value="Python"> |
| 499 | ```python |
| 500 | session = composio.sessions.create( |
| 501 | user_id="user_123", |
| 502 | tools={ |
| 503 | # All Slack tools except delete |
| 504 | "slack": {"disable": ["SLACK_DELETE_MESSAGE"]}, |
| 505 | # All GitHub tools except destructive ones |
| 506 | "github": {"disable": ["GITHUB_DELETE_REPO", "GITHUB_DELETE_BRANCH"]} |
| 507 | } |
| 508 | ) |
| 509 | ``` |
| 510 | </Tab> |
| 511 | <Tab value="TypeScript"> |
| 512 | ```typescript |
| 513 | import { Composio } from '@composio/core'; |
| 514 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 515 | // ---cut--- |
| 516 | const session = await composio.create("user_123", { |
| 517 | tools: { |
| 518 | // All Slack tools except delete |
| 519 | slack: { disable: ["SLACK_DELETE_MESSAGE"] }, |
| 520 | // All GitHub tools except destructive ones |
| 521 | github: { disable: ["GITHUB_DELETE_REPO", "GITHUB_DELETE_BRANCH"] } |
| 522 | } |
| 523 | }); |
| 524 | ``` |
| 525 | </Tab> |
| 526 | <Tab value="API"> |
| 527 | ```bash |
| 528 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 529 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 530 | -H "Content-Type: application/json" \ |
| 531 | -d '{ |
| 532 | "user_id": "user_123", |
| 533 | "tools": { |
| 534 | "slack": {"disable": ["SLACK_DELETE_MESSAGE"]}, |
| 535 | "github": {"disable": ["GITHUB_DELETE_REPO", "GITHUB_DELETE_BRANCH"]} |
| 536 | } |
| 537 | }' |
| 538 | ``` |
| 539 | </Tab> |
| 540 | </Tabs> |
| 541 | |
| 542 | ## Filtering tools by tags |
| 543 | |
| 544 | Every tool has a [hint](/docs/governance/tool-hints) 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: |
| 545 | |
| 546 | - **Allow:** leave the hint out. This is the default. |
| 547 | - **Block:** add the hint to `tags.disable`. The agent can't see or call these tools. |
| 548 | - **Require approval:** add the hint to `tags.require_approval`. These tools wait for the user's approval before they run. See [Approvals](/docs/governance/approvals). |
| 549 | |
| 550 | For example, to block every tool that can delete something: |
| 551 | |
| 552 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 553 | <Tab value="Python"> |
| 554 | ```python |
| 555 | session = composio.sessions.create( |
| 556 | user_id="user_123", |
| 557 | tags={"disable": ["destructiveHint"]} |
| 558 | ) |
| 559 | ``` |
| 560 | </Tab> |
| 561 | <Tab value="TypeScript"> |
| 562 | ```typescript |
| 563 | import { Composio } from '@composio/core'; |
| 564 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 565 | // ---cut--- |
| 566 | const session = await composio.create("user_123", { |
| 567 | tags: { disable: ["destructiveHint"] } |
| 568 | }); |
| 569 | ``` |
| 570 | </Tab> |
| 571 | <Tab value="API"> |
| 572 | ```bash |
| 573 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 574 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 575 | -H "Content-Type: application/json" \ |
| 576 | -d '{"user_id": "user_123", "tags": {"disable": ["destructiveHint"]}}' |
| 577 | ``` |
| 578 | </Tab> |
| 579 | </Tabs> |
| 580 | |
| 581 | ### Overriding for a toolkit |
| 582 | |
| 583 | The session-wide `tags` 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. |
| 584 | |
| 585 | For example, this session blocks tools that update or delete everywhere, but overrides GitHub so only its tools that delete are blocked: |
| 586 | |
| 587 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 588 | <Tab value="Python"> |
| 589 | ```python |
| 590 | session = composio.sessions.create( |
| 591 | user_id="user_123", |
| 592 | # Everywhere: block tools that update or delete |
| 593 | tags={"disable": ["updateHint", "destructiveHint"]}, |
| 594 | tools={ |
| 595 | # GitHub: block only tools that delete |
| 596 | "github": {"tags": {"disable": ["destructiveHint"]}} |
| 597 | } |
| 598 | ) |
| 599 | ``` |
| 600 | </Tab> |
| 601 | <Tab value="TypeScript"> |
| 602 | ```typescript |
| 603 | import { Composio } from '@composio/core'; |
| 604 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 605 | // ---cut--- |
| 606 | const session = await composio.create("user_123", { |
| 607 | // Everywhere: block tools that update or delete |
| 608 | tags: { disable: ["updateHint", "destructiveHint"] }, |
| 609 | tools: { |
| 610 | // GitHub: block only tools that delete |
| 611 | github: { tags: { disable: ["destructiveHint"] } } |
| 612 | } |
| 613 | }); |
| 614 | ``` |
| 615 | </Tab> |
| 616 | <Tab value="API"> |
| 617 | ```bash |
| 618 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 619 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 620 | -H "Content-Type: application/json" \ |
| 621 | -d '{ |
| 622 | "user_id": "user_123", |
| 623 | "tags": {"disable": ["updateHint", "destructiveHint"]}, |
| 624 | "tools": {"github": {"tags": {"disable": ["destructiveHint"]}}} |
| 625 | }' |
| 626 | ``` |
| 627 | </Tab> |
| 628 | </Tabs> |
| 629 | |
| 630 | Listing a toolkit's tools with `enable` or `disable`, as in [Enabling or disabling specific tools](#enabling-or-disabling-specific-tools), also overrides the session-wide `tags` for that toolkit. |
| 631 | |
| 632 | ## Preloading tools |
| 633 | |
| 634 | Return a known set of tools directly from `session.tools()` and the session MCP tool list, without the agent searching for them first. |
| 635 | |
| 636 | By default, sessions expose [meta tools](/toolkits/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. |
| 637 | |
| 638 | Keep the preloaded set small, generally fewer than 20 tools, to avoid context bloat. |
| 639 | |
| 640 | <Callout type="info"> |
| 641 | Requires `@composio/core` ≥ `0.9.0` (TypeScript) or `composio` ≥ `0.13.0` |
| 642 | (Python). Older SDKs do not support `preload.tools`, |
| 643 | `sessionPreset` / `session_preset`, or local-tool `preload`. |
| 644 | </Callout> |
| 645 | |
| 646 | <Callout type="info"> |
| 647 | `preload.tools` is not supported when `multiAccount.enable` is true. See |
| 648 | [Managing multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts). |
| 649 | </Callout> |
| 650 | |
| 651 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 652 | <Tab value="Python"> |
| 653 | ```python |
| 654 | from composio import Composio |
| 655 | from composio_openai_agents import OpenAIAgentsProvider |
| 656 | |
| 657 | composio = Composio( |
| 658 | api_key="your_api_key", |
| 659 | provider=OpenAIAgentsProvider(), |
| 660 | ) |
| 661 | |
| 662 | session = composio.sessions.create( |
| 663 | user_id="user_123", |
| 664 | toolkits=["gmail"], |
| 665 | preload={ |
| 666 | "tools": [ |
| 667 | "GMAIL_FETCH_EMAILS", |
| 668 | "GMAIL_CREATE_EMAIL_DRAFT", |
| 669 | ], |
| 670 | }, |
| 671 | ) |
| 672 | |
| 673 | tools = session.tools() |
| 674 | print([tool.name for tool in tools]) |
| 675 | # GMAIL_FETCH_EMAILS |
| 676 | # GMAIL_CREATE_EMAIL_DRAFT |
| 677 | # COMPOSIO_SEARCH_TOOLS |
| 678 | # ... other default meta tools |
| 679 | ``` |
| 680 | </Tab> |
| 681 | <Tab value="TypeScript"> |
| 682 | ```typescript |
| 683 | import { Composio } from '@composio/core'; |
| 684 | import { OpenAIAgentsProvider } from '@composio/openai-agents'; |
| 685 | |
| 686 | const composio = new Composio({ |
| 687 | apiKey: 'your_api_key', |
| 688 | provider: new OpenAIAgentsProvider(), |
| 689 | }); |
| 690 | // ---cut--- |
| 691 | const session = await composio.create("user_123", { |
| 692 | toolkits: ["gmail"], |
| 693 | preload: { |
| 694 | tools: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"], |
| 695 | }, |
| 696 | }); |
| 697 | |
| 698 | const tools = await session.tools(); |
| 699 | console.log(tools.map((tool) => tool.name)); |
| 700 | // GMAIL_FETCH_EMAILS |
| 701 | // GMAIL_CREATE_EMAIL_DRAFT |
| 702 | // COMPOSIO_SEARCH_TOOLS |
| 703 | // ... other default meta tools |
| 704 | ``` |
| 705 | </Tab> |
| 706 | <Tab value="API"> |
| 707 | ```bash |
| 708 | SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 709 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 710 | -H "Content-Type: application/json" \ |
| 711 | -d '{ |
| 712 | "user_id": "user_123", |
| 713 | "toolkits": {"enable": ["gmail"]}, |
| 714 | "preload": {"tools": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"]} |
| 715 | }' | jq -r '.session_id') |
| 716 | |
| 717 | curl -s -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools \ |
| 718 | -H "x-api-key: $COMPOSIO_API_KEY" | jq -r '.items[].slug' |
| 719 | ``` |
| 720 | </Tab> |
| 721 | </Tabs> |
| 722 | |
| 723 | For SDK local tools, set `preload: true` on the local tool or local toolkit. See [Preloading local tools](/docs/extending-sessions/local-tools-and-toolkits#preloading-local-tools). |
| 724 | |
| 725 | 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. |
| 726 | |
| 727 | ## Custom auth configs |
| 728 | |
| 729 | Use your own OAuth credentials instead of Composio's defaults. Pass an auth config ID per toolkit: |
| 730 | |
| 731 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 732 | <Tab value="Python"> |
| 733 | ```python |
| 734 | session = composio.sessions.create( |
| 735 | user_id="user_123", |
| 736 | auth_configs={ |
| 737 | "github": "ac_your_github_config", |
| 738 | "slack": "ac_your_slack_config" |
| 739 | } |
| 740 | ) |
| 741 | ``` |
| 742 | </Tab> |
| 743 | <Tab value="TypeScript"> |
| 744 | ```typescript |
| 745 | import { Composio } from '@composio/core'; |
| 746 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 747 | // ---cut--- |
| 748 | const session = await composio.create("user_123", { |
| 749 | authConfigs: { |
| 750 | github: "ac_your_github_config", |
| 751 | slack: "ac_your_slack_config", |
| 752 | }, |
| 753 | }); |
| 754 | ``` |
| 755 | </Tab> |
| 756 | <Tab value="API"> |
| 757 | ```bash |
| 758 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 759 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 760 | -H "Content-Type: application/json" \ |
| 761 | -d '{ |
| 762 | "user_id": "user_123", |
| 763 | "auth_configs": {"github": "ac_your_github_config", "slack": "ac_your_slack_config"} |
| 764 | }' |
| 765 | ``` |
| 766 | </Tab> |
| 767 | </Tabs> |
| 768 | |
| 769 | See [White-labeling authentication](/docs/authentication/white-labeling-authentication) for branding, or [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) for toolkits that require your own credentials. |
| 770 | |
| 771 | ## Account selection |
| 772 | |
| 773 | When a user has multiple connected accounts for the same toolkit, specify which one the session uses: |
| 774 | |
| 775 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 776 | <Tab value="Python"> |
| 777 | ```python |
| 778 | session = composio.sessions.create( |
| 779 | user_id="user_123", |
| 780 | connected_accounts={ |
| 781 | "gmail": ["ca_work_gmail"], |
| 782 | "github": ["ca_personal_github"], |
| 783 | } |
| 784 | ) |
| 785 | ``` |
| 786 | </Tab> |
| 787 | <Tab value="TypeScript"> |
| 788 | ```typescript |
| 789 | import { Composio } from '@composio/core'; |
| 790 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 791 | // ---cut--- |
| 792 | const session = await composio.create("user_123", { |
| 793 | connectedAccounts: { |
| 794 | gmail: ["ca_work_gmail"], |
| 795 | github: ["ca_personal_github"], |
| 796 | }, |
| 797 | }); |
| 798 | ``` |
| 799 | </Tab> |
| 800 | <Tab value="API"> |
| 801 | ```bash |
| 802 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 803 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 804 | -H "Content-Type: application/json" \ |
| 805 | -d '{ |
| 806 | "user_id": "user_123", |
| 807 | "connected_accounts": {"gmail": ["ca_work_gmail"], "github": ["ca_personal_github"]} |
| 808 | }' |
| 809 | ``` |
| 810 | </Tab> |
| 811 | </Tabs> |
| 812 | |
| 813 | <Callout type="info"> |
| 814 | 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](/docs/authentication/managing-multiple-connected-accounts) is disabled. |
| 815 | </Callout> |
| 816 | |
| 817 | ### Precedence |
| 818 | |
| 819 | When executing a tool, the session selects the connected account in this order: |
| 820 | |
| 821 | 1. The `connectedAccounts` override, if provided in the session config. |
| 822 | 2. The `authConfigs` override, which finds or creates a connection on that config. |
| 823 | 3. An auth config previously created for this toolkit. |
| 824 | 4. A new auth config created using Composio managed auth. |
| 825 | 5. Otherwise, an error if no Composio managed auth scheme exists for the toolkit. |
| 826 | |
| 827 | When a user has multiple connected accounts for a toolkit, the session uses the most recently connected one. |
| 828 | |
| 829 | If an account exists but the session doesn't use it, see [When a session can't find a connected account](/docs/authentication/session-cant-find-account). |
| 830 | |
| 831 | ## Disabling the sandbox |
| 832 | |
| 833 | By default, sessions include the [sandbox](/docs/sandbox/remote), a persistent environment that provides `COMPOSIO_REMOTE_WORKBENCH` and `COMPOSIO_REMOTE_BASH_TOOL`. If your use case doesn't need code execution, disable it: |
| 834 | |
| 835 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 836 | <Tab value="Python"> |
| 837 | ```python |
| 838 | session = composio.sessions.create( |
| 839 | user_id="user_123", |
| 840 | sandbox={ |
| 841 | "enable": False |
| 842 | } |
| 843 | ) |
| 844 | ``` |
| 845 | </Tab> |
| 846 | <Tab value="TypeScript"> |
| 847 | ```typescript |
| 848 | // @noErrors |
| 849 | import { Composio } from '@composio/core'; |
| 850 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 851 | // ---cut--- |
| 852 | const session = await composio.create("user_123", { |
| 853 | sandbox: { |
| 854 | enable: false, |
| 855 | }, |
| 856 | }); |
| 857 | ``` |
| 858 | </Tab> |
| 859 | <Tab value="API"> |
| 860 | ```bash |
| 861 | # The REST API names the sandbox block `workbench` |
| 862 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 863 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 864 | -H "Content-Type: application/json" \ |
| 865 | -d '{"user_id": "user_123", "workbench": {"enable": false}}' |
| 866 | ``` |
| 867 | </Tab> |
| 868 | </Tabs> |
| 869 | |
| 870 | When disabled: |
| 871 | - `COMPOSIO_REMOTE_WORKBENCH` and `COMPOSIO_REMOTE_BASH_TOOL` are excluded from the session |
| 872 | - Sandbox-related system prompt lines are stripped |
| 873 | - Direct sandbox calls are rejected with a 400 error |
| 874 | |
| 875 | [Zero Data Retention](/docs/security/zero-data-retention) does not cover the sandbox, so disable it in sessions that handle data that needs ZDR. |
| 876 | |
| 877 | To keep the sandbox but block raw HTTP calls from it, set `enable_proxy_execution` (Python) or `enableProxyExecution` (TypeScript) to `false`. See [Proxy execute](/docs/extending-sessions/proxy-execute#session-restrictions) for how session restrictions apply to proxy calls. |
| 878 | |
| 879 | <Callout> |
| 880 | `sandbox` is the preferred config key. `workbench` still works as a fully supported alias and isn't deprecated, so existing code keeps running unchanged. |
| 881 | </Callout> |
| 882 | |
| 883 | ## Sandbox compute tier |
| 884 | |
| 885 | 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 via `sandbox.sandbox_size` (snake_case on the wire, `sandboxSize` in the TypeScript SDK). |
| 886 | |
| 887 | <Callout type="info"> |
| 888 | 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](/docs/changelog/2026/04/28). |
| 889 | </Callout> |
| 890 | |
| 891 | |
| 892 | | Tier | vCPU | RAM | |
| 893 | | ---------- | ---- | ----- | |
| 894 | | `standard` | 1 | 1 GB | |
| 895 | | `medium` | 2 | 2 GB | |
| 896 | | `large` | 4 | 4 GB | |
| 897 | | `xlarge` | 8 | 8 GB | |
| 898 | |
| 899 | Defaults to `standard` when omitted. |
| 900 | |
| 901 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 902 | <Tab value="Python"> |
| 903 | ```python |
| 904 | session = composio.sessions.create( |
| 905 | user_id="user_123", |
| 906 | sandbox={ |
| 907 | "enable": True, |
| 908 | "sandbox_size": "large", |
| 909 | }, |
| 910 | ) |
| 911 | ``` |
| 912 | </Tab> |
| 913 | <Tab value="TypeScript"> |
| 914 | ```typescript |
| 915 | // @noErrors |
| 916 | import { Composio } from '@composio/core'; |
| 917 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 918 | // ---cut--- |
| 919 | const session = await composio.create("user_123", { |
| 920 | sandbox: { |
| 921 | enable: true, |
| 922 | sandboxSize: "large", |
| 923 | }, |
| 924 | }); |
| 925 | ``` |
| 926 | </Tab> |
| 927 | <Tab value="API"> |
| 928 | ```bash |
| 929 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 930 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 931 | -H "Content-Type: application/json" \ |
| 932 | -d '{"user_id": "user_123", "workbench": {"enable": true, "sandbox_size": "large"}}' |
| 933 | ``` |
| 934 | </Tab> |
| 935 | </Tabs> |
| 936 | |
| 937 | <Callout type="info"> |
| 938 | **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. |
| 939 | </Callout> |
| 940 | |
| 941 | Changing `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](/docs/sandbox/remote#files-and-mounts) survives the restart. |
| 942 | |
| 943 | ## Updating a session |
| 944 | |
| 945 | `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. |
| 946 | |
| 947 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 948 | <Tab value="Python"> |
| 949 | ```python |
| 950 | session = composio.sessions.use("session_id") |
| 951 | |
| 952 | session.update(toolkits={"enable": ["gmail", "github"]}) |
| 953 | ``` |
| 954 | </Tab> |
| 955 | <Tab value="TypeScript"> |
| 956 | ```typescript |
| 957 | import { Composio } from '@composio/core'; |
| 958 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 959 | // ---cut--- |
| 960 | const session = await composio.sessions.use("session_id"); |
| 961 | |
| 962 | await session.update({ toolkits: { enable: ["gmail", "github"] } }); |
| 963 | ``` |
| 964 | </Tab> |
| 965 | <Tab value="API"> |
| 966 | ```bash |
| 967 | curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \ |
| 968 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 969 | -H "Content-Type: application/json" \ |
| 970 | -d '{"toolkits": {"enable": ["gmail", "github"]}}' |
| 971 | ``` |
| 972 | </Tab> |
| 973 | </Tabs> |
| 974 | |
| 975 | <Callout type="info"> |
| 976 | The update behavior below requires `@composio/core` ≥ `0.19.1` (TypeScript) or `composio` ≥ `0.22.1` (Python). |
| 977 | </Callout> |
| 978 | |
| 979 | ### Maps replace, they don't merge |
| 980 | |
| 981 | A `tools`, `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. |
| 982 | |
| 983 | Stored before the update: |
| 984 | |
| 985 | ```json |
| 986 | { |
| 987 | "tools": { |
| 988 | "gmail": { "enable": ["GMAIL_FETCH_EMAILS"] }, |
| 989 | "slack": { "enable": ["SLACK_SEND_MESSAGE"] } |
| 990 | } |
| 991 | } |
| 992 | ``` |
| 993 | |
| 994 | The update: |
| 995 | |
| 996 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 997 | <Tab value="Python"> |
| 998 | ```python |
| 999 | session.update( |
| 1000 | tools={"slack": {"enable": ["SLACK_SEND_MESSAGE", "SLACK_LIST_CHANNELS"]}}, |
| 1001 | ) |
| 1002 | ``` |
| 1003 | </Tab> |
| 1004 | <Tab value="TypeScript"> |
| 1005 | ```typescript |
| 1006 | import { Composio } from '@composio/core'; |
| 1007 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1008 | const session = await composio.sessions.use("session_id"); |
| 1009 | // ---cut--- |
| 1010 | await session.update({ |
| 1011 | tools: { slack: { enable: ["SLACK_SEND_MESSAGE", "SLACK_LIST_CHANNELS"] } }, |
| 1012 | }); |
| 1013 | ``` |
| 1014 | </Tab> |
| 1015 | <Tab value="API"> |
| 1016 | ```bash |
| 1017 | curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \ |
| 1018 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 1019 | -H "Content-Type: application/json" \ |
| 1020 | -d '{"tools": {"slack": {"enable": ["SLACK_SEND_MESSAGE", "SLACK_LIST_CHANNELS"]}}}' |
| 1021 | ``` |
| 1022 | </Tab> |
| 1023 | </Tabs> |
| 1024 | |
| 1025 | Stored after the update. The `gmail` entry is gone: |
| 1026 | |
| 1027 | ```json |
| 1028 | { |
| 1029 | "tools": { |
| 1030 | "slack": { "enable": ["SLACK_SEND_MESSAGE", "SLACK_LIST_CHANNELS"] } |
| 1031 | } |
| 1032 | } |
| 1033 | ``` |
| 1034 | |
| 1035 | To change one entry, send the whole map with every entry you want to keep. An empty map (`{}`) is stored as an explicit empty map. |
| 1036 | |
| 1037 | 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. |
| 1038 | |
| 1039 | ### Narrowing an existing session to no app toolkits |
| 1040 | |
| 1041 | 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. |
| 1042 | |
| 1043 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1044 | <Tab value="Python"> |
| 1045 | ```python |
| 1046 | session.update(toolkits={"enable": []}) |
| 1047 | ``` |
| 1048 | </Tab> |
| 1049 | <Tab value="TypeScript"> |
| 1050 | ```typescript |
| 1051 | import { Composio } from '@composio/core'; |
| 1052 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1053 | const session = await composio.sessions.use("session_id"); |
| 1054 | // ---cut--- |
| 1055 | await session.update({ toolkits: { enable: [] } }); |
| 1056 | ``` |
| 1057 | </Tab> |
| 1058 | <Tab value="API"> |
| 1059 | ```bash |
| 1060 | curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \ |
| 1061 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 1062 | -H "Content-Type: application/json" \ |
| 1063 | -d '{"toolkits": {"enable": []}}' |
| 1064 | ``` |
| 1065 | </Tab> |
| 1066 | </Tabs> |
| 1067 | |
| 1068 | ### Removing a callback URL |
| 1069 | |
| 1070 | `manageConnections.callbackUrl: null` removes only the stored callback URL. `enable` and the other connection settings stay as they are. An empty string is rejected. |
| 1071 | |
| 1072 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1073 | <Tab value="Python"> |
| 1074 | ```python |
| 1075 | session.update(manage_connections={"callback_url": None}) |
| 1076 | ``` |
| 1077 | </Tab> |
| 1078 | <Tab value="TypeScript"> |
| 1079 | ```typescript |
| 1080 | // @noErrors |
| 1081 | import { Composio } from '@composio/core'; |
| 1082 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1083 | const session = await composio.sessions.use("session_id"); |
| 1084 | // ---cut--- |
| 1085 | await session.update({ manageConnections: { callbackUrl: null } }); |
| 1086 | ``` |
| 1087 | </Tab> |
| 1088 | <Tab value="API"> |
| 1089 | {/* code-example: unchecked-api rule="api-body-schema" operation="PATCH /api/v3.1/tool_router/session/{session_id}" field="manage_connections.callback_url" reason="openapi.json types callback_url as a string; the API accepts null to remove it" */} |
| 1090 | ```bash |
| 1091 | curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \ |
| 1092 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 1093 | -H "Content-Type: application/json" \ |
| 1094 | -d '{"manage_connections": {"callback_url": null}}' |
| 1095 | ``` |
| 1096 | </Tab> |
| 1097 | </Tabs> |
| 1098 | |
| 1099 | ### Clearing a block with null |
| 1100 | |
| 1101 | Passing `null` (`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`. |
| 1102 | |
| 1103 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1104 | <Tab value="Python"> |
| 1105 | ```python |
| 1106 | session.update(manage_connections=None, multi_account=None) |
| 1107 | ``` |
| 1108 | </Tab> |
| 1109 | <Tab value="TypeScript"> |
| 1110 | ```typescript |
| 1111 | import { Composio } from '@composio/core'; |
| 1112 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1113 | const session = await composio.sessions.use("session_id"); |
| 1114 | // ---cut--- |
| 1115 | await session.update({ manageConnections: null, multiAccount: null }); |
| 1116 | ``` |
| 1117 | </Tab> |
| 1118 | <Tab value="API"> |
| 1119 | ```bash |
| 1120 | curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \ |
| 1121 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 1122 | -H "Content-Type: application/json" \ |
| 1123 | -d '{"manage_connections": null, "multi_account": null}' |
| 1124 | ``` |
| 1125 | </Tab> |
| 1126 | </Tabs> |
| 1127 | |
| 1128 | Clearing a policy can widen access. `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. |
| 1129 | |
| 1130 | ### Blocks you can set only on update |
| 1131 | |
| 1132 | `search`, `execute`, and `experimental` are not part of `create()`. Reach them with `session.update()` on an existing session. |
| 1133 | |
| 1134 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1135 | <Tab value="Python"> |
| 1136 | ```python |
| 1137 | session.update( |
| 1138 | search={"enable": False}, |
| 1139 | execute={"enable_multi_execute": False}, |
| 1140 | ) |
| 1141 | ``` |
| 1142 | </Tab> |
| 1143 | <Tab value="TypeScript"> |
| 1144 | ```typescript |
| 1145 | // @noErrors |
| 1146 | import { Composio } from '@composio/core'; |
| 1147 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1148 | const session = await composio.sessions.use("session_id"); |
| 1149 | // ---cut--- |
| 1150 | await session.update({ |
| 1151 | search: { enable: false }, |
| 1152 | execute: { enableMultiExecute: false }, |
| 1153 | }); |
| 1154 | ``` |
| 1155 | </Tab> |
| 1156 | <Tab value="API"> |
| 1157 | ```bash |
| 1158 | curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \ |
| 1159 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 1160 | -H "Content-Type: application/json" \ |
| 1161 | -d '{"search": {"enable": false}, "execute": {"enable_multi_execute": false}}' |
| 1162 | ``` |
| 1163 | </Tab> |
| 1164 | </Tabs> |
| 1165 | |
| 1166 | Both blocks are on by default. `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. |
| 1167 | |
| 1168 | The `experimental` block on update holds server-side session settings: `permissions`, `linkUrlOverwrite`, `fastMode`, `submitFeedback`, and `sessionConfigId`. `sessionConfigId` applies a [saved Session config](/docs/session-configs#applying-a-config-to-an-existing-session) 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 [local tools and toolkits](/docs/extending-sessions/local-tools-and-toolkits) that run in your process, so `experimental: null` on an update leaves those alone. |
| 1169 | |
| 1170 | ### Multi-account mode after an update |
| 1171 | |
| 1172 | 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`. |
| 1173 | |
| 1174 | ### Preload must stay inside the policy |
| 1175 | |
| 1176 | An update that narrows `toolkits`, `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: |
| 1177 | |
| 1178 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1179 | <Tab value="Python"> |
| 1180 | ```python |
| 1181 | session.update( |
| 1182 | toolkits={"enable": ["slack"]}, |
| 1183 | preload={"tools": ["SLACK_SEND_MESSAGE"]}, |
| 1184 | ) |
| 1185 | ``` |
| 1186 | </Tab> |
| 1187 | <Tab value="TypeScript"> |
| 1188 | ```typescript |
| 1189 | import { Composio } from '@composio/core'; |
| 1190 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1191 | const session = await composio.sessions.use("session_id"); |
| 1192 | // ---cut--- |
| 1193 | await session.update({ |
| 1194 | toolkits: { enable: ["slack"] }, |
| 1195 | preload: { tools: ["SLACK_SEND_MESSAGE"] }, |
| 1196 | }); |
| 1197 | ``` |
| 1198 | </Tab> |
| 1199 | <Tab value="API"> |
| 1200 | ```bash |
| 1201 | curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \ |
| 1202 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 1203 | -H "Content-Type: application/json" \ |
| 1204 | -d '{"toolkits": {"enable": ["slack"]}, "preload": {"tools": ["SLACK_SEND_MESSAGE"]}}' |
| 1205 | ``` |
| 1206 | </Tab> |
| 1207 | </Tabs> |
| 1208 | |
| 1209 | ### Concurrent updates |
| 1210 | |
| 1211 | 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. |
| 1212 | |
| 1213 | <Callout type="info"> |
| 1214 | The API must support `expected_config_version`. If it doesn't, it rejects a conditional update with a `400`. |
| 1215 | </Callout> |
| 1216 | |
| 1217 | On a conflict, the SDK raises `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: |
| 1218 | |
| 1219 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1220 | <Tab value="Python"> |
| 1221 | ```python |
| 1222 | from composio.exceptions import SessionConfigConflictError |
| 1223 | |
| 1224 | session = composio.sessions.use("session_id") |
| 1225 | |
| 1226 | try: |
| 1227 | session.update( |
| 1228 | toolkits={"enable": ["gmail", "github"]}, |
| 1229 | expected_config_version=session.config_version, |
| 1230 | ) |
| 1231 | except SessionConfigConflictError: |
| 1232 | # Another client changed the session first. Nothing was written. |
| 1233 | session = composio.sessions.use("session_id") |
| 1234 | session.update( |
| 1235 | toolkits={"enable": ["gmail", "github"]}, |
| 1236 | expected_config_version=session.config_version, |
| 1237 | ) |
| 1238 | ``` |
| 1239 | </Tab> |
| 1240 | <Tab value="TypeScript"> |
| 1241 | ```typescript |
| 1242 | // @noErrors |
| 1243 | import { Composio, ComposioSessionConfigConflictError } from '@composio/core'; |
| 1244 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1245 | // ---cut--- |
| 1246 | let session = await composio.sessions.use("session_id"); |
| 1247 | |
| 1248 | try { |
| 1249 | await session.update({ |
| 1250 | toolkits: { enable: ["gmail", "github"] }, |
| 1251 | expectedConfigVersion: session.configVersion, |
| 1252 | }); |
| 1253 | } catch (error) { |
| 1254 | if (!(error instanceof ComposioSessionConfigConflictError)) throw error; |
| 1255 | // Another client changed the session first. Nothing was written. |
| 1256 | session = await composio.sessions.use("session_id"); |
| 1257 | await session.update({ |
| 1258 | toolkits: { enable: ["gmail", "github"] }, |
| 1259 | expectedConfigVersion: session.configVersion, |
| 1260 | }); |
| 1261 | } |
| 1262 | ``` |
| 1263 | </Tab> |
| 1264 | <Tab value="API"> |
| 1265 | {/* code-example: unchecked-api rule="api-body-schema" operation="PATCH /api/v3.1/tool_router/session/{session_id}" field="expected_config_version" reason="the PATCH endpoint accepts expected_config_version but its OpenAPI schema omits the field" */} |
| 1266 | ```bash |
| 1267 | CONFIG_VERSION=$(curl -s -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \ |
| 1268 | -H "x-api-key: $COMPOSIO_API_KEY" | jq -r '.config_version') |
| 1269 | |
| 1270 | # Returns 409 and writes nothing if another client changed the session first. |
| 1271 | # Re-read config_version and retry. |
| 1272 | curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \ |
| 1273 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 1274 | -H "Content-Type: application/json" \ |
| 1275 | -d '{"toolkits": {"enable": ["gmail", "github"]}, "expected_config_version": '"$CONFIG_VERSION"'}' |
| 1276 | ``` |
| 1277 | </Tab> |
| 1278 | </Tabs> |
| 1279 | |
| 1280 | You can also pass a version you read elsewhere, for example one stored with a queued job. `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. |
| 1281 | |
| 1282 | Raw HTTP callers set `expected_config_version` in the `PATCH` body themselves; without it the last writer wins. |
| 1283 | |
| 1284 | 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. |
| 1285 | |
| 1286 | ## Session methods |
| 1287 | |
| 1288 | For framework examples, see provider-specific documentation like [OpenAI](/docs/providers/openai) or [Vercel AI SDK](/docs/providers/vercel). To connect over MCP instead, see [Using sessions via MCP](/docs/sessions-via-mcp). |
| 1289 | |
| 1290 | ### tools() |
| 1291 | |
| 1292 | Get the tools the session exposes for your AI framework. By default these are the session's [meta tools](/toolkits/meta-tools), formatted for your configured provider. |
| 1293 | |
| 1294 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1295 | <Tab value="Python"> |
| 1296 | ```python |
| 1297 | tools = session.tools() |
| 1298 | ``` |
| 1299 | </Tab> |
| 1300 | <Tab value="TypeScript"> |
| 1301 | ```typescript |
| 1302 | import { Composio } from '@composio/core'; |
| 1303 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1304 | const session = await composio.create("user_123"); |
| 1305 | // ---cut--- |
| 1306 | const tools = await session.tools(); |
| 1307 | ``` |
| 1308 | </Tab> |
| 1309 | <Tab value="API"> |
| 1310 | ```bash |
| 1311 | curl -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools \ |
| 1312 | -H "x-api-key: $COMPOSIO_API_KEY" |
| 1313 | ``` |
| 1314 | </Tab> |
| 1315 | </Tabs> |
| 1316 | |
| 1317 | ### executeMeta() / execute_meta() |
| 1318 | |
| 1319 | Run a `COMPOSIO_*` [meta tool](/toolkits/meta-tools) directly from your session with a slug and optional arguments: |
| 1320 | |
| 1321 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1322 | <Tab value="Python"> |
| 1323 | ```python |
| 1324 | from composio import Composio |
| 1325 | |
| 1326 | composio = Composio(api_key="your_api_key") |
| 1327 | session = composio.create(user_id="user_123") |
| 1328 | result = session.execute_meta( |
| 1329 | "COMPOSIO_SEARCH_TOOLS", |
| 1330 | arguments={"queries": [{"use_case": "send an email"}]}, |
| 1331 | ) |
| 1332 | print(result.data, result.result_type) |
| 1333 | ``` |
| 1334 | </Tab> |
| 1335 | <Tab value="TypeScript"> |
| 1336 | ```typescript |
| 1337 | import { Composio } from '@composio/core'; |
| 1338 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1339 | const session = await composio.create("user_123"); |
| 1340 | // ---cut--- |
| 1341 | const result = await session.executeMeta("COMPOSIO_SEARCH_TOOLS", { |
| 1342 | queries: [{ use_case: "send an email" }], |
| 1343 | }); |
| 1344 | console.log(result.data, result.resultType); |
| 1345 | ``` |
| 1346 | </Tab> |
| 1347 | <Tab value="API"> |
| 1348 | ```bash |
| 1349 | SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 1350 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 1351 | -H "Content-Type: application/json" \ |
| 1352 | -d '{"user_id": "user_123"}' | jq -r '.session_id') |
| 1353 | |
| 1354 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/execute_meta \ |
| 1355 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 1356 | -H "Content-Type: application/json" \ |
| 1357 | -d '{"slug": "COMPOSIO_SEARCH_TOOLS", "arguments": {"queries": [{"use_case": "send an email"}]}}' |
| 1358 | ``` |
| 1359 | </Tab> |
| 1360 | </Tabs> |
| 1361 | |
| 1362 | The exported `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. |
| 1363 | |
| 1364 | 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)`. |
| 1365 | |
| 1366 | `COMPOSIO_MULTI_EXECUTE_TOOL` calls through this method run on the backend. Local tools named in those calls are not executed in your process. |
| 1367 | |
| 1368 | ### authorize() |
| 1369 | |
| 1370 | Manually authenticate a user to a toolkit outside of the chat flow. |
| 1371 | |
| 1372 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1373 | <Tab value="Python"> |
| 1374 | ```python |
| 1375 | connection_request = session.authorize( |
| 1376 | "github", |
| 1377 | callback_url="https://myapp.com/callback", |
| 1378 | ) |
| 1379 | |
| 1380 | print(connection_request.redirect_url) |
| 1381 | |
| 1382 | connected_account = connection_request.wait_for_connection() |
| 1383 | ``` |
| 1384 | </Tab> |
| 1385 | <Tab value="TypeScript"> |
| 1386 | ```typescript |
| 1387 | import { Composio } from '@composio/core'; |
| 1388 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1389 | const session = await composio.create("user_123"); |
| 1390 | // ---cut--- |
| 1391 | const connectionRequest = await session.authorize("github", { |
| 1392 | callbackUrl: "https://myapp.com/callback", |
| 1393 | }); |
| 1394 | |
| 1395 | console.log(connectionRequest.redirectUrl); |
| 1396 | |
| 1397 | const connectedAccount = await connectionRequest.waitForConnection(); |
| 1398 | ``` |
| 1399 | </Tab> |
| 1400 | <Tab value="API"> |
| 1401 | ```bash |
| 1402 | curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/link \ |
| 1403 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 1404 | -H "Content-Type: application/json" \ |
| 1405 | -d '{"toolkit": "github", "callback_url": "https://myapp.com/callback"}' | jq -r '.redirect_url' |
| 1406 | ``` |
| 1407 | </Tab> |
| 1408 | </Tabs> |
| 1409 | |
| 1410 | For more details, see [Manually authenticating users](/docs/authentication/manually-authenticating). |
| 1411 | |
| 1412 | ### toolkits() |
| 1413 | |
| 1414 | 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 its `slug`, `name`, `logo`, and connection status, and the call returns the first 20 by default. |
| 1415 | |
| 1416 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1417 | <Tab value="Python"> |
| 1418 | ```python |
| 1419 | toolkits = session.toolkits() |
| 1420 | |
| 1421 | for toolkit in toolkits.items: |
| 1422 | connection = toolkit.connection |
| 1423 | if connection and connection.is_active and connection.connected_account: |
| 1424 | status = connection.connected_account.id |
| 1425 | else: |
| 1426 | status = "Not connected" |
| 1427 | print(f"{toolkit.name}: {status}") |
| 1428 | ``` |
| 1429 | </Tab> |
| 1430 | <Tab value="TypeScript"> |
| 1431 | ```typescript |
| 1432 | import { Composio } from '@composio/core'; |
| 1433 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1434 | const session = await composio.create("user_123"); |
| 1435 | // ---cut--- |
| 1436 | const toolkits = await session.toolkits(); |
| 1437 | |
| 1438 | toolkits.items.forEach((toolkit) => { |
| 1439 | console.log(`${toolkit.name}: ${toolkit.connection?.connectedAccount?.id ?? "Not connected"}`); |
| 1440 | }); |
| 1441 | ``` |
| 1442 | </Tab> |
| 1443 | <Tab value="API"> |
| 1444 | ```bash |
| 1445 | curl -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/toolkits \ |
| 1446 | -H "x-api-key: $COMPOSIO_API_KEY" |
| 1447 | ``` |
| 1448 | </Tab> |
| 1449 | </Tabs> |
| 1450 | |
| 1451 | Filter to only connected toolkits: |
| 1452 | |
| 1453 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1454 | <Tab value="Python"> |
| 1455 | ```python |
| 1456 | connected = session.toolkits(is_connected=True) |
| 1457 | ``` |
| 1458 | </Tab> |
| 1459 | <Tab value="TypeScript"> |
| 1460 | ```typescript |
| 1461 | import { Composio } from '@composio/core'; |
| 1462 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1463 | const session = await composio.create("user_123"); |
| 1464 | // ---cut--- |
| 1465 | const connected = await session.toolkits({ isConnected: true }); |
| 1466 | ``` |
| 1467 | </Tab> |
| 1468 | <Tab value="API"> |
| 1469 | ```bash |
| 1470 | curl -X GET "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/toolkits?is_connected=true" \ |
| 1471 | -H "x-api-key: $COMPOSIO_API_KEY" |
| 1472 | ``` |
| 1473 | </Tab> |
| 1474 | </Tabs> |
| 1475 | |
| 1476 | Paginate through every toolkit with `limit` and the returned cursor: |
| 1477 | |
| 1478 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1479 | <Tab value="Python"> |
| 1480 | ```python |
| 1481 | all_toolkits = [] |
| 1482 | cursor = None |
| 1483 | |
| 1484 | while True: |
| 1485 | result = session.toolkits(limit=20, next_cursor=cursor) |
| 1486 | all_toolkits.extend(result.items) |
| 1487 | cursor = result.next_cursor |
| 1488 | if not cursor: |
| 1489 | break |
| 1490 | ``` |
| 1491 | </Tab> |
| 1492 | <Tab value="TypeScript"> |
| 1493 | ```typescript |
| 1494 | import { Composio } from '@composio/core'; |
| 1495 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1496 | const session = await composio.create("user_123"); |
| 1497 | // ---cut--- |
| 1498 | const allToolkits: any[] = []; |
| 1499 | let cursor: string | undefined; |
| 1500 | |
| 1501 | do { |
| 1502 | const { items, cursor: nextCursor } = await session.toolkits({ limit: 20, cursor }); |
| 1503 | allToolkits.push(...items); |
| 1504 | cursor = nextCursor; |
| 1505 | } while (cursor); |
| 1506 | ``` |
| 1507 | </Tab> |
| 1508 | <Tab value="API"> |
| 1509 | ```bash |
| 1510 | CURSOR="" |
| 1511 | while true; do |
| 1512 | PAGE=$(curl -s -X GET "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/toolkits?limit=20${CURSOR:+&cursor=$CURSOR}" \ |
| 1513 | -H "x-api-key: $COMPOSIO_API_KEY") |
| 1514 | echo "$PAGE" | jq -c '.items[]' |
| 1515 | CURSOR=$(echo "$PAGE" | jq -r '.next_cursor // empty') |
| 1516 | [ -z "$CURSOR" ] && break |
| 1517 | done |
| 1518 | ``` |
| 1519 | </Tab> |
| 1520 | </Tabs> |
| 1521 | |
| 1522 | ### update() |
| 1523 | |
| 1524 | Patch the session configuration in place. See [Updating a session](#updating-a-session) for what omitted fields, replaced maps, `null`, and `expectedConfigVersion` do. |
| 1525 | |
| 1526 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1527 | <Tab value="Python"> |
| 1528 | ```python |
| 1529 | config = session.update(toolkits={"enable": ["gmail", "github"]}) |
| 1530 | ``` |
| 1531 | </Tab> |
| 1532 | <Tab value="TypeScript"> |
| 1533 | ```typescript |
| 1534 | import { Composio } from '@composio/core'; |
| 1535 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1536 | const session = await composio.create("user_123"); |
| 1537 | // ---cut--- |
| 1538 | const config = await session.update({ toolkits: { enable: ["gmail", "github"] } }); |
| 1539 | ``` |
| 1540 | </Tab> |
| 1541 | <Tab value="API"> |
| 1542 | ```bash |
| 1543 | curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \ |
| 1544 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 1545 | -H "Content-Type: application/json" \ |
| 1546 | -d '{"toolkits": {"enable": ["gmail", "github"]}}' |
| 1547 | ``` |
| 1548 | </Tab> |
| 1549 | </Tabs> |
| 1550 | |
| 1551 | ### Configuration history |
| 1552 | |
| 1553 | Inspect the configurations a session has used with `session.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. |
| 1554 | |
| 1555 | 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. |
| 1556 | |
| 1557 | ### delete() |
| 1558 | |
| 1559 | Delete a session when you're done with it. Deleted sessions immediately stop being retrievable or executable, and the call returns the deleted `session_id`. Deleting a missing or already-deleted session surfaces the backend `404`. |
| 1560 | |
| 1561 | <Callout type="info"> |
| 1562 | Requires `@composio/core` ≥ `0.13.1` (TypeScript) or `composio` ≥ `0.17.1` (Python). |
| 1563 | </Callout> |
| 1564 | |
| 1565 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1566 | <Tab value="Python"> |
| 1567 | ```python |
| 1568 | result = session.delete() |
| 1569 | print(result["session_id"], result["deleted"]) |
| 1570 | ``` |
| 1571 | </Tab> |
| 1572 | <Tab value="TypeScript"> |
| 1573 | ```typescript |
| 1574 | import { Composio } from '@composio/core'; |
| 1575 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1576 | const session = await composio.create('user_123'); |
| 1577 | // ---cut--- |
| 1578 | const result = await session.delete(); |
| 1579 | console.log(result.sessionId, result.deleted); |
| 1580 | ``` |
| 1581 | </Tab> |
| 1582 | <Tab value="API"> |
| 1583 | ```bash |
| 1584 | curl -X DELETE https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \ |
| 1585 | -H "x-api-key: $COMPOSIO_API_KEY" |
| 1586 | ``` |
| 1587 | </Tab> |
| 1588 | </Tabs> |
| 1589 | |
| 1590 | ## Browsing the catalog |
| 1591 | |
| 1592 | Before configuring a session, explore the toolkits and tools available. Browse them visually at [dashboard.composio.dev](https://dashboard.composio.dev?utm_source=docs&utm_medium=content&utm_campaign=docs-configuring-sessions) or in the [docs catalog](/toolkits), or fetch them programmatically: |
| 1593 | |
| 1594 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1595 | <Tab value="Python"> |
| 1596 | ```python |
| 1597 | # List toolkits |
| 1598 | toolkits = composio.toolkits.get() |
| 1599 | |
| 1600 | # List tools within a toolkit (top 20 by default) |
| 1601 | tools = composio.tools.get("user_123", toolkits=["GITHUB"]) |
| 1602 | ``` |
| 1603 | </Tab> |
| 1604 | <Tab value="TypeScript"> |
| 1605 | ```typescript |
| 1606 | import { Composio } from '@composio/core'; |
| 1607 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1608 | const userId = 'user_123'; |
| 1609 | // ---cut--- |
| 1610 | // List toolkits |
| 1611 | const toolkits = await composio.toolkits.get(); |
| 1612 | |
| 1613 | // List tools within a toolkit (top 20 by default) |
| 1614 | const tools = await composio.tools.get(userId, { toolkits: ["GITHUB"] }); |
| 1615 | ``` |
| 1616 | </Tab> |
| 1617 | <Tab value="API"> |
| 1618 | ```bash |
| 1619 | # List toolkits |
| 1620 | curl -X GET https://backend.composio.dev/api/v3.1/toolkits \ |
| 1621 | -H "x-api-key: $COMPOSIO_API_KEY" |
| 1622 | |
| 1623 | # List tools within a toolkit (top 20 by default) |
| 1624 | curl -X GET "https://backend.composio.dev/api/v3.1/tools?toolkit_slug=GITHUB&limit=20" \ |
| 1625 | -H "x-api-key: $COMPOSIO_API_KEY" |
| 1626 | ``` |
| 1627 | </Tab> |
| 1628 | </Tabs> |
| 1629 | |
| 1630 | Inspect a tool's input and output schema without a user context with `getRawComposioToolBySlug`: |
| 1631 | |
| 1632 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 1633 | <Tab value="Python"> |
| 1634 | ```python |
| 1635 | tool = composio.tools.get_raw_composio_tool_by_slug("GMAIL_SEND_EMAIL") |
| 1636 | print(tool.name) |
| 1637 | print(tool.description) |
| 1638 | print(tool.input_parameters) |
| 1639 | print(tool.output_parameters) |
| 1640 | ``` |
| 1641 | </Tab> |
| 1642 | <Tab value="TypeScript"> |
| 1643 | ```typescript |
| 1644 | import { Composio } from '@composio/core'; |
| 1645 | const composio = new Composio({ apiKey: 'your_api_key' }); |
| 1646 | // ---cut--- |
| 1647 | const tool = await composio.tools.getRawComposioToolBySlug("GMAIL_SEND_EMAIL"); |
| 1648 | console.log(tool.name); |
| 1649 | console.log(tool.description); |
| 1650 | console.log(tool.inputParameters); |
| 1651 | console.log(tool.outputParameters); |
| 1652 | ``` |
| 1653 | </Tab> |
| 1654 | <Tab value="API"> |
| 1655 | ```bash |
| 1656 | curl -X GET https://backend.composio.dev/api/v3.1/tools/GMAIL_SEND_EMAIL \ |
| 1657 | -H "x-api-key: $COMPOSIO_API_KEY" |
| 1658 | ``` |
| 1659 | </Tab> |
| 1660 | </Tabs> |
| 1661 | |
| 1662 | To fetch several toolkits in one request, use `composio.toolkits.get_many(["github", "slack"])` in Python or `await composio.toolkits.getMany(['github', 'slack'])` in TypeScript. Both return the matching toolkits. |
| 1663 | |
| 1664 | ## Next |
| 1665 | |
| 1666 | <Card icon={<Database />} title="Sandbox" href="/docs/sandbox/remote" description="Give sessions a persistent compute environment with COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL" /> |