Toolkit versioning migration

View as markdown

Starting with Python SDK v0.9.0 and TypeScript SDK v0.2.0, manual tool execution requires explicit version specification. This is a breaking change from earlier versions where toolkit versioning was optional.

Breaking change

Manual tool execution now requires explicit version specification. The tools.execute() method will fail without a version.

Before (will fail)

# Raises ToolVersionRequiredError
result = composio.tools.execute(
    "GITHUB_CREATE_ISSUE",
    {"user_id": "user-123", "arguments": {...}}
)
// Throws ComposioToolVersionRequiredError
const const result: anyresult = await composio.tools.execute({
    toolSlug: stringtoolSlug: "GITHUB_CREATE_ISSUE",
    userId: stringuserId: "user-123",
    arguments: anyarguments: {...}
});

After (required)

Choose one of three migration strategies:

Option 1: Configure version at SDK level

from composio import Composio

# Pin specific versions for each toolkit
composio = Composio(
    api_key="YOUR_API_KEY",
    toolkit_versions={
        "github": "20251027_00",
        "slack": "20251027_00",
        "gmail": "20251027_00"
    }
)
import { class Composio<TProvider extends BaseComposioProvider<unknown, unknown, unknown> = OpenAIProvider>
This is the core class for Composio. It is used to initialize the Composio SDK and provide a global configuration.
Composio
} from "@composio/core";
// Pin specific versions for each toolkit const const composio: Composio<OpenAIProvider>composio = new new Composio<OpenAIProvider>(config?: ComposioConfig<OpenAIProvider> | undefined): Composio<OpenAIProvider>
Creates a new instance of the Composio SDK. The constructor initializes the SDK with the provided configuration options, sets up the API client, and initializes all core models (tools, toolkits, etc.).
@paramconfig - Configuration options for the Composio SDK@paramconfig.apiKey - The API key for authenticating with the Composio API@paramconfig.baseURL - The base URL for the Composio API (defaults to production URL)@paramconfig.allowTracking - Whether to allow anonymous usage analytics@paramconfig.provider - The provider to use for this Composio instance (defaults to OpenAIProvider)@example```typescript // Initialize with default configuration const composio = new Composio(); // Initialize with custom API key and base URL const composio = new Composio({ apiKey: 'your-api-key', baseURL: 'https://api.composio.dev' }); // Initialize with custom provider const composio = new Composio({ apiKey: 'your-api-key', provider: new CustomProvider() }); ```
Composio
({
apiKey?: string | null | undefined
The API key for the Composio API.
@example'sk-1234567890'
apiKey
: "YOUR_API_KEY",
toolkitVersions?: "latest" | Record<string, string> | undefined
The versions of the toolkits to use for tool execution and retrieval. Omit to use 'latest' for all toolkits. **Version Control:** When executing tools manually (via `tools.execute()`), if this resolves to "latest", you must either: - Set `dangerouslySkipVersionCheck: true` in the execute params (not recommended for production) - Specify a concrete version here or in environment variables - Pass a specific `version` parameter to the execute call Defaults to 'latest' if nothing is provided. You can specify individual toolkit versions via environment variables: `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`
@exampleGlobal version for all toolkits, omit to use 'latest' ```typescript const composio = new Composio(); ```@exampleSpecific versions for different toolkits (recommended for production) ```typescript const composio = new Composio({ toolkitVersions: { github: '20250909_00', slack: '20250902_00' } }); ```@exampleSet via environment variables ```typescript // Set environment variables: // COMPOSIO_TOOLKIT_VERSION_GITHUB=20250909_00 // COMPOSIO_TOOLKIT_VERSION_SLACK=20250902_00 const composio = new Composio(); // Will use env variables ```
toolkitVersions
: {
github: stringgithub: "20251027_00", slack: stringslack: "20251027_00", gmail: stringgmail: "20251027_00" } });

Option 2: Pass version with each execution

# Specify version directly in execute call
result = composio.tools.execute(
    "GITHUB_LIST_STARGAZERS",
    arguments={
        "owner": "ComposioHQ",
        "repo": "composio"
    },
    user_id="user-k7334",
    version="20251027_00"  # Override version for this execution
)
print(result)
// Specify version directly in execute call
const const result: anyresult = await composio.tools.execute("GITHUB_LIST_STARGAZERS", {
    userId: stringuserId: "user-k7334",
    
arguments: {
    owner: string;
    repo: string;
}
arguments
: {
owner: stringowner: "ComposioHQ", repo: stringrepo: "composio" }, version: stringversion: "20251027_00" // Override version for this execution }); var console: Console
The `console` module provides a simple debugging console that is similar to the JavaScript console mechanism provided by web browsers. The module exports two specific components: * A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream. * A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v24.x/api/process.html#processstdout) and [`process.stderr`](https://nodejs.org/docs/latest-v24.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module. _**Warning**_: The global console object's methods are neither consistently synchronous like the browser APIs they resemble, nor are they consistently asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v24.x/api/process.html#a-note-on-process-io) for more information. Example using the global `console`: ```js console.log('hello world'); // Prints: hello world, to stdout console.log('hello %s', 'world'); // Prints: hello world, to stdout console.error(new Error('Whoops, something bad happened')); // Prints error message and stack trace to stderr: // Error: Whoops, something bad happened // at [eval]:5:15 // at Script.runInThisContext (node:vm:132:18) // at Object.runInThisContext (node:vm:309:38) // at node:internal/process/execution:77:19 // at [eval]-wrapper:6:22 // at evalScript (node:internal/process/execution:76:60) // at node:internal/main/eval_string:23:3 const name = 'Will Robinson'; console.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to stderr ``` Example using the `Console` class: ```js const out = getStreamSomehow(); const err = getStreamSomehow(); const myConsole = new console.Console(out, err); myConsole.log('hello world'); // Prints: hello world, to out myConsole.log('hello %s', 'world'); // Prints: hello world, to out myConsole.error(new Error('Whoops, something bad happened')); // Prints: [Error: Whoops, something bad happened], to err const name = 'Will Robinson'; myConsole.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to err ```
@see[source](https://github.com/nodejs/node/blob/v24.x/lib/console.js)
console
.Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)
Prints to `stdout` with newline. Multiple arguments can be passed, with the first used as the primary message and all additional used as substitution values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html) (the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v24.x/api/util.html#utilformatformat-args)). ```js const count = 5; console.log('count: %d', count); // Prints: count: 5, to stdout console.log('count:', count); // Prints: count: 5, to stdout ``` See [`util.format()`](https://nodejs.org/docs/latest-v24.x/api/util.html#utilformatformat-args) for more information.
@sincev0.1.100
log
(const result: anyresult);

Option 3: Use environment variables

export COMPOSIO_TOOLKIT_VERSION_GITHUB="20251027_00"

Migration checklist

  1. Audit your code: Find all tools.execute() calls in your codebase
  2. Choose a strategy: Select one of the three options above based on your needs
  3. Test thoroughly: Verify tools work correctly with pinned versions
  4. Deploy gradually: Roll out changes incrementally to minimize risk

Temporary workaround

During migration, you can temporarily skip version checks (not recommended for production):

result = composio.tools.execute(
    "GITHUB_CREATE_ISSUE",
    {
        "user_id": "user-123",
        "arguments": {...}
    },
    dangerously_skip_version_check=True
)
const const result: anyresult = await composio.tools.execute({
    toolSlug: stringtoolSlug: "GITHUB_CREATE_ISSUE",
    userId: stringuserId: "user-123",
    arguments: anyarguments: {...},
    dangerouslySkipVersionCheck: booleandangerouslySkipVersionCheck: true
});

The dangerouslySkipVersionCheck flag is only for migration or debugging. Never use in production.

Next steps

For complete documentation on toolkit versioning, including best practices and advanced configuration, see Toolkit versioning.