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: add .use() with custom tools, update connectedAccounts to array
- Added "Attaching custom tools to an existing session" section to custom-tools-and-toolkits.mdx showing composio.use() with customs - Updated all connectedAccounts examples to array format (string[]) matching the v3.1 SDK types - Updated configuring-sessions to note multi-account restriction - Updated users-and-sessions: custom tools can be attached to existing sessions via .use() - Removed TypeScript-only qualifier for custom tools Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Abir Taheer committed
May 6, 2026 at 22:18 UTC
15df5fad7f0a317bbf73504be432758662928836
6 files changed
+79
-15
docs/content/docs/configuring-sessions.mdx
+7
-5
@@ -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
-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).
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).
28
29
## Enabling toolkits
30
@@ -373,8 +373,8 @@ If a user has multiple connected accounts for the same toolkit, you can specify
373
session = composio.create(
374
user_id="user_123",
375
connected_accounts={
376
- "gmail": "ca_work_gmail",
377
- "github": "ca_personal_github"
376
+ "gmail": ["ca_work_gmail"],
377
+ "github": ["ca_personal_github"],
378
}
379
)
380
```
@@ -386,14 +386,16 @@ const composio = new Composio({ apiKey: 'your_api_key' });
386
// ---cut---
387
const session = await composio.create("user_123", {
388
connectedAccounts: {
389
- gmail: "ca_work_gmail",
390
- github: "ca_personal_github",
389
+ gmail: ["ca_work_gmail"],
390
+ github: ["ca_personal_github"],
391
},
392
});
393
```
394
</Tab>
395
</Tabs>
396
397
+Only one account per toolkit is allowed when [multi-account mode](/docs/managing-multiple-connected-accounts) is disabled.
398
+
399
### Precedence
400
401
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
@@ -636,6 +636,66 @@ custom_toolkits = session.custom_toolkits()
636
</Tab>
637
</Tabs>
638
639
+## Attaching custom tools to an existing session
640
+
641
+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.
642
+
643
+<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
644
+<Tab value="TypeScript">
645
+```typescript
646
+// @noErrors
647
+import { Composio, experimental_createTool } from "@composio/core";
648
+import { z } from "zod/v3";
649
+
650
+declare const getUserProfile: ReturnType<typeof experimental_createTool>;
651
+const composio = new Composio({ apiKey: "your_api_key" });
652
+// ---cut---
653
+
654
+// Rehydrate with custom tools
655
+const session = await composio.use("session_id", {
656
+ customTools: [getUserProfile],
657
+});
658
+
659
+const tools = await session.tools();
660
+```
661
+</Tab>
662
+<Tab value="Python">
663
+```python
664
+from composio import Composio
665
+
666
+composio = Composio(api_key="your_api_key")
667
+
668
+# Rehydrate with custom tools
669
+session = composio.use(
670
+ "session_id",
671
+ custom_tools=[get_user_profile],
672
+)
673
+
674
+tools = session.tools()
675
+```
676
+</Tab>
677
+</Tabs>
678
+
679
+Without custom tools, `composio.use()` simply rehydrates the session:
680
+
681
+<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
682
+<Tab value="TypeScript">
683
+```typescript
684
+// @noErrors
685
+import { Composio } from "@composio/core";
686
+const composio = new Composio({ apiKey: "your_api_key" });
687
+// ---cut---
688
+
689
+const session = await composio.use("session_id");
690
+```
691
+</Tab>
692
+<Tab value="Python">
693
+```python
694
+session = composio.use("session_id")
695
+```
696
+</Tab>
697
+</Tabs>
698
+
699
## Programmatic execution
700
701
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
+4
-2
@@ -107,9 +107,11 @@ 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
-### Sessions are immutable
110
+### Session configuration is fixed at creation
111
112
-A session's configuration is fixed at creation. You cannot change the toolkits, auth configs, or connected accounts on an existing session.
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: [...] })`.
115
116
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.
117