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 direct tools to sessions migration guide and revamp migration pages

Sushmithamalleshf2a84b381c58
diff --git a/docs/content/docs/migration-guide/direct-to-sessions.mdx b/docs/content/docs/migration-guide/direct-to-sessions.mdx
new file mode 100644
index 000000000..45d651dba
--- /dev/null
+++ b/docs/content/docs/migration-guide/direct-to-sessions.mdx
@@ -0,0 +1,276 @@
+---
+title: Migrating from Direct Tools to Sessions
+description: Move from direct tool execution to the sessions paradigm
+keywords: [migrate, sessions, direct tools, upgrade]
+---
+
+This guide is for developers who are using Composio's **direct tool execution** pattern and want to migrate to **sessions**.
+
+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.
+
+If you're starting fresh, skip this guide and head to the [Quickstart](/docs/quickstart).
+
+## What changes
+
+| | Direct tools | Sessions |
+|---|---|---|
+| **Tool discovery** | You fetch specific tools by name/toolkit | Agent discovers tools at runtime via meta tools |
+| **Authentication** | You manage connect links and wait for connections | In-chat auth prompts users automatically, or use `session.authorize()` |
+| **Execution** | You call `tools.execute()` with version pinning | Agent executes tools through `COMPOSIO_MULTI_EXECUTE_TOOL` |
+| **Toolkit versions** | You manage versions manually | Handled automatically |
+
+## Migrating
+
+<Steps>
+<Step>
+<StepTitle>Pass your existing auth configs to the session</StepTitle>
+
+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.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio()
+
+# Before: manual tool fetching with user_id
+# tools = composio.tools.get(user_id="user_123", toolkits=["GITHUB", "SLACK"])
+
+# After: create a session with your existing auth configs
+session = composio.create(
+ user_id="user_123",
+ auth_configs={
+ "github": "ac_your_github_config",
+ "slack": "ac_your_slack_config"
+ }
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+
+const composio = new Composio();
+
+// Before: manual tool fetching with userId
+// const tools = await composio.tools.get("user_123", { toolkits: ["GITHUB", "SLACK"] });
+
+// After: create a session with your existing auth configs
+const session = await composio.create("user_123", {
+ authConfigs: {
+ github: "ac_your_github_config",
+ slack: "ac_your_slack_config",
+ },
+});
+```
+</Tab>
+</Tabs>
+
+Since the session uses the same `user_id` and auth configs, it automatically picks up existing connected accounts. No re-authentication needed.
+
+</Step>
+
+<Step>
+<StepTitle>Replace manual tool fetching with session tools</StepTitle>
+
+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.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+# Before: manually specifying which tools to fetch
+# tools = composio.tools.get(user_id="user_123", toolkits=["GITHUB"])
+
+# After: session provides meta tools that handle discovery
+tools = session.tools()
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+// Before: manually specifying which tools to fetch
+// const tools = await composio.tools.get("user_123", { toolkits: ["GITHUB"] });
+
+// After: session provides meta tools that handle discovery
+const tools = await session.tools();
+```
+</Tab>
+</Tabs>
+
+</Step>
+
+<Step>
+<StepTitle>Remove manual auth flows</StepTitle>
+
+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.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+# Before: manual auth flow
+# connection_request = composio.connected_accounts.link(
+# user_id="user_123",
+# auth_config_id="ac_your_github_config",
+# callback_url="https://your-app.com/callback"
+# )
+# redirect_url = connection_request.redirect_url
+
+# After: auth happens automatically in-chat
+# Or if you need to pre-authenticate outside of chat:
+connection_request = session.authorize("github")
+print(connection_request.redirect_url)
+connected_account = connection_request.wait_for_connection()
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+// Before: manual auth flow
+// const connectionRequest = await composio.connectedAccounts.link("user_123", "ac_your_github_config", {
+// callbackUrl: "https://your-app.com/callback"
+// });
+// const redirectUrl = connectionRequest.redirectUrl;
+
+// After: auth happens automatically in-chat
+// Or if you need to pre-authenticate outside of chat:
+const connectionRequest = await session.authorize("github", {
+ callbackUrl: "https://your-app.com/callback",
+});
+console.log(connectionRequest.redirectUrl);
+const connectedAccount = await connectionRequest.waitForConnection();
+```
+</Tab>
+</Tabs>
+
+</Step>
+
+<Step>
+<StepTitle>Remove toolkit version management</StepTitle>
+
+If you were pinning toolkit versions in your code or environment variables, you can remove that. Sessions handle versioning automatically.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+# Before: manual version pinning
+# composio = Composio(
+# toolkit_versions={
+# "github": "20251027_00",
+# "slack": "20251027_00",
+# }
+# )
+
+# After: no version management needed
+composio = Composio()
+session = composio.create(user_id="user_123")
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+// Before: manual version pinning
+// const composio = new Composio({
+// toolkitVersions: {
+// github: "20251027_00",
+// slack: "20251027_00",
+// },
+// });
+
+// After: no version management needed
+const composio = new Composio();
+const session = await composio.create("user_123");
+```
+</Tab>
+</Tabs>
+
+</Step>
+</Steps>
+
+## Restricting toolkits
+
+If you were fetching tools from specific toolkits, you can restrict the session to only those toolkits:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session = composio.create(
+ user_id="user_123",
+ toolkits=["github", "gmail", "slack"],
+ auth_configs={
+ "github": "ac_your_github_config",
+ "gmail": "ac_your_gmail_config",
+ "slack": "ac_your_slack_config"
+ }
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ toolkits: ["github", "gmail", "slack"],
+ authConfigs: {
+ github: "ac_your_github_config",
+ gmail: "ac_your_gmail_config",
+ slack: "ac_your_slack_config",
+ },
+});
+```
+</Tab>
+</Tabs>
+
+## Multiple connected accounts
+
+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:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session = composio.create(
+ user_id="user_123",
+ auth_configs={
+ "gmail": "ac_your_gmail_config"
+ },
+ connected_accounts={
+ "gmail": "ca_work_gmail"
+ }
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ authConfigs: {
+ gmail: "ac_your_gmail_config",
+ },
+ connectedAccounts: {
+ gmail: "ca_work_gmail",
+ },
+});
+```
+</Tab>
+</Tabs>
+
+If you don't specify, the most recently connected account is used. See [Managing multiple connected accounts](/docs/managing-multiple-connected-accounts) for details.
+
+## Triggers
+
+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.
+
+See [Setting up triggers](/docs/setting-up-triggers) for more.
+
+## White labeling
+
+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.
+
+See [White-labeling authentication](/docs/white-labeling-authentication) for more.
+
+## Get started
+
+<Cards>
+ <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build your first agent with sessions" />
+ <Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Toolkits, auth configs, account selection, and session methods" />
+</Cards>
diff --git a/docs/content/docs/migration-guide/index.mdx b/docs/content/docs/migration-guide/index.mdx
index 73f973e58..670c21f57 100644
--- a/docs/content/docs/migration-guide/index.mdx
+++ b/docs/content/docs/migration-guide/index.mdx
@@ -23,4 +23,10 @@ description: Guides for migrating to newer versions of Composio
[View Tool Router migration guide →](/docs/migration-guide/tool-router-beta)
</Accordion>
+
+ <Accordion title="Migrating from Direct Tools to Sessions">
+ Move from manual tool fetching and execution to the sessions paradigm. Your existing auth configs and connected accounts carry over.
+
+ [View Direct Tools migration guide →](/docs/migration-guide/direct-to-sessions)
+ </Accordion>
</Accordions>
diff --git a/docs/content/docs/migration-guide/meta.json b/docs/content/docs/migration-guide/meta.json
index c361754d1..825aa1241 100644
--- a/docs/content/docs/migration-guide/meta.json
+++ b/docs/content/docs/migration-guide/meta.json
@@ -3,6 +3,7 @@
"pages": [
"new-sdk",
"toolkit-versioning",
- "tool-router-beta"
+ "tool-router-beta",
+ "direct-to-sessions"
]
}
diff --git a/docs/content/docs/migration-guide/new-sdk.mdx b/docs/content/docs/migration-guide/new-sdk.mdx
index 3257cdd04..2140ababf 100644
--- a/docs/content/docs/migration-guide/new-sdk.mdx
+++ b/docs/content/docs/migration-guide/new-sdk.mdx
@@ -3,6 +3,10 @@ title: Our next generation SDKs
description: Learn more about Composio's next generation SDKs and how to migrate
---
+<Callout type="info">
+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.
+</Callout>
+
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.
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.