--- canonical_url: "https://docs.composio.dev/kb/guide/platform-production-readiness" markdown_url: "https://docs.composio.dev/kb/guide/platform-production-readiness.md" product: "platform" version: null last_updated: null --- # Move a Composio Integration from Prototype to Production (/kb/guide/platform-production-readiness) ## Replace example user IDs with stable application user IDs [#replace-example-user-ids-with-stable-application-user-ids] Create sessions and connected accounts with a stable identifier from the application database, such as a UUID or primary key. Do not use an email address that can change, and never use `default` in production. Composio uses the user ID to isolate connections and tool calls, so each application user must resolve to the same Composio user ID across sessions. * [Authentication and user IDs](https://docs.composio.dev/docs/authentication) * [How Composio sessions work](https://docs.composio.dev/docs/how-composio-works) ## Isolate environments with separate Composio projects when needed [#isolate-environments-with-separate-composio-projects-when-needed] A Composio project scopes its API keys, connected accounts, auth configs, and webhooks. Use separate projects for development, staging, and production when those resources must not overlap. Use the API key for the intended project in each deployment, and create environment-specific auth configs when the OAuth apps, scopes, or provider credentials differ. * [Composio glossary: Project](https://docs.composio.dev/reference/glossary#project) * [Configure authentication](https://docs.composio.dev/docs/tools-direct/authenticating-tools) ## Switch from managed auth only when production requirements call for it [#switch-from-managed-auth-only-when-production-requirements-call-for-it] Composio managed auth is suitable for development, internal tools, and early prototypes. Create a custom auth config when users must see the application's own OAuth brand, the integration needs custom scopes or a dedicated provider quota, polling requirements differ, or the provider uses a custom instance. Pass the resulting auth config ID to the session; creating the config alone does not make the session use it. * [Managed vs custom auth](https://docs.composio.dev/docs/authentication/custom-app-vs-managed-app) * [Controlling OAuth scopes](https://docs.composio.dev/docs/authentication/controlling-scopes) ## Restrict the production session to the capabilities the agent needs [#restrict-the-production-session-to-the-capabilities-the-agent-needs] Set toolkit, tool, and behavior-tag filters when creating the session. For a sensitive or deterministic workflow, prefer an explicit allowlist of exact tool slugs. For a broader read-only agent, filter on `readOnlyHint` and disable `destructiveHint`, then inspect the resulting tool set before rollout. * [Configure session tool access](https://docs.composio.dev/docs/configuring-sessions) * [Create read-only and restricted sessions](/kb/guide/platform-session-tool-policies) ## Reuse a stored session until the user or configuration changes [#reuse-a-stored-session-until-the-user-or-configuration-changes] Store the session ID and restore it with `composio.use(session_id)` instead of creating a new session for every turn. Create a new session for a different user or a materially different setup, such as a new tool policy or auth-config mapping. A session preserves its scoped runtime state, but it is not the language model's conversation memory. * [Reuse a session](https://docs.composio.dev/docs/how-composio-works#how-sessions-behave) ## Test production trigger handling through the real webhook path [#test-production-trigger-handling-through-the-real-webhook-path] The local `subscribe()` stream is useful for inspecting events, but it bypasses the production webhook handler and signature verification. Before rollout, forward events to the real local handler or use a tunnel, verify the signed payload with `parse()`, and then register the production HTTPS webhook URL for the production project. * [Receive trigger events locally and in production](https://docs.composio.dev/docs/setting-up-triggers/subscribing-to-events) --- 📚 **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.