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: 'latest' requires dangerously_skip_version_check for manual execution
Soumya Medapati52e538286e12
diff --git a/docs/content/docs/auth-configuration/custom-auth-params.mdx b/docs/content/docs/auth-configuration/custom-auth-params.mdxindex 775ae3f67..f9a405bfd 100644--- a/docs/content/docs/auth-configuration/custom-auth-params.mdx+++ b/docs/content/docs/auth-configuration/custom-auth-params.mdx@@ -27,6 +27,7 @@ result = composio.tools.execute(slug="GOOGLECALENDAR_LIST_EVENTS",user_id="user_123",arguments={},+ dangerously_skip_version_check=True, # required when running "latest"custom_auth_params={"parameters": [{@@ -54,6 +55,7 @@ const result = await composio.tools.execute({userId: "user_123",arguments: {},+ dangerouslySkipVersionCheck: true, // required when running "latest"customAuthParams: {parameters: [{@@ -127,6 +129,7 @@ result = composio.tools.execute(slug="NOTION_GET_DATABASE_ITEMS",user_id="user_123",arguments={},+ dangerously_skip_version_check=True, # required when running "latest"modifiers=[add_custom_auth,],diff --git a/docs/content/docs/sessions-vs-direct-execution.mdx b/docs/content/docs/sessions-vs-direct-execution.mdxindex 6ded98cb5..97a88f72d 100644--- a/docs/content/docs/sessions-vs-direct-execution.mdx+++ b/docs/content/docs/sessions-vs-direct-execution.mdx@@ -144,7 +144,8 @@ tools = composio.tools.get(result = composio.tools.execute("GITHUB_CREATE_ISSUE",user_id="user_123",- arguments={"owner": "my-org", "repo": "my-repo", "title": "Fix login bug"}+ arguments={"owner": "my-org", "repo": "my-repo", "title": "Fix login bug"},+ dangerously_skip_version_check=True, # required when running "latest"; or pin via version=...)```</Tab>@@ -174,6 +175,7 @@ const allTools = await composio.tools.get("user_123", {const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {userId: "user_123",arguments: { owner: "my-org", repo: "my-repo", title: "Fix login bug" },+ dangerouslySkipVersionCheck: true, // required when running "latest"; or pin via version});```</Tab>diff --git a/docs/content/docs/tools-direct/executing-tools.mdx b/docs/content/docs/tools-direct/executing-tools.mdxindex 1db96d63b..f74971c6c 100644--- a/docs/content/docs/tools-direct/executing-tools.mdx+++ b/docs/content/docs/tools-direct/executing-tools.mdx@@ -209,7 +209,12 @@ 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).+**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:++- **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.+- **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="..."`.++See [toolkit versioning](/docs/tools-direct/toolkit-versioning) for the full tradeoffs.</Callout><Callout type="info">@@ -239,7 +244,9 @@ composio = Composio(result = composio.tools.execute("GITHUB_LIST_STARGAZERS",user_id=user_id,- arguments={"owner": "ComposioHQ", "repo": "composio", "page": 1, "per_page": 5}+ arguments={"owner": "ComposioHQ", "repo": "composio", "page": 1, "per_page": 5},+ # "latest" requires this opt-in; to pin instead, pass version=composio.toolkits.get(slug="github").meta.version+ dangerously_skip_version_check=True,)print(result)```@@ -265,6 +272,8 @@ const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {"page": 1,"per_page": 5},+ // "latest" requires this opt-in; to pin instead, pass version from (await composio.toolkits.get("github")).meta.version+ dangerouslySkipVersionCheck: true,});console.log('GitHub stargazers:', JSON.stringify(result, null, 2));```@@ -361,6 +370,7 @@ result = composio.tools.execute(slug="GOOGLEDRIVE_UPLOAD_FILE",user_id="user-1235***",arguments={"file_to_upload": os.path.join(os.getcwd(), "document.pdf")},+ dangerously_skip_version_check=True, # required when running "latest")print(result) # Print Google Drive file details@@ -382,7 +392,8 @@ const result = await composio.tools.execute('GOOGLEDRIVE_UPLOAD_FILE', {userId: 'user-4235***',arguments: {file_to_upload: path.join(__dirname, 'document.pdf')- }+ },+ dangerouslySkipVersionCheck: true, // required when running "latest"});console.log(result.data); // Contains Google Drive file details@@ -404,6 +415,7 @@ result = composio.tools.execute("body": "Please find the report attached.","attachment": "https://example.com/report.pdf",},+ dangerously_skip_version_check=True, # required when running "latest")```</Tab>@@ -423,6 +435,7 @@ const result = await composio.tools.execute('GMAIL_SEND_EMAIL', {body: 'Please find the report attached.',attachment: 'https://example.com/report.pdf',},+ dangerouslySkipVersionCheck: true, // required when running "latest"});```</Tab>@@ -446,6 +459,7 @@ result = composio.tools.execute("GOOGLEDRIVE_DOWNLOAD_FILE",user_id="user-1235***",arguments={"file_id": "your_file_id"},+ dangerously_skip_version_check=True, # required when running "latest")# Result includes local file path@@ -467,7 +481,8 @@ const result = await composio.tools.execute('GOOGLEDRIVE_DOWNLOAD_FILE', {userId: 'user-1235***',arguments: {file_id: 'your-file-id'- }+ },+ dangerouslySkipVersionCheck: true, // required when running "latest"});// Result includes local file path@@ -539,6 +554,7 @@ await composio.tools.execute({userId: 'user-4235***',arguments: { file_to_upload: path.join(__dirname, 'document.pdf') },+ dangerouslySkipVersionCheck: true, // required when running "latest"},{ beforeFileUpload });@@ -564,6 +580,7 @@ composio.tools.execute("GOOGLEDRIVE_UPLOAD_FILE",{"file_to_upload": os.path.join(os.getcwd(), "document.pdf")},user_id="user-1235***",+ dangerously_skip_version_check=True, # required when running "latest"modifiers=[audit_path],)```@@ -602,6 +619,7 @@ result = composio.tools.execute("GOOGLEDRIVE_UPLOAD_FILE",user_id="user-1",arguments={"file_to_upload": prestaged_descriptor},+ dangerously_skip_version_check=True, # required when running "latest")```</Tab>@@ -629,6 +647,7 @@ const fileData = await composio.files.upload({await composio.tools.execute('GOOGLEDRIVE_UPLOAD_FILE', {userId: 'user-1',arguments: { file_to_upload: fileData },+ dangerouslySkipVersionCheck: true, // required when running "latest"});```</Tab>diff --git a/docs/content/docs/tools-direct/modify-tool-behavior/after-execution-modifiers.mdx b/docs/content/docs/tools-direct/modify-tool-behavior/after-execution-modifiers.mdxindex b33126b2f..cafabf5d4 100644--- a/docs/content/docs/tools-direct/modify-tool-behavior/after-execution-modifiers.mdx+++ b/docs/content/docs/tools-direct/modify-tool-behavior/after-execution-modifiers.mdx@@ -90,6 +90,7 @@ if (tool_calls) {{userId,arguments: JSON.parse(toolArgs),+ dangerouslySkipVersionCheck: true, // required when running "latest"},{afterExecute: ({ toolSlug, toolkitSlug, result }) => {diff --git a/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdx b/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdxindex ec3208fff..9fba22506 100644--- a/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdx+++ b/docs/content/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.mdx@@ -92,6 +92,7 @@ if (tool_calls) {{userId,arguments: JSON.parse(toolArgs),+ dangerouslySkipVersionCheck: true, // required when running "latest"},{beforeExecute: ({ toolSlug, toolkitSlug, params }) => {@@ -206,6 +207,7 @@ composio.tools.execute("GOOGLEDRIVE_UPLOAD_FILE",{"file_to_upload": "/path/to/document.pdf"},user_id="user_123",+ dangerously_skip_version_check=True, # required when running "latest"modifiers=[audit_path],)```diff --git a/docs/content/docs/tools-direct/toolkit-versioning.mdx b/docs/content/docs/tools-direct/toolkit-versioning.mdxindex 007f2db84..15057dda5 100644--- a/docs/content/docs/tools-direct/toolkit-versioning.mdx+++ b/docs/content/docs/tools-direct/toolkit-versioning.mdx@@ -19,7 +19,7 @@ To view available versions, go to [Dashboard](https://dashboard.composio.dev?utmYou 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.<Callout type="info">-Starting from Python SDK v0.9.0 and TypeScript SDK v0.2.0, specifying versions is required for manual tool execution.+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).</Callout>## Default version behavior@@ -140,7 +140,8 @@ Versions follow the format `YYYYMMDD_NN`:# Pin to a specific versiontoolkit_versions = {"github": "20251027_00"}-# Always use the newest tools+# Always use the newest tools (manual execution additionally requires+# dangerously_skip_version_check=True on the execute call)toolkit_versions = {"github": "latest"}```@@ -148,7 +149,7 @@ toolkit_versions = {"github": "latest"}The right choice depends on how your application consumes tool outputs:-- **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.+- **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.- **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.diff --git a/docs/lib/llm-guardrails/direct-execution.ts b/docs/lib/llm-guardrails/direct-execution.tsindex 55ecabc63..7b933cfb8 100644--- a/docs/lib/llm-guardrails/direct-execution.ts+++ b/docs/lib/llm-guardrails/direct-execution.ts@@ -43,7 +43,7 @@ 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\`.+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.\`\`\`pythoncomposio = Composio(toolkit_versions={"github": "latest"})@@ -53,6 +53,7 @@ result = composio.tools.execute("GITHUB_CREATE_ISSUE",{"owner": "org", "repo": "repo", "title": "Bug report"},user_id="user_123",+ dangerously_skip_version_check=True, # required when running "latest")\`\`\`@@ -63,6 +64,7 @@ const tools = await composio.tools.get("user_123", { tools: ["GITHUB_CREATE_ISSUconst result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {userId: "user_123",arguments: { owner: "org", repo: "repo", title: "Bug report" },+ dangerouslySkipVersionCheck: true, // required when running "latest"});\`\`\`@@ -72,7 +74,7 @@ const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {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=..., 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\`.+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\`.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\`.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>"\`.diff --git a/docs/tests/static/execute-version.test.ts b/docs/tests/static/execute-version.test.tsindex 383ec5494..d7110c717 100644--- a/docs/tests/static/execute-version.test.ts+++ b/docs/tests/static/execute-version.test.ts@@ -11,6 +11,12 @@* `toolkit_versions` / `toolkitVersions` (constructor), `version=` /* `version:` (per-call), or a `COMPOSIO_TOOLKIT_VERSION_*` env var.*+ * Additionally: `"latest"` as a toolkit_versions value is rejected by the+ * SDK for manual execution (runtime-verified 2026-08-03: ToolVersionRequiredError,+ * '"latest" is not supported in manual execution') unless the execute call+ * passes `dangerously_skip_version_check` / `dangerouslySkipVersionCheck`.+ * Pages showing "latest" alongside execute samples must also show the flag.+ ** Scope: content/docs and content/examples. Excluded: content/reference* (generated upstream), changelog (historical records), and* docs/migration-guide (point-in-time documents that may show old APIs).@@ -35,6 +41,8 @@ const EXCLUDED_PATH_SEGMENTS = ["docs/migration-guide/"];const EXECUTE_CALL_RE = /\btools\.execute\s*\(/;const VERSION_TOKEN_RE =/toolkit_versions|toolkitVersions|version\s*[=:]|COMPOSIO_TOOLKIT_VERSION_|dangerously_skip_version_check|dangerouslySkipVersionCheck/;+const LATEST_VALUE_RE = /toolkit_?[vV]ersions[^}\n]{0,120}["']latest["']/;+const SKIP_FLAG_RE = /dangerously_skip_version_check|dangerouslySkipVersionCheck/;async function findMdxFiles(dir: string): Promise<string[]> {const results: string[] = [];@@ -70,9 +78,14 @@ function fencedCode(content: string): string {return fences.join("\n");}-function violates(content: string): boolean {+function violates(content: string): string | null {const code = fencedCode(content);- return EXECUTE_CALL_RE.test(code) && !VERSION_TOKEN_RE.test(code);+ if (!EXECUTE_CALL_RE.test(code)) return null;+ if (!VERSION_TOKEN_RE.test(code)) return "no version configuration";+ if (LATEST_VALUE_RE.test(code) && !SKIP_FLAG_RE.test(code)) {+ return '"latest" without dangerously_skip_version_check (rejected at runtime for manual execution)';+ }+ return null;}describe("direct-execution samples show toolkit versions", () => {@@ -88,16 +101,16 @@ describe("direct-execution samples show toolkit versions", () => {continue;}const content = await readFile(file, "utf-8");- if (violates(content)) {- failures.push(relPath);+ const problem = violates(content);+ if (problem) {+ failures.push(`${relPath} — ${problem}`);}}expect(failures,- `Pages with tools.execute() samples but no version configuration ` +- `(add toolkit_versions/toolkitVersions to the constructor or ` +- `version= per call — see /docs/tools-direct/toolkit-versioning):\n` ++ `Pages with broken tools.execute() version handling ` ++ `(see /docs/tools-direct/toolkit-versioning):\n` +failures.map((f) => ` - ${f}`).join("\n"),).toEqual([]);});@@ -109,8 +122,8 @@ describe("direct-execution samples show toolkit versions", () => {] as const) {expect(violates(guardrails),- `${name} contains a tools.execute() sample without version configuration`,- ).toBe(false);+ `${name} has broken tools.execute() version handling: ${violates(guardrails)}`,+ ).toBeNull();}});});