Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
ts 108 lines 5.84 KB
Raw
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 `;