Agent skill

anth-upgrade-migration

Upgrade Anthropic SDK versions and migrate between Claude API versions. Use when upgrading the Python/TypeScript SDK, migrating from Text Completions to Messages API, or adopting new API features like tool use or batches. Trigger with phrases like "upgrade anthropic sdk", "anthropic migration", "update claude sdk", "migrate to messages api".

Stars 1,803
Forks 241

Install this agent skill to your Project

npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/anthropic-pack/skills/anth-upgrade-migration

SKILL.md

Anthropic Upgrade & Migration

Overview

Guide for upgrading the Anthropic SDK and migrating between API versions. The SDK follows semver — major versions may have breaking changes.

Check Current Versions

bash
# Python
pip show anthropic | grep Version
# Version: 0.40.0

# TypeScript
npm list @anthropic-ai/sdk
# @anthropic-ai/sdk@0.35.0

# Check latest available
pip index versions anthropic 2>/dev/null | head -1
npm view @anthropic-ai/sdk version

Upgrade Path

Step 1: Create Upgrade Branch

bash
git checkout -b upgrade/anthropic-sdk

Step 2: Upgrade SDK

bash
# Python
pip install --upgrade anthropic
pip show anthropic | grep Version

# TypeScript
npm install @anthropic-ai/sdk@latest

Step 3: Review Breaking Changes

Key breaking changes by version:

Python SDK 0.20+ (anthropic-version: 2023-06-01)

python
# OLD: Text Completions API (deprecated)
response = client.completions.create(
    model="claude-2",
    prompt="\n\nHuman: Hello\n\nAssistant:",
    max_tokens_to_sample=256
)

# NEW: Messages API
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=256,
    messages=[{"role": "user", "content": "Hello"}]
)

Python SDK 0.30+ (streaming changes)

python
# OLD: Manual SSE parsing
response = client.messages.create(..., stream=True)
for line in response.iter_lines():
    ...

# NEW: High-level streaming
with client.messages.stream(...) as stream:
    for text in stream.text_stream:
        print(text)

TypeScript SDK 0.20+ (import path change)

typescript
// OLD
import Anthropic from 'anthropic';

// NEW
import Anthropic from '@anthropic-ai/sdk';

Step 4: Update API Version Header

python
# The SDK sends anthropic-version header automatically
# To pin a specific version:
client = anthropic.Anthropic(
    default_headers={"anthropic-version": "2023-06-01"}
)

# For beta features:
client = anthropic.Anthropic(
    default_headers={"anthropic-beta": "token-counting-2024-11-01"}
)

Step 5: Run Tests and Verify

bash
# Run your test suite
python -m pytest tests/ -v
npm test

# Verify a live call
python3 -c "
import anthropic
c = anthropic.Anthropic()
m = c.messages.create(model='claude-haiku-4-20250514', max_tokens=8, messages=[{'role':'user','content':'hi'}])
print(f'OK: {m.model} {m.usage}')
"

Migration: Text Completions to Messages

Text Completions Messages API
client.completions.create() client.messages.create()
prompt (string) messages (array)
max_tokens_to_sample max_tokens
model: "claude-2" model: "claude-sonnet-4-20250514"
\n\nHuman:...\n\nAssistant: [{role: "user"}, {role: "assistant"}]
response.completion response.content[0].text

Rollback

bash
# Python — pin to previous version
pip install anthropic==0.39.0

# TypeScript — pin to previous version
npm install @anthropic-ai/sdk@0.34.0

# Git rollback
git checkout main -- package.json package-lock.json
npm install

Resources

Next Steps

For CI integration during upgrades, see anth-ci-integration.

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results