@devries-cameron20 / composio Mirror · read-only / commits / bcaeab47a
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, 23:30 UTC

docs: add guidance on when to use latest vs pinned toolkit versions

Replace the blanket "never use latest in production" advice with nuanced guidance: use `latest` when outputs are consumed by an LLM or agent (agentic), pin a version when outputs are parsed programmatically (schematic). Updated across 6 pages: - toolkit-versioning.mdx: new "Choosing between latest and a pinned version" section replaces the old warning - changelog: added "which default is right for you" to migration guide - common-faq.mdx: expanded toolkit versioning FAQ - sessions-vs-direct-execution.mdx: added version management row - executing-tools.mdx: added version strategy callout - creating-triggers.mdx: expanded trigger versioning note Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: rahul.lingala <rahul.lingala@composio.dev>

Zen Agent committed Apr 14, 2026 at 05:33 UTC bcaeab47a3d057935683b45de12f288a6b069a0d
6 files changed +24 -5
docs/content/changelog/04-08-26-v31-api.mdx
+2
@@ -40,6 +40,8 @@ Every non-tool endpoint (`/auth_configs`, `/connected_accounts`, `/triggers`, `/
40 2. If you depend on a specific pinned version, pass it explicitly — `version=00000000_00` for most endpoints, or `toolkit_versions=00000000_00` for `GET /tools` (see table above)
41 3. If you were already passing `version: "latest"` (or `toolkit_versions: "latest"`), you can drop the parameter entirely on v3.1
42
43 +**Which default is right for you?** If your application passes tool outputs to an LLM or AI agent, the v3.1 default (`latest`) is the better fit — agents interpret responses dynamically and benefit from always having the newest tools. If your code parses tool outputs programmatically (e.g., destructuring specific fields or mapping to a database schema), pin to a specific version so schema changes don't silently break your integration. See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version) for details.
44 +
45 **Before (v3):**
46 ```bash
47 curl "https://backend.composio.dev/api/v3/tools/GMAIL_SEND_EMAIL?version=latest" \
docs/content/docs/common-faq.mdx
+2
@@ -91,6 +91,8 @@ You can request new tools or toolkits on the [tool request board](https://reques
91 <Accordion title="How do I work with toolkit versions?">
92 Composio toolkits are versioned using date-based identifiers (e.g., `20251027_00`). You can pin versions at SDK initialization or per tool execution to keep behavior consistent across deployments.
93
94 +**When to use `latest` vs a pinned version:** Use `latest` when tool outputs and trigger payloads are consumed by an LLM or AI agent — agents adapt to response changes dynamically and benefit from always having the newest tools. Pin to a specific version when your code parses outputs programmatically (e.g., destructuring fields, mapping to a schema, or feeding into a typed pipeline).
95 +
96 This applies to direct tool execution only. Sessions with meta tools always use the latest version. See [Toolkit versioning](/docs/tools-direct/toolkit-versioning).
97 </Accordion>
98
docs/content/docs/sessions-vs-direct-execution.mdx
+1
@@ -19,6 +19,7 @@ Use sessions unless you need full control over which tools are available and whe
19 | **Auth** | [In-chat](/docs/authenticating-users/in-chat-authentication): agent prompts the user to connect when needed. Also supports [manual](/docs/authenticating-users/manually-authenticating) | You build the auth flow with [connect links](/docs/tools-direct/authenticating-tools) |
20 | **[Workbench](/docs/workbench)** | Built in, large responses offloaded automatically | Not available |
21 | **Human approval** | You configure approval rules on the session. Harder to intercept individual calls since tools are discovered dynamically | You intercept before each call in your code |
22 +| **Version management** | Always uses `latest` — ideal for agentic workflows where an LLM interprets outputs | You [choose the version](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version): `latest` for agent-consumed outputs, pinned for programmatic parsing |
23 | **Latency** | Multiple LLM turns (search, then execute) | Single call |
24
25 Sessions are configurable. You can [enable or disable specific toolkits](/docs/toolkits/enable-and-disable-toolkits), set [auth configs](/docs/auth-configuration/custom-auth-configs) for white-labeled OAuth, and pin specific [connected accounts](/docs/configuring-sessions#account-selection). See [Configuring Sessions](/docs/configuring-sessions) for the full list.
docs/content/docs/setting-up-triggers/creating-triggers.mdx
+1 -1
@@ -73,7 +73,7 @@ console.log(`Trigger created: ${trigger.triggerId}`);
73 </Tabs>
74
75 <Callout>
76 -The trigger instance uses the toolkit version configured during Composio initialization (defaults to `'latest'`). See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for details.
76 +Trigger instances default to `'latest'` toolkit version. This is the recommended setting for most use cases — trigger payloads are typically consumed by an LLM or agent that adapts to response changes dynamically. If your code parses trigger payloads programmatically against a fixed schema, you can pin a specific version at SDK initialization. See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version) for details.
77 </Callout>
78
79 ## Using the dashboard
docs/content/docs/tools-direct/executing-tools.mdx
+4
@@ -246,6 +246,10 @@ console.log('GitHub stargazers:', JSON.stringify(result, null, 2));
246 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.
247 </Callout>
248
249 +<Callout type="info">
250 +**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).
251 +</Callout>
252 +
253 ### Proxy Execute
254
255 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
+14 -4
@@ -136,17 +136,27 @@ Versions follow the format `YYYYMMDD_NN`:
136 - `NN`: Sequential release number
137
138 ```python
139 -# Production — pin to a specific version
139 +# Pin to a specific version
140 toolkit_versions = {"github": "20251027_00"}
141
142 -# Development — always use the newest tools
142 +# Always use the newest tools
143 toolkit_versions = {"github": "latest"}
144 ```
145
146 -<Callout type="warn">
147 -Never use `latest` in production. It can introduce breaking changes. Pin to a specific version instead.
146 +## Choosing between `latest` and a pinned version
147 +
148 +The right choice depends on how your application consumes tool outputs:
149 +
150 +- **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.
151 +
152 +- **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.
153 +
154 +<Callout type="info">
155 +As a rule of thumb: if an LLM reads the output, use `latest`. If your code parses the output, pin the version.
156 </Callout>
157
158 +Most agentic applications — including all [session-based](/docs/configuring-sessions) workflows — use `latest` by default and benefit from always having the most up-to-date tools. If you're building structured data pipelines or integrations with fixed response parsing, pin to a tested version and upgrade on your own schedule.
159 +
160 ## Version resolution order
161
162 1. Per-execution version (highest priority)