Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: make toolkit-version requirement explicit in direct-execution samples
Soumya Medapati6b81b404f57f
diff --git a/docs/content/docs/quickstart.mdx b/docs/content/docs/quickstart.mdxindex 630233d92..e33ece9a3 100644--- a/docs/content/docs/quickstart.mdx+++ b/docs/content/docs/quickstart.mdx@@ -20,6 +20,8 @@ The TypeScript SDK is ESM-only and requires Node.js 22.22.3 or newer. Use `impor<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">+The Composio Python SDK requires **Python 3.10 or newer** (on older versions the import fails with an unrelated-looking `typing.TypeAlias` error).+<PackageInstall ecosystem="python" packages="python-dotenv composio composio-openai-agents openai-agents" /></Tab><Tab value="TypeScript">diff --git a/docs/content/docs/tools-direct/executing-tools.mdx b/docs/content/docs/tools-direct/executing-tools.mdxindex c7d659dc6..3366ec556 100644--- a/docs/content/docs/tools-direct/executing-tools.mdx+++ b/docs/content/docs/tools-direct/executing-tools.mdx@@ -208,6 +208,10 @@ console.log(text);If you just want to call a tool without using any framework or LLM provider, you can use the `execute` method directly.+<Callout type="warn">+**A toolkit version is required for direct execution** — calling `tools.execute()` without one raises `ToolVersionRequiredError`. Set versions for your toolkits at SDK initialization (shown below), pass `version="..."` per call, or use environment variables. Use `"latest"` unless you need to pin — see [toolkit versioning](/docs/tools-direct/toolkit-versioning) for the tradeoffs and how to [look up a toolkit's versions](/docs/tools-direct/toolkit-versioning#managing-versions).+</Callout>+<Callout type="info">**Finding tool parameters and types:**@@ -222,10 +226,11 @@ If you just want to call a tool without using any framework or LLM provider, youfrom composio import Composiouser_id = "user-k7334"-# Configure toolkit versions at SDK level+# Configure toolkit versions at SDK level for every toolkit you execute.+# Use "latest", or pin a version — find them with composio.toolkits.get(slug="github").meta.available_versionscomposio = Composio(api_key="your_composio_key",- toolkit_versions={"github": "20251027_00"}+ toolkit_versions={"github": "latest"})# Find available arguments for any tool in the Composio dashboard@@ -242,10 +247,11 @@ print(result)import { Composio } from "@composio/core";const userId = "user-k7334";-// Configure toolkit versions at SDK level+// Configure toolkit versions at SDK level for every toolkit you execute.+// Use "latest", or pin a version — find them with (await composio.toolkits.get("github")).meta.availableVersionsconst composio = new Composio({apiKey: "your_composio_key",- toolkitVersions: { github: "20251027_00" }+ toolkitVersions: { github: "latest" }});// Find available arguments for any tool in the Composio dashboard@@ -344,6 +350,7 @@ Pass local file paths, URLs, or File objects to tools that accept files. The SDK```pythoncomposio = Composio(api_key="your_composio_key",+ toolkit_versions={"googledrive": "latest", "gmail": "latest"},dangerously_allow_auto_upload_download_files=True,)@@ -364,6 +371,7 @@ import { Composio } from '@composio/core';import path from 'path';const composio = new Composio({apiKey: 'your_api_key',+ toolkitVersions: { googledrive: 'latest' },dangerouslyAllowAutoUploadDownloadFiles: true,});// ---cut---@@ -400,7 +408,10 @@ result = composio.tools.execute(<Tab value="TypeScript">```typescriptimport { Composio } from '@composio/core';-const composio = new Composio({ apiKey: 'your_api_key' });+const composio = new Composio({+ apiKey: 'your_api_key',+ toolkitVersions: { gmail: 'latest' },+});// ---cut---const result = await composio.tools.execute('GMAIL_SEND_EMAIL', {userId: 'user-1235***',@@ -424,6 +435,7 @@ When tools return files, Composio downloads them to the local directory and prov```pythoncomposio = Composio(api_key="your_composio_key",+ toolkit_versions={"googledrive": "latest"},dangerously_allow_auto_upload_download_files=True,file_download_dir="./downloads", # Optional: Specify download directory)@@ -444,6 +456,7 @@ print(result)import { Composio } from '@composio/core';const composio = new Composio({apiKey: 'your_api_key',+ toolkitVersions: { googledrive: 'latest' },dangerouslyAllowAutoUploadDownloadFiles: true,});// ---cut---@@ -507,7 +520,10 @@ composio = Composio(// @noErrorsimport { Composio, type beforeFileUploadModifier } from '@composio/core';import path from 'node:path';-const composio = new Composio({ apiKey: 'your_api_key' });+const composio = new Composio({+ apiKey: 'your_api_key',+ toolkitVersions: { googledrive: 'latest' },+});// ctx.source is 'path' | 'url' | 'file' — useful if you only want to audit// local paths and let URLs / File objects pass through unchanged.const beforeFileUpload: beforeFileUploadModifier = async ctx => {@@ -521,7 +537,6 @@ await composio.tools.execute({userId: 'user-4235***',arguments: { file_to_upload: path.join(__dirname, 'document.pdf') },- dangerouslySkipVersionCheck: true,},{ beforeFileUpload });@@ -541,7 +556,7 @@ def audit_path(ctx) -> str | bool:# ...audit ctx["path"]...return ctx["path"]-composio = Composio()+composio = Composio(toolkit_versions={"googledrive": "latest"})composio.tools.execute("GOOGLEDRIVE_UPLOAD_FILE",@@ -572,6 +587,7 @@ from composio import Composiocomposio = Composio(api_key="your_composio_key",+ toolkit_versions={"googledrive": "latest"},dangerously_allow_auto_upload_download_files=True,file_upload_dirs=["/srv/agent/uploads", "~/.composio/temp"],)@@ -596,6 +612,7 @@ import path from 'path';// ---cut---const composio = new Composio({apiKey: process.env.COMPOSIO_API_KEY,+ toolkitVersions: { googledrive: 'latest' },// Default: dangerouslyAllowAutoUploadDownloadFiles is false; set true only to opt in});diff --git a/docs/lib/llm-guardrails/direct-execution.ts b/docs/lib/llm-guardrails/direct-execution.tsindex 6ed093a0c..a1cfc4478 100644--- a/docs/lib/llm-guardrails/direct-execution.ts+++ b/docs/lib/llm-guardrails/direct-execution.ts@@ -43,7 +43,10 @@ console.log(connection.redirectUrl); // send user here to authenticate### Executing Tools+A toolkit version is **required** for direct execution — \`tools.execute()\` without one raises \`ToolVersionRequiredError\`. Set \`toolkit_versions\` / \`toolkitVersions\` at SDK initialization (or pass \`version\` per call). Use \`"latest"\` unless outputs are parsed programmatically, in which case pin a version from \`composio.toolkits.get(slug).meta.available_versions\`.+\`\`\`python+composio = Composio(toolkit_versions={"github": "latest"})tools = composio.tools.get("user_123", tools=["GITHUB_CREATE_ISSUE"])result = composio.tools.execute(@@ -54,6 +57,7 @@ result = composio.tools.execute(\`\`\`\`\`\`typescript+const composio = new Composio({ toolkitVersions: { github: "latest" } });const tools = await composio.tools.get("user_123", { tools: ["GITHUB_CREATE_ISSUE"] });const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {@@ -67,8 +71,9 @@ const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {## Rules1. **\`user_id\` is required** — pass it to \`tools.get()\`, \`tools.execute()\`, and \`provider.handle_tool_calls()\`.-2. **\`tools.execute()\` signature** — Python: \`execute(slug, arguments_dict, *, user_id=...)\` (arguments is the second positional param). TypeScript: \`execute(slug, { userId, arguments })\`.-3. **Provider at init** — \`Composio(provider=OpenAIProvider())\` in Python, \`new Composio({ provider: new OpenAIProvider() })\` in TypeScript. Defaults to OpenAI if omitted.-4. **Correct provider imports** — \`composio_<provider>\` for Python, \`@composio/<provider>\` for TypeScript. For OpenAI Agents SDK use \`composio_openai_agents\` / \`@composio/openai-agents\`.+2. **\`tools.execute()\` signature** — Python: \`execute(slug, arguments_dict, *, user_id=..., version=...)\` (arguments is the second positional param). TypeScript: \`execute(slug, { userId, arguments, version })\`.+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\`.+4. **Provider at init** — \`Composio(provider=OpenAIProvider())\` in Python, \`new Composio({ provider: new OpenAIProvider() })\` in TypeScript. Defaults to OpenAI if omitted.+5. **Correct provider imports** — \`composio_<provider>\` for Python, \`@composio/<provider>\` for TypeScript. For OpenAI Agents SDK use \`composio_openai_agents\` / \`@composio/openai-agents\`.${TERMINOLOGY_MIGRATION}`;