@devries-cameron20 / composio-1 / commits / f2a84b381
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 direct tools to sessions migration guide and revamp migration pages

- New guide: Migrating from Direct Tools to Sessions - Revamp tool router beta guide title and intro - Add callout to new-sdk guide pointing to sessions migration - Covers auth configs, connected accounts, multiple accounts, triggers, white labeling Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmithamallesh committed Feb 19, 2026 at 19:00 UTC f2a84b381c586bc1ec145a9da7444f9b98efa09b
4 files changed +288 -1
docs/content/docs/migration-guide/direct-to-sessions.mdx new
+276
@@ -0,0 +1,276 @@
1 +---
2 +title: Migrating from Direct Tools to Sessions
3 +description: Move from direct tool execution to the sessions paradigm
4 +keywords: [migrate, sessions, direct tools, upgrade]
5 +---
6 +
7 +This guide is for developers who are using Composio's **direct tool execution** pattern and want to migrate to **sessions**.
8 +
9 +With sessions, you don't need to manage tool fetching, authentication, or execution yourself. You create a session and it handles everything. Your existing auth configs and connected accounts carry over, so your users don't need to re-authenticate.
10 +
11 +If you're starting fresh, skip this guide and head to the [Quickstart](/docs/quickstart).
12 +
13 +## What changes
14 +
15 +| | Direct tools | Sessions |
16 +|---|---|---|
17 +| **Tool discovery** | You fetch specific tools by name/toolkit | Agent discovers tools at runtime via meta tools |
18 +| **Authentication** | You manage connect links and wait for connections | In-chat auth prompts users automatically, or use `session.authorize()` |
19 +| **Execution** | You call `tools.execute()` with version pinning | Agent executes tools through `COMPOSIO_MULTI_EXECUTE_TOOL` |
20 +| **Toolkit versions** | You manage versions manually | Handled automatically |
21 +
22 +## Migrating
23 +
24 +<Steps>
25 +<Step>
26 +<StepTitle>Pass your existing auth configs to the session</StepTitle>
27 +
28 +You already have auth configs (e.g. `ac_github_config`, `ac_slack_config`). Pass them when creating a session so it uses your existing OAuth credentials and your users' connected accounts carry over.
29 +
30 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
31 +<Tab value="Python">
32 +```python
33 +from composio import Composio
34 +
35 +composio = Composio()
36 +
37 +# Before: manual tool fetching with user_id
38 +# tools = composio.tools.get(user_id="user_123", toolkits=["GITHUB", "SLACK"])
39 +
40 +# After: create a session with your existing auth configs
41 +session = composio.create(
42 + user_id="user_123",
43 + auth_configs={
44 + "github": "ac_your_github_config",
45 + "slack": "ac_your_slack_config"
46 + }
47 +)
48 +```
49 +</Tab>
50 +<Tab value="TypeScript">
51 +```typescript
52 +import { Composio } from '@composio/core';
53 +
54 +const composio = new Composio();
55 +
56 +// Before: manual tool fetching with userId
57 +// const tools = await composio.tools.get("user_123", { toolkits: ["GITHUB", "SLACK"] });
58 +
59 +// After: create a session with your existing auth configs
60 +const session = await composio.create("user_123", {
61 + authConfigs: {
62 + github: "ac_your_github_config",
63 + slack: "ac_your_slack_config",
64 + },
65 +});
66 +```
67 +</Tab>
68 +</Tabs>
69 +
70 +Since the session uses the same `user_id` and auth configs, it automatically picks up existing connected accounts. No re-authentication needed.
71 +
72 +</Step>
73 +
74 +<Step>
75 +<StepTitle>Replace manual tool fetching with session tools</StepTitle>
76 +
77 +Instead of fetching specific tools by name, get the session's meta tools. These let the agent discover, authenticate, and execute any tool at runtime.
78 +
79 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
80 +<Tab value="Python">
81 +```python
82 +# Before: manually specifying which tools to fetch
83 +# tools = composio.tools.get(user_id="user_123", toolkits=["GITHUB"])
84 +
85 +# After: session provides meta tools that handle discovery
86 +tools = session.tools()
87 +```
88 +</Tab>
89 +<Tab value="TypeScript">
90 +```typescript
91 +// Before: manually specifying which tools to fetch
92 +// const tools = await composio.tools.get("user_123", { toolkits: ["GITHUB"] });
93 +
94 +// After: session provides meta tools that handle discovery
95 +const tools = await session.tools();
96 +```
97 +</Tab>
98 +</Tabs>
99 +
100 +</Step>
101 +
102 +<Step>
103 +<StepTitle>Remove manual auth flows</StepTitle>
104 +
105 +If you were manually creating connect links and waiting for connections, sessions handle this automatically. When a tool requires authentication, the agent prompts the user with a connect link in-chat.
106 +
107 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
108 +<Tab value="Python">
109 +```python
110 +# Before: manual auth flow
111 +# connection_request = composio.connected_accounts.link(
112 +# user_id="user_123",
113 +# auth_config_id="ac_your_github_config",
114 +# callback_url="https://your-app.com/callback"
115 +# )
116 +# redirect_url = connection_request.redirect_url
117 +
118 +# After: auth happens automatically in-chat
119 +# Or if you need to pre-authenticate outside of chat:
120 +connection_request = session.authorize("github")
121 +print(connection_request.redirect_url)
122 +connected_account = connection_request.wait_for_connection()
123 +```
124 +</Tab>
125 +<Tab value="TypeScript">
126 +```typescript
127 +// Before: manual auth flow
128 +// const connectionRequest = await composio.connectedAccounts.link("user_123", "ac_your_github_config", {
129 +// callbackUrl: "https://your-app.com/callback"
130 +// });
131 +// const redirectUrl = connectionRequest.redirectUrl;
132 +
133 +// After: auth happens automatically in-chat
134 +// Or if you need to pre-authenticate outside of chat:
135 +const connectionRequest = await session.authorize("github", {
136 + callbackUrl: "https://your-app.com/callback",
137 +});
138 +console.log(connectionRequest.redirectUrl);
139 +const connectedAccount = await connectionRequest.waitForConnection();
140 +```
141 +</Tab>
142 +</Tabs>
143 +
144 +</Step>
145 +
146 +<Step>
147 +<StepTitle>Remove toolkit version management</StepTitle>
148 +
149 +If you were pinning toolkit versions in your code or environment variables, you can remove that. Sessions handle versioning automatically.
150 +
151 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
152 +<Tab value="Python">
153 +```python
154 +# Before: manual version pinning
155 +# composio = Composio(
156 +# toolkit_versions={
157 +# "github": "20251027_00",
158 +# "slack": "20251027_00",
159 +# }
160 +# )
161 +
162 +# After: no version management needed
163 +composio = Composio()
164 +session = composio.create(user_id="user_123")
165 +```
166 +</Tab>
167 +<Tab value="TypeScript">
168 +```typescript
169 +// Before: manual version pinning
170 +// const composio = new Composio({
171 +// toolkitVersions: {
172 +// github: "20251027_00",
173 +// slack: "20251027_00",
174 +// },
175 +// });
176 +
177 +// After: no version management needed
178 +const composio = new Composio();
179 +const session = await composio.create("user_123");
180 +```
181 +</Tab>
182 +</Tabs>
183 +
184 +</Step>
185 +</Steps>
186 +
187 +## Restricting toolkits
188 +
189 +If you were fetching tools from specific toolkits, you can restrict the session to only those toolkits:
190 +
191 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
192 +<Tab value="Python">
193 +```python
194 +session = composio.create(
195 + user_id="user_123",
196 + toolkits=["github", "gmail", "slack"],
197 + auth_configs={
198 + "github": "ac_your_github_config",
199 + "gmail": "ac_your_gmail_config",
200 + "slack": "ac_your_slack_config"
201 + }
202 +)
203 +```
204 +</Tab>
205 +<Tab value="TypeScript">
206 +```typescript
207 +import { Composio } from '@composio/core';
208 +const composio = new Composio({ apiKey: 'your_api_key' });
209 +// ---cut---
210 +const session = await composio.create("user_123", {
211 + toolkits: ["github", "gmail", "slack"],
212 + authConfigs: {
213 + github: "ac_your_github_config",
214 + gmail: "ac_your_gmail_config",
215 + slack: "ac_your_slack_config",
216 + },
217 +});
218 +```
219 +</Tab>
220 +</Tabs>
221 +
222 +## Multiple connected accounts
223 +
224 +If your users have multiple accounts for the same toolkit (e.g., work and personal Gmail), you can specify which one to use per session:
225 +
226 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
227 +<Tab value="Python">
228 +```python
229 +session = composio.create(
230 + user_id="user_123",
231 + auth_configs={
232 + "gmail": "ac_your_gmail_config"
233 + },
234 + connected_accounts={
235 + "gmail": "ca_work_gmail"
236 + }
237 +)
238 +```
239 +</Tab>
240 +<Tab value="TypeScript">
241 +```typescript
242 +import { Composio } from '@composio/core';
243 +const composio = new Composio({ apiKey: 'your_api_key' });
244 +// ---cut---
245 +const session = await composio.create("user_123", {
246 + authConfigs: {
247 + gmail: "ac_your_gmail_config",
248 + },
249 + connectedAccounts: {
250 + gmail: "ca_work_gmail",
251 + },
252 +});
253 +```
254 +</Tab>
255 +</Tabs>
256 +
257 +If you don't specify, the most recently connected account is used. See [Managing multiple connected accounts](/docs/managing-multiple-connected-accounts) for details.
258 +
259 +## Triggers
260 +
261 +Triggers don't work with sessions yet. Continue using them the same way you do today with `composio.triggers.create()`, `composio.triggers.enable()`, and webhook subscriptions.
262 +
263 +See [Setting up triggers](/docs/setting-up-triggers) for more.
264 +
265 +## White labeling
266 +
267 +If you've set up white-labeled OAuth screens with custom auth configs, those carry over automatically. Just pass the same auth config IDs to your session via `auth_configs` / `authConfigs`. Your users will continue to see your branding on consent screens.
268 +
269 +See [White-labeling authentication](/docs/white-labeling-authentication) for more.
270 +
271 +## Get started
272 +
273 +<Cards>
274 + <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build your first agent with sessions" />
275 + <Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Toolkits, auth configs, account selection, and session methods" />
276 +</Cards>
docs/content/docs/migration-guide/index.mdx
+6
@@ -23,4 +23,10 @@ description: Guides for migrating to newer versions of Composio
23
24 [View Tool Router migration guide →](/docs/migration-guide/tool-router-beta)
25 </Accordion>
26 +
27 + <Accordion title="Migrating from Direct Tools to Sessions">
28 + Move from manual tool fetching and execution to the sessions paradigm. Your existing auth configs and connected accounts carry over.
29 +
30 + [View Direct Tools migration guide →](/docs/migration-guide/direct-to-sessions)
31 + </Accordion>
32 </Accordions>
docs/content/docs/migration-guide/meta.json
+2 -1
@@ -3,6 +3,7 @@
3 "pages": [
4 "new-sdk",
5 "toolkit-versioning",
6 - "tool-router-beta"
6 + "tool-router-beta",
7 + "direct-to-sessions"
8 ]
9 }
docs/content/docs/migration-guide/new-sdk.mdx
+4
@@ -3,6 +3,10 @@ title: Our next generation SDKs
3 description: Learn more about Composio's next generation SDKs and how to migrate
4 ---
5
6 +<Callout type="info">
7 +This guide covers migrating from the legacy SDK (v1) to the current SDK (v3). The recommended way to use Composio is now through **sessions** — see [Migrating from Direct Tools to Sessions](/docs/migration-guide/direct-to-sessions) or the [Quickstart](/docs/quickstart) if you're starting fresh.
8 +</Callout>
9 +
10 In the last few months, we have experienced very rapid growth in usage of our platform. As such, our team has been working hard to radically improve the performance and developer experience of our platform.
11
12 A lot of these changes have happened in the background, but we are excited to finally share our new SDKs with you that complement our new infra.