Claude Opus 5.5 Migration: What Breaks and What It Saves

Claude Opus 5.5 went live on September 22, 2026. It is the top of the mid-priced tier in the Claude 5.5 family, aimed at long-running agentic coding and knowledge work. The model ID is claude-opus-5-5 on the Claude API and Google Cloud, and it is also available on Amazon Bedrock, Microsoft Foundry and Claude Platform on AWS.

The specs matter less than the price. Opus 5.5 lists at $4 per million input tokens and $20 per million output tokens, with a 1M token context window and 128K tokens of maximum output. Launch coverage put Opus 5 at $5 and $25, so the list price dropped by a fifth. Anthropic also says typical workloads at default settings cost about 40 percent less than they did on Opus 5. That second number is a vendor claim about its own workloads. Treat it as a hypothesis to test on your traffic, not a promise.

If you run an AI feature on Opus 5 today, you have a decision to make this month. The cheaper model is tempting, and the upgrade is not a one-line change. Four things in the API behave differently, and one of them can make your app look frozen without throwing a single error.

Anthropic's docs list four breaking changes for code already running on Opus 5, and a fifth change that alters the response without failing a request. Read all five before you touch a model string.

1. Thinking cannot be turned off

Adaptive thinking is always on in Opus 5.5. If your code sends a request that disables thinking, it will not behave as it did. You control depth through the effort parameter instead. The default effort is medium, which is lower than the default on Fable 5.1 and Sonnet 5.5, both of which default to high.

This matters for latency and cost. A short classification call that used to return fast with thinking off now carries some reasoning overhead. For those calls, a smaller model is usually the right answer anyway, and we will get to routing below.

2. Forced tool use returns an error

If you pass a setting that forces the model to call a specific tool, Opus 5.5 returns an error. A lot of production code does this to get structured output: define a tool that matches your JSON schema, force the model to call it, read the arguments. That pattern breaks. You will need to switch to a supported way of requesting structured output or let the model choose the tool and validate what comes back.

This is the change most likely to take down a feature on deploy day, because it fails loudly and immediately. Grep your codebase for forced tool choice before anything else.

3. Thinking blocks are tied to the model and the conversation

If you store conversation history and replay it, thinking blocks from one model cannot be replayed into another. A conversation that started on Opus 5 and continues on Opus 5.5 will not carry its thinking blocks across. Any app that persists full assistant messages, including the thinking content, needs a plan for conversations that are in flight at cutover.

The simple fix is to let existing conversations finish on the old model and start new ones on the new model. The cleaner fix is to strip thinking blocks when you persist history, if your use case does not need them.

4. The older computer use tool is rejected

On the Claude API and Google Cloud, the earlier computer_20251124 computer use tool is not accepted. If you built a browser or desktop automation feature on it, you need the newer tool version before you can switch.

5. Text between tool calls moves into thinking blocks

This is the quiet one. In an agent loop, the model often writes a sentence between tool calls: "Checking your order history now." Many apps stream that text to the user as a progress indicator. On Opus 5.5, that text comes back inside thinking blocks, and at the default display setting those blocks are empty. Nothing errors. Your progress updates just stop, and your users stare at a spinner for forty seconds.

The fix is to set a display value that returns the text. It is one parameter, but you only find it if you test the streaming UI by hand. Automated tests that check for a final answer will pass.

List price is only half of the cost picture. Here is how to work out what Opus 5.5 does to your bill.

The published rates for Opus 5.5 are $4 input and $20 output per million tokens. Cached input reads cost $0.20 per million, which is 5 percent of the base input price. A five-minute cache write is $5 and a one-hour cache write is $8. The Batch API takes 50 percent off both input and output, so $2 and $10. Fast mode, which trades price for latency, is priced separately.

Take a support agent that handles 50,000 conversations a month. Say each one averages 6,000 input tokens (system prompt, retrieved articles, history) and 800 output tokens. That is 300 million input tokens and 40 million output tokens a month.

• At $5 and $25: $1,500 for input plus $1,000 for output, about $2,500 a month.
• At $4 and $20: $1,200 for input plus $800 for output, about $2,000 a month.
• At $4 and $20 with 70 percent of input served from cache: the cached share costs $0.20 per million instead of $4, so it is about $42 and the remaining 30 percent is $360. Input drops to roughly $400, and with $800 of output the total lands near $1,200 a month, before the small cost of cache writes.

The list price cut saves you about 20 percent. Caching saves you more than the model change does ($800 against $500 in this example), and it works on the old model too. If you have not turned on prompt caching, do that first. It is the cheapest win in this whole article.

Those are illustrative numbers in my own arithmetic, not a benchmark. Your token counts will differ, and you should measure them from your logs before you forecast anything. Our guide to managing LLM API costs covers how to instrument that properly.

Anthropic says typical workloads cost about 40 percent less on Opus 5.5 than Opus 5. Part of that is the 20 percent list price cut. The rest has to come from somewhere else, and the likely source is that the model reaches answers with fewer tokens at the default medium effort.

That can go either way for you. If your prompts were tuned to make Opus 5 think hard, you might see lower quality at medium effort and pay to raise it. If your prompts were verbose because the old model needed hand-holding, you might see a bigger saving than 40 percent.

So run the test. Pull 200 real requests from your logs, the ugly ones included. Run them through both models with your actual prompts. Score the outputs with whatever evaluation you already trust, whether that is a rubric, a human review or an automated grader. Record cost per request and p95 latency next to quality. A one-day experiment with real traffic is worth more than any vendor chart, and it gives you a number you can show your board.

If you have no evaluation set at all, build one before you migrate anything. Fifty good examples is enough to start. You will need it for the next model release too, and there is always a next release.

The cheapest mistake to avoid is routing every request to the biggest model because it is the newest. The 5.5 lineup has four tiers, and the price spread is large.

• Fable 5.1: $10 input and $50 output per million tokens. Slower, defaults to high effort. Reserve it for the hardest reasoning and the highest-stakes outputs.
• Opus 5.5: $4 and $20. Moderate latency. The workhorse for agentic coding and multi-step knowledge work.
• Sonnet 5.5: $2 and $10. Fast. Good for most chat, drafting and extraction.
• Haiku 5.5: from $0.10 input and $0.50 output. Fastest. Classification, routing, tagging and anything high volume.

Opus 5.5 costs twice what Sonnet 5.5 does and forty times what the cheapest Haiku does on input. If a third of your traffic is simple intent classification and entity extraction, sending it to Opus is like hiring a staff engineer to rename files.

A sensible split for a typical product: Haiku decides what kind of request it is, Sonnet handles the routine ones, Opus handles the ones that need multi-step work, and Fable handles the rare case where being wrong costs real money. You do not need an elaborate router. Start with a rule based on the feature, not on the individual request. Settings and search suggestions go to Haiku. Chat goes to Sonnet. The agent that edits a customer's records goes to Opus.

We compared the top-tier options head to head in Claude Fable 5 vs GPT-5.5 for app development. If you are not locked to one vendor, read it before you commit your routing table.

Here is the sequence we would follow on a production feature. It takes about a week of calendar time and a few days of actual engineering for a typical app.

1. Inventory. List every place your code calls a Claude model. Include background jobs, cron tasks and that one internal script someone wrote in March. Note the model string, whether thinking is disabled, whether tool choice is forced, whether history is persisted, and whether the output is streamed to a user.
2. Fix the breaking changes behind a flag. Replace forced tool use, remove any disable-thinking setting, set the display value for streamed text, and update the computer use tool if you use it. Ship these changes while still pointing at Opus 5. Most of them are safe on the old model, so you separate code risk from model risk.
3. Run the evaluation. Same 200 requests, both models, cost and quality side by side. Decide per feature whether Opus 5.5, Sonnet 5.5 or Haiku 5.5 is the right home.
4. Shadow traffic. Send a copy of live requests to the new model and compare, without showing users the result. A day or two is enough to catch format surprises.
5. Canary at 5 percent. Switch a small slice of users, watch error rates, latency and the feedback signals you already collect, then step up to 25, 50 and 100 percent.
6. Let old conversations finish. Do not move an in-flight conversation across models while you persist thinking blocks. New sessions go to the new model, old sessions finish where they started.
7. Keep the old model string one release longer. Rolling back should be a config change, not a deploy.

Anthropic lists the retirement of Opus 5.5 as not sooner than September 22, 2027, so you have a year of stability on this model. That is a useful number when you decide how much to invest in the migration now versus waiting for the next release.

The fact that you are doing this migration by hand is the real finding. Model lifecycles are short. OpenAI is retiring GPT-4 and o1 on October 23, and teams that hard-coded those names are scrambling right now. We wrote up that case in our GPT-4 and o1 migration plan. The same thing will happen with whatever you run today, on a schedule you do not control.

A few habits turn the next migration from a project into a pull request.

One config layer for models

Put every model name behind a single mapping, keyed by task, not by vendor. "support-agent" maps to a model and an effort setting. When the model changes, you edit one file.

A standing evaluation set

Keep your 200 real requests and your scoring method in the repo. Run it in CI on a schedule. When a new model ships, the comparison takes an afternoon.

Provider abstraction, but not too much

A thin wrapper that normalizes request and response shapes is worth having. A giant abstraction layer that hides every vendor feature is not. You want the ability to switch, and you also want to use the features that make a model good.

Cost logging per feature

Tag every call with the feature that made it, and log tokens in, tokens out, cached tokens and latency. When the bill changes, you want to know which feature changed it within five minutes.

None of this is glamorous, and all of it pays for itself the first time a vendor announces a deadline. Founders who skip it spend a sprint on every model release, and the sprint always lands in the middle of something more important.

Not every team should rush. Here is how we would call it.

Upgrade now if you run agentic workflows on Opus 5 with a meaningful monthly bill, say over $1,000. A 20 percent list price cut on that spend pays for a few days of engineering within a couple of months, and if the 40 percent claim holds on your traffic, much faster. Also upgrade now if you are about to build a new feature. Start on the current model and avoid doing this migration later.

Wait a few weeks if your feature is stable, your spend is small and the breaking changes touch your core flow. Forced tool use for structured output is the usual culprit. If that pattern sits at the center of your product, schedule the work, do not squeeze it in on a Friday.

Move to a cheaper tier instead if your feature does not need Opus-level reasoning. Plenty of apps we see are paying top-tier prices for work Sonnet 5.5 would handle without anyone noticing. The cheapest migration is to a smaller model, and you can combine it with this one.

Rescue first if your AI feature was thrown together with a vibe-coding tool and nobody can tell you where the model calls live. You cannot migrate what you cannot find. Fix the inventory problem before you chase a price cut.

The pattern behind all four is the same. Measure your own traffic, change one thing at a time, and keep a way back. The price cut is real, and the savings you capture depend on how carefully you move.

If you want a second pair of eyes on your model calls, your routing and your bill, we do this kind of audit for founders regularly. Book a free strategy call and bring your current monthly spend and a list of where your app calls a model.