@devries-cameron20 / composio-1 / commits / e5e9a7446
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.

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