Skip to content

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: make toolkit-version requirement explicit in direct-execution samples

Soumya Medapati6b81b404f57f
diff --git a/docs/content/docs/quickstart.mdx b/docs/content/docs/quickstart.mdx
index 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.mdx
index 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, you
from composio import Composio
user_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_versions
composio = 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.availableVersions
const 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
```python
composio = 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">
```typescript
import { 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
```python
composio = 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(
// @noErrors
import { 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 Composio
composio = 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.ts
index 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", {
## Rules
1. **\`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}
`;