The Claude Sonnet 5.5 migration checklist
1. Change the model ID in a test environment
Set the model to claude-sonnet-5-5. Keep the old model available as a rollback path until the new configuration passes your evaluation set.
Do not begin with live customer traffic. Use sanitized inputs that represent your real mix of short requests, long context, tool calls, images and refusal-sensitive tasks. Record the old model's accepted result rate, latency, token use, tool failures and review time before changing anything.
Pass condition: the test client reaches the intended model, returns a valid response and leaves production routing unchanged.
2. Replace unsupported thinking settings
Sonnet 5.5 uses adaptive thinking when the request omits the thinking field. A configuration that sends thinking: {"type": "disabled"} returns a 400 error.
If you need to avoid thinking before the first answer, Anthropic directs developers to use thinking: {"type": "between_tools"} at low, medium or high effort. This setting is not accepted at xhigh or max. It also cannot include display, budget_tokens or block_binding.
If you are migrating from Sonnet 4.6 or earlier, remove fixed thinking budgets and choose an effort level instead. There is no direct conversion from a token budget to an effort setting, so test more than one level.
Pass condition: every supported reasoning mode completes without a 400 error and stays within the workflow's time and cost limits.
3. Parse response blocks by type
A Sonnet 5.5 response can begin with a thinking block. Code that assumes content[0].text can break even when the API request succeeds.
Iterate through content blocks and handle each supported type deliberately. In tool loops, pass thinking blocks back unchanged, including empty blocks. Anthropic also notes that longer progress updates between tool calls can arrive as thinking blocks rather than text blocks. A user interface that reads only text blocks may appear silent during a working run.
Pass condition: text, thinking, tool-use and refusal paths render or log as intended, with no missing progress state.
Sonnet 5.5 rejects tool_choice values that force any or a named tool. Anthropic recommends auto, with strict tool schemas where the platform supports them, plus clear instructions that describe when a tool should be used.
This changes the control boundary. Under auto, the model can answer without calling a tool. Your application must validate whether the required action occurred instead of assuming the request parameter guaranteed it.
On Amazon Bedrock, strict structured tool use is not available for Sonnet 5.5, according to Anthropic's migration guide. Use auto, explain the trigger in the prompt and validate inputs in application code.
Pass condition: required tool calls occur in representative cases, optional calls remain optional and every tool input passes schema and permission checks.
5. Keep conversation history append-only
Sonnet 5.5 thinking blocks are signed against the conversation that produced them. Editing earlier messages and then replaying a later block can produce a 400 error on accounts where this enforcement applies.
Keep stored history append-only. If instructions or tools need to change during a conversation, use the supported mid-conversation mechanisms rather than rewriting previous turns. Also test any workflow that moves conversations between models or accounts because compatibility differs by source model and account relationship.
Pass condition: multi-turn and tool-use conversations can be replayed without modified history, dropped state or signature errors.
If your workflow uses computer use, confirm the correct tool version for your platform. Anthropic states that the Claude API and Google Cloud use the computer_toolset_20260801 toolset for Sonnet 5.5, while Amazon Bedrock uses computer_20251124. Older computer tool versions can return errors.
Handle stop_reason: "refusal" explicitly. Sonnet 5.5 can decline requests in categories including cyber, biology, frontier-model development, reasoning extraction and general harms. A refusal is not a normal completion and should not be silently converted into an empty answer or an automatic retry loop.
Pass condition: the correct platform tool version works, refusals create a visible controlled state, and no retry path bypasses safety or permissions.
7. Re-run evaluations and re-baseline cost
Do not carry forward an effort setting only because its name is familiar. Anthropic says the effort levels are recalibrated. Its migration guide suggests starting at medium for well-specified agentic work, moving to high for harder or longer tasks, and testing lower settings for latency-sensitive work.
Measure complete-task cost rather than token price alone:
complete-task cost = model tokens + tool fees + retries + review time + failure impact
Use the same inputs, tools, permissions and acceptance rubric for the old and new configurations. Record accepted results, not attractive demos. A shorter or faster response is useful only if it still meets the task's quality and safety bar.
Pass condition: the chosen effort level meets the acceptance threshold at a documented complete-task cost, with a rollback trigger defined.
A safe migration test plan
Use this sequence for one workflow before a wider rollout:
- Freeze a representative set of sanitized test cases.
- Record the current model, parameters, tool versions and baseline results.
- Apply the seven migration changes in a separate environment.
- Run automated schema, tool and output checks.
- Review failures and refusals as evidence, not noise.
- Compare quality, latency, token use, retries and human review time.
- Send a small percentage of eligible traffic to the new configuration.
- Expand only after the acceptance gate remains stable.
For high-impact actions, keep human approval outside the model. A successful migration test does not authorize payments, account changes, legal decisions, security changes or irreversible actions.
Example acceptance gate
Imagine a support-drafting workflow that retrieves approved policy text, drafts a reply and routes uncertain cases to a person. A reasonable gate could require:
- every factual claim is traceable to the retrieved policy source
- required escalation categories never receive an automatic final reply
- tool inputs pass the schema and access policy
- refusals and missing context create a visible review state
- median reviewer correction time does not exceed the baseline
- complete-task cost stays inside the team's approved range
This is an illustrative gate, not a benchmark. Your thresholds should reflect the consequences of error in your own workflow.
What not to infer from the launch
Anthropic's speed, benchmark and cost-per-task claims describe its evaluations and selected early tests. They do not prove that Sonnet 5.5 will be faster, cheaper or more accurate for your prompts and tools.
The release also does not remove the need for source validation, access controls, monitoring, fallbacks or human review. A capable model can still fail on ambiguous instructions, missing context, unsafe tool permissions or untested response handling.
Bottom line
Claude Sonnet 5.5 can be a practical upgrade for well-scoped API workflows, but the reliable path is a controlled migration. Update the model ID, then test thinking behavior, block parsing, tool choice, conversation integrity, platform tools, refusals and complete-task cost. Promote the new configuration only when it passes the same acceptance gate as the workflow it replaces.
Sources
Verified October 2, 2026.
Keep building
