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

# Sessions vs Direct Execution

> When to use session-based meta tools vs direct tool fetching and execution

A **session** is the runtime context Composio creates for one of your users with `composio.create(userId)`. It ties together the user, available toolkits, auth, and connected accounts. By default it gives your agent [meta tools](https://composio-preview.mintlify.site/docs/how-composio-works.md#meta-tools) so the agent discovers which app tools to use, authenticates users, and executes tools at runtime.

**Direct execution** skips the session. Your code fetches specific tool schemas, manages auth itself, and calls `tools.execute()` directly.

> [!NOTE]
>
> **Use sessions for new integrations**
>
> Direct execution is a legacy interface that remains supported for existing integrations. We recommend sessions for new integrations and encourage existing users to [migrate to sessions](https://composio-preview.mintlify.site/docs/migration-guide/direct-to-sessions.md). Sessions handle runtime tool discovery, authentication, and execution.

If your application needs a fixed tool set, consider the [direct tools preset](https://composio-preview.mintlify.site/docs/configuring-sessions.md#direct-tools-preset) within a session. If you need approval before execution, use [approvals](https://composio-preview.mintlify.site/docs/governance/approvals.md): the session asks the user before it runs the tools you choose, including calls inside meta tools that execute multiple app tools. The comparison below describes the tradeoffs when maintaining a direct-execution integration.

| | Sessions | Direct execution |
| - | - | - |
| **Discovery** | Agent finds tools at runtime and resolves dependencies automatically (e.g., if a tool needs an ID from another API, the agent finds that tool, runs it, and continues) | You select all tools upfront and need to account for any dependencies between them |
| **Context cost** | Only meta tools in context, app tools loaded on demand | Every tool schema you select is loaded upfront |
| **Guidance** | Search returns recommended steps and common pitfalls alongside schemas | You get tool schemas only |
| **Memory** | Meta tools share context across calls, storing discovered IDs and relationships | You manage state between calls |
| **Auth** | [In-chat](https://composio-preview.mintlify.site/docs/authentication#in-chat-authentication): agent prompts the user to connect when needed. Also supports [manual](https://composio-preview.mintlify.site/docs/authentication/manually-authenticating.md) | You build the auth flow with [connect links](https://composio-preview.mintlify.site/docs/tools-direct/authenticating-tools.md) |
| [**Sandbox**](https://composio-preview.mintlify.site/docs/sandbox/remote.md) | Built in, large responses offloaded automatically | Not available |
| **Human approval** | [Approvals](https://composio-preview.mintlify.site/docs/governance/approvals.md) ask the user before the tools you choose run, including inside meta tools | You intercept before each call in your code |
| **Latency** | Multiple LLM turns (search, then execute) | Single call |

Sessions are configurable. [Restrict toolkits](https://composio-preview.mintlify.site/docs/configuring-sessions.md), set [auth configs](https://composio-preview.mintlify.site/docs/auth-configuration/custom-auth-configs.md) for white-labeled OAuth, and pin [connected accounts](https://composio-preview.mintlify.site/docs/configuring-sessions.md#account-selection). See [Configuring Sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md) for the full list.

Sessions aren't all-or-nothing. With the [direct tools preset](https://composio-preview.mintlify.site/docs/configuring-sessions.md#direct-tools-preset), a session returns a fixed set of tools directly from `session.tools()` with no search or meta tools, so the agent sees exactly the tools you list while you keep session auth, connected accounts, and the sandbox. It's the middle ground between runtime discovery and direct execution.

## Sessions

`composio.create()` returns [meta tools](https://composio-preview.mintlify.site/docs/how-composio-works.md#meta-tools):

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
> from composio_openai import OpenAIProvider
>
> composio = Composio(provider=OpenAIProvider())
> session = composio.create(user_id="user_123")
> tools = session.tools()
> # Returns meta tools like COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS,
> # COMPOSIO_MULTI_EXECUTE_TOOL, COMPOSIO_REMOTE_WORKBENCH, etc.
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> import { OpenAIProvider } from '@composio/openai';
>
> const composio = new Composio({
>   apiKey: process.env.COMPOSIO_API_KEY,
>   provider: new OpenAIProvider(),
> });
> const session = await composio.create("user_123");
> const tools = await session.tools();
> // Returns meta tools like COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS,
> // COMPOSIO_MULTI_EXECUTE_TOOL, COMPOSIO_REMOTE_WORKBENCH, etc.
> ```

> [tab] API
>
> ```bash theme={null}
> SESSION_ID=$(curl -s -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"}' | jq -r '.session_id')
>
> # Returns meta tools like COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS,
> # COMPOSIO_MULTI_EXECUTE_TOOL, COMPOSIO_REMOTE_WORKBENCH, etc.
> curl -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

The agent discovers app tools through `COMPOSIO_SEARCH_TOOLS`:

```text theme={null}
User: "Create a GitHub issue for the login bug"

> Agent calls COMPOSIO_SEARCH_TOOLS({ query: "create github issue" })
  Returns: GITHUB_CREATE_ISSUE schema + connection status

> Agent calls COMPOSIO_MANAGE_CONNECTIONS({ toolkits: ["github"] })
  Returns: confirms connected (or auth link if not)

> Agent calls COMPOSIO_MULTI_EXECUTE_TOOL({ tool: "GITHUB_CREATE_ISSUE", args: {...} })
  Returns: issue details

Agent: "Created issue #42 on your-org/your-repo"
```

> [!NOTE]
>
> `session.tools()` returns **meta tools** (`COMPOSIO_SEARCH_TOOLS`, etc.), not app tools (`GMAIL_SEND_EMAIL`, etc.). The agent discovers app tools at runtime through search. To work with app tools directly, use direct execution.

### Configuration

Restrict toolkits, set auth configs, pin connected accounts:

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

> [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"],
>   authConfigs: { github: "ac_my_config" },
>   connectedAccounts: { gmail: ["ca_work"] },
> });
> ```

> [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"]},
>     "auth_configs": {"github": "ac_my_config"},
>     "connected_accounts": {"gmail": ["ca_work"]}
>   }'
> ```

See [Configuring Sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md) for details.

## Direct execution

Fetch tools by slug or toolkit. Pass them to your LLM or call `tools.execute()` without one.

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
> from composio_openai import OpenAIProvider
>
> composio = Composio(
>     provider=OpenAIProvider(),
>     toolkit_versions={"github": "latest"},  # required for direct execution
> )
>
> # Fetch specific tools
> tools = composio.tools.get(
>     user_id="user_123",
>     tools=["GITHUB_CREATE_ISSUE", "GITHUB_LIST_ISSUES"]
> )
>
> # Or by toolkit
> tools = composio.tools.get(
>     user_id="user_123",
>     toolkits=["github"],
>     limit=50
> )
>
> # Execute without an LLM
> result = composio.tools.execute(
>     "GITHUB_CREATE_ISSUE",
>     user_id="user_123",
>     arguments={"owner": "my-org", "repo": "my-repo", "title": "Fix login bug"},
>     dangerously_skip_version_check=True,  # required when running "latest"; or pin via version=...
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> import { OpenAIProvider } from '@composio/openai';
>
> const composio = new Composio({
>   apiKey: process.env.COMPOSIO_API_KEY,
>   provider: new OpenAIProvider(),
>   toolkitVersions: { github: 'latest' },  // required for direct execution
> });
>
> // Fetch specific tools
> const tools = await composio.tools.get("user_123", {
>   tools: ["GITHUB_CREATE_ISSUE", "GITHUB_LIST_ISSUES"],
> });
>
> // Or by toolkit
> const allTools = await composio.tools.get("user_123", {
>   toolkits: ["github"],
>   limit: 50,
> });
>
> // Execute without an LLM
> const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
>   userId: "user_123",
>   arguments: { owner: "my-org", repo: "my-repo", title: "Fix login bug" },
>   dangerouslySkipVersionCheck: true, // required when running "latest"; or pin via version
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # Fetch specific tools
> curl -X GET "https://backend.composio.dev/api/v3.1/tools?tool_slugs=GITHUB_CREATE_ISSUE,GITHUB_LIST_ISSUES&toolkit_versions=latest" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
>
> # Or by toolkit
> curl -X GET "https://backend.composio.dev/api/v3.1/tools?toolkit_slug=github&limit=50&toolkit_versions=latest" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
>
> # Execute without an LLM
> curl -X POST https://backend.composio.dev/api/v3.1/tools/execute/GITHUB_CREATE_ISSUE \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "version": "latest",
>     "arguments": {"owner": "my-org", "repo": "my-repo", "title": "Fix login bug"}
>   }'
> ```

> [!WARNING]
>
> `tools.get()` returns up to 20 tools by default. A limit caps the result count; it does not select tools by task relevance. When fetching from multiple toolkits (e.g., `toolkits=["gmail", "github", "tavily"]`), the limit may cut off tools from later toolkits. For a fixed workflow, fetch explicit tool names. See [tool filtering and the TypeScript important filter](https://composio-preview.mintlify.site/docs/tools-direct/fetching-tools.md#by-toolkit).

With direct execution, you manage [auth configs](https://composio-preview.mintlify.site/docs/auth-configuration/custom-auth-configs.md), [connect links](https://composio-preview.mintlify.site/docs/tools-direct/authenticating-tools.md), and [toolkit versioning](https://composio-preview.mintlify.site/docs/tools-direct/toolkit-versioning.md) yourself.

## Migrating

See the [migration guide](https://composio-preview.mintlify.site/docs/migration-guide/direct-to-sessions.md). Auth configs and connected accounts carry over.

## Next

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