# Sessions vs Direct Execution (/docs/sessions-vs-direct-execution) **Sessions** give your agent [meta tools](/docs/tools-and-toolkits#meta-tools). The agent discovers which app tools to use, authenticates users, and executes tools at runtime through these meta tools. **Direct execution** is the legacy/manual path. It gives your code specific tool schemas, but you decide which tools to fetch, manage auth yourself, and call `tools.execute()` directly. Use sessions for new agent builds. Use direct execution only when you are maintaining an older integration or need a tightly controlled backend workflow that should not use meta tools. | | 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](/docs/authenticating-users/in-chat-authentication): agent prompts the user to connect when needed. Also supports [manual](/docs/authenticating-users/manually-authenticating) | You build the auth flow with [connect links](/docs/legacy/tools-direct/authenticating-tools) | | **[Workbench](/docs/workbench)** | Built in, large responses offloaded automatically | Not available | | **Human approval** | You configure approval rules on the session. Harder to intercept individual calls since tools are discovered dynamically | You intercept before each call in your code | | **Latency** | Multiple LLM turns (search, then execute) | Single call | Sessions are configurable. You can [enable or disable specific toolkits](/docs/toolkits/enable-and-disable-toolkits), set [auth configs](/docs/using-custom-auth-configuration) for white-labeled OAuth, and pin specific [connected accounts](/docs/configuring-sessions#account-selection). See [Configuring Sessions](/docs/configuring-sessions) for the full list. # Sessions `composio.create()` returns [meta tools](/docs/tools-and-toolkits#meta-tools): **Python:** ```python 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. ``` **TypeScript:** ```typescript 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. ``` The agent discovers app tools through `COMPOSIO_SEARCH_TOOLS`: ``` 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" ``` > `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 load specific app tool schemas outside a session, see [Direct execution (legacy)](#direct-execution). ## Configuration Restrict toolkits, set auth configs, pin connected accounts: **Python:** ```python session = composio.create( user_id="user_123", toolkits=["github", "gmail"], auth_configs={"github": "ac_my_config"}, connected_accounts={"gmail": ["ca_work"]}, ) ``` **TypeScript:** ```typescript 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"] }, }); ``` See [Configuring Sessions](/docs/configuring-sessions) for details. # Direct execution > Direct execution is a legacy/maintenance path. New agent builds should use sessions and meta tools. Use this section if you are maintaining an older integration or migrating to sessions. Fetch tools by slug or toolkit. Pass them to your LLM or call `tools.execute()` without one. **Python:** ```python from composio import Composio from composio_openai import OpenAIProvider composio = Composio(provider=OpenAIProvider()) # 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"} ) ``` **TypeScript:** ```typescript import { Composio } from '@composio/core'; import { OpenAIProvider } from '@composio/openai'; const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY, provider: new OpenAIProvider(), }); // 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" }, }); ``` > `tools.get()` returns 20 tools by default. When fetching from multiple toolkits (e.g., `toolkits=["gmail", "github", "tavily"]`), the limit may cut off tools from later toolkits. Increase `limit` or fetch each toolkit separately. With direct execution, you manage [auth configs](/docs/using-custom-auth-configuration), [connect links](/docs/legacy/tools-direct/authenticating-tools), and [toolkit versioning](/docs/legacy/tools-direct/toolkit-versioning) yourself. # Migrating See the [migration guide](/docs/migration-guide/direct-to-sessions). Auth configs and connected accounts carry over. # Next steps - [Quickstart](/docs/quickstart): Build an agent with sessions - [Configuring Sessions](/docs/configuring-sessions): Toolkits, auth configs, and connected accounts - [Direct Tool Execution (legacy)](/docs/legacy/tools-direct/executing-tools): Maintain or migrate older direct-execution integrations --- 📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Glossary](https://docs.composio.dev/llms.mdx/docs/glossary) | [Cookbooks](https://docs.composio.dev/llms.mdx/cookbooks) | [API Reference](https://docs.composio.dev/llms.mdx/reference) --- # Composio SDK — Instructions for AI Code Generators **Purpose:** Enforce only the **current** and **correct** patterns for integrating [Composio](https://composio.dev/) tools into AI agents. **Scope:** All AI-generated code using Composio must follow these guardrails. --- ## 1. Correct Composio Integration Composio supports two integration modes: **Native Tools** (with a provider package) and **MCP** (no provider package needed). ### Native Tools ```python # ✅ CORRECT — Python (defaults to OpenAI) from composio import Composio composio = Composio() session = composio.create(user_id="user_123") tools = session.tools() # Pass tools to your agent/LLM framework ``` ```typescript // ✅ CORRECT — TypeScript (defaults to OpenAI) import { Composio } from "@composio/core"; const composio = new Composio(); const session = await composio.create("user_123"); const tools = await session.tools(); // Pass tools to your agent/LLM framework ``` For other providers, pass the provider explicitly. Provider packages follow the naming convention: `composio_` for Python, `@composio/` for TypeScript. ### MCP Use `session.mcp.url` and `session.mcp.headers` with any MCP-compatible client (Claude Desktop, Cursor, OpenAI Agents, etc.). No provider package needed. --- ## 2. CRITICAL INSTRUCTIONS FOR AI MODELS ### 2.1 — ALWAYS DO THE FOLLOWING 1. **Use `composio.create(user_id)`** to create a session — this is the entry point for all Composio integrations. 2. **Use `session.tools()`** for native tool integration or **`session.mcp.url`** for MCP integration. 3. **Import** from the correct provider package (`composio_` for Python, `@composio/` for TypeScript). 4. **Pass `user_id` to `composio.create()`**, not to individual tool calls. ### 2.2 — NEVER DO THE FOLLOWING 1. **Do not** instruct users to manually create auth configs or connected accounts before running. 2. **Do not** import from `composio_openai` / `@composio/openai` when using OpenAI Agents SDK — use `composio_openai_agents` / `@composio/openai-agents` instead. ### 2.3 — DISCOURAGED (do not use unless user explicitly asks) Do **not** generate `composio.tools.get()`, `composio.tools.execute()`, or `composio.provider.handle_tool_calls()` unless the user explicitly requests direct tool execution. These are a supported but **not recommended** low-level interface. --- ## Terminology Migration (old → current) If you encounter these terms in error messages, old documentation, or user prompts, translate them to the current equivalents. **Do not use the old terms in generated code or explanations.** | Old term (v1/v2) | Current term (v3) | In code | |---|---|---| | entity ID | user ID | `user_id` parameter | | actions | tools | e.g., `GITHUB_CREATE_ISSUE` is a *tool* | | apps / appType | toolkits | e.g., `github` is a *toolkit* | | integration / integration ID | auth config / auth config ID | `auth_config_id` parameter | | connection | connected account | `connected_accounts` namespace | | ComposioToolSet / OpenAIToolSet | `Composio` class with a provider | `Composio(provider=...)` | | toolset | provider | e.g., `OpenAIProvider` | If a user says "entity ID", they mean `user_id`. If they say "integration", they mean "auth config". Always respond using the current terminology.