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

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

Prerequisites

• Record the current SDK version, lockfile digest, API version header, model identifiers, supported runtime versions, and a tested rollback revision.
• Obtain release notes from the official SDK/API sources and an approved sandbox workspace with synthetic prompts; production credentials must not be used for migration tests.
• Define compatibility, latency, cost, and response-shape acceptance thresholds and identify the owner who approves promotion.

Instructions

1. Create a migration branch and lock the current dependency graph. Compare the target SDK and API behavior against official release notes; do not infer compatibility from a package version alone.
2. Update the SDK and request shapes in a sandbox, preserving explicit model IDs, max_tokens, authentication through the secret manager, and least-privileged workspace access.
3. Run unit, contract, streaming, tool-use, error, and token-count tests using synthetic fixtures. Compare redacted response-shape and usage receipts with the baseline; never log prompt or response content.
4. Canary the pinned artifact on an isolated workspace with zero customer traffic. Promote only after owner approval and threshold checks; monitor errors, latency, rate limits, and spend during the rollout.
5. If any gate fails, stop promotion, restore the prior lockfile/revision, revoke temporary credentials, and preserve the redacted migration receipt.

Output

Produce a migration receipt containing source and target SDK versions, API-version header, lockfile/artifact digests, test and canary results, model IDs, workspace/environment, approval, rollout state, rollback reference, and retention deadline. Exclude API keys, prompt/response text, customer identifiers, and raw exception payloads.

Error Handling

Examples

For a synthetic migration fixture, pin anthropic from 0.39.0 to the reviewed target, run 100 sandbox Messages API calls with customer=fixture-017, assert response-shape parity and customer_content_logged=0, then promote to a 1% internal canary. A failed threshold yields promotion=halted; rollback=prior-lockfile.

Resources

• Python SDK Changelog
• TypeScript SDK Changelog
• API Versioning

Next Steps

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