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: enforce toolkit-version policy on execution samples via static test

Soumya Medapati70f6772037e0
diff --git a/docs/content/docs/auth-configuration/custom-auth-params.mdx b/docs/content/docs/auth-configuration/custom-auth-params.mdx
index ba5432362..775ae3f67 100644
--- a/docs/content/docs/auth-configuration/custom-auth-params.mdx
+++ b/docs/content/docs/auth-configuration/custom-auth-params.mdx
@@ -21,7 +21,7 @@ Pass `customAuthParams` in the `tools.execute()` call to inject your own token a
```python
from composio import Composio
-composio = Composio()
+composio = Composio(toolkit_versions={"googlecalendar": "latest"})
result = composio.tools.execute(
slug="GOOGLECALENDAR_LIST_EVENTS",
@@ -46,6 +46,7 @@ import { Composio } from "@composio/core";
const composio = new Composio({
apiKey: process.env.COMPOSIO_API_KEY,
+ toolkitVersions: { googlecalendar: "latest" },
});
const result = await composio.tools.execute(
@@ -100,7 +101,7 @@ Before Execute Modifiers are a way to modify the parameters of a tool before it
from composio import Composio, before_execute
from composio.types import ToolExecuteParams
-composio = Composio()
+composio = Composio(toolkit_versions={"notion": "latest"})
@before_execute(toolkits=["NOTION"])
diff --git a/docs/content/docs/sessions-vs-direct-execution.mdx b/docs/content/docs/sessions-vs-direct-execution.mdx
index 694769d2a..6ded98cb5 100644
--- a/docs/content/docs/sessions-vs-direct-execution.mdx
+++ b/docs/content/docs/sessions-vs-direct-execution.mdx
@@ -122,7 +122,10 @@ Fetch tools by slug or toolkit. Pass them to your LLM or call `tools.execute()`
from composio import Composio
from composio_openai import OpenAIProvider
-composio = Composio(provider=OpenAIProvider())
+composio = Composio(
+ provider=OpenAIProvider(),
+ toolkit_versions={"github": "latest"}, # required for direct execution
+)
# Fetch specific tools
tools = composio.tools.get(
@@ -153,6 +156,7 @@ import { OpenAIProvider } from '@composio/openai';
const composio = new Composio({
apiKey: process.env.COMPOSIO_API_KEY,
provider: new OpenAIProvider(),
+ toolkitVersions: { github: 'latest' }, // required for direct execution
});
// Fetch specific tools
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 a20193eb5..b33126b2f 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
@@ -122,7 +122,10 @@ from composio import Composio, after_execute
from composio.types import ToolExecutionResponse
from composio_crewai import CrewAIProvider
-composio = Composio(provider=CrewAIProvider())
+composio = Composio(
+ provider=CrewAIProvider(),
+ toolkit_versions={"hackernews": "latest"},
+)
@after_execute(tools=["HACKERNEWS_GET_USER"])
def after_execute_modifier(
@@ -156,6 +159,7 @@ import { v4 as uuidv4 } from "uuid";
const composio = new Composio({
apiKey: process.env.COMPOSIO_API_KEY,
provider: new VercelProvider(),
+ toolkitVersions: { hackernews: "latest" },
});
const userId = uuidv4();
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 28927521a..ec3208fff 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
@@ -34,7 +34,7 @@ from openai import OpenAI
from composio import Composio, before_execute
from composio.types import ToolExecuteParams
-composio = Composio()
+composio = Composio(toolkit_versions={"hackernews": "latest"})
openai_client = OpenAI()
user_id = "[email protected]"
@@ -201,7 +201,7 @@ def audit_path(ctx) -> str | bool:
# return a new path string, or False to abort the upload
return ctx["path"]
-composio = Composio()
+composio = Composio(toolkit_versions={"googledrive": "latest"})
composio.tools.execute(
"GOOGLEDRIVE_UPLOAD_FILE",
{"file_to_upload": "/path/to/document.pdf"},
diff --git a/docs/tests/static/execute-version.test.ts b/docs/tests/static/execute-version.test.ts
new file mode 100644
index 000000000..383ec5494
--- /dev/null
+++ b/docs/tests/static/execute-version.test.ts
@@ -0,0 +1,116 @@
+/**
+ * Toolkit-version policy for direct-execution samples.
+ *
+ * Direct tool execution requires a toolkit version — `tools.execute()`
+ * without one raises ToolVersionRequiredError at runtime. A 97-run agent
+ * eval of the docs found the top failure (72/97 runs) was readers copying
+ * version-less `tools.execute()` samples.
+ *
+ * Rule: any authored MDX page whose code fences call `tools.execute(` must
+ * also show version configuration somewhere in its code fences — one of
+ * `toolkit_versions` / `toolkitVersions` (constructor), `version=` /
+ * `version:` (per-call), or a `COMPOSIO_TOOLKIT_VERSION_*` env var.
+ *
+ * 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).
+ * The LLM guardrail blocks appended to .md responses are checked too —
+ * they are samples agents copy verbatim.
+ */
+import { describe, test, expect } from "bun:test";
+import { readdir, readFile } from "fs/promises";
+import { join, relative } from "path";
+
+import {
+ SESSION_GUARDRAILS,
+ DIRECT_EXECUTION_GUARDRAILS,
+} from "../../lib/llm-guardrails";
+
+const CONTENT_DIRS = ["docs", "examples"].map((dir) =>
+ join(import.meta.dir, "../../content", dir),
+);
+const CONTENT_ROOT = join(import.meta.dir, "../../content");
+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/;
+
+async function findMdxFiles(dir: string): Promise<string[]> {
+ const results: string[] = [];
+ let entries;
+ try {
+ entries = await readdir(dir, { withFileTypes: true });
+ } catch {
+ return results;
+ }
+
+ for (const entry of entries) {
+ const fullPath = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ results.push(...(await findMdxFiles(fullPath)));
+ } else if (entry.name.endsWith(".mdx")) {
+ results.push(fullPath);
+ }
+ }
+ return results;
+}
+
+/** Concatenated contents of all fenced code blocks in a document. */
+function fencedCode(content: string): string {
+ const fences: string[] = [];
+ let inFence = false;
+ for (const line of content.split("\n")) {
+ if (/^\s*(```|~~~)/.test(line)) {
+ inFence = !inFence;
+ continue;
+ }
+ if (inFence) fences.push(line);
+ }
+ return fences.join("\n");
+}
+
+function violates(content: string): boolean {
+ const code = fencedCode(content);
+ return EXECUTE_CALL_RE.test(code) && !VERSION_TOKEN_RE.test(code);
+}
+
+describe("direct-execution samples show toolkit versions", () => {
+ test("every authored page with a tools.execute() sample shows version configuration", async () => {
+ const files = (
+ await Promise.all(CONTENT_DIRS.map((dir) => findMdxFiles(dir)))
+ ).flat();
+ const failures: string[] = [];
+
+ for (const file of files) {
+ const relPath = relative(CONTENT_ROOT, file);
+ if (EXCLUDED_PATH_SEGMENTS.some((seg) => relPath.startsWith(seg))) {
+ continue;
+ }
+ const content = await readFile(file, "utf-8");
+ if (violates(content)) {
+ failures.push(relPath);
+ }
+ }
+
+ 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` +
+ failures.map((f) => ` - ${f}`).join("\n"),
+ ).toEqual([]);
+ });
+
+ test("LLM guardrail blocks with tools.execute() samples show version configuration", () => {
+ for (const [name, guardrails] of [
+ ["SESSION_GUARDRAILS", SESSION_GUARDRAILS],
+ ["DIRECT_EXECUTION_GUARDRAILS", DIRECT_EXECUTION_GUARDRAILS],
+ ] as const) {
+ expect(
+ violates(guardrails),
+ `${name} contains a tools.execute() sample without version configuration`,
+ ).toBe(false);
+ }
+ });
+});