Migrating to Claude Sonnet 5.5 means switching to claude-sonnet-5-5, adapting to adaptive thinking being enabled by default, removing non-default temperature, top_p, and top_k values and legacy assistant prefills, replacing forced tool use with auto plus strict tools, and reading and returning thinking blocks by block type.
Suitable tasks: Migrating a Messages API integration from Claude Sonnet 5, Sonnet 4.6 or earlier Sonnet models, or Haiku 4.5 to Sonnet 5.5, including checks for the agent loop, tool use, computer use, and thinking handling.
Not suitable for: Treating this as a complete migration guide for other models or non-Messages API products, or assuming that old effort levels, thinking budgets, token costs, or block handling remain equivalent.
Applicable model versions: The target model is claude-sonnet-5-5; the guide covers Claude Sonnet 5, Sonnet 4.6, Sonnet 4.5, Sonnet 4, Claude 3.7 Sonnet, and Claude Haiku 4.5.
Applicable client, agent, or API: Messages API. Claude Managed Agents only require a model-name update; Amazon Bedrock and Google Cloud require the platform-specific model IDs, computer-use tools, and structured-output capabilities described on the page.
Recommended reasoning levels and parameters: Sonnet 5.5 has five levels: low, medium, high, xhigh, and max. The Claude API defaults to high. Start at medium for well-specified agentic coding and multistep tool use, move to high for harder tasks, and re-run an effort sweep and cost baseline after migration.
The following Python request is the Sonnet 5.5 example published in the migration guide. It sets effort and reads the response by block type. The example omits five settings that return 400: thinking budgets, sampling parameters, assistant prefills, forced tool choice, and thinking: {"type": "disabled"}.
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Analyze the trade-offs between microservices and monolithic architectures",
}
],
output_config={"effort": "medium"},
)
print(f"Stop reason: {response.stop_reason}")
for block in response.content:
if block.type == "text":
print(block.text)When the thinking field is absent, Sonnet 5.5 uses adaptive thinking by default. To keep the low-thinking mode that only produces updates between tool calls, use thinking: {"type": "between_tools"}. This setting accepts only low, medium, and high; xhigh and max return 400.
Before (Claude Sonnet 5):
client.messages.create(
model="claude-sonnet-5",
max_tokens=16000,
thinking={"type": "disabled"},
output_config={"effort": "xhigh"},
messages=[{"role": "user", "content": "..."}],
)After (Claude Sonnet 5.5):
client.messages.create(
model="claude-sonnet-5-5",
max_tokens=16000,
thinking={"type": "between_tools"},
output_config={"effort": "high"},
messages=[{"role": "user", "content": "..."}],
)Official boundary: between_tools requires no beta header. It cannot be sent with display, budget_tokens, or block_binding. With server-side fallback, a request that falls back to Sonnet 5 uses thinking: {"type": "disabled"} on the fallback model.
When migrating from Sonnet 4.6 or earlier, a fixed thinking budget returns 400. Anthropic recommends adaptive thinking plus effort and a fresh evaluation at two or three levels; there is no fixed mapping from a budget to an effort level.
Before (Claude Sonnet 4.6):
client.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "..."}],
)After (Claude Sonnet 5.5):
client.messages.create(
model="claude-sonnet-5-5",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "high"}, # or "max", "xhigh", "medium", "low"
messages=[{"role": "user", "content": "..."}],
)Sonnet 5.5 rejects tool_choice types tool and any, including on the token-counting endpoint. During migration, use auto. To make tool input match the schema, mark tools that need strict validation with strict: true and state in the prompt when to call them. Strict tool use requires additionalProperties: false on every object and allows at most 20 strict tools per request. Amazon Bedrock does not provide structured outputs for Sonnet 5.5, so use auto without strict there and validate tool input in your code.
Before (Claude Sonnet 5):
client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "tool", "name": "get_weather"},
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)After (Claude Sonnet 5.5):
client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
# strict tool use: every call matches the tool's input_schema
tools=[{**tool, "strict": True} for tool in tools],
tool_choice={"type": "auto"},
messages=[
{
"role": "user",
"content": "What's the weather in Paris? Use the get_weather tool.",
}
],
)The guide gives this Claude API skill command for Claude Code. It first asks you to confirm the migration scope, then applies model ID, breaking-parameter, prefill-replacement, and effort-calibration changes, and produces a checklist for manual verification:
/claude-api migrate this project to claude-sonnet-5-5This command is part of the Claude Code workflow published on the Anthropic page; whether it is available depends on the current Claude Code and skill environment.
Change the model ID to claude-sonnet-5-5; use the ID listed under Availability on other platforms.
Read content by block type and pass thinking blocks back unchanged in the tool-use loop, including empty blocks.
If you do not want up-front thinking, use between_tools at high effort or below.
Replace forced tool use with auto plus strict tools; on Amazon Bedrock, use auto without strict.
Keep the conversation append-only; use mid-conversation system messages when changing instructions or tools.
On the Claude API and Google Cloud, move computer use to computer_toolset_20260801 and remove the fine-grained-tool-streaming-2025-05-14 beta header.
Pair the advisor tool only with supported advisors and expect an encrypted advisor_redacted_result.
Read text between tool calls from thinking blocks.
Handle refusal and configure fallback.
Re-run the effort sweep and establish a new cost baseline.
Account for thinking being enabled by default when the thinking field is absent, and revisit max_tokens.
Remove fixed thinking budgets and use effort.
Remove non-default temperature, top_p, and top_k; non-default values return 400 on Sonnet 5.5.
If you display thinking text, set display: "summarized".
Recount tokens and revisit the image-token budget.
Remove assistant prefills. For classification, use structured outputs or a tool with enum fields; move continuations, context reminders, and preambles to the user turn or system prompt.
Parse tool-call input with a standard JSON parser.
Computer use no longer accepts computer_20250124; switch to the toolset or computer_20251124 as required by the platform.
Set output_config.effort explicitly.
Remove the context-window beta header.
Remove interleaved-thinking-2025-05-14; replace fine-grained-tool-streaming-2025-05-14 with eager_input_streaming: true on tools that need it.
Move output_format to output_config.format; the old field requires the structured-outputs beta header and is deprecated.
Check the official migration guide for changes to the legacy text_editor_20250728 and code_execution_20260521 tools, the model_context_window_exceeded error, and trailing newlines in tool strings.
Remove the legacy token-efficient-tools-2025-02-19 and output-128k-2025-02-19 beta headers.
Sonnet 4 has been retired from the Claude API but remains available on Amazon Bedrock and Google Cloud; distinguish platforms in a migration plan.
Replace claude-haiku-4-5-20251001 or the claude-haiku-4-5 alias with claude-sonnet-5-5.
Recount tokens and establish a cost baseline; the page says Sonnet 5.5 has a higher price per token and produces more tokens for the same text.
Re-check prompt caching: the guide says the minimum cacheable prompt length changes from 4,096 tokens on Haiku 4.5 to 512 tokens on Sonnet 5.5.
Remove the interleaved-thinking beta header; adaptive thinking runs between tool calls automatically.
When moving from Haiku 4.5 to Sonnet 5.5, Sonnet 5.5 can read Haiku 4.5 thinking blocks. Moving back to Haiku 4.5 drops Sonnet 5.5's blocks.
| Old setting or behavior | Sonnet 5.5 handling |
|---|---|
thinking: {"type": "disabled"} | 400; use {"type": "between_tools"} to turn off up-front thinking |
thinking: {"type": "enabled", "budget_tokens": N} | 400; use adaptive and output_config.effort |
Non-default temperature, top_p, or top_k | 400; remove these parameters |
tool_choice: {"type": "tool"} or {"type": "any"} | 400; use {"type": "auto"} and strict tools where needed |
| Assistant prefill | 400; use structured outputs, tools, the system prompt, or a user turn as appropriate |
Reading only content[0].text | Can fail when the first block is thinking; read by block type |
| Dropping thinking blocks in the tool loop | Can disrupt later calls; pass blocks back unchanged, including empty blocks |
| Editing signed conversation history | Can return 400 by default for accounts created after 2026-08-31; keep conversations append-only |
computer_20251124 on the Claude API / Google Cloud | 400; use computer_toolset_20260801 |
fine-grained-tool-streaming-2025-05-14 sent with the toolset | 400; use eager_input_streaming: true on each applicable tool |
interleaved-thinking-2025-05-14 | Remove it; adaptive thinking interleaves automatically |
Thinking blocks are tied to the model and the conversation. Sonnet 5.5 can read blocks from Sonnet 5, Opus 4.8, Haiku 4.5, and earlier models, but not from Opus 5, Opus 5.5, Fable, or Mythos models. The API drops blocks the model cannot read, still returns 200, and does not bill for the dropped blocks. Thinking blocks generated by Sonnet 5.5 work only in the account that generated them or an account linked to it.
Longer text between tool calls returns as progress-update thinking blocks, with an empty thinking field at the default display. To show progress, adaptive thinking can use display: "updates" and the beta header described on the page, or display: "summarized". Render every non-empty thinking block before the following tool_use block.
Safety refusals can return stop_reason: "refusal", with categories including cyber, bio, frontier_llm, reasoning_extraction, and general_harms. Claude API server-side fallback retries cyber and frontier_llm, but does not retry the other three categories.
The most likely sources of 400 errors or silent behavior changes when migrating to Sonnet 5.5 are thinking configuration, sampling parameters, assistant prefills, forced tool choice, the computer-use toolset, and reading or returning thinking blocks. A successful API response does not prove that the agent loop is correct: a client that reads only text blocks can appear silent during a long tool run, and dropping thinking blocks can remove context needed for later tool interactions.
Quality, latency, and cost after migration cannot be inferred from the old model's same-named effort level. The guide requires a fresh effort sweep. It explicitly compares token changes for Sonnet 4.6, Sonnet 4.5, and Haiku 4.5: the same text produces about 30% more tokens, while maximum image resolution and visual-token budgets also change. Do not extrapolate that figure to Sonnet 4 or Claude 3.7 Sonnet. The guide's pricing note says Sonnet 5.5 and Sonnet 5 have the same prices, while prompt cache reads cost $0.10 per million tokens, half the Sonnet 5 rate; check the current Claude pricing page for the current price.
Using the before/after code on this page, you can send the same Messages API request to Sonnet 5, Sonnet 4.6 or Haiku 4.5 and Sonnet 5.5, recording HTTP status, stop_reason, content-block type, tool choice, thinking round-trip, token billing, and latency. To fully reproduce the guide's migration behavior, you would also need to fix the platform, model deployment, SDK version, beta headers, tool schema, account-creation date, fallback configuration, and conversation history. The page does not determine all of these environment conditions.
Claude Sonnet 5.5