Migrating to Claude Sonnet 5.5: fix rejected settings and missing progress updates
Check request compatibility, response rendering, and tool-loop state before switching production traffic.
A model upgrade can fail loudly with HTTP 400, or quietly with a successful request that no longer shows progress. Claude Sonnet 5.5 changes both request compatibility and response shape. Replacing the model ID is only the beginning of a Messages API migration.
This guide is for integration maintainers. Anthropic says Claude Managed Agents needs no change beyond the model name; people using a product's model picker do not need to edit API parameters themselves. The examples below explain documented interfaces, not a tested production deployment.
Start with the model you are leaving
For Sonnet 5, check thinking-off settings, forced tool use, history replay, computer use, and advisor pairings. From Sonnet 4.6 or earlier, also inspect manual thinking budgets, sampling parameters, and token counts. From 4.5 or earlier, review assistant prefill and legacy beta headers.
The tokenizer is unchanged from Sonnet 5. Against Sonnet 4.6, 4.5, or Haiku 4.5, Anthropic reports roughly 30% more tokens for the same text, depending on content. Those are different migrations, not a single universal token increase. Capture the starting model, platform, SDK, tool schemas, thinking configuration, and a raw response before editing anything.
Remove incompatible request settings first
Use claude-sonnet-5-5. Adaptive thinking is on by default, and Claude API effort defaults to High. thinking: {"type":"disabled"} now fails. To remove up-front thinking, use between_tools at Low, Medium, or High.
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=4096,
thinking={"type": "between_tools"},
output_config={"effort": "high"},
messages=[{"role": "user", "content": "Summarize the supplied release notes."}],
)
Do not add display, budget_tokens, or block_binding to between_tools. It does not support Xhigh, Max, or changing effort mid-conversation. Use adaptive thinking for those cases, checking the relevant beta requirements. Without tools, between_tools answers without up-front reasoning, so it is not a universal optimization for reasoning tasks.
Forced tool_choice types any and tool also fail. Use auto, explain when a tool applies, and apply strict tool schemas where supported. Strict constrains arguments when a call happens; it does not force a call. Sonnet 5.5 on Amazon Bedrock does not support strict tool use, so validate inputs in the application.
For older starting models, replace enabled thinking budgets, non-default temperature/top_p/top_k, and assistant prefill. There is no fixed budget-to-effort conversion. Test two or three levels instead of translating a token budget mechanically.
A silent interface may be a renderer problem
Longer notes between tool calls now arrive as progress-update thinking blocks; shorter remarks can remain text. With adaptive thinking and the default display: "omitted", those blocks contain empty visible thinking text. A text-only renderer can therefore look idle while the agent continues.
Check transport, tool execution, and rendering separately. Blind retries can duplicate side effects without restoring progress. Under adaptive thinking, display: "updates" returns updates and requires the thinking-display-updates-2026-08-18 beta header. summarized mixes updates with reasoning summaries. Under between_tools, summaries are returned without a display field.
Read content by block type rather than assuming content[0].text. In tool loops, return assistant blocks unchanged, including empty thinking blocks and signatures. A user-visible summary is not a substitute for the protocol block that must be replayed.
Preserve history and check platform-specific tools
Sonnet 5.5 thinking blocks bind to the producing model and the preceding conversation. For accounts created from August 31, 2026, 00:00 UTC, prefix checks are enforced by default. Editing earlier messages, system instructions, or tools before replaying a block can produce HTTP 400.
Prefer append-only history and documented mid-conversation updates. An unreadable block from another model can be dropped while the request still succeeds; HTTP 200 does not prove all prior reasoning survived a model switch.
Claude API and Google Cloud require computer_toolset_20260801 for computer use, whereas Amazon Bedrock still accepts computer_20251124. Advisor integrations also need a supported model pairing and must handle encrypted results. A Claude API example is not automatically portable to every provider.
A migration walkthrough: isolate the request, tools and history
This is a constructed debugging example based on the documented API rules, not a production incident. Suppose an older Sonnet 5 integration disables thinking, forces a lookup tool, renders only text blocks and compresses history into a summary after each turn. Changing its model ID can expose three separate problems.
First, fix request rejection. The request contains both thinking.type=disabled and tool_choice.type=any. Fixing only one may still leave an invalid request. Keep the original error response, switch to a supported thinking configuration in an isolated environment, then change tool selection to auto. Removing every tool and all history just to get a 200 tests a different request; it does not establish that the original workflow works.
Second, test the tool call independently. Auto does not mean guaranteed invocation. Use an input that genuinely requires the lookup and have the test tool return a recognizable marker. Check the tool name, arguments and whether the result reaches the final answer. If the task needs current inventory but the model gives a number without a lookup, a successful response is not a pass. Business preconditions that must be guaranteed still need application-level checks; strict argument validation is not a replacement.
Third, repair progress and history handling. Once the request succeeds, inspect raw content and streaming events before treating a quiet interface as a failed task. Send displayable updates to the UI while retaining complete protocol blocks for the next turn. A text-only array with empty blocks removed cannot safely serve both purposes. Test long-session compaction separately: arbitrary rewriting by an older integration is not automatically a supported compaction protocol.
These stages have different exit criteria: a valid request, a completed tool cycle and a continuable history. Passing one does not certify the next. Verify exact response formats against the current SDK and documentation; this walkthrough is not a complete adapter to paste into production.
Keep evidence that distinguishes failure modes
Logs should answer five questions: which model and thinking/effort configuration ran; which request or tool call failed; what the stop reason was; which content block types appeared; and whether execution already produced a side effect. Raw blocks containing signatures, customer data or credentials need access controls, not public logging.
| Observation | First evidence to inspect | What it does not establish |
|---|---|---|
| HTTP 400 | Full error fields, old thinking/tool_choice and platform differences | That task capability deteriorated |
| 200 with no visible progress | Block types, display settings, renderer and streaming parser | That tools did not run |
| Tool succeeds but answer omits its data | tool_result association and the complete next-turn message | That the result was correctly used |
| Failure after history editing | Signed blocks, prefix changes, account and cross-model rules | That a retry will fix it |
| Reply ends before delivery | stop_reason, max_tokens, tool results and task state | That receiving text means completion |
The point is to avoid the wrong recovery action, not to collect more text. If a write succeeded but the display connection broke, replaying the entire turn may duplicate the write. The application must consult its own transaction state before retrying. A model migration does not provide business deduplication or rollback.
Roll out through three regression gates
First test the protocol: plain text, one real tool loop, progress rendering, refusals, and max_tokens termination. Then test history: appended turns, model switches, supported compaction, and saved-session replay. Finally test business delivery with fixed inputs and acceptance criteria, recording quality, elapsed time, consumption, and rework.
Begin with read-only tools and test data. Expand to side effects only when retries cannot duplicate writes and rollback is explicit. Effort calibration comes after compatibility, not instead of it.
FAQ
Is changing the model ID enough?
Not necessarily for Messages API. Managed Agents has a different documented migration scope.
Does strict replace forced tool use?
No. It validates the shape of a call, not whether a call will occur.
Can empty thinking blocks be deleted?
Hide empty text in the UI if needed, but preserve protocol blocks unchanged in the tool loop.
Does no HTTP 400 mean migration is complete?
No. Validate progress, history, side effects, and accepted business output.