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