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)

1
# Raises ToolVersionRequiredError
2
result = composio.tools.execute(
3
    "GITHUB_CREATE_ISSUE",
4
    {"user_id": "user-123", "arguments": {...}}
5
)

After (required)

Choose one of three migration strategies:

Option 1: Configure version at SDK level

1
from composio import Composio
2
3
# Pin specific versions for each toolkit
4
composio = Composio(
5
    api_key="YOUR_API_KEY",
6
    toolkit_versions={
7
        "github": "20251027_00",
8
        "slack": "20251027_00",
9
        "gmail": "20251027_00"
10
    }
11
)

Option 2: Pass version with each execution

1
result = composio.tools.execute(
2
    "GITHUB_LIST_STARGAZERS",
3
    arguments={
4
        "owner": "ComposioHQ",
5
        "repo": "composio"
6
    },
7
    user_id="user-k7334",
8
    version="20251027_00"  # Override version for this execution
9
)
10
print(result)

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):

1
result = composio.tools.execute(
2
    "GITHUB_CREATE_ISSUE",
3
    {
4
        "user_id": "user-123",
5
        "arguments": {...}
6
    },
7
    dangerously_skip_version_check=True
8
)

Next steps

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