How to Migrate a Production Agent from Claude Sonnet 4.5

The dates below apply to Anthropic-operated platforms: the Claude API, Claude Platform on AWS, and Microsoft Foundry. Amazon Bedrock and Google Cloud set their own retirement schedules, so check your provider's model table if you call Claude there.

Claude Haiku 4.5 is not in this list. As of October 6, 2026 it is active, with retirement not sooner than October 15, 2026 and no retirement date announced.

These return a 400 error on Claude Sonnet 5.5, so they show up immediately in testing. Anthropic's migration guide lists the full set; these are the ones agents hit most often.

Thinking is on by default. A request with no thinking field now runs adaptive thinking. Code that reads content[0].text can break because a response may start with thinking blocks, max_tokens now covers thinking plus text, and thinking tokens are billed as output.

Tool calls are no longer guaranteed. Replacing forced tool use with auto means the model can answer without calling the tool. For an agent, this is the change most likely to cause a silent regression: an answer that sounds right but skipped the lookup it depended on.

Token counts and costs move. Sonnet 5.5 uses a new tokenizer that produces about 30% more tokens for the same text than Sonnet 4.5, effort levels are recalibrated, and images can cost more at the higher resolution tier. Re-baseline cost and latency rather than assuming parity.

More requests can be declined. Sonnet 5.5 declines in more categories, returning stop_reason refusal. Handle that stop reason explicitly so a refusal is not mistaken for an empty answer.

History must be append-only. For accounts created on or after August 31, 2026, replaying a thinking block after editing earlier conversation history returns a 400 error. Agents that rewrite or trim history need to change how they do it.

1. Inventory every call site. Find each request that names Sonnet 4.5 and note which of the settings above it uses. Anthropic's Claude API skill can apply the mechanical changes: in Claude Code, run /claude-api migrate with claude-sonnet-5-5 as the target, then review its checklist.

2. Freeze a baseline. Record the current prompt, tools, and model ID, and count the failure patterns you care about on recent production traffic so you have something to compare against.

3. Fix the hard errors. Work through the table above until every request succeeds on Sonnet 5.5 with no 400s.

4. Compare old and new on the same scenarios. Run real production scenarios, plus cases the agent already handles well, against both models several times each, with the prompt held constant. The regression testing guide covers what to measure. Pay special attention to tool-dependent flows now that tool use is no longer forced.

5. Tune one thing at a time. If the new model regresses, change the prompt or the effort level in small steps and re-run the same comparison. The guide to why AI agents regress after prompt or model changes covers how to isolate the cause.

6. Roll out gradually and verify on live traffic. Send part of the traffic to Sonnet 5.5 first and count the same failure patterns on both. The fix verification calculator shows whether a difference is bigger than chance.

7. Finish before the deadline. Rolling back to Sonnet 4.5 stops being possible on November 30, so leave time to fix what step 6 finds.

This example is constructed to show the risk; it is not customer data. A support agent on Sonnet 4.5 forced an order-lookup tool on refund questions with tool_choice tool. On Sonnet 5.5 that request returns a 400, so the team switches to tool_choice auto with a strict tool. Every request now succeeds, and spot checks look fine.

A head-to-head run on last month's refund conversations shows the difference: on a share of them, the new configuration answers from the conversation instead of calling the lookup, and quotes the wrong order status. The fix is an explicit instruction that a lookup is required before any refund answer, verified by re-running the same scenarios and then counting the pattern on live traffic.

Converra supports both Claude Sonnet 4.5 and Claude Sonnet 5.5. For a model swap, it compares the old and new model at the same prompt over a seven-day window on each side and needs at least 30 scored runs per model. It marks the swap regressed if mean quality drops by more than 5 points or the failure rate rises by more than 2 percentage points, and otherwise parity verified if cost per run fell or parity without savings if it did not. If the prompt changed during the window, the result is confounded.

Before the swap, Converra can run candidate models against the same regression suite it uses for prompt changes, so the head-to-head comparison in step 4 does not have to be built by hand.