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 = devcaster.tools.execute(
    "GITHUB_CREATE_ISSUE",
    {"user_id": "user-123", "arguments": {...}}
)

// Throws DevcasterToolVersionRequiredError
const result = await devcaster.tools.execute({
    toolSlug: "GITHUB_CREATE_ISSUE",
    userId: "user-123",
    arguments: {...}
});

After (required)

Choose one of three migration strategies:

Option 1: Configure version at SDK level

from devcaster import Devcaster

# Pin specific versions for each toolkit
devcaster = Devcaster(
    api_key="YOUR_API_KEY",
    toolkit_versions={
        "github": "20251027_00",
        "slack": "20251027_00",
        "gmail": "20251027_00"
    }
)

import { Devcaster } from "@devcaster/core";

// Pin specific versions for each toolkit
const devcaster = new Devcaster({
    apiKey: "YOUR_API_KEY",
    toolkitVersions: {
        github: "20251027_00",
        slack: "20251027_00",
        gmail: "20251027_00"
    }
});

Option 2: Pass version with each execution

# Specify version directly in execute call
result = devcaster.tools.execute(
    "GITHUB_LIST_STARGAZERS",
    arguments={
        "owner": "DevcasterHQ",
        "repo": "devcaster"
    },
    user_id="user-k7334",
    version="20251027_00"  # Override version for this execution
)
print(result)

// Specify version directly in execute call
const result = await devcaster.tools.execute("GITHUB_LIST_STARGAZERS", {
    userId: "user-k7334",
    arguments: {
        owner: "DevcasterHQ",
        repo: "devcaster"
    },
    version: "20251027_00"  // Override version for this execution
});
console.log(result);

Option 3: Use environment variables

export DEVCASTER_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 = devcaster.tools.execute(
    "GITHUB_CREATE_ISSUE",
    {
        "user_id": "user-123",
        "arguments": {...}
    },
    dangerously_skip_version_check=True
)

const result = await devcaster.tools.execute({
    toolSlug: "GITHUB_CREATE_ISSUE",
    userId: "user-123",
    arguments: {...},
    dangerouslySkipVersionCheck: 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.

Toolkit versioning migration

On this page