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

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

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

Failure	Response
Dependency or API contract test fails	Pin the prior version, isolate the failing fixture, and do not promote.
Authentication or permission failure	Stop the canary, verify the secret-manager reference and workspace scope, and never print the key.
429/5xx, timeout, or latency regression	Respect SDK retry guidance, apply a bounded circuit breaker, and roll back when the canary threshold is exceeded.
Response-shape or tool-use drift	Quarantine the result, update the adapter only after an approved contract decision, and rerun the full suite.

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

Next Steps

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

anth-upgrade-migration