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

next
mdx 1,666 lines 58.8 KB
Raw
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" />