Skip to content

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

Abir Taheer15df5fad7f0a
diff --git a/docs/content/docs/configuring-sessions.mdx b/docs/content/docs/configuring-sessions.mdx
index 069935819..d612185a2 100644
--- a/docs/content/docs/configuring-sessions.mdx
+++ b/docs/content/docs/configuring-sessions.mdx
@@ -24,7 +24,7 @@ const session = await composio.create("user_123");
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.
-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).
+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).
## Enabling toolkits
@@ -373,8 +373,8 @@ If a user has multiple connected accounts for the same toolkit, you can specify
session = composio.create(
user_id="user_123",
connected_accounts={
- "gmail": "ca_work_gmail",
- "github": "ca_personal_github"
+ "gmail": ["ca_work_gmail"],
+ "github": ["ca_personal_github"],
}
)
```
@@ -386,14 +386,16 @@ const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123", {
connectedAccounts: {
- gmail: "ca_work_gmail",
- github: "ca_personal_github",
+ gmail: ["ca_work_gmail"],
+ github: ["ca_personal_github"],
},
});
```
</Tab>
</Tabs>
+Only one account per toolkit is allowed when [multi-account mode](/docs/managing-multiple-connected-accounts) is disabled.
+
### Precedence
When executing a tool, the connected account is selected in this order:
diff --git a/docs/content/docs/managing-multiple-connected-accounts.mdx b/docs/content/docs/managing-multiple-connected-accounts.mdx
index bf49b376f..03edb9017 100644
--- a/docs/content/docs/managing-multiple-connected-accounts.mdx
+++ b/docs/content/docs/managing-multiple-connected-accounts.mdx
@@ -192,8 +192,8 @@ Pin a session to specific accounts by passing their IDs in the session config. T
session = composio.create(
user_id="user_123",
connected_accounts={
- "gmail": "ca_work_gmail_id",
- "github": "ca_personal_github_id",
+ "gmail": ["ca_work_gmail_id"],
+ "github": ["ca_personal_github_id"],
},
)
```
@@ -206,8 +206,8 @@ const composio = new Composio({ apiKey: 'your_api_key' });
// ---cut---
const session = await composio.create("user_123", {
connectedAccounts: {
- gmail: "ca_work_gmail_id",
- github: "ca_personal_github_id",
+ gmail: ["ca_work_gmail_id"],
+ github: ["ca_personal_github_id"],
},
});
```
diff --git a/docs/content/docs/migration-guide/direct-to-sessions.mdx b/docs/content/docs/migration-guide/direct-to-sessions.mdx
index bbfc971a2..339e3d86b 100644
--- a/docs/content/docs/migration-guide/direct-to-sessions.mdx
+++ b/docs/content/docs/migration-guide/direct-to-sessions.mdx
@@ -241,7 +241,7 @@ session = composio.create(
"gmail": "ac_your_gmail_config"
},
connected_accounts={
- "gmail": "ca_work_gmail"
+ "gmail": ["ca_work_gmail"]
}
)
```
@@ -256,7 +256,7 @@ const session = await composio.create("user_123", {
gmail: "ac_your_gmail_config",
},
connectedAccounts: {
- gmail: "ca_work_gmail",
+ gmail: ["ca_work_gmail"],
},
});
```
diff --git a/docs/content/docs/sessions-vs-direct-execution.mdx b/docs/content/docs/sessions-vs-direct-execution.mdx
index c54c14bf4..48f3a048f 100644
--- a/docs/content/docs/sessions-vs-direct-execution.mdx
+++ b/docs/content/docs/sessions-vs-direct-execution.mdx
@@ -89,7 +89,7 @@ session = composio.create(
user_id="user_123",
toolkits=["github", "gmail"],
auth_configs={"github": "ac_my_config"},
- connected_accounts={"gmail": "ca_work"},
+ connected_accounts={"gmail": ["ca_work"]},
)
```
</Tab>
@@ -101,7 +101,7 @@ const composio = new Composio({ apiKey: 'your_api_key' });
const session = await composio.create("user_123", {
toolkits: ["github", "gmail"],
authConfigs: { github: "ac_my_config" },
- connectedAccounts: { gmail: "ca_work" },
+ connectedAccounts: { gmail: ["ca_work"] },
});
```
</Tab>
diff --git a/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx b/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
index 35b3dff07..cceedf4e6 100644
--- a/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
+++ b/docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
@@ -636,6 +636,66 @@ custom_toolkits = session.custom_toolkits()
</Tab>
</Tabs>
+## Attaching custom tools to an existing session
+
+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.
+
+<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
+<Tab value="TypeScript">
+```typescript
+// @noErrors
+import { Composio, experimental_createTool } from "@composio/core";
+import { z } from "zod/v3";
+
+declare const getUserProfile: ReturnType<typeof experimental_createTool>;
+const composio = new Composio({ apiKey: "your_api_key" });
+// ---cut---
+
+// Rehydrate with custom tools
+const session = await composio.use("session_id", {
+ customTools: [getUserProfile],
+});
+
+const tools = await session.tools();
+```
+</Tab>
+<Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio(api_key="your_api_key")
+
+# Rehydrate with custom tools
+session = composio.use(
+ "session_id",
+ custom_tools=[get_user_profile],
+)
+
+tools = session.tools()
+```
+</Tab>
+</Tabs>
+
+Without custom tools, `composio.use()` simply rehydrates the session:
+
+<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
+<Tab value="TypeScript">
+```typescript
+// @noErrors
+import { Composio } from "@composio/core";
+const composio = new Composio({ apiKey: "your_api_key" });
+// ---cut---
+
+const session = await composio.use("session_id");
+```
+</Tab>
+<Tab value="Python">
+```python
+session = composio.use("session_id")
+```
+</Tab>
+</Tabs>
+
## Programmatic execution
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.
diff --git a/docs/content/docs/users-and-sessions.mdx b/docs/content/docs/users-and-sessions.mdx
index b2ff996a5..e1418f8dd 100644
--- a/docs/content/docs/users-and-sessions.mdx
+++ b/docs/content/docs/users-and-sessions.mdx
@@ -107,9 +107,11 @@ A session ties together a user, a set of available toolkits, auth configuration
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.
-### Sessions are immutable
+### Session configuration is fixed at creation
-A session's configuration is fixed at creation. You cannot change the toolkits, auth configs, or connected accounts on an existing session.
+A session's toolkits, auth configs, and connected accounts are fixed at creation. You cannot change them on an existing session.
+
+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: [...] })`.
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.