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: '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.mdx
index 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.mdx
index 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.mdx
index 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.mdx
index 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.mdx
index 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.mdx
index 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?utm
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.
<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 version
toolkit_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.ts
index 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.
\`\`\`python
composio = 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_ISSU
const 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.ts
index 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();
}
});
});