Toolkit versioning migration

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": {...}}
)

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"
    }
)

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)

Option 3: Use environment variables

export COMPOSIO_TOOLKIT_VERSION_GITHUB="20251027_00"

Migration checklist

Audit your code: Find all tools.execute() calls in your codebase
Choose a strategy: Select one of the three options above based on your needs
Test thoroughly: Verify tools work correctly with pinned versions
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
)

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

Migrate to sessions

Move from older tool execution patterns to sessions

Edit this page on GitHub