Claude Opus 5.5 Migration Guide

​

What’s New

1. Thinking is always adaptive. Turning thinking off or setting a thinking budget is rejected, and effort is the control for depth, latency, and cost
2. Forced tool use is rejected. tool_choice: {"type": "any"} or a named tool returns a 400
3. Mid-thinking display updates (beta). Request short progress notes during long tool-using turns
4. Preserved thinking. Thinking blocks are bound to the transcript prefix that produced them. Not enforced on requests through OpenRouter (see below)
5. Cache-friendly mid-conversation controls (beta). Ephemeral system messages via clear_at and per-turn effort changes, carried over from Fable 5.1
6. Computer use requires the new toolset. Relevant only if you call Anthropic directly, see below

​

Thinking Is Always Adaptive

• Disabling reasoning fails at OpenRouter, not upstream. The model is registered as mandatory-reasoning, so reasoning: {"enabled": false}, reasoning: {"effort": "none"}, and Messages API thinking: {"type": "disabled"} return a 400 (Reasoning is mandatory for this endpoint and cannot be disabled.) before the request is routed. The exception is a ~latest router alias, where OpenRouter coerces a disable request to the lowest supported effort instead. The /models entry reports reasoning.mandatory: true so client UIs can hide the disable control (see Reasoning Tokens).
• Budgets are not forwarded. reasoning.max_tokens and thinking.budget_tokens are accepted by OpenRouter but the request goes upstream as adaptive thinking with no budget, the same as Sonnet 5. Remove them and set an effort instead.
• Effort maps straight through. Chat Completions reasoning.effort and Messages API output_config.effort both become Anthropic’s output_config.effort. Requests that set no effort are sent without one and run at Anthropic’s API default, which Anthropic’s Opus 5.5 guide gives as medium (Opus 5’s default was high), so a request that never set effort gets a different setting than it did on Opus 5.

// Chat Completions API — pick an effort instead of a budget
{
  "model": "anthropic/claude-opus-5.5",
  "reasoning": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "Find the bug in this diff and propose a fix." }]
}

// Messages API — adaptive is the only thinking type; effort lives in output_config
{
  "model": "anthropic/claude-opus-5.5",
  "max_tokens": 64000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "Find the bug in this diff and propose a fix." }]
}

• Leave room in max_tokens. Thinking and the reply share the budget. Anthropic reports that 64k worked well for long agentic coding turns in its testing. A max_tokens sized for a non-thinking Opus 5 request can now end with stop_reason: "max_tokens" and no visible answer.
• Read responses by block type. A response can begin with a thinking block, so do not assume the first content block is text. Through OpenRouter, thinking blocks carry summarized text by default (OpenRouter sends display: "summarized" unless you set otherwise). Set thinking.display to "omitted", or reasoning.exclude: true on Chat Completions, if you do not want it.

​

Forced Tool Use Is Rejected

• Steering toward a tool: use tool_choice: {"type": "auto"} and state the expectation in the prompt (e.g. “Use the get_weather tool to answer”). Because auto does not guarantee a call, check that one was made and retry if not.
• Extracting structured data: if you were forcing a tool call to get JSON back, use structured outputs instead, which constrain the response format without skipping thinking.

// Messages API — steer with auto + prompt instead of forcing
{
  "model": "anthropic/claude-opus-5.5",
  "max_tokens": 16000,
  "tools": [{ "name": "get_weather", "description": "...", "input_schema": {} }],
  "tool_choice": { "type": "auto" },
  "messages": [
    { "role": "user", "content": "Use the get_weather tool to check Tokyo, then summarize." }
  ]
}

​

Mid-Thinking Display Updates (Beta)

// Messages API
{
  "model": "anthropic/claude-opus-5.5",
  "max_tokens": 64000,
  "thinking": { "type": "adaptive", "display": "updates" },
  "tools": ["..."],
  "messages": [{ "role": "user", "content": "Review the PRs open against our billing service." }]
}

​

Preserved Thinking

• Per-turn reminders or mid-session system prompt changes: append a mid-conversation system message instead of editing the system prompt, and for a one-turn reminder mark it ephemeral with clear_at: "next_user_message". Anthropic states this applies to Opus 5.5 as it does to Fable 5.1, see Ephemeral Mid-Conversation System Messages.
• Adding or removing tools: declare the full set at session start and send a mid-conversation tool-change block instead of changing tools.
• Compaction that summarizes older turns while replaying newer ones with their thinking blocks: replace the whole history with one summary message and replay no earlier thinking blocks, or set drop_block below so mismatched blocks are dropped instead of erroring.

// Messages API — drop mismatched thinking blocks instead of erroring
{
  "model": "anthropic/claude-opus-5.5",
  "max_tokens": 64000,
  "thinking": {
    "type": "adaptive",
    "block_binding": { "prefix_mismatch_behavior": "drop_block" }
  },
  "messages": ["...full history with thinking blocks replayed verbatim..."]
}

​

Per-Turn Effort Changes (Beta)

// Messages API — raise effort for one turn
{
  "model": "anthropic/claude-opus-5.5",
  "max_tokens": 64000,
  "messages": [
    { "role": "user", "content": "Summarize the failing test output." },
    { "role": "assistant", "content": "Three tests fail in the billing module..." },
    { "role": "system", "content": [], "output_config": { "effort": "xhigh" } },
    { "role": "user", "content": "Now find the root cause and fix it." }
  ]
}

​

Computer Use

​

Migration Checklist

1. Swap the slug to anthropic/claude-opus-5.5.
2. Remove any reasoning: {"enabled": false}, reasoning.effort: "none", thinking: {"type": "disabled"}, or thinking budget. Set an effort instead, starting at medium, and re-tune rather than carrying over your Opus 5 effort.
3. Raise max_tokens so thinking and the reply both fit, and parse responses by block type.
4. Replace forced tool use (tool_choice: {"type": "any"}, a named tool, or Chat Completions "required") with {"type": "auto"} plus prompt instructions, or structured outputs for JSON extraction. Add a check-and-retry when a tool call is required.
5. If your product shows progress during long agentic turns, try thinking: {"type": "adaptive", "display": "updates"}, and keep "summarized" where you need thinking text on every request.
6. Keep passing thinking blocks back unchanged. Move per-turn reminders to clear_at system messages, tool-set changes to mid-conversation tool-change blocks, and audit transcript edits with prefix_mismatch_behavior: "drop_block" plus input_transformations logging.
7. If you pin to Amazon Bedrock, do not use per-message output_config.effort.
8. Re-baseline cost: $4/M input,$20/M output, $0.20/M cache reads, 1M context. Anthropic reports fewer tokens per completed task at equal effort, so per-task cost may fall by more than the 20% list-price change.

​

Breaking Changes

​

Resources

• Claude Fable 5.1 Migration Guide, clear_at ephemeral system messages and per-turn effort in full
• Claude Opus 5 Migration Guide, mid-conversation tool changes
• Reasoning Tokens
• Structured Outputs
• OpenRouter Messages API
• Anthropic model migration guide
• Anthropic preserved thinking