# Sessions (/reference/sdk-reference/typescript/sessions) # Usage [#usage] Access this class through the `composio.sessions` property: ```typescript const composio = new Composio({ apiKey: 'your-api-key' }); const result = await composio.sessions.list(); ``` # Methods [#methods] ## create() [#create] Creates a new tool router session for a user. Use `sessionPreset: SessionPreset.DIRECT_TOOLS` when all needed tools should be exposed directly; see `ToolRouterCreateSessionConfig`. **Overload 1** ```typescript async create(userId: string, config: ToolRouterCreateSessionConfig & { mcp: true }, requestOptions?: ComposioRequestOptions): Promise> ``` **Parameters** | Name | Type | Description | | ----------------- | ------------------------------------------------- | ----------------------------------------------------------------------- | | `userId` | `string` | \{string} The user id to create the session for | | `config` | `ToolRouterCreateSessionConfig & \{ mcp: true \}` | \{ToolRouterCreateSessionConfig} The config for the tool router session | | `requestOptions?` | `ComposioRequestOptions` | | **Returns** `Promise>` — The tool router session **Overload 2** ```typescript async create(userId: string, config?: ToolRouterCreateSessionConfig, requestOptions?: ComposioRequestOptions): Promise> ``` **Parameters** | Name | Type | Description | | ----------------- | ------------------------------- | ----------------------------------------------------------------------- | | `userId` | `string` | \{string} The user id to create the session for | | `config?` | `ToolRouterCreateSessionConfig` | \{ToolRouterCreateSessionConfig} The config for the tool router session | | `requestOptions?` | `ComposioRequestOptions` | | **Returns** `Promise>` — The tool router session **Example** ```typescript import { Composio } from '@composio/core'; const composio = new Composio(); const session = await composio.sessions.create('user_123', { toolkits: ['gmail'], manageConnections: true, experimental: { customTools: [myCustomTool], customToolkits: [myToolkit], }, }); ``` *** ## delete() [#delete] Delete a tool router session by ID. Deleted sessions immediately stop being retrievable or executable. Deleting a missing or already-deleted session surfaces the backend 404. ```typescript async delete(id: string, requestOptions?: ComposioRequestOptions): Promise ``` **Parameters** | Name | Type | | ----------------- | ------------------------ | | `id` | `string` | | `requestOptions?` | `ComposioRequestOptions` | **Returns** `Promise` *** ## use() [#use] Use an existing session **Overload 1** ```typescript async use(id: string, options: { customTools?: CustomTool[]; customToolkits?: CustomToolkit[]; mcp: true }, requestOptions?: ComposioRequestOptions): Promise> ``` **Parameters** | Name | Type | Description | | ----------------- | ------------------------------------------------------------------------------- | -------------------------------------- | | `id` | `string` | \{string} The id of the session to use | | `options` | `\{ customTools?: CustomTool[]; customToolkits?: CustomToolkit[]; mcp: true \}` | | | `requestOptions?` | `ComposioRequestOptions` | | **Returns** `Promise>` — The tool router session **Overload 2** ```typescript async use(id: string, options?: { customTools?: CustomTool[]; customToolkits?: CustomToolkit[]; mcp?: boolean }, requestOptions?: ComposioRequestOptions): Promise> ``` **Parameters** | Name | Type | Description | | ----------------- | ----------------------------------------------------------------------------------- | -------------------------------------- | | `id` | `string` | \{string} The id of the session to use | | `options?` | `\{ customTools?: CustomTool[]; customToolkits?: CustomToolkit[]; mcp?: boolean \}` | | | `requestOptions?` | `ComposioRequestOptions` | | **Returns** `Promise>` — The tool router session **Example** ```typescript import { Composio } from '@composio/core'; const composio = new Composio(); const id = 'session_123'; const session = await composio.sessions.use(id); console.log(session.mcp.url); console.log(session.mcp.headers); ``` *** --- 📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Glossary](https://docs.composio.dev/llms.mdx/reference/glossary) | [Examples](https://docs.composio.dev/llms.mdx/examples) | [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.