@devries-cameron20 / composio-1 / commits / 8b07933f8
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 per-call tool version pinning easier to find (#4803)

## Summary Developers had to look below SDK-wide configuration and `latest` examples to find the `version` argument on `composio.tools.execute()`. The execution and toolkit versioning guides now lead with complete per-call pinning examples in TypeScript and Python, explain override precedence, and link to available versions. Closes [DEVREL-203](https://linear.app/composio/issue/DEVREL-203/make-per-call-tool-version-pinning-visible-in-sdk-docs). The issue records the source screenshot of Alberto's example and Karan's request to make it easier to find. ## Changes - Add a direct link to the pinned-version example near the top of the execution guide. - Put per-call pinning before `latest` and SDK-wide configuration, while retaining the existing section anchors. - Clarify that a per-call version leaves other calls' defaults unchanged. Keep the `latest` opt-in and sessions guidance. ## Type of change - [x] Documentation ## How Has This Been Tested? - `bun run test`: 626 tests passed. - `bun run lint`: passed with existing warnings in unchanged files. - `bun run lint:links`: no errors. - `bun run types:check`: passed. - `bun run check:kb-semantic --allow-stale`: passed with the expected content-hash freshness warning. - Parsed all 16 Python snippets in the two pages with `ast.parse`. - `bun run build`: passed, including Twoslash validation; existing file-tracing warnings remain. - `bun run test:integration`: 93 passed, 1 skipped because `COMPOSIO_API_KEY` is unavailable. - Both changed HTML and `.md` endpoints returned successfully; verified the pinning anchors and both languages in Markdown. - `pnpm validate:agent-skills` and `pnpm validate:skill-routing`: passed. - `git diff --check`: passed. No new runtime tests or changeset are needed for this docs-only change. Verified version precedence against both SDK implementations. ## Screenshots Visual inspection could not be completed: the collaborative browser's localhost automation failed, and the private VM preview requires exe.dev authentication. No screenshot is attached. ## Checklist - [x] Read and reviewed the full diff. - [x] Ran documentation checks locally. - [x] Updated documentation. - [x] No new third-party links or runtime behavior changes.

Brendan O'Leary committed Oct 12, 2026 at 13:08 UTC 8b07933f85856c2efa62273369609732455ed787
2 files changed +102 -99
docs/content/docs/tools-direct/executing-tools.mdx
+51 -54
@@ -1,7 +1,7 @@
1 ---
2 title: Executing tools directly
3 description: Maintain legacy integrations that call composio.tools.execute(); prefer sessions for new integrations
4 -keywords: [execute, run, tool calling, function calling, direct execution]
4 +keywords: [execute, run, tool calling, function calling, direct execution, version, pin version]
5 llmGuardrails: "direct-execution"
6 legacy: true
7 ---
@@ -14,6 +14,8 @@ LLMs on their own can only do generation. Tool calling changes that by letting t
14
15 In Composio, every **tool** is a single API action—fully described with schema, parameters, and return type. Tools live inside **toolkits** like Gmail, Slack, or GitHub, and Composio handles authentication and user scoping.
16
17 +To run a specific tool version, pass `version` directly to `composio.tools.execute()`. See [Pin a version](#pin-a-version) for complete Python and TypeScript examples.
18 +
19 ## Canceling TypeScript requests
20
21 TypeScript SDK methods accept an `AbortSignal` in their trailing request options. Aborted requests throw `ComposioRequestCancelledError`, so cancellation can be handled separately from execution failures:
@@ -227,26 +229,24 @@ See [toolkit versioning](/docs/tools-direct/toolkit-versioning) for the full tra
229 **CLI**: For Python and TypeScript projects, run `composio generate` to generate types. [Learn more →](/docs/cli#generate-type-definitions)
230 </Callout>
231
232 +### Pin a version
233 +
234 +Pass `version` on the `tools.execute()` call to select a specific tool version. This overrides SDK initialization and environment defaults for that call without changing other executions.
235 +
236 +Choose an available version from the [GitHub toolkit page](/toolkits/github) or [look it up with the SDK](/docs/tools-direct/toolkit-versioning#managing-versions). The examples below use `20250909_00`. Replace it with the version you have tested, and keep that string in your code or configuration.
237 +
238 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
239 <Tab value="Python">
240 ```python
241 from composio import Composio
242
235 -user_id = "user-k7334"
236 -# Configure toolkit versions at SDK level for every toolkit you execute.
237 -# Use "latest", or pin a version (see "Pin a version" below)
238 -composio = Composio(
239 - api_key="your_composio_key",
240 - toolkit_versions={"github": "latest"}
241 -)
243 +composio = Composio(api_key="your_composio_key")
244
243 -# Find available arguments for any tool in the Composio dashboard
245 result = composio.tools.execute(
246 "GITHUB_LIST_STARGAZERS",
246 - user_id=user_id,
247 + user_id="user-k7334",
248 + version="20250909_00",
249 arguments={"owner": "ComposioHQ", "repo": "composio", "page": 1, "per_page": 5},
248 - # "latest" requires this opt-in; to pin instead, pass version (see "Pin a version" below)
249 - dangerously_skip_version_check=True,
250 )
251 print(result)
252 ```
@@ -255,80 +255,77 @@ print(result)
255 ```typescript
256 import { Composio } from "@composio/core";
257
258 -const userId = "user-k7334";
259 -// Configure toolkit versions at SDK level for every toolkit you execute.
260 -// Use "latest", or pin a version (see "Pin a version" below)
261 -const composio = new Composio({
262 - apiKey: "your_composio_key",
263 - toolkitVersions: { github: "latest" }
264 -});
258 +const composio = new Composio({ apiKey: "your_composio_key" });
259
266 -// Find available arguments for any tool in the Composio dashboard
260 const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
268 - userId,
269 - arguments: {
270 - "owner": "ComposioHQ",
271 - "repo": "composio",
272 - "page": 1,
273 - "per_page": 5
274 - },
275 - // "latest" requires this opt-in; to pin instead, pass `version` (see "Pin a version" below)
276 - dangerouslySkipVersionCheck: true,
261 + userId: "user-k7334",
262 + version: "20250909_00",
263 + arguments: { owner: "ComposioHQ", repo: "composio", page: 1, per_page: 5 },
264 });
278 -console.log('GitHub stargazers:', JSON.stringify(result, null, 2));
265 +console.log(result);
266 ```
267 </Tab>
268 </Tabs>
269
283 -### Pin a version
270 +A dated `version` satisfies the direct-execution version check. To set a default for all calls to a toolkit, configure [SDK initialization or environment variables](/docs/tools-direct/toolkit-versioning#configuration-methods).
271 +
272 +### Use the latest version
273
285 -When your code parses tool outputs, look up the current version once, then pass that dated string as `version` on every call. Hard-code the string (or keep it in config) rather than looking it up at runtime, so a new release can't change the output shape without you noticing.
274 +If an LLM consumes the output and can handle schema changes, you can use `latest`. Direct execution requires the explicit opt-in shown below.
275
276 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
277 <Tab value="Python">
278 ```python
279 from composio import Composio
280
292 -composio = Composio(api_key="your_composio_key")
293 -
294 -# One-off lookup: prints something like "20250909_00"
295 -print(composio.toolkits.get(slug="github").meta.version)
281 +user_id = "user-k7334"
282 +# Configure toolkit versions at SDK level for every toolkit you execute.
283 +# Use "latest", or pin a version (see "Pin a version" above)
284 +composio = Composio(
285 + api_key="your_composio_key",
286 + toolkit_versions={"github": "latest"}
287 +)
288
289 +# Find available arguments for any tool in the Composio dashboard
290 result = composio.tools.execute(
291 "GITHUB_LIST_STARGAZERS",
299 - user_id="user-k7334",
300 - version="20250909_00",
292 + user_id=user_id,
293 arguments={"owner": "ComposioHQ", "repo": "composio", "page": 1, "per_page": 5},
294 + # "latest" requires this opt-in; to pin instead, pass version (see "Pin a version" above)
295 + dangerously_skip_version_check=True,
296 )
297 +print(result)
298 ```
299 </Tab>
300 <Tab value="TypeScript">
301 ```typescript
302 import { Composio } from "@composio/core";
303
309 -const composio = new Composio({ apiKey: "your_composio_key" });
310 -
311 -// One-off lookup: prints something like "20250909_00"
312 -const tool = await composio.tools.getRawComposioToolBySlug("GITHUB_LIST_STARGAZERS");
313 -console.log(tool.version);
304 +const userId = "user-k7334";
305 +// Configure toolkit versions at SDK level for every toolkit you execute.
306 +// Use "latest", or pin a version (see "Pin a version" above)
307 +const composio = new Composio({
308 + apiKey: "your_composio_key",
309 + toolkitVersions: { github: "latest" }
310 +});
311
312 +// Find available arguments for any tool in the Composio dashboard
313 const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
316 - userId: "user-k7334",
317 - version: "20250909_00",
318 - arguments: { owner: "ComposioHQ", repo: "composio", page: 1, per_page: 5 },
314 + userId,
315 + arguments: {
316 + "owner": "ComposioHQ",
317 + "repo": "composio",
318 + "page": 1,
319 + "per_page": 5
320 + },
321 + // "latest" requires this opt-in; to pin instead, pass `version` (see "Pin a version" above)
322 + dangerouslySkipVersionCheck: true,
323 });
324 +console.log('GitHub stargazers:', JSON.stringify(result, null, 2));
325 ```
326 </Tab>
327 </Tabs>
328
324 -<Callout>
325 -The examples above configure toolkit versions at SDK initialization. You can also pass versions per-execution or use environment variables. See [toolkit versioning](/docs/tools-direct/toolkit-versioning) for all configuration options.
326 -</Callout>
327 -
328 -<Callout type="info">
329 -**Choosing a version strategy:** Use `latest` when tool outputs are consumed by an LLM or AI agent — agents adapt to schema changes dynamically. Pin to a specific version when your code parses outputs programmatically. See [choosing between `latest` and a pinned version](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version).
330 -</Callout>
331 -
329 ### Proxy Execute
330
331 You can proxy requests to any supported toolkit API and let Composio inject the authentication state. This is useful when you need an API endpoint that isn't available as a predefined tool.
docs/content/docs/tools-direct/toolkit-versioning.mdx
+51 -45
@@ -1,7 +1,7 @@
1 ---
2 title: Toolkit Versioning
3 -description: Pin specific tool versions for consistent behavior in production
4 -keywords: [version, pin version, tool versioning]
3 +description: Pin a tool version per execute call or configure defaults for consistent behavior in production
4 +keywords: [version, pin version, tool versioning, tools.execute, per-execution override]
5 llmGuardrails: "direct-execution"
6 legacy: true
7 ---
@@ -12,6 +12,54 @@ If you're building an agent, we recommend using [sessions](/docs/configuring-ses
12
13 Toolkit versioning ensures your tools behave consistently across deployments. You can pin specific versions in production, test new releases in development, and roll back when needed.
14
15 +## Per-execution override
16 +
17 +Pass `version` directly to `composio.tools.execute()` to pin one call. The per-call value takes precedence over SDK initialization and environment variables, and leaves the defaults for other calls unchanged.
18 +
19 +These examples use `20251027_00`. Replace it with an available version you have tested for your toolkit.
20 +
21 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
22 + <Tab value="Python">
23 +```python
24 +from composio import Composio
25 +
26 +composio = Composio(api_key="YOUR_API_KEY")
27 +
28 +result = composio.tools.execute(
29 + "GITHUB_LIST_STARGAZERS",
30 + arguments={
31 + "owner": "ComposioHQ",
32 + "repo": "composio"
33 + },
34 + user_id="user-k7334",
35 + version="20251027_00",
36 +)
37 +print(result)
38 +```
39 + </Tab>
40 + <Tab value="TypeScript">
41 +```typescript
42 +import { Composio } from "@composio/core";
43 +
44 +const composio = new Composio({ apiKey: "YOUR_API_KEY" });
45 +
46 +const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
47 + userId: "user-k7334",
48 + version: "20251027_00",
49 + arguments: {
50 + owner: "ComposioHQ",
51 + repo: "composio"
52 + }
53 +});
54 +console.log(result);
55 +```
56 + </Tab>
57 +</Tabs>
58 +
59 +A dated version passes the direct-execution version check without a bypass flag. See [Direct Tool Execution](/docs/tools-direct/executing-tools#direct-tool-execution) for more examples.
60 +
61 +## Find available versions
62 +
63 To view available versions, go to [Dashboard](https://dashboard.composio.dev?utm_source=docs&utm_medium=content&utm_campaign=docs-tools-direct-toolkit-versioning) > **All Toolkits** > select a toolkit. The version dropdown shows the latest and all available versions:
64
65 ![Toolkit version selector on the Composio dashboard](/images/toolkit-version-dashboard.png)
@@ -42,7 +90,7 @@ curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=googledrive&toolkit
90
91 ## Configuration methods
92
45 -Configure toolkit versions using one of three methods:
93 +To use the same version across calls, set a default at SDK initialization or through environment variables. A [per-execution override](#per-execution-override) takes precedence over either default.
94
95 ### SDK initialization
96
@@ -88,48 +136,6 @@ export COMPOSIO_TOOLKIT_VERSION_SLACK="20251027_00"
136 export COMPOSIO_TOOLKIT_VERSION_GMAIL="20251027_00"
137 ```
138
91 -### Per-execution override
92 -
93 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
94 - <Tab value="Python">
95 -```python
96 -from composio import Composio
97 -
98 -composio = Composio(api_key="YOUR_API_KEY")
99 -
100 -# Specify version directly in execute call
101 -result = composio.tools.execute(
102 - "GITHUB_LIST_STARGAZERS",
103 - arguments={
104 - "owner": "ComposioHQ",
105 - "repo": "composio"
106 - },
107 - user_id="user-k7334",
108 - version="20251027_00" # Override version for this execution
109 -)
110 -print(result)
111 -```
112 - </Tab>
113 - <Tab value="TypeScript">
114 -```typescript
115 -import { Composio } from "@composio/core";
116 -
117 -const composio = new Composio({ apiKey: "YOUR_API_KEY" });
118 -
119 -// Specify version directly in execute call
120 -const result = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
121 - userId: "user-k7334",
122 - arguments: {
123 - owner: "ComposioHQ",
124 - repo: "composio"
125 - },
126 - version: "20251027_00" // Override version for this execution
127 -});
128 -console.log(result);
129 -```
130 - </Tab>
131 -</Tabs>
132 -
139 ## Version format
140
141 Versions follow the format `YYYYMMDD_NN`: