Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
mdx 128 lines 4.68 KB
Raw
1 ---
2 title: "Toolkit Versioning in SDKs"
3 description: "Pin specific toolkit versions for consistent behavior and controlled updates in production"
4 date: "2025-09-16"
5 ---
6
7 Composio Toolkit Versioning provides **granular control over tool versions** across all your integrations. Instead of always using the latest version of tools, developers can now specify exact toolkit versions, ensuring consistent behavior and controlled updates in production environments.
8
9 ### Why Use Toolkit Versioning?
10
11 - **Version Stability**: Pin specific toolkit versions to avoid unexpected changes in production
12 - **Controlled Updates**: Test new toolkit versions before deploying to production
13 - **Environment Consistency**: Ensure the same toolkit versions across development, staging, and production
14 - **Rollback Capability**: Easily revert to previous toolkit versions if issues arise
15 - **Fine-grained Control**: Set different versions for different toolkits based on your needs
16
17 ---
18
19 ### Python SDK (v0.8.11)
20
21 **Added**
22
23 - **Toolkit Versioning Support**: New `toolkit_versions` parameter for controlling tool versions
24 - Added `toolkit_versions` parameter to `Composio` class initialization
25 - Support for global version setting (e.g., `'latest'`)
26 - Support for per-toolkit version mapping (e.g., `{'github': '20250902_00', 'slack': '20250902_00'}`)
27 - Environment variable support with `COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>` pattern
28 - New `toolkit_version.py` utility module for version resolution logic
29
30 **Examples:**
31
32 ```python
33 # Global version for all toolkits, only `latest` is supported
34 composio = Composio(toolkit_versions='latest')
35
36 # Per-toolkit version mapping
37 composio = Composio(toolkit_versions={
38 'github': '20250902_00',
39 'slack': '20250902_00',
40 'gmail': '20250901_01'
41 })
42
43 # Using environment variables
44 # Set COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
45 composio = Composio() # Automatically picks up env vars
46
47 # Get tools with specific versions
48 tools = composio.tools.get('default', {'toolkits': ['github']})
49 ```
50
51 ### TypeScript SDK (v0.1.52)
52
53 **Added**
54
55 - **Toolkit Versioning Support**: Added `toolkitVersions` configuration option
56 - New `toolkitVersions` parameter in `Composio` class constructor
57 - Support for global version string or per-toolkit version mapping
58 - Environment variable parsing with `getToolkitVersionsFromEnv()` utility
59 - Enhanced `getRawComposioToolBySlug()` method for version-specific tool retrieval
60 - Version-aware tool filtering and search capabilities
61
62 **Examples:**
63
64 ```typescript
65 // @noErrors
66 // Global version for all toolkits
67 const composio = new Composio({
68 toolkitVersions: '20250902_00'
69 });
70
71 // Per-toolkit version mapping
72 const composio = new Composio({
73 toolkitVersions: {
74 'github': '20250902_00',
75 'slack': '20250902_00',
76 'gmail': '20250901_01'
77 }
78 });
79
80 // Using environment variables
81 // Set COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
82 const composio = new Composio(); // Automatically picks up env vars
83
84 // Get specific tool version
85 const tool = await composio.tools.getRawComposioToolBySlug(
86 'GITHUB_GET_REPO',
87 );
88
89 // Get tools with version-aware filtering
90 const tools = await composio.tools.get('default', {
91 toolkits: ['github'],
92 limit: 10
93 });
94 ```
95
96 ### Key Benefits
97
98 - **Environment Variables**: Set `COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>=<VERSION>` for automatic version resolution
99 - **Flexible Configuration**: Choose between global versions or per-toolkit version mapping
100 - **Backward Compatibility**: Existing code works unchanged - versioning is opt-in
101 - **Version Fallback**: Automatically falls back to 'latest' when no version is specified
102 - **Cross-Platform Consistency**: Identical developer experience across Python and TypeScript
103
104 ### Version Format
105
106 Toolkit versions follow the format: `YYYYMMDD_NN` (e.g., `20250902_00`) or use `'latest'` for the most recent version only supported at global scope and not individual toolkit level.
107
108 ### Environment Variables
109
110 ```bash
111 # Set specific versions for different toolkits
112 export COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
113 export COMPOSIO_TOOLKIT_VERSION_SLACK=20250902_00
114 export COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_01
115 ```
116
117 ### Migration Note
118
119 This feature is fully backward compatible. Existing code will continue to work without changes, using the latest versions by default. To enable versioning, simply add the `toolkit_versions` parameter during SDK initialization.
120
121 ---
122
123 ### Additional Updates
124
125 - **Package Updates**: Bumped all Python provider packages to v0.8.10
126 - **Documentation**: Enhanced API documentation with versioning examples
127 - **Testing**: Added comprehensive test coverage (400+ new test cases) for versioning functionality
128 - **Examples**: New versioning examples demonstrating practical usage patterns