Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 22:15 UTC
revert: remove docs changes, will ship after SDK release
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Abir Taheer committed
May 6, 2026 at 22:03 UTC
49598b5ee5fb014f7b3b5168af3f49e1e01be838
6 files changed
+15
-79
docs/content/docs/configuring-sessions.mdx
+5
-7
@@ -24,7 +24,7 @@ const session = await composio.create("user_123");
24
25
By default, a session has access to **all toolkits** 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.
26
27
-You can also attach local experimental custom tools and custom toolkits that run in-process alongside Composio tools. See [Custom tools and toolkits](/docs/toolkits/custom-tools-and-toolkits).
27
+For TypeScript sessions, you can also attach local experimental custom tools and custom toolkits that run in-process with Composio tools. See [Custom tools and toolkits](/docs/toolkits/custom-tools-and-toolkits).
28
29
## Enabling toolkits
30
@@ -132,8 +132,8 @@ If a user has multiple connected accounts for the same toolkit, you can specify
132
session = composio.create(
133
user_id="user_123",
134
connected_accounts={
135
- "gmail": ["ca_work_gmail"],
136
- "github": ["ca_personal_github"],
135
+ "gmail": "ca_work_gmail",
136
+ "github": "ca_personal_github"
137
}
138
)
139
```
@@ -145,16 +145,14 @@ const composio = new Composio({ apiKey: 'your_api_key' });
145
// ---cut---
146
const session = await composio.create("user_123", {
147
connectedAccounts: {
148
- gmail: ["ca_work_gmail"],
149
- github: ["ca_personal_github"],
148
+ gmail: "ca_work_gmail",
149
+ github: "ca_personal_github",
150
},
151
});
152
```
153
</Tab>
154
</Tabs>
155
156
-Only one account per toolkit is allowed when [multi-account mode](/docs/managing-multiple-connected-accounts) is disabled.
157
-
156
### Precedence
157
158
When executing a tool, the connected account is selected in this order:
docs/content/docs/managing-multiple-connected-accounts.mdx
+4
-4
@@ -192,8 +192,8 @@ Pin a session to specific accounts by passing their IDs in the session config. T
192
session = composio.create(
193
user_id="user_123",
194
connected_accounts={
195
- "gmail": ["ca_work_gmail_id"],
196
- "github": ["ca_personal_github_id"],
195
+ "gmail": "ca_work_gmail_id",
196
+ "github": "ca_personal_github_id",
197
},
198
)
199
```
@@ -206,8 +206,8 @@ const composio = new Composio({ apiKey: 'your_api_key' });
206
// ---cut---
207
const session = await composio.create("user_123", {
208
connectedAccounts: {
209
- gmail: ["ca_work_gmail_id"],
210
- github: ["ca_personal_github_id"],
209
+ gmail: "ca_work_gmail_id",
210
+ github: "ca_personal_github_id",
211
},
212
});
213
```
docs/content/docs/migration-guide/direct-to-sessions.mdx
+2
-2
@@ -241,7 +241,7 @@ session = composio.create(
241
"gmail": "ac_your_gmail_config"
242
},
243
connected_accounts={
244
- "gmail": ["ca_work_gmail"]
244
+ "gmail": "ca_work_gmail"
245
}
246
)
247
```
@@ -256,7 +256,7 @@ const session = await composio.create("user_123", {
256
gmail: "ac_your_gmail_config",
257
},
258
connectedAccounts: {
259
- gmail: ["ca_work_gmail"],
259
+ gmail: "ca_work_gmail",
260
},
261
});
262
```
docs/content/docs/sessions-vs-direct-execution.mdx
+2
-2
@@ -89,7 +89,7 @@ session = composio.create(
89
user_id="user_123",
90
toolkits=["github", "gmail"],
91
auth_configs={"github": "ac_my_config"},
92
- connected_accounts={"gmail": ["ca_work"]},
92
+ connected_accounts={"gmail": "ca_work"},
93
)
94
```
95
</Tab>
@@ -101,7 +101,7 @@ const composio = new Composio({ apiKey: 'your_api_key' });
101
const session = await composio.create("user_123", {
102
toolkits: ["github", "gmail"],
103
authConfigs: { github: "ac_my_config" },
104
- connectedAccounts: { gmail: ["ca_work"] },
104
+ connectedAccounts: { gmail: "ca_work" },
105
});
106
```
107
</Tab>
docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
-60
@@ -557,66 +557,6 @@ custom_toolkits = session.custom_toolkits()
557
</Tab>
558
</Tabs>
559
560
-## Attaching custom tools to an existing session
561
-
562
-Use `composio.use()` to rehydrate an existing session and attach custom tools to it. This is useful when you have a session ID from a previous `create()` call and want to bind custom tools in a different process or request.
563
-
564
-<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
565
-<Tab value="TypeScript">
566
-```typescript
567
-// @noErrors
568
-import { Composio, experimental_createTool } from "@composio/core";
569
-import { z } from "zod/v3";
570
-
571
-declare const getUserProfile: ReturnType<typeof experimental_createTool>;
572
-const composio = new Composio({ apiKey: "your_api_key" });
573
-// ---cut---
574
-
575
-// Rehydrate with custom tools
576
-const session = await composio.use("session_id", {
577
- customTools: [getUserProfile],
578
-});
579
-
580
-const tools = await session.tools();
581
-```
582
-</Tab>
583
-<Tab value="Python">
584
-```python
585
-from composio import Composio
586
-
587
-composio = Composio(api_key="your_api_key")
588
-
589
-# Rehydrate with custom tools
590
-session = composio.use(
591
- "session_id",
592
- custom_tools=[get_user_profile],
593
-)
594
-
595
-tools = session.tools()
596
-```
597
-</Tab>
598
-</Tabs>
599
-
600
-Without custom tools, `composio.use()` simply rehydrates the session:
601
-
602
-<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
603
-<Tab value="TypeScript">
604
-```typescript
605
-// @noErrors
606
-import { Composio } from "@composio/core";
607
-const composio = new Composio({ apiKey: "your_api_key" });
608
-// ---cut---
609
-
610
-const session = await composio.use("session_id");
611
-```
612
-</Tab>
613
-<Tab value="Python">
614
-```python
615
-session = composio.use("session_id")
616
-```
617
-</Tab>
618
-</Tabs>
619
-
560
## Programmatic execution
561
562
Use `session.execute()` to run custom tools directly, outside of an agent loop. Custom tools execute in-process; remote tools are sent to the backend automatically.
docs/content/docs/users-and-sessions.mdx
+2
-4
@@ -107,11 +107,9 @@ A session ties together a user, a set of available toolkits, auth configuration
107
108
You don't need to cache session IDs, manage session lifetimes, or worry about expiration. Sessions persist on the server and don't expire. Just call `create()` with what you need.
109
110
-### Session configuration is fixed at creation
110
+### Sessions are immutable
111
112
-A session's toolkits, auth configs, and connected accounts are fixed at creation. You cannot change them on an existing session.
113
-
114
-The one exception is [custom tools](/docs/toolkits/custom-tools-and-toolkits): you can attach custom tools to an existing session via `composio.use(sessionId, { customTools: [...] })`.
112
+A session's configuration is fixed at creation. You cannot change the toolkits, auth configs, or connected accounts on an existing session.
113
114
This means the boundary for a new session isn't a new chat or a new request. It's when the contract changes. If a user starts with "search my personal Gmail" and then says "actually use my work email," that's a different session because the auth changed.
115