Migrating to Claude Opus 5.5: Four Breaking Changes to Fix First

Before you start

The SDKs also publish constants, such as Model.CLAUDE_OPUS_5_5 in Java and anthropic.ModelClaudeOpus5_5 in Go. The bare string works everywhere.

The context window (1M tokens), output limit (128K), tokenizer and feature set match Opus 5. Prompt caching, batch, the Files API, vision, structured outputs, task budgets and compaction all carry over. Coming from Opus 4.8 or older, apply the Opus 5 migration steps first, but skip anything about disabling thinking.

1. Thinking can't be disabled

On Opus 5, thinking: {type: "disabled"} was allowed at high effort or below. On Opus 5.5 it returns a 400 at every effort level, and so does a manual budget:

"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

# Before: accepted on Opus 5, 400 on Opus 5.5
client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "..."}],
)

# After: thinking is always on; effort is the control
client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    output_config={"effort": "low"},
    messages=[{"role": "user", "content": "..."}],
)

• Size max_tokens for thinking plus the reply. Thinking counts toward the limit even when its text isn’t returned. Anthropic suggests 64K for long agentic coding turns.
• Read content blocks by type, not position. A response can start with one or more thinking blocks, returned with empty text by default.
• Delete prompts that stood in for thinking. Instructions such as “show your reasoning step by step in the answer” can now be declined under the reasoning_extraction category. Delete any “don’t think” rule too: the model can’t follow it.

Choosing the right effort level is now the main tuning job. Our Opus 5.5 effort levels guide covers it in detail.

2. Forced tool use is rejected

tool_choice: {"type": "any"} and {"type": "tool", "name": "..."} return a 400 on the Messages API, the Batches API and token counting. auto and none still work. How you replace a forced call depends on why you forced it.

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    tools=[{**tool, "strict": True} for tool in tools],
    tool_choice={"type": "auto"},
    messages=[{
        "role": "user",
        "content": "What's the weather in Kochi? Use the get_weather tool.",
    }],
)

# auto doesn't guarantee a call, so check and retry if needed
if not any(block.type == "tool_use" for block in response.content):
    ...

If you only forced a tool call to get JSON back, switch to structured outputs with output_config.format instead. It returns schema-valid JSON without a tool at all.

3. Thinking blocks are tied to the conversation

Opus 5.5 uses what Anthropic calls preserved thinking. Each thinking block records which model produced it and the exact conversation it was produced in. Two rules follow.

Model binding. Opus 5.5 reads thinking blocks from Opus 5 and older Opus, Sonnet and Haiku models, but not from Fable or Mythos. On the Claude API, only Fable 5.1 and Mythos 5.1 read Opus 5.5’s blocks. If a router or fallback moves a conversation from Opus 5.5 to Opus 5, the API drops Opus 5.5’s thinking. The request still succeeds and dropped blocks aren’t billed.

Conversation binding. The API checks that the system prompt, the tools array and every earlier message are byte-identical to when a block was produced. For accounts created on or after August 31, 2026, a replayed block after such an edit returns a 400 on every platform. Older accounts can opt in.

Three common harness patterns break this check. Replace each with its append-only form:

If you can’t make the harness append-only yet, send the thinking-binding-controls-2026-08-01 beta header and set thinking.block_binding.prefix_mismatch_behavior to "drop_block". Affected blocks are then dropped instead of failing the request.

4. Computer use needs the toolset

On the Claude API and Google Cloud, Opus 5.5 accepts computer use only as computer_toolset_20260801. The older computer_20251124 tool returns a 400. On Amazon Bedrock the older tool still works, so no change is needed there.

# Before: 400 on Opus 5.5 (Claude API, Google Cloud)
client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["computer-use-2025-11-24"],
    tools=[{"type": "computer_20251124", "name": "computer",
            "display_width_px": 1024, "display_height_px": 768}],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

# After: no beta header, no name, no display size
client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    tools=[{"type": "computer_toolset_20260801"}],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

The agent loop changes too:

• The action is the tool_use block’s name (screenshot, left_click, type, zoom, ...), not input.action.
• One turn can contain several actions. Return one tool_result per tool_use, all in the next user message.
• Every result must echo "toolset_name": "computer". Only screenshot and zoom results need an image. A short “OK” is enough for the rest.

Opus 5 accepts both forms, so make this change and test it on Opus 5 before switching models.

The silent change: progress updates

On Opus 5, short notes between tool calls (“Found the failing test, fixing the import next”) came back as text blocks. On Opus 5.5, notes longer than a sentence or two come back as thinking blocks, which are empty by default. Nothing fails, but an app that streams those notes goes quiet for the length of a long task.

POST /v1/messages
anthropic-beta: thinking-display-updates-2026-08-18

{
  "model": "claude-opus-5-5",
  "max_tokens": 64000,
  "thinking": {"type": "adaptive", "display": "updates"},
  "tools": [...],
  "messages": [...]
}

Render each non-empty thinking block ahead of the tool call it precedes, and pass the blocks back unchanged. If you want updates at a steady rhythm, say so in the system prompt, for example a one-line plan before the first tool call and a short recap at the end.

Handle refusals from day one

Opus 5.5 runs cybersecurity and biology classifiers, plus the new reasoning_extraction check. A decline is an HTTP 200 with stop_reason: "refusal", so always check the stop reason before reading content.

POST /v1/messages
anthropic-beta: server-side-fallback-2026-07-01

{
  "model": "claude-opus-5-5",
  "max_tokens": 16000,
  "fallbacks": "default",
  "messages": [...]
}

Server-side fallback works on the Claude API and Claude Platform on AWS. On Bedrock, Google Cloud and Foundry, use the SDK’s client-side fallback middleware. Two caveats: the fallback model runs without Opus 5.5’s thinking blocks, and reasoning_extraction declines are not retried.

Migration checklist

1. Change the model ID to claude-opus-5-5 (Bedrock: anthropic.claude-opus-5-5).
2. Remove thinking: disabled and budget_tokens everywhere. Set effort explicitly on every route.
3. Raise max_tokens to leave room for thinking. Read content blocks by type.
4. Replace tool_choice any and tool with auto plus strict tools, or with structured outputs.
5. Make the harness append-only, or set prefix_mismatch_behavior while you fix it.
6. Move computer use to computer_toolset_20260801 on the Claude API and Google Cloud.
7. Render thinking blocks if your UI shows progress between tool calls.
8. Check stop_reason for refusals and turn on fallback.
9. Run your evaluation set and compare cost per completed task against Opus 5.

Not sure the upgrade is worth the work yet? Weigh it in Claude Opus 5.5 vs Opus 5, or see the full Opus 5.5 overview.