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, 18:30 UTC
docs: make toolkit-version requirement explicit in direct-execution samples
97-agent docs eval: 72/97 agents hit ToolVersionRequiredError copying version-less tools.execute() samples. Adds an explicit requirement callout, uses 'latest' with a lookup pointer instead of a hardcoded GitHub-only pin, adds versions to all file-handling samples, fixes the LLM guardrails block's version-less signature, and states the Python 3.10+ requirement in the quickstart. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Soumya Medapati committed
Jul 29, 2026 at 18:51 UTC
6b81b404f57fe6aaea0f5d9f86077fa8a294d958
3 files changed
+35
-11
docs/content/docs/quickstart.mdx
+2
@@ -20,6 +20,8 @@ The TypeScript SDK is ESM-only and requires Node.js 22.22.3 or newer. Use `impor
20
21
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
22
<Tab value="Python">
23
+The Composio Python SDK requires **Python 3.10 or newer** (on older versions the import fails with an unrelated-looking `typing.TypeAlias` error).
24
+
25
<PackageInstall ecosystem="python" packages="python-dotenv composio composio-openai-agents openai-agents" />
26
</Tab>
27
<Tab value="TypeScript">
docs/content/docs/tools-direct/executing-tools.mdx
+25
-8
@@ -208,6 +208,10 @@ console.log(text);
208
209
If you just want to call a tool without using any framework or LLM provider, you can use the `execute` method directly.
210
211
+<Callout type="warn">
212
+**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).
213
+</Callout>
214
+
215
<Callout type="info">
216
**Finding tool parameters and types:**
217
@@ -222,10 +226,11 @@ If you just want to call a tool without using any framework or LLM provider, you
226
from composio import Composio
227
228
user_id = "user-k7334"
225
-# Configure toolkit versions at SDK level
229
+# Configure toolkit versions at SDK level for every toolkit you execute.
230
+# Use "latest", or pin a version — find them with composio.toolkits.get(slug="github").meta.available_versions
231
composio = Composio(
232
api_key="your_composio_key",
228
- toolkit_versions={"github": "20251027_00"}
233
+ toolkit_versions={"github": "latest"}
234
)
235
236
# Find available arguments for any tool in the Composio dashboard
@@ -242,10 +247,11 @@ print(result)
247
import { Composio } from "@composio/core";
248
249
const userId = "user-k7334";
245
-// Configure toolkit versions at SDK level
250
+// Configure toolkit versions at SDK level for every toolkit you execute.
251
+// Use "latest", or pin a version — find them with (await composio.toolkits.get("github")).meta.availableVersions
252
const composio = new Composio({
253
apiKey: "your_composio_key",
248
- toolkitVersions: { github: "20251027_00" }
254
+ toolkitVersions: { github: "latest" }
255
});
256
257
// 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
350
```python
351
composio = Composio(
352
api_key="your_composio_key",
353
+ toolkit_versions={"googledrive": "latest", "gmail": "latest"},
354
dangerously_allow_auto_upload_download_files=True,
355
)
356
@@ -364,6 +371,7 @@ import { Composio } from '@composio/core';
371
import path from 'path';
372
const composio = new Composio({
373
apiKey: 'your_api_key',
374
+ toolkitVersions: { googledrive: 'latest' },
375
dangerouslyAllowAutoUploadDownloadFiles: true,
376
});
377
// ---cut---
@@ -400,7 +408,10 @@ result = composio.tools.execute(
408
<Tab value="TypeScript">
409
```typescript
410
import { Composio } from '@composio/core';
403
-const composio = new Composio({ apiKey: 'your_api_key' });
411
+const composio = new Composio({
412
+ apiKey: 'your_api_key',
413
+ toolkitVersions: { gmail: 'latest' },
414
+});
415
// ---cut---
416
const result = await composio.tools.execute('GMAIL_SEND_EMAIL', {
417
userId: 'user-1235***',
@@ -424,6 +435,7 @@ When tools return files, Composio downloads them to the local directory and prov
435
```python
436
composio = Composio(
437
api_key="your_composio_key",
438
+ toolkit_versions={"googledrive": "latest"},
439
dangerously_allow_auto_upload_download_files=True,
440
file_download_dir="./downloads", # Optional: Specify download directory
441
)
@@ -444,6 +456,7 @@ print(result)
456
import { Composio } from '@composio/core';
457
const composio = new Composio({
458
apiKey: 'your_api_key',
459
+ toolkitVersions: { googledrive: 'latest' },
460
dangerouslyAllowAutoUploadDownloadFiles: true,
461
});
462
// ---cut---
@@ -507,7 +520,10 @@ composio = Composio(
520
// @noErrors
521
import { Composio, type beforeFileUploadModifier } from '@composio/core';
522
import path from 'node:path';
510
-const composio = new Composio({ apiKey: 'your_api_key' });
523
+const composio = new Composio({
524
+ apiKey: 'your_api_key',
525
+ toolkitVersions: { googledrive: 'latest' },
526
+});
527
// ctx.source is 'path' | 'url' | 'file' — useful if you only want to audit
528
// local paths and let URLs / File objects pass through unchanged.
529
const beforeFileUpload: beforeFileUploadModifier = async ctx => {
@@ -521,7 +537,6 @@ await composio.tools.execute(
537
{
538
userId: 'user-4235***',
539
arguments: { file_to_upload: path.join(__dirname, 'document.pdf') },
524
- dangerouslySkipVersionCheck: true,
540
},
541
{ beforeFileUpload }
542
);
@@ -541,7 +556,7 @@ def audit_path(ctx) -> str | bool:
556
# ...audit ctx["path"]...
557
return ctx["path"]
558
544
-composio = Composio()
559
+composio = Composio(toolkit_versions={"googledrive": "latest"})
560
561
composio.tools.execute(
562
"GOOGLEDRIVE_UPLOAD_FILE",
@@ -572,6 +587,7 @@ from composio import Composio
587
588
composio = Composio(
589
api_key="your_composio_key",
590
+ toolkit_versions={"googledrive": "latest"},
591
dangerously_allow_auto_upload_download_files=True,
592
file_upload_dirs=["/srv/agent/uploads", "~/.composio/temp"],
593
)
@@ -596,6 +612,7 @@ import path from 'path';
612
// ---cut---
613
const composio = new Composio({
614
apiKey: process.env.COMPOSIO_API_KEY,
615
+ toolkitVersions: { googledrive: 'latest' },
616
// Default: dangerouslyAllowAutoUploadDownloadFiles is false; set true only to opt in
617
});
618
docs/lib/llm-guardrails/direct-execution.ts
+8
-3
@@ -43,7 +43,10 @@ console.log(connection.redirectUrl); // send user here to authenticate
43
44
### Executing Tools
45
46
+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\`.
47
+
48
\`\`\`python
49
+composio = Composio(toolkit_versions={"github": "latest"})
50
tools = composio.tools.get("user_123", tools=["GITHUB_CREATE_ISSUE"])
51
52
result = composio.tools.execute(
@@ -54,6 +57,7 @@ result = composio.tools.execute(
57
\`\`\`
58
59
\`\`\`typescript
60
+const composio = new Composio({ toolkitVersions: { github: "latest" } });
61
const tools = await composio.tools.get("user_123", { tools: ["GITHUB_CREATE_ISSUE"] });
62
63
const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
@@ -67,8 +71,9 @@ const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
71
## Rules
72
73
1. **\`user_id\` is required** — pass it to \`tools.get()\`, \`tools.execute()\`, and \`provider.handle_tool_calls()\`.
70
-2. **\`tools.execute()\` signature** — Python: \`execute(slug, arguments_dict, *, user_id=...)\` (arguments is the second positional param). TypeScript: \`execute(slug, { userId, arguments })\`.
71
-3. **Provider at init** — \`Composio(provider=OpenAIProvider())\` in Python, \`new Composio({ provider: new OpenAIProvider() })\` in TypeScript. Defaults to OpenAI if omitted.
72
-4. **Correct provider imports** — \`composio_<provider>\` for Python, \`@composio/<provider>\` for TypeScript. For OpenAI Agents SDK use \`composio_openai_agents\` / \`@composio/openai-agents\`.
74
+2. **\`tools.execute()\` signature** — Python: \`execute(slug, arguments_dict, *, user_id=..., version=...)\` (arguments is the second positional param). TypeScript: \`execute(slug, { userId, arguments, version })\`.
75
+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\`.
76
+4. **Provider at init** — \`Composio(provider=OpenAIProvider())\` in Python, \`new Composio({ provider: new OpenAIProvider() })\` in TypeScript. Defaults to OpenAI if omitted.
77
+5. **Correct provider imports** — \`composio_<provider>\` for Python, \`@composio/<provider>\` for TypeScript. For OpenAI Agents SDK use \`composio_openai_agents\` / \`@composio/openai-agents\`.
78
${TERMINOLOGY_MIGRATION}
79
`;