@devries-cameron20 / composio-1 / commits / 6b81b404f
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.

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