Migrating to Claude Sonnet 5.5: 7 essential tips for a clean switch

1. Claude Sonnet 5.5 keeps the price and changes the defaults

Features overview. Anthropic released Claude Sonnet 5.5 on September 28, 2026. The model overview lists the ID as claude-sonnet-5-5 with no date suffix (anthropic.claude-sonnet-5-5 on Bedrock), a 1M-token context window and 128K max output, or 300K on Message Batches with the output-300k-2026-03-24 beta header. Adaptive thinking is on by default, and effort runs from low to max, defaulting to high.

Prices are $2 / $10 per million input / output tokens and $0.20 for cache reads, identical to Sonnet 5. The pricing page also confirms that Sonnet 5's planned increase to $3 / $15 on September 1 will not happen, so staying on Sonnet 5 a little longer costs nothing extra.

Key differences. Per what's new in Sonnet 5.5, the same text produces the same token counts as on Sonnet 5. Coming from 4.x, the migration guide counts about 30% more tokens for the same text and about 2.5 times as many for a 2000×1500 image.

Anthropic's announcement says Sonnet 5.5 is 30%+ faster than Sonnet 5 and, at Low or Medium effort, beats Sonnet 5's best score "for about a tenth of the cost per task". Artificial Analysis looked at the other end of the dial. At max it scores 56 on their Intelligence Index, two points behind Opus 5.5, but used about 193K output tokens per task and cost $7.60 per task, roughly 50% more than Sonnet 5. Rajesh Beri's comparison of the same data has Opus 5.5 at xhigh reaching that 56 for $3.46.

So the per-task bill depends mostly on the effort level you pick, and cheaper is something you verify on your own traffic.

2. Prepare for migrating to Claude Sonnet 5.5 before you touch the model ID

Inventory what breaks. A plain text search across the repo finds nearly everything, as long as it covers config and wrapper-library settings, not only your own API calls.

Build the eval before the swap. Capture a baseline on the current model first, or every later comparison runs on memory. Anthropic's guide to building evals says to "mirror your real-world task distribution" and adds that more questions with automated grading beat fewer hand-graded ones. A hundred real requests from last week's logs beat twenty showcase prompts.

Let tools do part of it. In Claude Code, /claude-api migrate this project to claude-sonnet-5-5 runs the bundled migration skill, which swaps IDs, rewrites breaking parameters and prefills, and "produces a checklist of items that require manual verification". The guide's ant CLI samples won't help on Bedrock, which the Bedrock page says the CLI does not support.

3. Prompt engineering techniques for Sonnet 5.5 start with deleting lines

The Sonnet 5.5 prompting page opens with: "Existing Claude Sonnet 5 prompts should perform well without changes." The trouble is in the corrective lines teams piled up over earlier model generations.

What to remove. The best-practices page says to dial back anti-laziness prompting: where you wrote "CRITICAL: You MUST use this tool when...", plain "Use this tool when..." is enough. Drop "minimize tool calls" and "only use tools when strictly necessary", and drop "hold all findings for the final response", which suppresses the progress notes the model now writes between tool calls.

Two removals matter more than the rest. Asking the model to think less "doesn't reliably reduce its thinking", and with between_tools it makes the model "more likely" to leak internal XML tags into visible output, so lower the effort instead. And prompts asking the model to write out its reasoning now invite reasoning_extraction refusals.

What to add. The prompting page documents a few lines with measured effects.

Testing and refining. Effort is now the main dial, and the level you ran on Sonnet 5 deserves a re-test rather than a copy. The effort docs say: "Start at high unless your workload is agentic or latency-sensitive. For agentic coding and multistep tool use, start at medium for well-specified tasks and move to high for harder or longer ones. For chat and other latency-sensitive work, start at medium or low." Then run your eval at two or three levels. We put every agent build through this sweep before a model change, and it is the step we would keep if we could keep only one.

4. Five settings from Sonnet 5 now return a 400

The release notes put it plainly: "Code written for Claude Sonnet 5 can break on Claude Sonnet 5.5 in five ways." Each fails loudly, in the first test run.

Thinking off has rules. between_tools works only at high effort or below, allows no other field inside thinking, and rejects per-message effort changes. Before using it, try adaptive thinking at low, where the model "skips thinking on most simple requests". Addy Osmani's launch post notes that with between_tools "total response time is the same or faster". Measure both.

Check your wrappers. In a kinby issue, "Recap fails on claude-sonnet-5-5 because it forces tool_choice" - the code never set tool_choice itself. LangChain's with_structured_output() did, and the fix was method="json_schema". Since auto does not guarantee a call, check that it happened. On Bedrock, structured outputs and strict tool use aren't available for Sonnet 5.5, so validate in your own code.

Thinking blocks are bound. Sonnet 5.5 reads blocks from Sonnet 5, so live conversations carry over, but no other model reads Sonnet 5.5's blocks; they are silently dropped. The preserved thinking docs add a history check for accounts created on or after August 31, 2026 on the Claude API, Bedrock and Google Cloud: replaying a block after editing the system prompt, tools or earlier messages is a 400. Beri reports the Turnstone framework's automatic compaction failing on exactly this.

Legacy considerations. From Sonnet 4.6 or earlier, budget_tokens must become an effort level. From Sonnet 4.5 and Haiku 4.5, assistant prefills return a 400. Haiku 4.5 users may want to wait: VentureBeat reports Haiku 5.5 is due within weeks.

5. The new Claude Sonnet features pay off in cache hits and latency

Per-message effort (beta mid-conversation-output-config-2026-07-01) lets one hard question run at high inside a low session. That matters because changing top-level effort between requests "invalidates prompt caching", per the effort docs. It needs adaptive thinking.

Mid-conversation system messages and inline tools let you add an instruction or a tool by appending instead of editing the system prompt, which keeps earlier thinking blocks valid. One caution from the prompting page: "Never put user text inside a tool_result block".

Compaction on demand (beta compact-2026-09-04, since September 14) gives long agent sessions a controlled point to shrink context instead of hand-editing history.

Progress notes changed shape. Text between tool calls now arrives in thinking blocks, empty by default, so a UI that renders only text goes quiet with no error. Set display: "updates" or "summarized" with adaptive thinking.

Smaller things add up too. The tool-use system prompt is 286 tokens against 354 on Sonnet 5, and short prompts now cache from 512 tokens. Lovable told VentureBeat it saw one-third fewer tool calls, though that is their workload and not yours.

6. After the switch, measure cost per completed task

With the same per-token price, the number that moves is cost per completed task: every token spent, thinking included, divided by the tasks that passed your eval.

Refusals cost money again. A refusal is an HTTP 200 with stop_reason: "refusal". Since September 24, pre-output refusals in bio, frontier_llm and reasoning_extraction are billed. Server-side fallback retries only cyber and frontier_llm on Sonnet 5; the rest is yours to handle.

Silent regressions. Some failures never throw. A router switch or fallback runs the next turns without Sonnet 5.5's reasoning. A stop_reason: "max_tokens" with JSON that happens to parse is still a failure; for agentic coding the docs recommend max_tokens of 128,000 with streaming.

Close the loop. Assert that response.model starts with claude-sonnet-5-5 in your smoke test. Mind the prefix: it also starts with claude-sonnet-5, so an old Sonnet 5 check passes on both. Unmeasured changes are the thread running through why AI deployments fail, and a model swap is one.

7. Put the next model swap on a schedule

The useful output of this migration is a procedure you can repeat. The deprecation page promises "at least 60 days' notice" before retirement and lists the earliest dates.

Bookmark the release notes, the deprecation page and the per-model prompting page. The best-practices page adds the rule behind every tip here: re-check a prompt "against your own evals before applying it to another" model. The changelog below records each time we re-check the dates here.

It is also a good moment to ask whether a route needs a model at all; agents vs workflows covers that trade-off.

The Sonnet 5.5 migration checklist you can run alone

Capture a baseline on the current model: pass rate, tokens, tool calls, latency.

Search the repo using the table in tip 2, wrappers and config included.

Swap the ID to claude-sonnet-5-5 (anthropic.claude-sonnet-5-5 on Bedrock).

Replace disabled thinking with adaptive at low, or between_tools at high or below.

Replace forced `tool_choice` with auto plus strict: true or structured outputs, and check the call happened.

Clean 4.x leftovers: budget_tokens, sampling parameters, prefills.

Keep history append-only and pass thinking blocks back unchanged.

Update computer use and advisor pairings.

Handle refusals by category before reading content.

Edit prompts: remove think-less and write-your-reasoning lines, add the documented paragraphs.

Sweep effort at two or three levels and set it explicitly.

Re-baseline cost per completed task and p95 latency, and assert the response.model prefix.

If you want a second pair of eyes on an agent running on Claude, that's part of what we look at when you book a free process audit. The checklist works fine without us, and the first two items are worth doing this week even if the switch waits a month.

FAQ