Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
versioning docs
Sushmithamallesh committed
Oct 25, 2025 at 09:07 UTC
e5e9a7446ea96cfe9901d72ea659f87006565826
20 files changed
+1225
-3
fern/pages/src/migration-guide.mdx
+88
-1
@@ -205,6 +205,93 @@ To examine the raw schema definition of a tool for understanding input/output pa
205
/>
206
</CodeGroup>
207
208
+### Toolkit versioning
209
+
210
+As of October 22, 2025, Composio enforces toolkit versioning to ensure consistent tool behavior across environments. This is a breaking change for manual tool execution.
211
+
212
+#### Version requirement for manual execution
213
+
214
+Manual tool execution now requires explicit version specification:
215
+
216
+<CodeGroup>
217
+```python Python
218
+# Will fail without version (breaking change)
219
+result = composio.tools.execute(
220
+ "GITHUB_CREATE_ISSUE",
221
+ {"user_id": "user-123", "arguments": {...}}
222
+)
223
+
224
+# Option 1: Configure version at SDK level
225
+composio = Composio(
226
+ api_key="YOUR_API_KEY",
227
+ toolkit_versions={"github": "20250116_00"}
228
+)
229
+
230
+# Option 2: Pass version with execution
231
+result = composio.tools.execute(
232
+ "GITHUB_CREATE_ISSUE",
233
+ {
234
+ "user_id": "user-123",
235
+ "arguments": {...},
236
+ "toolkit_version": "20250116_00"
237
+ }
238
+)
239
+
240
+# Option 3: Skip version check (not recommended)
241
+result = composio.tools.execute(
242
+ "GITHUB_CREATE_ISSUE",
243
+ {
244
+ "user_id": "user-123",
245
+ "arguments": {...},
246
+ "dangerously_skip_version_check": True
247
+ }
248
+)
249
+```
250
+
251
+```typescript TypeScript
252
+// Will fail without version (breaking change)
253
+const result = await composio.tools.execute({
254
+ toolSlug: "GITHUB_CREATE_ISSUE",
255
+ userId: "user-123",
256
+ arguments: {...}
257
+});
258
+
259
+// Option 1: Configure version at SDK level
260
+const composio = new Composio({
261
+ apiKey: "YOUR_API_KEY",
262
+ toolkitVersions: { github: "20250116_00" }
263
+});
264
+
265
+// Option 2: Pass version with execution
266
+const result = await composio.tools.execute({
267
+ toolSlug: "GITHUB_CREATE_ISSUE",
268
+ userId: "user-123",
269
+ arguments: {...},
270
+ toolkitVersion: "20250116_00"
271
+});
272
+
273
+// Option 3: Skip version check (not recommended)
274
+const result = await composio.tools.execute({
275
+ toolSlug: "GITHUB_CREATE_ISSUE",
276
+ userId: "user-123",
277
+ arguments: {...},
278
+ dangerouslySkipVersionCheck: true
279
+});
280
+```
281
+</CodeGroup>
282
+
283
+#### Migration steps
284
+
285
+1. **Audit your code**: Find all `tools.execute()` calls
286
+2. **Choose a strategy**:
287
+ - Set toolkit versions globally in SDK initialization (recommended)
288
+ - Add version parameter to each execute call
289
+ - Use environment variables for deployment configuration
290
+3. **Test thoroughly**: Verify tools work with pinned versions
291
+4. **Deploy gradually**: Roll out changes incrementally
292
+
293
+For complete documentation, see [Toolkit versioning](/tool-calling/toolkit-versioning).
294
+
295
### Executing tools
296
297
Tool execution remains largely unchanged, with `user_id` now explicitly required.
@@ -586,7 +673,7 @@ For development, you can also [listen to triggers through the SDK](/docs/using-t
673
/>
674
</CodeGroup>
675
589
-## 🚧 Coming Soon
676
+## Coming Soon
677
678
### Local tools
679
fern/pages/src/tool-calling/executing-tools.mdx
+72
-2
@@ -58,14 +58,84 @@ Composio provides support for frameworks like this by making sure the tools are
58
59
In case you just want to call a tool without using any framework or LLM provider, you can use the `execute` method directly.
60
61
+<Warning>
62
+As of October 22, 2025, manual tool execution requires explicit version specification. Either configure toolkit versions in your SDK initialization or pass the version with each execution. See [toolkit versioning](/tool-calling/toolkit-versioning) for details.
63
+</Warning>
64
+
65
<Tip icon="lightbulb">
66
**Finding tool arguments**: In the [Auth Configs
67
tab](https://platform.composio.dev?next_page=/auth-configs) → Select your toolkit → Tools &
68
Triggers → Select the tool to see its required and optional parameters, types, and descriptions.
69
</Tip>
70
+
71
<CodeGroup>
67
- <SnippetCode src="fern/snippets/tool-calling/python/direct-tool-call.py" title="Python" />
68
- <SnippetCode src="fern/snippets/tool-calling/typescript/direct-tool-call.ts" title="TypeScript" />
72
+```python Python
73
+# Method 1: Configure version at SDK level
74
+composio = Composio(
75
+ api_key="YOUR_API_KEY",
76
+ toolkit_versions={"github": "20250116_00"}
77
+)
78
+
79
+result = composio.tools.execute(
80
+ "GITHUB_CREATE_ISSUE",
81
+ {
82
+ "user_id": "user-123",
83
+ "arguments": {
84
+ "repo": "composio",
85
+ "owner": "composiohq",
86
+ "title": "Bug Report",
87
+ "body": "Issue description"
88
+ }
89
+ }
90
+)
91
+
92
+# Method 2: Pass version with execution
93
+result = composio.tools.execute(
94
+ "GITHUB_CREATE_ISSUE",
95
+ {
96
+ "user_id": "user-123",
97
+ "arguments": {
98
+ "repo": "composio",
99
+ "owner": "composiohq",
100
+ "title": "Bug Report",
101
+ "body": "Issue description"
102
+ },
103
+ "toolkit_version": "20250116_00"
104
+ }
105
+)
106
+```
107
+
108
+```typescript TypeScript
109
+// Method 1: Configure version at SDK level
110
+const composio = new Composio({
111
+ apiKey: "YOUR_API_KEY",
112
+ toolkitVersions: { github: "20250116_00" }
113
+});
114
+
115
+const result = await composio.tools.execute({
116
+ toolSlug: "GITHUB_CREATE_ISSUE",
117
+ userId: "user-123",
118
+ arguments: {
119
+ repo: "composio",
120
+ owner: "composiohq",
121
+ title: "Bug Report",
122
+ body: "Issue description"
123
+ }
124
+});
125
+
126
+// Method 2: Pass version with execution
127
+const result = await composio.tools.execute({
128
+ toolSlug: "GITHUB_CREATE_ISSUE",
129
+ userId: "user-123",
130
+ arguments: {
131
+ repo: "composio",
132
+ owner: "composiohq",
133
+ title: "Bug Report",
134
+ body: "Issue description"
135
+ },
136
+ toolkitVersion: "20250116_00"
137
+});
138
+```
139
</CodeGroup>
140
141
### Proxy Execute -- Manually calling toolkit APIs
fern/pages/src/tool-calling/fetching-tools.mdx
+52
@@ -94,6 +94,58 @@ const tools = await composio.tools.get(userId, {
94
```
95
</CodeGroup>
96
97
+## Fetching versioned tools
98
+
99
+Control which version of tools you fetch by specifying toolkit versions. This ensures consistent tool behavior across different environments.
100
+
101
+<CodeGroup>
102
+```python Python maxLines=60 wordWrap
103
+# Fetch tools with specific versions
104
+composio = Composio(
105
+ api_key="YOUR_API_KEY",
106
+ toolkit_versions={
107
+ "github": "20250116_00",
108
+ "slack": "20250115_01"
109
+ }
110
+)
111
+
112
+tools = composio.tools.get(
113
+ user_id,
114
+ toolkits=["GITHUB", "SLACK"]
115
+)
116
+
117
+# Inspect tool version
118
+for tool in tools:
119
+ print(f"Tool: {tool.slug}")
120
+ print(f"Version: {tool.toolkit_version}")
121
+```
122
+
123
+```typescript TypeScript maxLines=60 wordWrap
124
+// Fetch tools with specific versions
125
+const composio = new Composio({
126
+ apiKey: "YOUR_API_KEY",
127
+ toolkitVersions: {
128
+ github: "20250116_00",
129
+ slack: "20250115_01"
130
+ }
131
+});
132
+
133
+const tools = await composio.tools.get(userId, {
134
+ toolkits: ["GITHUB", "SLACK"]
135
+});
136
+
137
+// Inspect tool version
138
+tools.forEach(tool => {
139
+ console.log(`Tool: ${tool.slug}`);
140
+ console.log(`Version: ${tool.toolkitVersion}`);
141
+});
142
+```
143
+</CodeGroup>
144
+
145
+<Note>
146
+Tools fetched with specific versions will maintain consistent schemas and behavior. Learn more about [toolkit versioning](/tool-calling/toolkit-versioning).
147
+</Note>
148
+
149
## Filtering by tool
150
You may specify the list of tools to fetch by directly providing the tool names. Browse the list of tools [here](/tools) to view and inspect the tools for each toolkit.
151
fern/pages/src/tool-calling/toolkit-versioning.mdx
new
+304
@@ -0,0 +1,304 @@
1
+---
2
+title: Toolkit versioning
3
+image: "https://og.composio.dev/api/og?title=Toolkit%20versioning"
4
+keywords: "toolkit versioning, tool version, version pinning, stable tools"
5
+subtitle: "Pin specific tool versions for consistent, predictable behavior in production"
6
+hide-nav-links: false
7
+---
8
+
9
+Toolkit versioning ensures your tools behave consistently across deployments. You can pin specific versions in production, test new releases in development, and roll back easily when needed.
10
+
11
+## Quick start
12
+
13
+Configure toolkit versions using one of three methods, listed in order of precedence:
14
+
15
+### Method 1: SDK initialization (Recommended)
16
+
17
+Set versions when initializing the SDK. This applies to all tool operations.
18
+
19
+<CodeGroup>
20
+<SnippetCode
21
+ src="fern/snippets/tool-calling/versioning/python/sdk-initialization.py"
22
+ title="Python"
23
+ startLine={1}
24
+ endLine={16}
25
+/>
26
+<SnippetCode
27
+ src="fern/snippets/tool-calling/versioning/typescript/sdk-initialization.ts"
28
+ title="TypeScript"
29
+ startLine={1}
30
+ endLine={15}
31
+/>
32
+</CodeGroup>
33
+
34
+### Method 2: Environment variables
35
+
36
+Set toolkit versions through environment variables. Useful for deployment configurations.
37
+
38
+```bash
39
+# Set versions for specific toolkits
40
+export COMPOSIO_TOOLKIT_VERSION_GITHUB="20250116_00"
41
+export COMPOSIO_TOOLKIT_VERSION_SLACK="20250115_01"
42
+
43
+# Or set one version for all toolkits
44
+export COMPOSIO_TOOLKIT_VERSION="20250116_00"
45
+```
46
+
47
+<CodeGroup>
48
+<SnippetCode
49
+ src="fern/snippets/tool-calling/versioning/python/environment-variables.py"
50
+ title="Python"
51
+ startLine={11}
52
+ endLine={18}
53
+/>
54
+<SnippetCode
55
+ src="fern/snippets/tool-calling/versioning/typescript/environment-variables.ts"
56
+ title="TypeScript"
57
+ startLine={11}
58
+ endLine={18}
59
+/>
60
+</CodeGroup>
61
+
62
+### Method 3: Per-execution override
63
+
64
+Override versions for specific tool executions. Takes precedence over SDK and environment settings.
65
+
66
+<CodeGroup>
67
+<SnippetCode
68
+ src="fern/snippets/tool-calling/versioning/python/per-execution-override.py"
69
+ title="Python"
70
+ startLine={11}
71
+ endLine={21}
72
+/>
73
+<SnippetCode
74
+ src="fern/snippets/tool-calling/versioning/typescript/per-execution-override.ts"
75
+ title="TypeScript"
76
+ startLine={11}
77
+ endLine={19}
78
+/>
79
+</CodeGroup>
80
+
81
+## Version formats
82
+
83
+### Version identifiers
84
+
85
+Toolkit versions follow the format `YYYYMMDD_NN`:
86
+- `YYYYMMDD`: Release date
87
+- `NN`: Sequential release number for that day
88
+
89
+```python
90
+# Production: Use specific version
91
+toolkit_versions = {
92
+ "github": "20250116_00" # Released January 16, 2025, first version
93
+}
94
+
95
+# Development: Use latest
96
+toolkit_versions = {
97
+ "github": "latest" # Always use newest version
98
+}
99
+```
100
+
101
+### Version resolution
102
+
103
+Versions are resolved in this order:
104
+1. **Per-execution version** (if specified)
105
+2. **SDK initialization version** (if configured)
106
+3. **Environment variable** for specific toolkit
107
+4. **Global environment variable** (applies to all)
108
+5. **Default**: `latest`
109
+
110
+<Warning>
111
+Never use `latest` in production. It can introduce breaking changes without warning.
112
+</Warning>
113
+
114
+## Configuration patterns
115
+
116
+### Multi-environment setup
117
+
118
+Manage different versions across development, staging, and production environments:
119
+
120
+<CodeGroup>
121
+<SnippetCode
122
+ src="fern/snippets/tool-calling/versioning/python/multi-environment.py"
123
+ title="Python"
124
+/>
125
+<SnippetCode
126
+ src="fern/snippets/tool-calling/versioning/typescript/multi-environment.ts"
127
+ title="TypeScript"
128
+/>
129
+</CodeGroup>
130
+
131
+### CI/CD pipeline
132
+
133
+```yaml
134
+# .github/workflows/deploy.yml
135
+env:
136
+ COMPOSIO_TOOLKIT_VERSION_GITHUB: "20250110_00"
137
+ COMPOSIO_TOOLKIT_VERSION_SLACK: "20250110_00"
138
+ COMPOSIO_TOOLKIT_VERSION_GMAIL: "20250109_00"
139
+```
140
+
141
+## Managing versions
142
+
143
+### List available versions
144
+
145
+<CodeGroup>
146
+<SnippetCode
147
+ src="fern/snippets/tool-calling/versioning/python/list-versions.py"
148
+ title="Python"
149
+ startLine={5}
150
+ endLine={14}
151
+/>
152
+<SnippetCode
153
+ src="fern/snippets/tool-calling/versioning/typescript/list-versions.ts"
154
+ title="TypeScript"
155
+ startLine={5}
156
+ endLine={14}
157
+/>
158
+</CodeGroup>
159
+
160
+### Test new versions
161
+
162
+Test updates in isolated environments before production deployment:
163
+
164
+<CodeGroup>
165
+<SnippetCode
166
+ src="fern/snippets/tool-calling/versioning/python/test-new-version.py"
167
+ title="Python"
168
+ startLine={4}
169
+ endLine={29}
170
+/>
171
+<SnippetCode
172
+ src="fern/snippets/tool-calling/versioning/typescript/test-new-version.ts"
173
+ title="TypeScript"
174
+ startLine={3}
175
+ endLine={40}
176
+/>
177
+</CodeGroup>
178
+
179
+### Roll back versions
180
+
181
+If issues arise, immediately revert to a previous stable version:
182
+
183
+<CodeGroup>
184
+<SnippetCode
185
+ src="fern/snippets/tool-calling/versioning/python/rollback.py"
186
+ title="Python"
187
+ startLine={4}
188
+ endLine={22}
189
+/>
190
+<SnippetCode
191
+ src="fern/snippets/tool-calling/versioning/typescript/rollback.ts"
192
+ title="TypeScript"
193
+ startLine={3}
194
+ endLine={22}
195
+/>
196
+</CodeGroup>
197
+
198
+## Breaking changes
199
+
200
+### Manual execution requires version
201
+
202
+As of October 22, 2025, manual tool execution requires explicit version specification:
203
+
204
+<CodeGroup>
205
+<SnippetCode
206
+ src="fern/snippets/tool-calling/versioning/python/breaking-changes.py"
207
+ title="Python"
208
+ startLine={21}
209
+ endLine={61}
210
+/>
211
+<SnippetCode
212
+ src="fern/snippets/tool-calling/versioning/typescript/breaking-changes.ts"
213
+ title="TypeScript"
214
+ startLine={20}
215
+ endLine={54}
216
+/>
217
+</CodeGroup>
218
+
219
+<Warning>
220
+The `dangerouslySkipVersionCheck` flag bypasses version validation. Use only during migration or debugging.
221
+</Warning>
222
+
223
+### Migration checklist
224
+
225
+1. **Audit current usage**: Identify all `tools.execute()` calls
226
+2. **Choose strategy**:
227
+ - Set toolkit versions in SDK initialization (recommended)
228
+ - Add version parameter to each execute call
229
+ - Use environment variables for deployment config
230
+3. **Test in staging**: Verify tools work with pinned versions
231
+4. **Deploy gradually**: Roll out to production incrementally
232
+5. **Monitor errors**: Watch for version-related failures
233
+
234
+## Best practices
235
+
236
+### Version pinning strategy
237
+
238
+```python
239
+# Development: Latest for rapid iteration
240
+dev_versions = {"github": "latest", "slack": "latest"}
241
+
242
+# Staging: Test specific new versions
243
+staging_versions = {"github": "20250116_00", "slack": "20250115_00"}
244
+
245
+# Production: Pin stable versions
246
+prod_versions = {"github": "20250110_00", "slack": "20250110_00"}
247
+```
248
+
249
+### Update workflow
250
+
251
+1. **Development**: Test with `latest`
252
+2. **Staging**: Pin specific version for testing
253
+3. **Validation**: Run automated tests
254
+4. **Production**: Deploy tested version
255
+5. **Monitor**: Track errors and performance
256
+
257
+
258
+## Reference
259
+
260
+### SDK parameters
261
+
262
+<CodeGroup>
263
+```python Python
264
+Composio(
265
+ api_key="YOUR_API_KEY",
266
+ toolkit_versions={
267
+ "toolkit_name": "version" # Dict[str, str]
268
+ }
269
+)
270
+```
271
+
272
+```typescript TypeScript
273
+new Composio({
274
+ apiKey: "YOUR_API_KEY",
275
+ toolkitVersions: {
276
+ toolkitName: "version" // Record<string, string>
277
+ }
278
+})
279
+```
280
+</CodeGroup>
281
+
282
+### Environment variables
283
+
284
+```bash
285
+# Specific toolkit version
286
+COMPOSIO_TOOLKIT_VERSION_[TOOLKIT_NAME]="version"
287
+
288
+# Global version (all toolkits)
289
+COMPOSIO_TOOLKIT_VERSION="version"
290
+
291
+# Examples
292
+COMPOSIO_TOOLKIT_VERSION_GITHUB="20250116_00"
293
+COMPOSIO_TOOLKIT_VERSION_SLACK="20250115_01"
294
+COMPOSIO_TOOLKIT_VERSION="20250110_00"
295
+```
296
+
297
+### Error codes
298
+
299
+| Error | Description | Solution |
300
+|-------|-------------|----------|
301
+| `TOOLKIT_VERSION_REQUIRED` | Manual execution without version | Specify toolkit_version parameter |
302
+| `INVALID_TOOLKIT_VERSION` | Version format incorrect | Use YYYYMMDD_NN format |
303
+| `VERSION_NOT_FOUND` | Specified version doesn't exist | Check available versions |
304
+| `TOOLKIT_NOT_VERSIONED` | Toolkit doesn't support versioning | Contact support |
fern/snippets/tool-calling/versioning/python/breaking-changes.py
new
+66
@@ -0,0 +1,66 @@
1
+from composio import Composio
2
+
3
+composio = Composio(api_key="YOUR_API_KEY")
4
+
5
+# ❌ This will fail without version specification (after October 22, 2025)
6
+try:
7
+ result = composio.tools.execute(
8
+ "GITHUB_CREATE_ISSUE",
9
+ {
10
+ "user_id": "user-123",
11
+ "arguments": {
12
+ "repo": "my-repo",
13
+ "title": "Bug report",
14
+ "body": "Issue description"
15
+ }
16
+ }
17
+ )
18
+except Exception as e:
19
+ print(f"Error: {e}")
20
+ print("Manual execution requires toolkit version")
21
+
22
+# ✅ Solution 1: Specify version in execution
23
+result = composio.tools.execute(
24
+ "GITHUB_CREATE_ISSUE",
25
+ {
26
+ "user_id": "user-123",
27
+ "arguments": {
28
+ "repo": "my-repo",
29
+ "title": "Bug report",
30
+ "body": "Issue description"
31
+ },
32
+ "toolkit_version": "20250116_00"
33
+ }
34
+)
35
+
36
+# ✅ Solution 2: Configure version at SDK level
37
+composio_with_version = Composio(
38
+ api_key="YOUR_API_KEY",
39
+ toolkit_versions={"github": "20250116_00"}
40
+)
41
+
42
+result = composio_with_version.tools.execute(
43
+ "GITHUB_CREATE_ISSUE",
44
+ {
45
+ "user_id": "user-123",
46
+ "arguments": {
47
+ "repo": "my-repo",
48
+ "title": "Bug report",
49
+ "body": "Issue description"
50
+ }
51
+ }
52
+)
53
+
54
+# ⚠️ Emergency escape hatch (not recommended for production)
55
+result = composio.tools.execute(
56
+ "GITHUB_CREATE_ISSUE",
57
+ {
58
+ "user_id": "user-123",
59
+ "arguments": {
60
+ "repo": "my-repo",
61
+ "title": "Bug report",
62
+ "body": "Issue description"
63
+ },
64
+ "dangerously_skip_version_check": True
65
+ }
66
+)
\ No newline at end of file
fern/snippets/tool-calling/versioning/python/environment-variables.py
new
+22
@@ -0,0 +1,22 @@
1
+import os
2
+from composio import Composio
3
+
4
+# Set environment variables before running your application
5
+# export COMPOSIO_TOOLKIT_VERSION_GITHUB="20250116_00"
6
+# export COMPOSIO_TOOLKIT_VERSION_SLACK="20250115_01"
7
+
8
+# Or set a global version for all toolkits
9
+# export COMPOSIO_TOOLKIT_VERSION="20250116_00"
10
+
11
+# SDK automatically reads environment variables
12
+composio = Composio(api_key="YOUR_API_KEY")
13
+
14
+# Tools will use versions from environment variables
15
+tools = composio.tools.get(
16
+ user_id="user-123",
17
+ toolkits=["github", "slack"]
18
+)
19
+
20
+# Check which versions are being used
21
+for tool in tools:
22
+ print(f"Tool: {tool.slug}, Version: {tool.toolkit_version}")
\ No newline at end of file
fern/snippets/tool-calling/versioning/python/list-versions.py
new
+30
@@ -0,0 +1,30 @@
1
+from composio import Composio
2
+from datetime import datetime
3
+
4
+composio = Composio(api_key="YOUR_API_KEY")
5
+
6
+# Get all available versions for a toolkit
7
+versions = composio.tools.get_toolkit_versions("github")
8
+
9
+# Display version information
10
+for version in versions:
11
+ print(f"Version: {version['version']}")
12
+ print(f"Released: {version['created_at']}")
13
+ print(f"Status: {version['status']}")
14
+ print("-" * 40)
15
+
16
+# Find the latest stable version
17
+stable_versions = [v for v in versions if v['status'] == 'stable']
18
+if stable_versions:
19
+ latest_stable = stable_versions[0]
20
+ print(f"Latest stable version: {latest_stable['version']}")
21
+
22
+# Find versions released in the last 7 days
23
+recent_versions = []
24
+for version in versions:
25
+ release_date = datetime.fromisoformat(version['created_at'])
26
+ days_ago = (datetime.now() - release_date).days
27
+ if days_ago <= 7:
28
+ recent_versions.append(version)
29
+
30
+print(f"Versions released in last 7 days: {len(recent_versions)}")
\ No newline at end of file
fern/snippets/tool-calling/versioning/python/multi-environment.py
new
+33
@@ -0,0 +1,33 @@
1
+import os
2
+from composio import Composio
3
+
4
+# Get current environment from environment variable
5
+env = os.getenv("ENVIRONMENT", "development")
6
+
7
+# Define version configurations for each environment
8
+version_configs = {
9
+ "development": {
10
+ "github": "latest",
11
+ "slack": "latest",
12
+ "gmail": "latest"
13
+ },
14
+ "staging": {
15
+ "github": "20250116_00", # Test new GitHub version
16
+ "slack": "20250110_00", # Keep stable Slack version
17
+ "gmail": "20250110_00"
18
+ },
19
+ "production": {
20
+ "github": "20250110_00", # Stable, tested version
21
+ "slack": "20250110_00", # Stable, tested version
22
+ "gmail": "20250109_00" # Stable, tested version
23
+ }
24
+}
25
+
26
+# Initialize Composio with environment-specific versions
27
+composio = Composio(
28
+ api_key=os.getenv("COMPOSIO_API_KEY"),
29
+ toolkit_versions=version_configs[env]
30
+)
31
+
32
+print(f"Environment: {env}")
33
+print(f"Toolkit versions: {version_configs[env]}")
\ No newline at end of file
fern/snippets/tool-calling/versioning/python/per-execution-override.py
new
+33
@@ -0,0 +1,33 @@
1
+from composio import Composio
2
+
3
+composio = Composio(
4
+ api_key="YOUR_API_KEY",
5
+ toolkit_versions={
6
+ "github": "20250110_00" # Default version
7
+ }
8
+)
9
+
10
+# Override version for a single execution
11
+result = composio.tools.execute(
12
+ "GITHUB_CREATE_ISSUE",
13
+ {
14
+ "user_id": "user-123",
15
+ "arguments": {
16
+ "repo": "my-repo",
17
+ "title": "Bug report",
18
+ "body": "Description here"
19
+ },
20
+ "toolkit_version": "20250115_00" # Override to different version
21
+ }
22
+)
23
+
24
+# This execution uses the SDK default version
25
+result2 = composio.tools.execute(
26
+ "GITHUB_LIST_ISSUES",
27
+ {
28
+ "user_id": "user-123",
29
+ "arguments": {
30
+ "repo": "my-repo"
31
+ }
32
+ }
33
+)
\ No newline at end of file
fern/snippets/tool-calling/versioning/python/rollback.py
new
+61
@@ -0,0 +1,61 @@
1
+from composio import Composio
2
+import os
3
+
4
+# Rollback Strategy 1: Update SDK initialization
5
+def rollback_via_sdk():
6
+ """Rollback to previous version by updating SDK configuration"""
7
+
8
+ # Previous configuration (problematic)
9
+ # composio = Composio(
10
+ # api_key="YOUR_API_KEY",
11
+ # toolkit_versions={
12
+ # "github": "20250116_00" # New version causing issues
13
+ # }
14
+ # )
15
+
16
+ # Rollback to stable version
17
+ composio = Composio(
18
+ api_key="YOUR_API_KEY",
19
+ toolkit_versions={
20
+ "github": "20250110_00" # Previous stable version
21
+ }
22
+ )
23
+
24
+ print("Rolled back GitHub toolkit to version 20250110_00")
25
+ return composio
26
+
27
+# Rollback Strategy 2: Update environment variables
28
+def rollback_via_env():
29
+ """Rollback by updating environment variables"""
30
+
31
+ # Set the stable version
32
+ os.environ["COMPOSIO_TOOLKIT_VERSION_GITHUB"] = "20250110_00"
33
+
34
+ # Initialize SDK (will use environment variable)
35
+ composio = Composio(api_key="YOUR_API_KEY")
36
+
37
+ print("Rolled back via environment variable")
38
+ return composio
39
+
40
+# Rollback Strategy 3: Emergency skip version check
41
+def emergency_rollback():
42
+ """Emergency rollback when version system itself has issues"""
43
+
44
+ composio = Composio(api_key="YOUR_API_KEY")
45
+
46
+ # Skip version check temporarily (use with caution)
47
+ result = composio.tools.execute(
48
+ "GITHUB_CREATE_ISSUE",
49
+ {
50
+ "user_id": "user-123",
51
+ "arguments": {
52
+ "repo": "my-repo",
53
+ "title": "Critical fix",
54
+ "body": "Emergency deployment"
55
+ },
56
+ "dangerously_skip_version_check": True
57
+ }
58
+ )
59
+
60
+ print("⚠️ Executed with version check skipped - fix version config ASAP")
61
+ return result
\ No newline at end of file
fern/snippets/tool-calling/versioning/python/sdk-initialization.py
new
+31
@@ -0,0 +1,31 @@
1
+from composio import Composio
2
+
3
+# Initialize SDK with specific toolkit versions
4
+composio = Composio(
5
+ api_key="YOUR_API_KEY",
6
+ toolkit_versions={
7
+ "github": "20250116_00",
8
+ "slack": "20250115_01",
9
+ "gmail": "latest" # Use latest version for development
10
+ }
11
+)
12
+
13
+# Fetch tools - they will use the specified versions
14
+tools = composio.tools.get(
15
+ user_id="user-123",
16
+ toolkits=["github", "slack"]
17
+)
18
+
19
+# Execute a tool - inherits version from SDK initialization
20
+result = composio.tools.execute(
21
+ "GITHUB_CREATE_ISSUE",
22
+ {
23
+ "user_id": "user-123",
24
+ "arguments": {
25
+ "repo": "my-repo",
26
+ "owner": "my-org",
27
+ "title": "Bug report",
28
+ "body": "Issue description"
29
+ }
30
+ }
31
+)
\ No newline at end of file
fern/snippets/tool-calling/versioning/python/test-new-version.py
new
+84
@@ -0,0 +1,84 @@
1
+from composio import Composio
2
+import pytest
3
+
4
+def test_new_github_version():
5
+ """Test a new GitHub toolkit version before production deployment"""
6
+
7
+ # Initialize with new version to test
8
+ test_composio = Composio(
9
+ api_key="YOUR_TEST_KEY",
10
+ toolkit_versions={"github": "20250116_00"}
11
+ )
12
+
13
+ # Test basic tool execution
14
+ result = test_composio.tools.execute(
15
+ "GITHUB_CREATE_ISSUE",
16
+ {
17
+ "user_id": "test-user",
18
+ "arguments": {
19
+ "repo": "test-repo",
20
+ "owner": "test-org",
21
+ "title": "Test issue",
22
+ "body": "Testing new version"
23
+ }
24
+ }
25
+ )
26
+
27
+ assert result["successful"] == True
28
+ assert "issue_number" in result["data"]
29
+
30
+ # Test tool fetching
31
+ tools = test_composio.tools.get(
32
+ user_id="test-user",
33
+ toolkits=["github"]
34
+ )
35
+
36
+ assert len(tools) > 0
37
+ assert all(tool.toolkit == "github" for tool in tools)
38
+
39
+ print("✓ New version tests passed")
40
+ return True
41
+
42
+def test_version_compatibility():
43
+ """Ensure new version maintains backward compatibility"""
44
+
45
+ old_version = "20250110_00"
46
+ new_version = "20250116_00"
47
+
48
+ # Initialize with old version
49
+ old_composio = Composio(
50
+ api_key="YOUR_TEST_KEY",
51
+ toolkit_versions={"github": old_version}
52
+ )
53
+
54
+ # Initialize with new version
55
+ new_composio = Composio(
56
+ api_key="YOUR_TEST_KEY",
57
+ toolkit_versions={"github": new_version}
58
+ )
59
+
60
+ # Get tools from both versions
61
+ old_tools = old_composio.tools.get(
62
+ user_id="test-user",
63
+ toolkits=["github"]
64
+ )
65
+
66
+ new_tools = new_composio.tools.get(
67
+ user_id="test-user",
68
+ toolkits=["github"]
69
+ )
70
+
71
+ # Check that essential tools still exist
72
+ old_tool_slugs = {tool.slug for tool in old_tools}
73
+ new_tool_slugs = {tool.slug for tool in new_tools}
74
+
75
+ essential_tools = [
76
+ "GITHUB_CREATE_ISSUE",
77
+ "GITHUB_CREATE_PULL_REQUEST",
78
+ "GITHUB_LIST_ISSUES"
79
+ ]
80
+
81
+ for tool in essential_tools:
82
+ assert tool in new_tool_slugs, f"Essential tool {tool} missing in new version"
83
+
84
+ print("✓ Backward compatibility verified")
\ No newline at end of file
fern/snippets/tool-calling/versioning/typescript/breaking-changes.ts
new
+59
@@ -0,0 +1,59 @@
1
+import { Composio } from "@composio/core";
2
+
3
+const composio = new Composio({ apiKey: "YOUR_API_KEY" });
4
+
5
+// ❌ This will fail without version specification (after October 22, 2025)
6
+try {
7
+ const result = await composio.tools.execute({
8
+ toolSlug: "GITHUB_CREATE_ISSUE",
9
+ userId: "user-123",
10
+ arguments: {
11
+ repo: "my-repo",
12
+ title: "Bug report",
13
+ body: "Issue description"
14
+ }
15
+ });
16
+} catch (error) {
17
+ console.error("Error:", error);
18
+ console.log("Manual execution requires toolkit version");
19
+}
20
+
21
+// ✅ Solution 1: Specify version in execution
22
+const result1 = await composio.tools.execute({
23
+ toolSlug: "GITHUB_CREATE_ISSUE",
24
+ userId: "user-123",
25
+ arguments: {
26
+ repo: "my-repo",
27
+ title: "Bug report",
28
+ body: "Issue description"
29
+ },
30
+ toolkitVersion: "20250116_00"
31
+});
32
+
33
+// ✅ Solution 2: Configure version at SDK level
34
+const composioWithVersion = new Composio({
35
+ apiKey: "YOUR_API_KEY",
36
+ toolkitVersions: { github: "20250116_00" }
37
+});
38
+
39
+const result2 = await composioWithVersion.tools.execute({
40
+ toolSlug: "GITHUB_CREATE_ISSUE",
41
+ userId: "user-123",
42
+ arguments: {
43
+ repo: "my-repo",
44
+ title: "Bug report",
45
+ body: "Issue description"
46
+ }
47
+});
48
+
49
+// ⚠️ Emergency escape hatch (not recommended for production)
50
+const result3 = await composio.tools.execute({
51
+ toolSlug: "GITHUB_CREATE_ISSUE",
52
+ userId: "user-123",
53
+ arguments: {
54
+ repo: "my-repo",
55
+ title: "Bug report",
56
+ body: "Issue description"
57
+ },
58
+ dangerouslySkipVersionCheck: true
59
+});
\ No newline at end of file
fern/snippets/tool-calling/versioning/typescript/environment-variables.ts
new
+23
@@ -0,0 +1,23 @@
1
+import { Composio } from "@composio/core";
2
+
3
+// Set environment variables before running your application
4
+// export COMPOSIO_TOOLKIT_VERSION_GITHUB="20250116_00"
5
+// export COMPOSIO_TOOLKIT_VERSION_SLACK="20250115_01"
6
+
7
+// Or set a global version for all toolkits
8
+// export COMPOSIO_TOOLKIT_VERSION="20250116_00"
9
+
10
+// SDK automatically reads environment variables
11
+const composio = new Composio({
12
+ apiKey: "YOUR_API_KEY"
13
+});
14
+
15
+// Tools will use versions from environment variables
16
+const tools = await composio.tools.get("user-123", {
17
+ toolkits: ["github", "slack"]
18
+});
19
+
20
+// Check which versions are being used
21
+tools.forEach(tool => {
22
+ console.log(`Tool: ${tool.slug}, Version: ${tool.toolkitVersion}`);
23
+});
\ No newline at end of file
fern/snippets/tool-calling/versioning/typescript/list-versions.ts
new
+30
@@ -0,0 +1,30 @@
1
+import { Composio } from "@composio/core";
2
+
3
+const composio = new Composio({ apiKey: "YOUR_API_KEY" });
4
+
5
+// Get all available versions for a toolkit
6
+const versions = await composio.tools.getToolkitVersions("github");
7
+
8
+// Display version information
9
+versions.forEach(version => {
10
+ console.log(`Version: ${version.version}`);
11
+ console.log(`Released: ${version.createdAt}`);
12
+ console.log(`Status: ${version.status}`);
13
+ console.log("-".repeat(40));
14
+});
15
+
16
+// Find the latest stable version
17
+const stableVersions = versions.filter(v => v.status === 'stable');
18
+if (stableVersions.length > 0) {
19
+ const latestStable = stableVersions[0];
20
+ console.log(`Latest stable version: ${latestStable.version}`);
21
+}
22
+
23
+// Find versions released in the last 7 days
24
+const recentVersions = versions.filter(version => {
25
+ const releaseDate = new Date(version.createdAt);
26
+ const daysAgo = Math.floor((Date.now() - releaseDate.getTime()) / (1000 * 60 * 60 * 24));
27
+ return daysAgo <= 7;
28
+});
29
+
30
+console.log(`Versions released in last 7 days: ${recentVersions.length}`);
\ No newline at end of file
fern/snippets/tool-calling/versioning/typescript/multi-environment.ts
new
+32
@@ -0,0 +1,32 @@
1
+import { Composio } from "@composio/core";
2
+
3
+// Get current environment from environment variable
4
+const env = process.env.ENVIRONMENT || "development";
5
+
6
+// Define version configurations for each environment
7
+const versionConfigs = {
8
+ development: {
9
+ github: "latest",
10
+ slack: "latest",
11
+ gmail: "latest"
12
+ },
13
+ staging: {
14
+ github: "20250116_00", // Test new GitHub version
15
+ slack: "20250110_00", // Keep stable Slack version
16
+ gmail: "20250110_00"
17
+ },
18
+ production: {
19
+ github: "20250110_00", // Stable, tested version
20
+ slack: "20250110_00", // Stable, tested version
21
+ gmail: "20250109_00" // Stable, tested version
22
+ }
23
+};
24
+
25
+// Initialize Composio with environment-specific versions
26
+const composio = new Composio({
27
+ apiKey: process.env.COMPOSIO_API_KEY!,
28
+ toolkitVersions: versionConfigs[env as keyof typeof versionConfigs]
29
+});
30
+
31
+console.log(`Environment: ${env}`);
32
+console.log(`Toolkit versions:`, versionConfigs[env as keyof typeof versionConfigs]);
\ No newline at end of file
fern/snippets/tool-calling/versioning/typescript/per-execution-override.ts
new
+29
@@ -0,0 +1,29 @@
1
+import { Composio } from "@composio/core";
2
+
3
+const composio = new Composio({
4
+ apiKey: "YOUR_API_KEY",
5
+ toolkitVersions: {
6
+ github: "20250110_00" // Default version
7
+ }
8
+});
9
+
10
+// Override version for a single execution
11
+const result = await composio.tools.execute({
12
+ toolSlug: "GITHUB_CREATE_ISSUE",
13
+ userId: "user-123",
14
+ arguments: {
15
+ repo: "my-repo",
16
+ title: "Bug report",
17
+ body: "Description here"
18
+ },
19
+ toolkitVersion: "20250115_00" // Override to different version
20
+});
21
+
22
+// This execution uses the SDK default version
23
+const result2 = await composio.tools.execute({
24
+ toolSlug: "GITHUB_LIST_ISSUES",
25
+ userId: "user-123",
26
+ arguments: {
27
+ repo: "my-repo"
28
+ }
29
+});
\ No newline at end of file
fern/snippets/tool-calling/versioning/typescript/rollback.ts
new
+59
@@ -0,0 +1,59 @@
1
+import { Composio } from "@composio/core";
2
+
3
+// Rollback Strategy 1: Update SDK initialization
4
+async function rollbackViaSdk(): Promise<Composio> {
5
+ // Previous configuration (problematic)
6
+ // const composio = new Composio({
7
+ // apiKey: "YOUR_API_KEY",
8
+ // toolkitVersions: {
9
+ // github: "20250116_00" // New version causing issues
10
+ // }
11
+ // });
12
+
13
+ // Rollback to stable version
14
+ const composio = new Composio({
15
+ apiKey: "YOUR_API_KEY",
16
+ toolkitVersions: {
17
+ github: "20250110_00" // Previous stable version
18
+ }
19
+ });
20
+
21
+ console.log("Rolled back GitHub toolkit to version 20250110_00");
22
+ return composio;
23
+}
24
+
25
+// Rollback Strategy 2: Update environment variables
26
+async function rollbackViaEnv(): Promise<Composio> {
27
+ // Set the stable version
28
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = "20250110_00";
29
+
30
+ // Initialize SDK (will use environment variable)
31
+ const composio = new Composio({
32
+ apiKey: "YOUR_API_KEY"
33
+ });
34
+
35
+ console.log("Rolled back via environment variable");
36
+ return composio;
37
+}
38
+
39
+// Rollback Strategy 3: Emergency skip version check
40
+async function emergencyRollback(): Promise<any> {
41
+ const composio = new Composio({
42
+ apiKey: "YOUR_API_KEY"
43
+ });
44
+
45
+ // Skip version check temporarily (use with caution)
46
+ const result = await composio.tools.execute({
47
+ toolSlug: "GITHUB_CREATE_ISSUE",
48
+ userId: "user-123",
49
+ arguments: {
50
+ repo: "my-repo",
51
+ title: "Critical fix",
52
+ body: "Emergency deployment"
53
+ },
54
+ dangerouslySkipVersionCheck: true
55
+ });
56
+
57
+ console.log("⚠️ Executed with version check skipped - fix version config ASAP");
58
+ return result;
59
+}
\ No newline at end of file
fern/snippets/tool-calling/versioning/typescript/sdk-initialization.ts
new
+28
@@ -0,0 +1,28 @@
1
+import { Composio } from "@composio/core";
2
+
3
+// Initialize SDK with specific toolkit versions
4
+const composio = new Composio({
5
+ apiKey: "YOUR_API_KEY",
6
+ toolkitVersions: {
7
+ github: "20250116_00",
8
+ slack: "20250115_01",
9
+ gmail: "latest" // Use latest version for development
10
+ }
11
+});
12
+
13
+// Fetch tools - they will use the specified versions
14
+const tools = await composio.tools.get("user-123", {
15
+ toolkits: ["github", "slack"]
16
+});
17
+
18
+// Execute a tool - inherits version from SDK initialization
19
+const result = await composio.tools.execute({
20
+ toolSlug: "GITHUB_CREATE_ISSUE",
21
+ userId: "user-123",
22
+ arguments: {
23
+ repo: "my-repo",
24
+ owner: "my-org",
25
+ title: "Bug report",
26
+ body: "Issue description"
27
+ }
28
+});
\ No newline at end of file
fern/snippets/tool-calling/versioning/typescript/test-new-version.ts
new
+89
@@ -0,0 +1,89 @@
1
+import { Composio } from "@composio/core";
2
+
3
+async function testNewGithubVersion(): Promise<boolean> {
4
+ // Initialize with new version to test
5
+ const testComposio = new Composio({
6
+ apiKey: "YOUR_TEST_KEY",
7
+ toolkitVersions: { github: "20250116_00" }
8
+ });
9
+
10
+ // Test basic tool execution
11
+ const result = await testComposio.tools.execute({
12
+ toolSlug: "GITHUB_CREATE_ISSUE",
13
+ userId: "test-user",
14
+ arguments: {
15
+ repo: "test-repo",
16
+ owner: "test-org",
17
+ title: "Test issue",
18
+ body: "Testing new version"
19
+ }
20
+ });
21
+
22
+ if (!result.successful) {
23
+ throw new Error("Tool execution failed");
24
+ }
25
+
26
+ if (!result.data.issue_number) {
27
+ throw new Error("Missing expected data in response");
28
+ }
29
+
30
+ // Test tool fetching
31
+ const tools = await testComposio.tools.get("test-user", {
32
+ toolkits: ["github"]
33
+ });
34
+
35
+ if (tools.length === 0) {
36
+ throw new Error("No tools returned");
37
+ }
38
+
39
+ if (!tools.every(tool => tool.toolkit === "github")) {
40
+ throw new Error("Unexpected toolkit in results");
41
+ }
42
+
43
+ console.log("✓ New version tests passed");
44
+ return true;
45
+}
46
+
47
+async function testVersionCompatibility(): Promise<void> {
48
+ const oldVersion = "20250110_00";
49
+ const newVersion = "20250116_00";
50
+
51
+ // Initialize with old version
52
+ const oldComposio = new Composio({
53
+ apiKey: "YOUR_TEST_KEY",
54
+ toolkitVersions: { github: oldVersion }
55
+ });
56
+
57
+ // Initialize with new version
58
+ const newComposio = new Composio({
59
+ apiKey: "YOUR_TEST_KEY",
60
+ toolkitVersions: { github: newVersion }
61
+ });
62
+
63
+ // Get tools from both versions
64
+ const oldTools = await oldComposio.tools.get("test-user", {
65
+ toolkits: ["github"]
66
+ });
67
+
68
+ const newTools = await newComposio.tools.get("test-user", {
69
+ toolkits: ["github"]
70
+ });
71
+
72
+ // Check that essential tools still exist
73
+ const oldToolSlugs = new Set(oldTools.map(tool => tool.slug));
74
+ const newToolSlugs = new Set(newTools.map(tool => tool.slug));
75
+
76
+ const essentialTools = [
77
+ "GITHUB_CREATE_ISSUE",
78
+ "GITHUB_CREATE_PULL_REQUEST",
79
+ "GITHUB_LIST_ISSUES"
80
+ ];
81
+
82
+ for (const tool of essentialTools) {
83
+ if (!newToolSlugs.has(tool)) {
84
+ throw new Error(`Essential tool ${tool} missing in new version`);
85
+ }
86
+ }
87
+
88
+ console.log("✓ Backward compatibility verified");
89
+}
\ No newline at end of file