composio-skills-reference/composio-sdk/rules/app-tool-versions.md

title, impact, description, tags

title	impact	description	tags
Tool Version Management	HIGH	Critical strategies for version pinning to ensure workflow stability and prevent runtime errors in production	tools versions stability production pinning

Tool Version Management

⚠️ CRITICAL: Never assume or make up version numbers. Always use composio.toolkits.get('toolkit_name') to fetch available versions, or check the dashboard to view versions and changes. Using non-existent versions will cause runtime errors.

Tool versions are critical for workflow stability. When manually executing tools, a specific version is required to prevent argument mismatches when tool schemas change.

Why Version Pinning Matters

• Tool schemas evolve: Tool argument schemas can change between versions
• Prevent runtime errors: Using 'latest' in workflows causes errors when tools update
• Workflow stability: Pinned versions ensure predictable behavior
• Production safety: Version validation prevents schema mismatch issues

Three Version Management Strategies

Strategy 1: Explicit Version in Execute Call (Recommended for One-off Executions)

Specify the version directly in the execute call:

const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
  userId: 'default',
  arguments: { owner: 'composio', repo: 'sdk' },
  version: '12082025_00', // Explicit version for this tool
});

Pros:

• Clear version visibility at execution point
• Different versions for different tools
• Easy to update individual tool versions

Cons:

• Repetitive if executing same tool multiple times
• Version scattered across codebase

Use when:

• One-off tool executions
• Testing different tool versions
• Tool versions need to differ within the same app

Strategy 2: Configure Toolkit Versions at Initialization (Recommended for Production)

Configure versions once at SDK initialization:

const composio = new Composio({
  toolkitVersions: {
    github: '12082025_00',
    slack: '10082025_01',
    gmail: '15082025_02'
  }
});

// Execute without version parameter - uses pinned version from config
const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
  userId: 'default',
  arguments: { owner: 'composio', repo: 'sdk' },
  // Uses github: '12082025_00' from initialization
});

Pros:

• Centralized version management
• Clean execution calls
• Easy to update all tools from a toolkit
• Best for production environments

Cons:

• All tools from a toolkit use the same version
• Requires initialization configuration

Use when:

• Building production applications
• Managing multiple tools from the same toolkit
• Want centralized version control

Strategy 3: dangerouslySkipVersionCheck (NOT Recommended for Production)

Bypass version validation entirely:

const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
  userId: 'default',
  arguments: { owner: 'composio', repo: 'sdk' },
  dangerouslySkipVersionCheck: true, // Uses 'latest' version
});

⚠️ Warning: This bypasses version validation and uses 'latest' version. Can lead to:

• Unexpected behavior when tool schemas change
• Argument mismatches in production
• Runtime errors when tools are updated
• Workflow breakage without notice

Only use for:

• Development and testing
• Prototyping
• When you explicitly want to test latest versions

NEVER use in:

• Production environments
• Critical workflows
• User-facing applications

Version Format

Versions follow the format: DDMMYYYY_XX

Examples:

• 12082025_00 - August 12, 2025, revision 00
• 10082025_01 - August 10, 2025, revision 01
• 15082025_02 - August 15, 2025, revision 02

Finding Available Versions

⚠️ CRITICAL: Never assume or guess version numbers. Always verify that a version exists before using it.

Method 1: Use SDK to List Available Versions

Fetch toolkit metadata to see all available versions:

// Get available versions for a specific toolkit
const toolkit = await composio.toolkits.get('github');
console.log('Available versions:', toolkit.versions);
console.log('Latest version:', toolkit.latestVersion);

// For Gmail
const gmailToolkit = await composio.toolkits.get('gmail');
console.log('Gmail versions:', gmailToolkit.versions);

// For Slack
const slackToolkit = await composio.toolkits.get('slack');
console.log('Slack versions:', slackToolkit.versions);

Method 2: Check Dashboard

View versions and changelog on the Composio dashboard:

• Navigate to Toolkits section
• Select the specific toolkit (e.g., GitHub, Gmail, Slack)
• View available versions and their changes

How to Use Versions Correctly

Once you've found available versions, choose a specific version to test, then pin it in your configuration:

Step 1: List available versions

const githubToolkit = await composio.toolkits.get('github');
console.log('Available versions:', githubToolkit.versions);
// Example output: ['12082025_00', '10082025_01', '08082025_00']

Step 2: Choose and test a specific version

// Test with a specific version from the list
const composio = new Composio({
  toolkitVersions: {
    github: '12082025_00', // Choose a specific version to test
  }
});

Step 3: Pin the tested version in production

// After testing, pin the version in your production config
const composio = new Composio({
  toolkitVersions: {
    github: '12082025_00',  // Pinned version that you've tested
    slack: '10082025_01',   // Pinned version that you've tested
  }
});

Using Environment Variables

You can also set toolkit versions using environment variables:

# Set specific versions for individual toolkits
export COMPOSIO_TOOLKIT_VERSION_GITHUB=12082025_00
export COMPOSIO_TOOLKIT_VERSION_SLACK=10082025_01
export COMPOSIO_TOOLKIT_VERSION_GMAIL=15082025_00

Then initialize Composio without specifying toolkitVersions:

const composio = new Composio({
  apiKey: 'your-api-key'
  // Will automatically use environment variables
});

IMPORTANT: Don't Auto-Use Latest Version

❌ DON'T DO THIS:

// This defeats the purpose of version pinning!
const githubToolkit = await composio.toolkits.get('github');
const composio = new Composio({
  toolkitVersions: {
    github: githubToolkit.latestVersion, // Always uses latest - no pinning!
  }
});

// Never use made-up version numbers either!
const composio = new Composio({
  toolkitVersions: {
    github: '01012025_00', // Random version - might not exist!
    slack: '25122024_99',  // Made up version - will fail!
  }
});

✅ DO THIS:

// 1. List available versions to find valid options
const githubToolkit = await composio.toolkits.get('github');
console.log('Available versions:', githubToolkit.versions);

// 2. Choose and test a specific version from the list
// 3. Pin that tested version in your code or environment variables
const composio = new Composio({
  toolkitVersions: {
    github: '12082025_00',  // Specific tested version
    slack: '10082025_01',   // Specific tested version
  }
});

Why this matters:

• Automatically using latestVersion means your app always uses the newest version, defeating the purpose of pinning
• Version pinning is about locking to a specific, tested version for stability
• When you're ready to upgrade, you explicitly choose and test a new version before deploying

Version Migration Strategy

When updating tool versions:

1. Test in development first

   // Dev environment
   const devComposio = new Composio({
     toolkitVersions: { github: '20082025_00' } // New version
   });
   

2. Validate schema changes

   const oldTool = await composio.tools.get('default', 'GITHUB_GET_ISSUES');
   const newTool = await composio.tools.get('default', 'GITHUB_GET_ISSUES');
   // Compare schemas before migrating
   

3. Update gradually

   • Update one toolkit at a time
   • Monitor for errors
   • Roll back if issues occur

4. Update production

   // Production environment
   const prodComposio = new Composio({
     toolkitVersions: { github: '20082025_00' } // Deploy new version
   });
   

Best Practices

1. Always pin versions in production: Never use 'latest' or skip version checks
2. Use initialization-level config: Centralize version management for maintainability
3. Document version choices: Comment why specific versions are used
4. Test version updates: Validate in dev before deploying to production
5. Monitor after updates: Watch for errors after version changes
6. Keep versions consistent: Use same version across environments when possible
7. Version control your config: Track toolkit versions in your repository

Common Patterns

Environment-based version config

const toolkitVersions = {
  development: {
    github: '12082025_00',
    slack: '10082025_01',
  },
  production: {
    github: '10082025_00', // Older stable version
    slack: '08082025_00',
  }
};

const composio = new Composio({
  toolkitVersions: toolkitVersions[process.env.NODE_ENV]
});

Override version for specific execution

// Use global config version by default
const composio = new Composio({
  toolkitVersions: { github: '12082025_00' }
});

// Override for specific execution
const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
  userId: 'default',
  arguments: { owner: 'composio', repo: 'sdk' },
  version: '15082025_00', // Override global version
});

Version validation helper

function validateToolVersion(version: string): boolean {
  // Check format: DDMMYYYY_XX
  const versionRegex = /^\d{8}_\d{2}$/;
  return versionRegex.test(version);
}

const version = '12082025_00';
if (!validateToolVersion(version)) {
  throw new Error('Invalid version format');
}