# Claude Opus 5.5 Is Not a Drop-In Upgrade: A Migration Playbook for Production Agents > Opus 5.5 is cheaper and stronger, but its API changes can break tool loops, response parsing, conversation state and computer-use agents. Here is how to migrate safely. Source: https://mcdougall-digital.de/en/blog/claude-opus-5-5-agent-migration/ Published: 2026-09-24 Author: Kyluke McDougall, McDougall Digital Language: en --- Claude Opus 5.5 is trending on X, and the headline numbers make an upgrade look obvious. Anthropic says the model performs near its more capable Fable 5.1 model on many tasks, costs 40% less than Opus 5 on typical workloads and generates output more than 30% faster. The list price has fallen from $5 to $4 per million input tokens and from $25 to $20 per million output tokens. Anthropic also reports stronger agentic coding and better resistance to prompt injection. For teams running Claude through an API, those improvements are not the most urgent part of the release. The urgent part is the migration contract. Opus 5.5 rejects request settings that earlier models accepted. It changes the shape of responses, the rules for replaying conversation state and the way computer-use tools are declared. Some mistakes produce an immediate HTTP 400. Others quietly change model effort, remove visible progress or strip reasoning context from a fallback. That makes Opus 5.5 a useful case study in a broader architecture principle: **A model upgrade is a dependency migration, not a configuration edit.** ## The model ID is the smallest change Anthropic's migration guide lists several settings that Opus 5.5 rejects: - disabling thinking or setting a manual thinking-token budget; - forcing tool use with `tool_choice: any` or a named tool; - sending non-default `temperature`, `top_p` or `top_k` values; - ending the conversation with a prefilled assistant response; - using the older computer-use tool on the Claude API or Google Cloud. Any one of these can turn a model-name change into a production error. The risk is larger in mature systems because model parameters are rarely defined in one place. They may be assembled across a gateway, an orchestration library, a prompt template, an observability proxy and task-specific overrides. A parameter that nobody remembers can remain harmless for months because the old model tolerated it. Before changing the model ID, capture the actual request envelope leaving your infrastructure. Search the codebase, but also inspect production traces. The wire format is the contract that matters. ## Always-on thinking changes response parsing Opus 5.5 always uses adaptive thinking. You can control its depth through the `effort` setting, but you cannot disable it. This changes more than model behaviour. A response can now begin with one or more thinking blocks before the first text block. Code such as `response.content[0].text` is no longer safe. Streaming handlers that assume the first content event is text can fail for the same reason. Consumers should branch on each block's `type` instead of its position. That applies to user interfaces, telemetry, result extraction and tool loops. Token accounting also changes. `max_tokens` covers thinking and visible output together. Thinking tokens are billed as output even when the thinking text is not returned. A limit that previously left enough room for a complete answer may now truncate a task after the model has spent part of the budget reasoning. There is a second, quieter change: Opus 5 defaulted to high effort, while Opus 5.5 defaults to medium. If your application omits the parameter, the upgraded request runs at a lower effort level without an error. This may be the right trade-off. Anthropic's central claim is that the new model produces better work with fewer tokens. But a silent default change is not an evaluation strategy. Set effort explicitly, then measure quality, latency and total task cost at low, medium and high on representative work. ## Tool loops need new invariants Many agents force a tool call when a step must query a database, run code or retrieve a document. Opus 5.5 no longer accepts forced tool selection through `any` or a named tool. Anthropic recommends automatic tool choice combined with strict tool schemas, structured outputs and clear instructions about when a tool must be used. That changes the guarantee your orchestration layer provides. If a business workflow cannot continue without a successful lookup, do not rely on prompt wording alone. Validate the model's output in application code. If the required tool was not called, stop, retry under a bounded policy or route the task for review. The invariant belongs in deterministic code, even when the model usually follows the instruction. Thinking blocks introduce another requirement. When an assistant response contains tool calls, the tool loop must return the thinking blocks complete and unmodified alongside the tool results. Filtering empty blocks, reordering content or rebuilding the assistant message can invalidate the state and cause an error. The safest pattern is simple: persist the assistant turn as received, attach tool results in a new message and treat signed provider state as opaque. ## Conversation compaction is now part of compatibility Long-running agents rarely keep every message forever. They trim history, summarise old turns, change available tools or update the system prompt as a workflow moves between phases. Those operations are no longer merely prompt-engineering choices. Opus 5.5 ties thinking blocks to the conversation and model that produced them. Editing earlier messages, tool definitions or the system prompt can invalidate preserved thinking. For newer accounts, replaying invalid blocks is rejected by default. Older accounts may not receive the same error yet, but Anthropic says the blocks are still invalid. Routers create a related risk. A fallback model may continue the conversation without Opus 5.5's earlier thinking blocks if it cannot read them. The request can succeed while the agent loses hidden state that influenced previous decisions. This does not mean agents should keep unlimited history. It means compaction needs an explicit boundary: 1. finish or checkpoint the current tool loop; 2. create a clean summary containing facts, decisions, open questions and artefact references; 3. start a new conversation from that summary; 4. record the model and policy transition in telemetry; 5. verify that the resumed task still satisfies its acceptance criteria. Treat this as a state migration, not string manipulation. ## Computer-use agents have a platform split On the Claude API and Google Cloud, Opus 5.5 replaces the earlier `computer_20251124` tool with the `computer_toolset_20260801` toolset. The event shape changes as well: a turn can contain several actions, and tool results need to identify the toolset. Amazon Bedrock retains the older computer-use tool at the time of publication. That is exactly the kind of platform difference a thin model abstraction can hide until runtime. If your system supports more than one provider route, make capability discovery explicit. Version request builders by model and platform. Test the event stream, not only the initial request. A green health check that sends “hello” says nothing about whether a multi-action browser loop can complete. ## Refusal is an application state Opus 5.5 can return `stop_reason: refusal` with structured details. An agent that understands only “completed,” “needs tool” and “hit token limit” may treat a refusal as a successful empty result or enter an unproductive retry loop. Map refusal into your domain state machine. The application should decide whether to: - explain the boundary to the user; - request safer input; - fall back to an approved model where policy permits; - send the task to a human; - terminate the workflow without side effects. Retries need limits. A policy refusal is not a transient network error. ## A production migration sequence A safe upgrade does not need months, but it should have stages. ### 1. Inventory the real integration Record model IDs, request parameters, SDK versions, tool schemas, response parsers, history-compaction rules, fallback routes and platform-specific tools. Use traces to verify what is actually sent. ### 2. Build contract tests Cover more than answer quality. Test every request profile, streaming block type, tool round trip, refusal path, context checkpoint and fallback transition. Include malformed and boundary cases. ### 3. Run an effort sweep Do not inherit the old default. Evaluate low, medium and high effort on real tasks. Measure accepted-task rate, latency, output tokens, review time and total cost. ### 4. Shadow production traffic Replay a privacy-safe sample without allowing the new model to cause side effects. Compare tool choices, structured outputs, refusal rates and completion quality with the current path. ### 5. Canary by workflow and risk Start with bounded, reversible tasks. Keep destructive tools and high-impact writes behind human approval. Increase traffic only when the operational metrics remain stable. ### 6. Preserve a tested rollback Rollback means more than changing the model ID back. Conversation state created by Opus 5.5 may not be portable. Be prepared to start a clean conversation from a checkpoint when returning to the previous route. ## The durable lesson Opus 5.5 may be a strong upgrade. Lower prices, faster output and better long-horizon coding could improve the economics of serious agent workflows. But the value appears only after the surrounding system is compatible. The model sits inside an architecture of request builders, tool contracts, state management, permissions, observability, evaluation and recovery. When the model changes any of those interfaces, the architecture has to absorb the change deliberately. The teams that benefit fastest from new models will not be the teams that switch model IDs fastest. They will be the teams that can test a new dependency, observe its behaviour, limit its blast radius and roll it back without losing the state of the product around it. --- This article was created with the help of AI. McDougall Digital is responsible for its content.