@devries-cameron20 / composio Mirror · read-only / commits / 8b9a5a738
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 16:00 UTC

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 `;