Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | import { TERMINOLOGY_MIGRATION } from './terminology'; |
| 2 | import { REST_VERSION_GUIDANCE, TOOL_VERSION_GUIDANCE } from '../api-version-guidance'; |
| 3 | |
| 4 | /** |
| 5 | * Default integration notes appended to most pages. |
| 6 | * Documents the session-based pattern (composio.create + session.tools) as the |
| 7 | * recommended default, states the common mistakes as facts rather than |
| 8 | * imperatives, and acknowledges direct execution as a supported alternative. |
| 9 | * (Rewritten after two eval rounds showed capable agents classify |
| 10 | * ALWAYS/NEVER-style instruction blocks as prompt injection and distrust the |
| 11 | * page they appear on.) |
| 12 | * |
| 13 | * A reader of a session guide may call any endpoint, so this is a broad |
| 14 | * channel: it composes both version guidance constants. They are interpolated |
| 15 | * from `lib/api-version-guidance.ts`, never retyped — see the composition rule |
| 16 | * there. |
| 17 | */ |
| 18 | export const SESSION_GUARDRAILS = ` |
| 19 | |
| 20 | --- |
| 21 | |
| 22 | # Composio SDK — Notes for AI Code Generators |
| 23 | |
| 24 | **Purpose:** Reference for generating current (v3) [Composio](https://composio.dev/) integration code. |
| 25 | **Scope:** Descriptive notes — they document the current API surface and the mistakes most commonly seen in generated code. |
| 26 | |
| 27 | --- |
| 28 | |
| 29 | ## 1. Recommended Integration: Sessions |
| 30 | |
| 31 | For agent tool delivery, Composio supports **Native Tools** (with a provider package) and **MCP** (no provider package needed). |
| 32 | |
| 33 | For application-owned tools or deterministic backend code, use [managed authentication with Proxy Execute](/docs/authentication/managed-auth-for-custom-tools). A session can provide a user-scoped runtime context without an LLM or MCP. Composio authenticates provider requests server-side; connected-account reads redact credentials and aren't a supported token-export workflow. |
| 34 | |
| 35 | ### Native Tools |
| 36 | |
| 37 | #### Python |
| 38 | |
| 39 | \`\`\`python |
| 40 | # ✅ CORRECT — Python (defaults to OpenAI) |
| 41 | from composio import Composio |
| 42 | |
| 43 | composio = Composio() |
| 44 | session = composio.create(user_id="user_123") |
| 45 | tools = session.tools() |
| 46 | # Pass tools to your agent/LLM framework |
| 47 | \`\`\` |
| 48 | |
| 49 | #### TypeScript |
| 50 | |
| 51 | \`\`\`typescript |
| 52 | // ✅ CORRECT — TypeScript (defaults to OpenAI) |
| 53 | import { Composio } from "@composio/core"; |
| 54 | |
| 55 | const composio = new Composio(); |
| 56 | const session = await composio.create("user_123"); |
| 57 | const tools = await session.tools(); |
| 58 | // Pass tools to your agent/LLM framework |
| 59 | \`\`\` |
| 60 | |
| 61 | #### API |
| 62 | |
| 63 | This produces the same default OpenAI function-tool shape, fetching every page. |
| 64 | |
| 65 | \`\`\`bash |
| 66 | set -euo pipefail |
| 67 | SESSION=$(curl --fail-with-body -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \\ |
| 68 | -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \\ |
| 69 | -d '{"user_id":"user_123"}') |
| 70 | SESSION_ID=$(echo "$SESSION" | jq -r '.session_id') |
| 71 | TOOLS='[]' |
| 72 | CURSOR='' |
| 73 | while true; do |
| 74 | PAGE=$(curl --fail-with-body -s --get "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools" \\ |
| 75 | -H "x-api-key: $COMPOSIO_API_KEY" --data-urlencode 'limit=500' --data-urlencode "cursor=$CURSOR") |
| 76 | TOOLS=$(jq -cn --argjson existing "$TOOLS" --argjson page "$PAGE" \\ |
| 77 | '$existing + [$page.items[] | {type:"function",function:{name:.slug,description:.description,parameters:.input_parameters}}]') |
| 78 | CURSOR=$(echo "$PAGE" | jq -r '.next_cursor // empty') |
| 79 | [ -n "$CURSOR" ] || break |
| 80 | done |
| 81 | printf '%s\\n' "$TOOLS" |
| 82 | \`\`\` |
| 83 | |
| 84 | For other providers, pass the provider explicitly. Provider packages follow the naming convention: \`composio_<provider>\` for Python, \`@composio/<provider>\` for TypeScript. |
| 85 | |
| 86 | ### MCP |
| 87 | |
| 88 | Use \`session.mcp.url\` and \`session.mcp.headers\` with any MCP-compatible client (Claude Desktop, Cursor, OpenAI Agents, etc.). No provider package needed. |
| 89 | |
| 90 | --- |
| 91 | |
| 92 | ## 2. Integration Notes |
| 93 | |
| 94 | - \`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. |
| 95 | - 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"\`. |
| 96 | - 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. |
| 97 | - 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). |
| 98 | - **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). |
| 99 | |
| 100 | --- |
| 101 | |
| 102 | # 3. Calling the REST API directly |
| 103 | |
| 104 | ${REST_VERSION_GUIDANCE} |
| 105 | |
| 106 | ${TOOL_VERSION_GUIDANCE} |
| 107 | ${TERMINOLOGY_MIGRATION} |
| 108 | `; |