> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating from Direct Tools to Sessions

> Move from direct tool execution to the sessions paradigm

This guide is for developers who are using Composio's **direct tool execution** pattern and want to migrate to **sessions**. For a comparison of the two patterns, see [Sessions vs Direct Execution](https://composio-preview.mintlify.site/docs/sessions-vs-direct-execution.md).

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, use [Configuring Sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md) instead.

## 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

**1. Pass your existing auth configs to the session**

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.

> [tab] Python
>
> ```python theme={null}
> 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] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> // 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] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "auth_configs": {"github": "ac_your_github_config", "slack": "ac_your_slack_config"}
>   }'
> ```

Since the session uses the same `user_id` and auth configs, it automatically picks up existing connected accounts. No re-authentication needed.

**2. Replace manual tool fetching with session tools**

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.

> [tab] Python
>
> ```python theme={null}
> # 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] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123");
> // 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] API
>
> ```bash theme={null}
> # SESSION_ID is the session_id returned when you created the session
> curl -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

**3. Remove manual auth flows**

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.

> [tab] Python
>
> ```python theme={null}
> # 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",
>     callback_url="https://your-app.com/callback",
> )
> print(connection_request.redirect_url)
> connected_account = connection_request.wait_for_connection()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123");
> // 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] API
>
> ```bash theme={null}
> # SESSION_ID is the session_id returned when you created the session
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/link \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"toolkit": "github", "callback_url": "https://your-app.com/callback"}'
> ```

**4. Remove toolkit version management**

If you were pinning toolkit versions in your code or environment variables, you can remove that. Sessions handle versioning automatically.

> [tab] Python
>
> ```python theme={null}
> # 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] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> // Before: manual version pinning
> // const composio = new Composio({
> //   toolkitVersions: {
> //     github: "20251027_00",
> //     slack: "20251027_00",
> //   },
> // });
>
> // After: no version management needed
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123");
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123"}'
> ```

## Restricting toolkits

If you were fetching tools from specific toolkits, you can restrict the session to only those toolkits:

> [tab] Python
>
> ```python theme={null}
> 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] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> 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] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "toolkits": {"enable": ["github", "gmail", "slack"]},
>     "auth_configs": {
>       "github": "ac_your_github_config",
>       "gmail": "ac_your_gmail_config",
>       "slack": "ac_your_slack_config"
>     }
>   }'
> ```

## 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:

> [tab] Python
>
> ```python theme={null}
> session = composio.create(
>     user_id="user_123",
>     auth_configs={
>         "gmail": "ac_your_gmail_config"
>     },
>     connected_accounts={
>         "gmail": ["ca_work_gmail"]
>     }
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   authConfigs: {
>     gmail: "ac_your_gmail_config",
>   },
>   connectedAccounts: {
>     gmail: ["ca_work_gmail"],
>   },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "auth_configs": {"gmail": "ac_your_gmail_config"},
>     "connected_accounts": {"gmail": ["ca_work_gmail"]}
>   }'
> ```

If you don't specify, the most recently connected account is used. See [Managing multiple connected accounts](https://composio-preview.mintlify.site/docs/authentication/managing-multiple-connected-accounts.md) 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 [Triggers](https://composio-preview.mintlify.site/docs/triggers.md) for setup instructions.

## 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](https://composio-preview.mintlify.site/docs/authentication/white-labeling-authentication.md) for more.

## Next

> [card] [Configuring Sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md)
>
> Toolkits, auth configs, account selection, and session methods
