Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdxindex 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 specifysession = 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.+### PrecedenceWhen 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.mdxindex 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. Tsession = 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.mdxindex 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.mdxindex 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.mdxindex 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 executionUse `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.mdxindex 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 configurationYou 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.