Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 |