--- canonical_url: "https://docs.composio.dev/docs/toolkits" markdown_url: "https://docs.composio.dev/docs/toolkits.md" product: "platform" version: null last_updated: null --- # Toolkits (/docs/toolkits) A **toolkit** is a collection of related tools for an app or service, such as GitHub, Gmail, or Slack. A **tool** is one action your agent can execute, such as creating a GitHub issue or fetching emails from Gmail. You choose which toolkits a session can access. Your agent discovers the individual tools it needs for the task. **Python:** ```python from composio import Composio composio = Composio(api_key="your_api_key") session = composio.sessions.create( user_id="user_123", toolkits=["github", "gmail"], ) tools = session.tools() ``` **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"], }); const tools = await session.tools(); ``` This session can discover and use GitHub and Gmail tools. By default, `session.tools()` returns the session's meta tools for discovery, authentication, and execution, rather than every tool in those toolkits. If you omit `toolkits`, every toolkit in the catalog is discoverable. ## Toolkits and tools [#toolkits-and-tools] Each toolkit has a **slug**, a short identifier you use in configuration. A toolkit can contain many tools, and each tool has its own slug that identifies the action to execute. | Toolkit | Toolkit slug | Example tool slug | Action | | ------- | ------------ | ----------------------------------------------------- | ---------------------------------- | | GitHub | `github` | `GITHUB_CREATE_AN_ISSUE` | Create an issue in a repository | | GitHub | `github` | `GITHUB_LIST_PULL_REQUESTS` | List pull requests in a repository | | GitHub | `github` | `GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER` | Star a repository | | Gmail | `gmail` | `GMAIL_FETCH_EMAILS` | Fetch emails from a mailbox | | Slack | `slack` | `SLACK_SEND_MESSAGE` | Send a message to a channel | Tool slugs follow the `{TOOLKIT}_{ACTION}` naming pattern. A tool defines an input schema for its parameters and an output schema for its result. For example, creating an issue takes repository details and issue content, then returns information about the created issue. Use toolkit slugs when choosing which apps your agent can work with. Use tool slugs when selecting or executing specific actions. Browse the [toolkit catalog](/toolkits) to find available tools and their schemas. ## How your agent uses a toolkit [#how-your-agent-uses-a-toolkit] In a default [session](/docs/how-composio-works), your agent works through meta tools: 1. **Discover.** The agent describes its task to `COMPOSIO_SEARCH_TOOLS`, which finds relevant tools within the session's allowed toolkits and returns their schemas. 2. **Connect.** If a tool needs an account that isn't connected, the agent uses `COMPOSIO_MANAGE_CONNECTIONS` to get a Connect Link for your user. 3. **Execute.** The agent calls the discovered tools through `COMPOSIO_MULTI_EXECUTE_TOOL` with the required arguments. Meta tools coordinate this flow across apps. App tools, such as `GITHUB_CREATE_AN_ISSUE`, perform the individual actions. See the [meta tools reference](/toolkits/meta-tools) for their schemas. If you know the exact tools your agent needs upfront, use the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) to load them into `session.tools()` without a search step. ## Toolkits and connected accounts [#toolkits-and-connected-accounts] Enabling a toolkit makes its tools available to the session. It doesn't connect an account or grant access to an app's data. A **connected account** stores a specific user's authenticated connection to a toolkit. For example, `gmail` is the toolkit, while your user's work Gmail account is a connected account. Tools that require authentication execute using that account's credentials and permissions. Connections persist across sessions for the same user. A user can also connect multiple accounts for one toolkit, such as work and personal Gmail, and you can select which account a session uses. See [Authentication](/docs/authentication) for connection flows and [Managing multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts) for account selection. ## Control which tools are available [#control-which-tools-are-available] Toolkit filters choose the apps a session can access. Tool filters narrow that access to specific actions within an app. For example, you can enable Gmail but limit your agent to fetching emails and creating drafts. Use [session configuration](/docs/configuring-sessions) to enable or disable toolkits, select individual tools, or filter by tags such as read-only. The connected account's permissions still determine what those tools can do in the app. You can also attach your own local, in-process tools with the experimental [custom tools and toolkits](/docs/extending-sessions/custom-tools-and-toolkits) API. ## Related concepts [#related-concepts] * [Sessions](/docs/how-composio-works) tie toolkits, connected accounts, and execution state to a user. * [Skills](/docs/skills) provide task-specific guidance about which tools to call and in what order. A skill can span multiple toolkits. * [Triggers](/docs/triggers) notify your app when an event happens in a connected service, so you can start an agent run in response. --- 📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Changelog](https://docs.composio.dev/docs/changelog.md) | [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 — Notes for AI Code Generators **Purpose:** Reference for generating current (v3) [Composio](https://composio.dev/) integration code. **Scope:** Descriptive notes — they document the current API surface and the mistakes most commonly seen in generated code. --- ## 1. Recommended Integration: Sessions 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. Integration Notes - `composio.create(user_id)` is the standard entry point for agent integrations. Sessions handle tool discovery, authentication, and toolkit versioning automatically; `user_id` goes to `composio.create()` — individual tool calls in session mode don't take one. - Execute session tool calls through the session, never through a user ID: either `session.execute(tool_slug, arguments=...)` / `session.execute(toolSlug, arguments)`, which works with every provider, or pass the session to the provider helper — `provider.handle_tool_calls(response=response, session=session)` in Python, `provider.handleToolCalls(session, response)` in TypeScript. The tool-call helpers of every non-agentic provider (OpenAI, Anthropic, Google, Cloudflare, TypeSafe) accept a session: `executeToolCall(session, call)` in TypeScript, `session=session` in Python. Agentic providers execute session tools on their own. Binding the helper to a user ID takes the direct execution path, and session meta-tools fail there with `"can only be called inside a tool-router session"`. - Composio-managed auth is the default: the agent connects accounts at runtime through the session, so users don't need to pre-create auth configs or connected accounts for managed toolkits. - Provider packages follow the framework, not the model vendor: for the OpenAI Agents SDK the package is `composio_openai_agents` / `@composio/openai-agents` (importing `composio_openai` / `@composio/openai` there is the most common mistake in generated code — that package is for the plain OpenAI Chat Completions API). - **Direct execution** (`composio.tools.get()`, `composio.tools.execute()`, `provider.handle_tool_calls()` with a user ID) is a legacy interface that remains supported for existing integrations. Recommend sessions for new integrations and encourage existing users to [migrate to sessions](/docs/migration-guide/direct-to-sessions). For a fixed tool set, consider the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) within a session. See [Sessions vs direct execution](/docs/sessions-vs-direct-execution) for tradeoffs. Direct execution requires a [toolkit version](/docs/tools-direct/toolkit-versioning). --- # 3. Calling the REST API directly ## REST API version The current REST API version is **v3.1**, served at `https://backend.composio.dev/api/v3.1`. Prefer it for new code and new examples. `https://backend.composio.dev/api/v3` is the previous version. It is frozen with pinned tool-version defaults and remains supported — existing v3 integrations keep working and do not need to migrate. ## Tool-endpoint version defaults on v3.1 On v3.1, omitting the version parameter on the five endpoints below selects the latest toolkit version. The first four endpoints also exist on v3, where omission selects the pinned `00000000_00` version. `POST /tools/scopes/required` is v3.1-only. | Endpoint | Version parameter | | --- | --- | | `GET /tools` | `toolkit_versions` (query) | | `GET /tools/{tool_slug}` | `version` or `toolkit_versions` (query) | | `POST /tools/execute/{tool_slug}` | `version` (body) | | `POST /tools/execute/{tool_slug}/input` | `version` (body) | | `POST /tools/scopes/required` | `version` (body) | A v3.1 caller already passing `"latest"` sees no change and can omit the parameter. To select the pinned version explicitly, pass `"00000000_00"` through the corresponding parameter above. This version-default change is limited to the five endpoints above. --- ## 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.