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