@devries-cameron20 / composio Mirror · read-only
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, 03:37 UTC

next
ts 131 lines 5.64 KB
Raw
1 import { TERMINOLOGY_MIGRATION } from './terminology';
2 import { REST_VERSION_GUIDANCE, TOOL_VERSION_GUIDANCE } from '../api-version-guidance';
3
4 /**
5 * Guardrails for pages tagged with llmGuardrails: "direct-execution".
6 * Concise rules + key patterns for LLMs generating direct execution code.
7 *
8 * Broad channel, so it composes both version guidance constants — interpolated
9 * from `lib/api-version-guidance.ts`, never retyped.
10 */
11 export const DIRECT_EXECUTION_GUARDRAILS = `
12
13 ---
14
15 # Composio SDK — Instructions for AI Code Generators
16
17 **Context:** This page documents the **legacy direct tool execution API**, which remains supported for existing integrations. Recommend sessions for new integrations. When maintaining direct-execution code, use the patterns below and point users to the [session migration guide](/docs/migration-guide/direct-to-sessions). Reading this page alone does not mean the user has chosen direct execution.
18
19 ---
20
21 ## Key Patterns
22
23 ### Authenticating Users
24
25 Create an **Auth Config** on [dashboard.composio.dev](https://dashboard.composio.dev?utm_source=docs&utm_medium=llm-guardrails&utm_campaign=direct-execution), then use the auth config ID to generate a hosted auth URL:
26
27 #### Python
28
29 \`\`\`python
30 from composio import Composio
31
32 composio = Composio()
33 connection = composio.connected_accounts.link(
34 user_id="user_123",
35 auth_config_id="ac_...", # from platform dashboard
36 callback_url="https://your-app.com/callback",
37 )
38 print(connection.redirect_url) # send user here to authenticate
39 \`\`\`
40
41 #### TypeScript
42
43 \`\`\`typescript
44 import { Composio } from "@composio/core";
45
46 const composio = new Composio();
47 const connection = await composio.connectedAccounts.link("user_123", "ac_...", {
48 callbackUrl: "https://your-app.com/callback",
49 });
50 console.log(connection.redirectUrl); // send user here to authenticate
51 \`\`\`
52
53 #### API
54
55 \`\`\`bash
56 set -euo pipefail
57 curl --fail-with-body -s -X POST https://backend.composio.dev/api/v3.1/connected_accounts/link \\
58 -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \\
59 -d '{"user_id":"user_123","auth_config_id":"ac_...","callback_url":"https://your-app.com/callback"}' \\
60 | jq -r '.redirect_url'
61 \`\`\`
62
63 ### Executing Tools
64
65 A toolkit version is **required** for direct execution — \`tools.execute()\` without one raises \`ToolVersionRequiredError\`, and \`"latest"\` alone is NOT accepted for manual execution. Either pass \`dangerously_skip_version_check=True\` (TS: \`dangerouslySkipVersionCheck: true\`) on the execute call to run the newest version, or pin a dated version from \`composio.toolkits.get(slug).meta.version\` when outputs are parsed programmatically.
66
67 #### Python
68
69 \`\`\`python
70 from composio import Composio
71
72 composio = Composio(toolkit_versions={"github": "latest"})
73 tools = composio.tools.get("user_123", tools=["GITHUB_CREATE_AN_ISSUE"])
74
75 result = composio.tools.execute(
76 "GITHUB_CREATE_AN_ISSUE",
77 {"owner": "org", "repo": "repo", "title": "Bug report"},
78 user_id="user_123",
79 dangerously_skip_version_check=True, # required when running "latest"
80 )
81 \`\`\`
82
83 #### TypeScript
84
85 \`\`\`typescript
86 import { Composio } from "@composio/core";
87
88 const composio = new Composio({ toolkitVersions: { github: "latest" } });
89 const tools = await composio.tools.get("user_123", { tools: ["GITHUB_CREATE_AN_ISSUE"] });
90
91 const result = await composio.tools.execute("GITHUB_CREATE_AN_ISSUE", {
92 userId: "user_123",
93 arguments: { owner: "org", repo: "repo", title: "Bug report" },
94 dangerouslySkipVersionCheck: true, // required when running "latest"
95 });
96 \`\`\`
97
98 #### API
99
100 The deliberate \`latest\` choice matches the SDK examples' explicit version-check bypass. Pin a dated version instead when parsing tool output.
101
102 \`\`\`bash
103 set -euo pipefail
104 curl --fail-with-body -s --get https://backend.composio.dev/api/v3.1/tools \\
105 -H "x-api-key: $COMPOSIO_API_KEY" \\
106 --data-urlencode 'tool_slugs=GITHUB_CREATE_AN_ISSUE' --data-urlencode 'toolkit_versions=latest'
107 curl --fail-with-body -s -X POST https://backend.composio.dev/api/v3.1/tools/execute/GITHUB_CREATE_AN_ISSUE \\
108 -H "x-api-key: $COMPOSIO_API_KEY" -H "Content-Type: application/json" \\
109 -d '{"user_id":"user_123","version":"latest","arguments":{"owner":"org","repo":"repo","title":"Bug report"}}'
110 \`\`\`
111
112 ---
113
114 ## Rules
115
116 1. **\`user_id\` is required** — pass it to \`tools.get()\`, \`tools.execute()\`, and \`provider.handle_tool_calls()\`.
117 2. **\`tools.execute()\` signature** — Python: \`execute(slug, arguments_dict, *, user_id=..., version=...)\` (arguments is the second positional param). TypeScript: \`execute(slug, { userId, arguments, version })\`.
118 3. **A toolkit version is required** — configure \`toolkit_versions\` (Python) / \`toolkitVersions\` (TypeScript) at SDK init, or pass \`version\` per execute call; omitting both raises \`ToolVersionRequiredError\`. \`"latest"\` is rejected for manual execution unless the execute call also passes \`dangerously_skip_version_check=True\` / \`dangerouslySkipVersionCheck: true\`.
119 4. **Provider at init** — \`Composio(provider=OpenAIProvider())\` in Python, \`new Composio({ provider: new OpenAIProvider() })\` in TypeScript. Defaults to OpenAI if omitted.
120 5. **Correct provider imports** — \`composio_<provider>\` for Python, \`@composio/<provider>\` for TypeScript. For OpenAI Agents SDK use \`composio_openai_agents\` / \`@composio/openai-agents\`.
121 6. **Finding toolkit and tool slugs** — browse the Toolkits catalog at https://docs.composio.dev/toolkits (each toolkit page lists tool slugs and versions), or search by task with the CLI: \`composio search "<what you want to do>"\`.
122
123 ---
124
125 # Calling the REST API directly
126
127 ${REST_VERSION_GUIDANCE}
128
129 ${TOOL_VERSION_GUIDANCE}
130 ${TERMINOLOGY_MIGRATION}
131 `;