@devries-cameron20 / composio Mirror · read-only / commits / 125242348
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 21:00 UTC

docs: reframe .use() around session rehydration, not custom tools

Primary use case is multi-turn chat apps reusing a session across requests. Custom tools are a secondary option when rehydrating. - Added "Reusing a session" section to users-and-sessions.mdx - Trimmed custom-tools page to a brief mention with link back - Updated "When should I create a new session?" accordion Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Abir Taheer committed May 8, 2026 at 02:37 UTC 1252423481cc5858ea842863e24a310263bac4d9
2 files changed +23 -32
docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
+2 -27
@@ -636,9 +636,9 @@ custom_toolkits = session.custom_toolkits()
636 </Tab>
637 </Tabs>
638
639 -## Attaching custom tools to an existing session
639 +## Reusing a session with custom tools
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.
641 +When [reusing a session](/docs/users-and-sessions#reusing-a-session) via `composio.use()`, you can attach custom tools at the same time:
642
643 <Tabs groupId="language" items={['TypeScript', 'Python']} persist>
644 <Tab value="TypeScript">
@@ -650,12 +650,9 @@ declare const getUserProfile: ReturnType<typeof experimental_createTool>;
650 const composio = new Composio({ apiKey: "your_api_key" });
651 // ---cut---
652
653 -// Rehydrate with custom tools
653 const session = await composio.use("session_id", {
654 customTools: [getUserProfile],
655 });
657 -
658 -const tools = await session.tools();
656 ```
657 </Tab>
658 <Tab value="Python">
@@ -664,32 +661,10 @@ from composio import Composio
661
662 composio = Composio(api_key="your_api_key")
663
667 -# Rehydrate with custom tools
664 session = composio.use(
665 "session_id",
666 custom_tools=[get_user_profile],
667 )
672 -
673 -tools = session.tools()
674 -```
675 -</Tab>
676 -</Tabs>
677 -
678 -Without custom tools, `composio.use()` simply rehydrates the session:
679 -
680 -<Tabs groupId="language" items={['TypeScript', 'Python']} persist>
681 -<Tab value="TypeScript">
682 -```typescript
683 -import { Composio } from "@composio/core";
684 -const composio = new Composio({ apiKey: "your_api_key" });
685 -// ---cut---
686 -
687 -const session = await composio.use("session_id");
688 -```
689 -</Tab>
690 -<Tab value="Python">
691 -```python
692 -session = composio.use("session_id")
668 ```
669 </Tab>
670 </Tabs>
docs/content/docs/users-and-sessions.mdx
+21 -5
@@ -107,13 +107,29 @@ 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 +### Reusing a session
111
112 -A session's toolkits, auth configs, and connected accounts are fixed at creation. You cannot change them on an existing session.
112 +In multi-turn chat apps, you create a session once and reuse it across requests. Store the session ID and call `composio.use()` to rehydrate it:
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: [...] })`.
114 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
115 +<Tab value="Python">
116 +```python
117 +session = composio.use("session_id")
118 +tools = session.tools()
119 +```
120 +</Tab>
121 +<Tab value="TypeScript">
122 +```typescript
123 +import { Composio } from '@composio/core';
124 +const composio = new Composio({ apiKey: 'your_api_key' });
125 +// ---cut---
126 +const session = await composio.use("session_id");
127 +const tools = await session.tools();
128 +```
129 +</Tab>
130 +</Tabs>
131
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.
132 +This returns the same session with the same toolkits, auth configs, and connected accounts. The session's configuration is fixed at creation — to change toolkits or auth, create a new session.
133
134 ### Connected accounts persist across sessions
135
@@ -121,7 +137,7 @@ Connections are tied to the user ID, not the session. A user who connected Gmail
137
138 <Accordions>
139 <Accordion title="When should I create a new session?">
124 -Create a new session when the config changes: different toolkits, different auth config, or a different connected account. You don't need to store or manage session IDs. Just call `create()` each time.
140 +Create a new session when the config changes: different toolkits, different auth config, or a different connected account. For multi-turn conversations where the config stays the same, reuse the session with `composio.use()`.
141 </Accordion>
142 </Accordions>
143