"Blue/green" is a deployment technique borrowed from ordinary software operations: you run the old version (blue) and the new version (green) side by side, shift a small share of traffic to green, watch it, and only then cut over — keeping blue warm for instant rollback. It maps cleanly onto Claude model upgrades, because a model swap changes more than answer style.
Why a model swap is a real change
Four documented behaviors make "just change the model ID" riskier than it looks:
- Token counts shift. Claude Opus 4.7 and later, Fable 5, and Sonnet 5 use a newer tokenizer that produces roughly 30% more tokens than earlier models for the same text. Re-run token counts against the model you will actually serve, or your cost and context-budget math will be wrong.
- Parameters that worked may now be rejected. On Fable 5 and Opus 4.8/4.7, sending
temperature,top_p,top_k, or a manual thinking budget (thinking: {"type": "enabled", "budget_tokens": N}) returns a 400 error; these models use adaptive thinking ({"type": "adaptive"}). Newer models also no longer support prefilled assistant messages — migrate to structured outputs. - Prompt caches are model-scoped. Switching models forces a full cache rebuild, so the first minutes of a cutover pay uncached input prices. Budget for it; don't mistake it for a regression.
- Rate limits are per model. Opus 4.8/4.7/4.6/4.5 share one combined limit bucket, while Sonnet 5 has its own separate limit. A canary can therefore run on fresh headroom — or contend with existing traffic — depending on which pair you're moving between.
The rollout, step by step
1. Pin both versions explicitly. Your gateway or config should carry two concrete model IDs, never an alias. Remember the platform differences: Bedrock prefixes IDs (anthropic.claude-opus-4-8) while Claude Platform on AWS, Vertex AI, and Foundry use bare 1P-style IDs (claude-opus-4-8).
2. Gate on an offline eval run. Before any live traffic, replay a fixed suite of real (sanitized) production prompts through the green model and score the outputs — see Evals in CI for the full pattern. On the first-party API and Claude Platform on AWS, the Message Batches API runs the suite at 50% of standard prices; Bedrock and Vertex AI don't offer that endpoint but have their own cloud-native batch inference for Claude.
3. Canary a deterministic slice. Route a small, sticky share of traffic (hash a stable key such as tenant or user ID) to green in your internal gateway. Stickiness matters: a user bouncing between models mid-conversation also bounces between caches and, on newer models, between thinking behaviors.
4. Watch operational metrics, not just quality. Compare error rates (especially 400s from newly rejected parameters), latency, stop_reason distribution, and per-request token usage between blue and green. The 429/529 handling you already have should ramp green gradually — sharp spikes can trigger the API's acceleration limits.
5. Cut over, keep blue warm. Shift to 100% green but leave the blue model ID configured and its prompts in version control. Rollback is then a config change, with the same cache-rebuild caveat in reverse.
Per-platform notes
| Platform | What to check before flipping traffic |
|---|---|
| Claude Platform on AWS | Same-day model parity with 1P; same rate-limit structure, but organizations stay on the Start tier |
| Amazon Bedrock | anthropic.-prefixed IDs; explicit cache breakpoints only (no automatic caching) |
| Google Vertex AI | Bare IDs for current models; older models use @date form |
| Microsoft Foundry | Bare IDs; some advanced features still beta — re-verify each one on the new model |
Where to go next
Pair this with Evals in CI for the gate, gateway extensions for the traffic split, and version pinning for the config discipline underneath it all.