Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: update documentation for new changelog entries (#3816)
## Summary Automated documentation updates triggered by new changelog entries merged to next. Generated by Codex via GitHub Actions. Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Alberto Schiabel committed
Jul 13, 2026 at 16:46 UTC
f9c2dc5d007d1f5d9aa35432dfba82aa2d3b8025
7 files changed
+72
-29
docs/content/docs/configuring-sessions.mdx
+17
-17
@@ -9,7 +9,7 @@ keywords: [session, toolkits, auth configs, connected accounts]
9
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
10
<Tab value="Python">
11
```python
12
-session = composio.create(user_id="user_123")
12
+session = composio.sessions.create(user_id="user_123")
13
```
14
</Tab>
15
<Tab value="TypeScript">
@@ -34,13 +34,13 @@ To limit a session to specific toolkits, pass an array of toolkit slugs. The age
34
<Tab value="Python">
35
```python
36
# Using array format
37
-session = composio.create(
37
+session = composio.sessions.create(
38
user_id="user_123",
39
toolkits=["github", "gmail", "slack"]
40
)
41
42
# Using object format with enable key
43
-session = composio.create(
43
+session = composio.sessions.create(
44
user_id="user_123",
45
toolkits={"enable": ["github", "gmail", "slack"]}
46
)
@@ -71,7 +71,7 @@ To keep every toolkit discoverable except a few, use the `disable` syntax. This
71
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
72
<Tab value="Python">
73
```python
74
-session = composio.create(
74
+session = composio.sessions.create(
75
user_id="user_123",
76
toolkits={"disable": ["exa", "firecrawl"]}
77
)
@@ -106,7 +106,7 @@ composio = Composio(
106
provider=OpenAIAgentsProvider(),
107
)
108
109
-session = composio.create(
109
+session = composio.sessions.create(
110
user_id="user_123",
111
toolkits=["gmail"],
112
tools={
@@ -169,7 +169,7 @@ composio = Composio(
169
provider=OpenAIAgentsProvider(),
170
)
171
172
-session = composio.create(
172
+session = composio.sessions.create(
173
user_id="user_123",
174
toolkits=["gmail"],
175
tools={
@@ -245,7 +245,7 @@ To enable only specific tools, pass an `enable` list per toolkit:
245
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
246
<Tab value="Python">
247
```python
248
-session = composio.create(
248
+session = composio.sessions.create(
249
user_id="user_123",
250
tools={
251
# Only these Gmail tools will be available
@@ -278,7 +278,7 @@ The shorthand array syntax is equivalent to `enable`:
278
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
279
<Tab value="Python">
280
```python
281
-session = composio.create(
281
+session = composio.sessions.create(
282
user_id="user_123",
283
tools={
284
"gmail": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
@@ -307,7 +307,7 @@ To keep every tool in a toolkit except a few, use `disable`:
307
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
308
<Tab value="Python">
309
```python
310
-session = composio.create(
310
+session = composio.sessions.create(
311
user_id="user_123",
312
tools={
313
# All Slack tools except delete
@@ -352,13 +352,13 @@ To apply tag filters across all toolkits, pass `tags` at the session level:
352
<Tab value="Python">
353
```python
354
# Only include read-only and idempotent tools
355
-session = composio.create(
355
+session = composio.sessions.create(
356
user_id="user_123",
357
tags=["readOnlyHint", "idempotentHint"]
358
)
359
360
# Enable some tags, disable others
361
-session = composio.create(
361
+session = composio.sessions.create(
362
user_id="user_123",
363
tags={
364
"enable": ["readOnlyHint"],
@@ -393,7 +393,7 @@ To override the global tags for a specific toolkit, set `tags` inside that toolk
393
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
394
<Tab value="Python">
395
```python
396
-session = composio.create(
396
+session = composio.sessions.create(
397
user_id="user_123",
398
# Global: only read-only tools
399
tags=["readOnlyHint"],
@@ -455,7 +455,7 @@ composio = Composio(
455
provider=OpenAIAgentsProvider(),
456
)
457
458
-session = composio.create(
458
+session = composio.sessions.create(
459
user_id="user_123",
460
toolkits=["gmail"],
461
preload={
@@ -512,7 +512,7 @@ Use your own OAuth credentials instead of Composio's defaults. Pass an auth conf
512
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
513
<Tab value="Python">
514
```python
515
-session = composio.create(
515
+session = composio.sessions.create(
516
user_id="user_123",
517
auth_configs={
518
"github": "ac_your_github_config",
@@ -545,7 +545,7 @@ When a user has multiple connected accounts for the same toolkit, specify which
545
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
546
<Tab value="Python">
547
```python
548
-session = composio.create(
548
+session = composio.sessions.create(
549
user_id="user_123",
550
connected_accounts={
551
"gmail": ["ca_work_gmail"],
@@ -592,7 +592,7 @@ By default, sessions include the [sandbox](/docs/sandbox/remote), a persistent e
592
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
593
<Tab value="Python">
594
```python
595
-session = composio.create(
595
+session = composio.sessions.create(
596
user_id="user_123",
597
sandbox={
598
"enable": False
@@ -645,7 +645,7 @@ Defaults to `standard` when omitted.
645
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
646
<Tab value="Python">
647
```python
648
-session = composio.create(
648
+session = composio.sessions.create(
649
user_id="user_123",
650
sandbox={
651
"sandbox_size": "large",
docs/content/docs/how-composio-works.mdx
+2
-2
@@ -4,7 +4,7 @@ description: What Composio sessions do, and how they scope users, tools, toolkit
4
keywords: [session, userID, tools, toolkits, meta tools, mcp, workbench]
5
---
6
7
-A **session** is the runtime context for an agentic run: the scoped environment an AI agent works in while it acts for one of your users. In TypeScript, you create it with `composio.sessions.create(userId)`; Python uses `composio.create(user_id)`. It ties together the user, the toolkits available, authentication, and connected accounts. By default it gives the agent meta tools to discover, authenticate, and execute app tools at runtime, instead of loading hundreds of tool definitions into context.
7
+A **session** is the runtime context for an agentic run: the scoped environment an AI agent works in while it acts for one of your users. Create one with `composio.sessions.create(...)` in either SDK. It ties together the user, the toolkits available, authentication, and connected accounts. By default it gives the agent meta tools to discover, authenticate, and execute app tools at runtime, instead of loading hundreds of tool definitions into context.
8
9
## The basics
10
@@ -13,7 +13,7 @@ Create a session for a user, then read its tools formatted for your framework. T
13
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
14
<Tab value="Python">
15
```python
16
-session = composio.create(user_id="user_123")
16
+session = composio.sessions.create(user_id="user_123")
17
18
tools = session.tools()
19
```
docs/content/docs/programmatic-auth-configs.mdx
+20
-1
@@ -139,7 +139,7 @@ Creating an auth config does not change which credentials a session uses. Pass t
139
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
140
<Tab value="Python">
141
```python
142
-session = composio.create(
142
+session = composio.sessions.create(
143
user_id="user_123",
144
auth_configs={"notion": auth_config.id},
145
)
@@ -160,6 +160,25 @@ const session = await composio.sessions.create('user_123', {
160
161
See [Configuring sessions](/docs/configuring-sessions#custom-auth-configs) for how `authConfigs` interacts with account selection and precedence.
162
163
+## Find auth configs
164
+
165
+In TypeScript, filter `authConfigs.list()` by name or ID with `search`. Disabled configs are excluded by default; set `showDisabled` to include them. Auth config responses use `id` as their canonical identifier.
166
+
167
+```typescript
168
+import { Composio } from '@composio/core';
169
+
170
+const composio = new Composio();
171
+// ---cut---
172
+const configs = await composio.authConfigs.list({
173
+ search: 'github',
174
+ showDisabled: true,
175
+});
176
+
177
+for (const config of configs.items) {
178
+ console.log(config.id);
179
+}
180
+```
181
+
182
## Discover the required fields
183
184
Different schemes need different credential fields. To build the `credentials` object dynamically, ask the toolkit which fields it requires for a given scheme before you create the config.
docs/content/docs/quickstart.mdx
+9
-5
@@ -6,6 +6,10 @@ keywords: [tutorial, setup, first agent]
6
7
Build your first AI agent with Composio Tools. You'll create a [session](/docs/how-composio-works) for a user, give your agent access to [tools](/docs/how-composio-works), and let it take action across 1000+ apps.
8
9
+<Callout type="info">
10
+The TypeScript SDK is ESM-only and requires Node.js 22.22.3 or newer. Use `import` syntax rather than CommonJS `require()`.
11
+</Callout>
12
+
13
<QuickstartFlow>
14
15
<FrameworkOption id="openai-agents" name="OpenAI Agents" logo="/images/providers/openai-logo.svg" logoDark="/images/providers/openai-logo-dark.svg">
@@ -62,10 +66,10 @@ composio = Composio(provider=OpenAIAgentsProvider())
66
67
# Create a session for your user
68
user_id = "user_123"
65
-session = composio.create(user_id=user_id)
69
+session = composio.sessions.create(user_id=user_id)
70
tools = session.tools()
71
68
-# For multi-turn, store the session ID in your db and reuse instead of calling create() again:
72
+# For multi-turn, store the session ID in your db and reuse instead of creating another session:
73
# session_id = session.session_id
74
# session = composio.use(session_id)
75
@@ -209,10 +213,10 @@ composio = Composio(provider=ClaudeAgentSDKProvider())
213
214
# Create a session for your user
215
user_id = "user_123"
212
-session = composio.create(user_id=user_id)
216
+session = composio.sessions.create(user_id=user_id)
217
tools = session.tools()
218
215
-# For multi-turn, store the session ID in your db and reuse instead of calling create() again:
219
+# For multi-turn, store the session ID in your db and reuse instead of creating another session:
220
# session_id = session.session_id
221
# session = composio.use(session_id)
222
@@ -426,7 +430,7 @@ readline.close();
430
431
</QuickstartFlow>
432
429
-By default, each `composio.create()` call returns a new session with access to all toolkits. Sessions are highly configurable beyond that: [Reusing a session](/docs/how-composio-works#how-sessions-behave) covers storing a session ID and calling `composio.use()` across multi-turn requests, while [Configuring Sessions](/docs/configuring-sessions) covers restricting toolkits, auth configs, and connected accounts.
433
+By default, each `composio.sessions.create()` call returns a new session with access to all toolkits. Sessions are highly configurable beyond that: [Reusing a session](/docs/how-composio-works#how-sessions-behave) covers storing a session ID and calling `composio.use()` across multi-turn requests, while [Configuring Sessions](/docs/configuring-sessions) covers restricting toolkits, auth configs, and connected accounts.
434
435
Prefer to connect over the Model Context Protocol instead? Every session also exposes an MCP endpoint. See [Using sessions via MCP](/docs/sessions-via-mcp).
436
docs/content/docs/sessions-via-mcp.mdx
+3
-3
@@ -18,7 +18,7 @@ Opt into MCP by passing `mcp: true` when you create the session. The session the
18
from composio import Composio
19
20
composio = Composio()
21
-session = composio.create(user_id="user_123", mcp=True)
21
+session = composio.sessions.create(user_id="user_123", mcp=True)
22
23
mcp_url = session.mcp.url
24
mcp_headers = session.mcp.headers
@@ -59,7 +59,7 @@ from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
59
60
composio = Composio()
61
62
-session = composio.create(
62
+session = composio.sessions.create(
63
user_id="user_123",
64
toolkits=["gmail"],
65
tools={"gmail": {"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"]}},
@@ -161,7 +161,7 @@ MCP is the more portable option. Any MCP-compatible client connects with just a
161
The trade-off is that the MCP client talks to Composio's server directly, so anything the SDK does *around* tool execution doesn't apply:
162
163
- **Tool-call modifiers don't run.** `beforeExecute` / `afterExecute` hooks and `modifySchema` transforms live in the SDK's execution path. Over MCP the client executes tools against the server and bypasses them, so you can't intercept, reshape, log, or gate calls the way you can with tools your agent calls directly.
164
-- **Session-bound custom tools and toolkits don't work.** Tools created with `createCustomTool` / `createCustomToolkit` run in your process. The MCP server only exposes Composio's hosted tools, so your local custom tools aren't available over the endpoint.
164
+- **Session-bound custom tools and toolkits don't work.** Tools created with `experimental_createTool` / `experimental_createToolkit` in TypeScript, or `composio.experimental.tool` / `composio.experimental.Toolkit` in Python, run in your process. The MCP server only exposes Composio's hosted tools, so your local custom tools aren't available over the endpoint.
165
166
If you need any of those, call tools directly through a [provider](/docs/providers) instead of over MCP.
167
docs/content/docs/shared-connections.mdx
+1
-1
@@ -102,7 +102,7 @@ The session config itself is **not** experimental. You pin the connection by ID
102
# user_alice starts a session that pins the shared Gmail connection.
103
# Gmail tools loaded from this session will resolve to that connection
104
# even though user_alice did not create it.
105
-session = composio.create(
105
+session = composio.sessions.create(
106
user_id="user_alice",
107
connected_accounts={
108
"gmail": ["ca_gmail_shared"],
docs/content/docs/tools-direct/executing-tools.mdx
+20
@@ -14,6 +14,26 @@ LLMs on their own can only do generation. Tool calling changes that by letting t
14
15
In Composio, every **tool** is a single API action—fully described with schema, parameters, and return type. Tools live inside **toolkits** like Gmail, Slack, or GitHub, and Composio handles authentication and user scoping.
16
17
+## Canceling TypeScript requests
18
+
19
+TypeScript SDK methods accept an `AbortSignal` in their trailing request options. Aborted requests throw `ComposioRequestCancelledError`, so cancellation can be handled separately from execution failures:
20
+
21
+```typescript
22
+import { Composio, ComposioRequestCancelledError } from '@composio/core';
23
+
24
+const composio = new Composio({ apiKey: 'your_composio_api_key' });
25
+
26
+try {
27
+ await composio.toolkits.get({}, { signal: AbortSignal.timeout(5_000) });
28
+} catch (error) {
29
+ if (error instanceof ComposioRequestCancelledError) {
30
+ console.log('Request canceled');
31
+ }
32
+}
33
+```
34
+
35
+Use an `AbortController` when application code decides when to cancel. Custom tools receive the same signal as `ctx.signal` and should pass it to cancellable work.
36
+
37
<Callout type="info">
38
**User Scoping**: All tools are scoped to a specific user - that's why every example includes a `user_id`. Learn how to structure User IDs in [User scoping](/docs/how-composio-works). Each user must authenticate with their respective services (Gmail, Calendar, etc.) - see [Authentication](/docs/tools-direct/authenticating-tools).
39
</Callout>