Anthropic Upgrade & Migration Skill

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

# 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

git checkout -b upgrade/anthropic-sdk

Step 2: Upgrade SDK

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

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

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

// OLD
import Anthropic from 'anthropic';

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

Step 4: Update API Version Header

# 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

# 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

# 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.

Agent Skills: Anthropic Upgrade & Migration

Install this agent skill to your local

Skill Files