@devries-cameron20 / composio Mirror · read-only / commits / 52e538286
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 17:15 UTC

docs: 'latest' requires dangerously_skip_version_check for manual execution

Runtime testing during eval-rerun prep caught that toolkit_versions 'latest' is rejected by tools.execute() (ToolVersionRequiredError: '"latest" is not supported in manual execution') — the guides recommended it anyway; only the TS SDK reference documented the real behavior. Per SDK team (Abir): pass dangerously_skip_version_check=True / dangerouslySkipVersionCheck: true when running 'latest' manually. All direct-execution samples now include the flag with a one-line comment; the version-required callout explains both paths (skip-check for LLM-consumed outputs, pinned via toolkits.get(slug).meta.version for parsed outputs); the toolkit-versioning page's 'latest' claims are corrected; the execute-version static test now fails any page showing 'latest' without the flag. Both patterns runtime-verified against the live API before shipping. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Soumya Medapati committed Aug 3, 2026 at 16:23 UTC 52e538286e1297880437b8fbf38a2bce696dd799
8 files changed +62 -19
docs/content/docs/auth-configuration/custom-auth-params.mdx
+3
@@ -27,6 +27,7 @@ result = composio.tools.execute(
27 slug="GOOGLECALENDAR_LIST_EVENTS",
28 user_id="user_123",
29 arguments={},
30 + dangerously_skip_version_check=True, # required when running "latest"
31 custom_auth_params={
32 "parameters": [
33 {
@@ -54,6 +55,7 @@ const result = await composio.tools.execute(
55 {
56 userId: "user_123",
57 arguments: {},
58 + dangerouslySkipVersionCheck: true, // required when running "latest"
59 customAuthParams: {
60 parameters: [
61 {
@@ -127,6 +129,7 @@ result = composio.tools.execute(
129 slug="NOTION_GET_DATABASE_ITEMS",
130 user_id="user_123",
131 arguments={},
132 + dangerously_skip_version_check=True, # required when running "latest"
133 modifiers=[
134 add_custom_auth,
135 ],
docs/content/docs/sessions-vs-direct-execution.mdx
+3 -1
@@ -144,7 +144,8 @@ tools = composio.tools.get(
144 result = composio.tools.execute(
145 "GITHUB_CREATE_ISSUE",
146 user_id="user_123",
147 - arguments={"owner": "my-org", "repo": "my-repo", "title": "Fix login bug"}
147 + arguments={"owner": "my-org", "repo": "my-repo", "title": "Fix login bug"},
148 + dangerously_skip_version_check=True, # required when running "latest"; or pin via version=...
149 )
150 ```
151 </Tab>
@@ -174,6 +175,7 @@ const allTools = await composio.tools.get("user_123", {
175 const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
176 userId: "user_123",
177 arguments: { owner: "my-org", repo: "my-repo", title: "Fix login bug" },
178 + dangerouslySkipVersionCheck: true, // required when running "latest"; or pin via version
179 });
180 ```
181 </Tab>
docs/content/docs/tools-direct/executing-tools.mdx
+23 -4
@@ -209,7 +209,12 @@ console.log(text);
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).
212 +**A toolkit version is required for direct execution** — calling `tools.execute()` without one raises `ToolVersionRequiredError`, and `"latest"` alone is not accepted here. Two ways to satisfy it:
213 +
214 +- **An LLM or agent consumes the outputs:** keep `"latest"` and pass `dangerously_skip_version_check=True` (TypeScript: `dangerouslySkipVersionCheck: true`) on the execute call — you always run the newest tools, and the flag's name is the reminder that output schemas can change between releases.
215 +- **Your code parses the outputs:** pin a dated version — look it up with `composio.toolkits.get(slug="...").meta.version` or in the [Toolkits catalog](/toolkits), and pass it at SDK initialization or per call via `version="..."`.
216 +
217 +See [toolkit versioning](/docs/tools-direct/toolkit-versioning) for the full tradeoffs.
218 </Callout>
219
220 <Callout type="info">
@@ -239,7 +244,9 @@ composio = Composio(
244 result = composio.tools.execute(
245 "GITHUB_LIST_STARGAZERS",
246 user_id=user_id,
242 - arguments={"owner": "ComposioHQ", "repo": "composio", "page": 1, "per_page": 5}
247 + arguments={"owner": "ComposioHQ", "repo": "composio", "page": 1, "per_page": 5},
248 + # "latest" requires this opt-in; to pin instead, pass version=composio.toolkits.get(slug="github").meta.version
249 + dangerously_skip_version_check=True,
250 )
251 print(result)
252 ```
@@ -265,6 +272,8 @@ const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
272 "page": 1,
273 "per_page": 5
274 },
275 + // "latest" requires this opt-in; to pin instead, pass version from (await composio.toolkits.get("github")).meta.version
276 + dangerouslySkipVersionCheck: true,
277 });
278 console.log('GitHub stargazers:', JSON.stringify(result, null, 2));
279 ```
@@ -361,6 +370,7 @@ result = composio.tools.execute(
370 slug="GOOGLEDRIVE_UPLOAD_FILE",
371 user_id="user-1235***",
372 arguments={"file_to_upload": os.path.join(os.getcwd(), "document.pdf")},
373 + dangerously_skip_version_check=True, # required when running "latest"
374 )
375
376 print(result) # Print Google Drive file details
@@ -382,7 +392,8 @@ const result = await composio.tools.execute('GOOGLEDRIVE_UPLOAD_FILE', {
392 userId: 'user-4235***',
393 arguments: {
394 file_to_upload: path.join(__dirname, 'document.pdf')
385 - }
395 + },
396 + dangerouslySkipVersionCheck: true, // required when running "latest"
397 });
398
399 console.log(result.data); // Contains Google Drive file details
@@ -404,6 +415,7 @@ result = composio.tools.execute(
415 "body": "Please find the report attached.",
416 "attachment": "https://example.com/report.pdf",
417 },
418 + dangerously_skip_version_check=True, # required when running "latest"
419 )
420 ```
421 </Tab>
@@ -423,6 +435,7 @@ const result = await composio.tools.execute('GMAIL_SEND_EMAIL', {
435 body: 'Please find the report attached.',
436 attachment: 'https://example.com/report.pdf',
437 },
438 + dangerouslySkipVersionCheck: true, // required when running "latest"
439 });
440 ```
441 </Tab>
@@ -446,6 +459,7 @@ result = composio.tools.execute(
459 "GOOGLEDRIVE_DOWNLOAD_FILE",
460 user_id="user-1235***",
461 arguments={"file_id": "your_file_id"},
462 + dangerously_skip_version_check=True, # required when running "latest"
463 )
464
465 # Result includes local file path
@@ -467,7 +481,8 @@ const result = await composio.tools.execute('GOOGLEDRIVE_DOWNLOAD_FILE', {
481 userId: 'user-1235***',
482 arguments: {
483 file_id: 'your-file-id'
470 - }
484 + },
485 + dangerouslySkipVersionCheck: true, // required when running "latest"
486 });
487
488 // Result includes local file path
@@ -539,6 +554,7 @@ await composio.tools.execute(
554 {
555 userId: 'user-4235***',
556 arguments: { file_to_upload: path.join(__dirname, 'document.pdf') },
557 + dangerouslySkipVersionCheck: true, // required when running "latest"
558 },
559 { beforeFileUpload }
560 );
@@ -564,6 +580,7 @@ composio.tools.execute(
580 "GOOGLEDRIVE_UPLOAD_FILE",
581 {"file_to_upload": os.path.join(os.getcwd(), "document.pdf")},
582 user_id="user-1235***",
583 + dangerously_skip_version_check=True, # required when running "latest"
584 modifiers=[audit_path],
585 )
586 ```
@@ -602,6 +619,7 @@ result = composio.tools.execute(
619 "GOOGLEDRIVE_UPLOAD_FILE",
620 user_id="user-1",
621 arguments={"file_to_upload": prestaged_descriptor},
622 + dangerously_skip_version_check=True, # required when running "latest"
623 )
624 ```
625 </Tab>
@@ -629,6 +647,7 @@ const fileData = await composio.files.upload({
647 await composio.tools.execute('GOOGLEDRIVE_UPLOAD_FILE', {
648 userId: 'user-1',
649 arguments: { file_to_upload: fileData },
650 + dangerouslySkipVersionCheck: true, // required when running "latest"
651 });
652 ```
653 </Tab>
docs/content/docs/tools-direct/modify-tool-behavior/after-execution-modifiers.mdx
+1
@@ -90,6 +90,7 @@ if (tool_calls) {
90 {
91 userId,
92 arguments: JSON.parse(toolArgs),
93 + dangerouslySkipVersionCheck: true, // required when running "latest"
94 },
95 {
96 afterExecute: ({ toolSlug, toolkitSlug, result }) => {
docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdx
+2
@@ -92,6 +92,7 @@ if (tool_calls) {
92 {
93 userId,
94 arguments: JSON.parse(toolArgs),
95 + dangerouslySkipVersionCheck: true, // required when running "latest"
96 },
97 {
98 beforeExecute: ({ toolSlug, toolkitSlug, params }) => {
@@ -206,6 +207,7 @@ composio.tools.execute(
207 "GOOGLEDRIVE_UPLOAD_FILE",
208 {"file_to_upload": "/path/to/document.pdf"},
209 user_id="user_123",
210 + dangerously_skip_version_check=True, # required when running "latest"
211 modifiers=[audit_path],
212 )
213 ```
docs/content/docs/tools-direct/toolkit-versioning.mdx
+4 -3
@@ -19,7 +19,7 @@ To view available versions, go to [Dashboard](https://dashboard.composio.dev?utm
19 You can also find the latest version for each toolkit on the [Toolkits](/toolkits) page in the docs. Select a toolkit to see its current version and available tools.
20
21 <Callout type="info">
22 -Starting from Python SDK v0.9.0 and TypeScript SDK v0.2.0, specifying versions is required for manual tool execution.
22 +Starting from Python SDK v0.9.0 and TypeScript SDK v0.2.0, specifying versions is required for manual tool execution — and `"latest"` is **not** accepted there on its own. To run the newest version with `tools.execute()`, pass `dangerously_skip_version_check=True` (TypeScript: `dangerouslySkipVersionCheck: true`) on the call; otherwise pin a dated version. `"latest"` works without the flag everywhere else (fetching tools, sessions).
23 </Callout>
24
25 ## Default version behavior
@@ -140,7 +140,8 @@ Versions follow the format `YYYYMMDD_NN`:
140 # Pin to a specific version
141 toolkit_versions = {"github": "20251027_00"}
142
143 -# Always use the newest tools
143 +# Always use the newest tools (manual execution additionally requires
144 +# dangerously_skip_version_check=True on the execute call)
145 toolkit_versions = {"github": "latest"}
146 ```
147
@@ -148,7 +149,7 @@ toolkit_versions = {"github": "latest"}
149
150 The right choice depends on how your application consumes tool outputs:
151
151 -- **Use `latest`** when tool outputs are consumed by an LLM or AI agent. Agents interpret responses dynamically and adapt to changes in output structure. Using `latest` ensures your agent always has access to the newest tools and improvements without manual intervention.
152 +- **Use `latest`** when tool outputs are consumed by an LLM or AI agent. Agents interpret responses dynamically and adapt to changes in output structure. Using `latest` ensures your agent always has access to the newest tools and improvements without manual intervention. For manual execution (`tools.execute()`), `latest` requires the explicit opt-in `dangerously_skip_version_check=True` / `dangerouslySkipVersionCheck: true` on the call — the flag's name is the reminder that output schemas can change between releases.
153
154 - **Pin a specific version** when tool outputs are consumed programmatically — for example, if your code destructures specific fields from a response, maps outputs to a database schema, or feeds results into a typed pipeline. Schema changes in a new version could silently break these integrations.
155
docs/lib/llm-guardrails/direct-execution.ts
+4 -2
@@ -43,7 +43,7 @@ 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\`.
46 +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.
47
48 \`\`\`python
49 composio = Composio(toolkit_versions={"github": "latest"})
@@ -53,6 +53,7 @@ result = composio.tools.execute(
53 "GITHUB_CREATE_ISSUE",
54 {"owner": "org", "repo": "repo", "title": "Bug report"},
55 user_id="user_123",
56 + dangerously_skip_version_check=True, # required when running "latest"
57 )
58 \`\`\`
59
@@ -63,6 +64,7 @@ const tools = await composio.tools.get("user_123", { tools: ["GITHUB_CREATE_ISSU
64 const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
65 userId: "user_123",
66 arguments: { owner: "org", repo: "repo", title: "Bug report" },
67 + dangerouslySkipVersionCheck: true, // required when running "latest"
68 });
69 \`\`\`
70
@@ -72,7 +74,7 @@ const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
74
75 1. **\`user_id\` is required** — pass it to \`tools.get()\`, \`tools.execute()\`, and \`provider.handle_tool_calls()\`.
76 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\`.
77 +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\`.
78 4. **Provider at init** — \`Composio(provider=OpenAIProvider())\` in Python, \`new Composio({ provider: new OpenAIProvider() })\` in TypeScript. Defaults to OpenAI if omitted.
79 5. **Correct provider imports** — \`composio_<provider>\` for Python, \`@composio/<provider>\` for TypeScript. For OpenAI Agents SDK use \`composio_openai_agents\` / \`@composio/openai-agents\`.
80 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>"\`.
docs/tests/static/execute-version.test.ts
+22 -9
@@ -11,6 +11,12 @@
11 * `toolkit_versions` / `toolkitVersions` (constructor), `version=` /
12 * `version:` (per-call), or a `COMPOSIO_TOOLKIT_VERSION_*` env var.
13 *
14 + * Additionally: `"latest"` as a toolkit_versions value is rejected by the
15 + * SDK for manual execution (runtime-verified 2026-08-03: ToolVersionRequiredError,
16 + * '"latest" is not supported in manual execution') unless the execute call
17 + * passes `dangerously_skip_version_check` / `dangerouslySkipVersionCheck`.
18 + * Pages showing "latest" alongside execute samples must also show the flag.
19 + *
20 * Scope: content/docs and content/examples. Excluded: content/reference
21 * (generated upstream), changelog (historical records), and
22 * docs/migration-guide (point-in-time documents that may show old APIs).
@@ -35,6 +41,8 @@ const EXCLUDED_PATH_SEGMENTS = ["docs/migration-guide/"];
41 const EXECUTE_CALL_RE = /\btools\.execute\s*\(/;
42 const VERSION_TOKEN_RE =
43 /toolkit_versions|toolkitVersions|version\s*[=:]|COMPOSIO_TOOLKIT_VERSION_|dangerously_skip_version_check|dangerouslySkipVersionCheck/;
44 +const LATEST_VALUE_RE = /toolkit_?[vV]ersions[^}\n]{0,120}["']latest["']/;
45 +const SKIP_FLAG_RE = /dangerously_skip_version_check|dangerouslySkipVersionCheck/;
46
47 async function findMdxFiles(dir: string): Promise<string[]> {
48 const results: string[] = [];
@@ -70,9 +78,14 @@ function fencedCode(content: string): string {
78 return fences.join("\n");
79 }
80
73 -function violates(content: string): boolean {
81 +function violates(content: string): string | null {
82 const code = fencedCode(content);
75 - return EXECUTE_CALL_RE.test(code) && !VERSION_TOKEN_RE.test(code);
83 + if (!EXECUTE_CALL_RE.test(code)) return null;
84 + if (!VERSION_TOKEN_RE.test(code)) return "no version configuration";
85 + if (LATEST_VALUE_RE.test(code) && !SKIP_FLAG_RE.test(code)) {
86 + return '"latest" without dangerously_skip_version_check (rejected at runtime for manual execution)';
87 + }
88 + return null;
89 }
90
91 describe("direct-execution samples show toolkit versions", () => {
@@ -88,16 +101,16 @@ describe("direct-execution samples show toolkit versions", () => {
101 continue;
102 }
103 const content = await readFile(file, "utf-8");
91 - if (violates(content)) {
92 - failures.push(relPath);
104 + const problem = violates(content);
105 + if (problem) {
106 + failures.push(`${relPath} — ${problem}`);
107 }
108 }
109
110 expect(
111 failures,
98 - `Pages with tools.execute() samples but no version configuration ` +
99 - `(add toolkit_versions/toolkitVersions to the constructor or ` +
100 - `version= per call — see /docs/tools-direct/toolkit-versioning):\n` +
112 + `Pages with broken tools.execute() version handling ` +
113 + `(see /docs/tools-direct/toolkit-versioning):\n` +
114 failures.map((f) => ` - ${f}`).join("\n"),
115 ).toEqual([]);
116 });
@@ -109,8 +122,8 @@ describe("direct-execution samples show toolkit versions", () => {
122 ] as const) {
123 expect(
124 violates(guardrails),
112 - `${name} contains a tools.execute() sample without version configuration`,
113 - ).toBe(false);
125 + `${name} has broken tools.execute() version handling: ${violates(guardrails)}`,
126 + ).toBeNull();
127 }
128 });
129 });