@devries-cameron20 / composio-1 / commits / 15df5fad7
Fork 0

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