Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: rewrite the AI guardrails block as descriptive notes
Three independent eval runs across two rounds show capable agents classify the CRITICAL INSTRUCTIONS block as prompt injection and ignore it; its ALWAYS/NEVER framing also contradicted the sessions-vs-direct-execution page. Same facts, no commands: sessions stay the recommended default, the provider-import gotcha and managed-auth default are kept, and direct execution is acknowledged as a supported lower-level interface with a link to the tradeoffs page. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Soumya Medapati committed
Aug 6, 2026 at 13:04 UTC
8b9a5a73814318210cc915a583da08754421b429
1 file changed
+16
-22
docs/lib/llm-guardrails/session.ts
+16
-22
@@ -1,21 +1,26 @@
1
import { TERMINOLOGY_MIGRATION } from './terminology';
2
3
/**
4
- * Default guardrails appended to most pages.
5
- * Steers LLMs toward the session-based pattern (composio.create + session.tools).
4
+ * Default integration notes appended to most pages.
5
+ * Documents the session-based pattern (composio.create + session.tools) as the
6
+ * recommended default, states the common mistakes as facts rather than
7
+ * imperatives, and acknowledges direct execution as a supported alternative.
8
+ * (Rewritten after two eval rounds showed capable agents classify
9
+ * ALWAYS/NEVER-style instruction blocks as prompt injection and distrust the
10
+ * page they appear on.)
11
*/
12
export const SESSION_GUARDRAILS = `
13
14
---
15
11
-# Composio SDK — Instructions for AI Code Generators
16
+# Composio SDK — Notes for AI Code Generators
17
13
-**Purpose:** Enforce only the **current** and **correct** patterns for integrating [Composio](https://composio.dev/) tools into AI agents.
14
-**Scope:** All AI-generated code using Composio must follow these guardrails.
18
+**Purpose:** Reference for generating current (v3) [Composio](https://composio.dev/) integration code.
19
+**Scope:** Descriptive notes — they document the current API surface and the mistakes most commonly seen in generated code.
20
21
---
22
18
-## 1. Correct Composio Integration
23
+## 1. Recommended Integration: Sessions
24
25
Composio supports two integration modes: **Native Tools** (with a provider package) and **MCP** (no provider package needed).
26
@@ -49,22 +54,11 @@ Use \`session.mcp.url\` and \`session.mcp.headers\` with any MCP-compatible clie
54
55
---
56
52
-## 2. CRITICAL INSTRUCTIONS FOR AI MODELS
57
+## 2. Integration Notes
58
54
-### 2.1 — ALWAYS DO THE FOLLOWING
55
-
56
-1. **Use \`composio.create(user_id)\`** to create a session — this is the entry point for all Composio integrations.
57
-2. **Use \`session.tools()\`** for native tool integration or **\`session.mcp.url\`** for MCP integration.
58
-3. **Import** from the correct provider package (\`composio_<provider>\` for Python, \`@composio/<provider>\` for TypeScript).
59
-4. **Pass \`user_id\` to \`composio.create()\`**, not to individual tool calls.
60
-
61
-### 2.2 — NEVER DO THE FOLLOWING
62
-
63
-1. **Do not** instruct users to manually create auth configs or connected accounts before running.
64
-2. **Do not** import from \`composio_openai\` / \`@composio/openai\` when using OpenAI Agents SDK — use \`composio_openai_agents\` / \`@composio/openai-agents\` instead.
65
-
66
-### 2.3 — DISCOURAGED (do not use unless user explicitly asks)
67
-
68
-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.
59
+- \`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.
60
+- 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.
61
+- 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).
62
+- **Direct execution** (\`composio.tools.get()\`, \`composio.tools.execute()\`, \`provider.handle_tool_calls()\`) is a fully supported lower-level interface: your code picks the tool, no runtime discovery. It fits deterministic workflows and scripts; sessions fit agents that decide at runtime. The tradeoffs are documented at https://docs.composio.dev/docs/sessions-vs-direct-execution. Note that direct execution requires a toolkit version (https://docs.composio.dev/docs/tools-direct/toolkit-versioning).
63
${TERMINOLOGY_MIGRATION}
64
`;