Claude Opus 5.5: how to migrate an agent without breaking it

An agent integration contains more contract surface than the model name: request shape, response blocks, tool selection, progress signals, output limits, caching, and recovery paths. If a team replaces an ID and the first demo answers correctly, silent failures can still remain in long tasks, streaming interfaces, or actions that depended on forcing a tool.

Anthropic announced Claude Opus 5.5 on September 22, 2026 and made it available that day. This September 23 article, dated in Lima, analyzes the documented contract rather than validating promotional figures. The announcement claims lower cost and higher speed than Opus 5, while the same page warns that narrow benchmark margins increasingly explain less about real-world differences. A responsible decision starts with your own tasks and verifiable outcomes.

The technical guide lists four changes that are incompatible with some Opus 5 clients. Adaptive thinking is always on and no longer accepts disabled mode or enabled mode with a manual budget. tool_choice no longer accepts any or a named tool. An earlier computer-use version is rejected on the Claude API and Google Cloud. In addition, text between calls can arrive as empty thinking blocks under the default display setting even when the request succeeds.

The consequence is twofold. Some problems are hard and visible, such as a 400 error; others degrade the experience without triggering alerts, such as a panel that appears frozen while the agent continues using tools. That is why migration needs contract tests in addition to semantic evaluation. The former verify that the system speaks the right protocol; the latter verify that completed work retains the quality the business needs.

Capture representative requests before migrating, removing secrets and personal data. Record the model, platform, SDK version, thinking, output_config.effort, max_tokens, tools, and beta flags. Then run structural checks against Opus 5.5: no obsolete configuration, content selected by type, and enough room for thinking plus the answer. Do not automatically turn a configuration error into a retry with different parameters, because that would hide an incompatibility.

Include multi-turn conversations and tool loops. The documentation requires returning thinking blocks unchanged where applicable; a normalizer that keeps only text can break continuity. Test serialization, persistence, queues, and recovery after a pause. The gate passes when the same typed artifact survives the entire path and expected errors reach observability with a classification, not when one isolated call returns HTTP 200.

If a workflow used tool_choice any or a named tool to force an action, the replacement is not merely auto. Define strict schemas, instructions that specify when to call, and an application check that decides whether the result is sufficient. When an operation is mandatory because of business rules, the orchestrator must detect that it did not happen and stop or request review; the model should not be the only layer enforcing the process.

Hypothetical example: an agent prepares vendor onboarding and must check sanctions before creating the record. Test three cases: a clear match, an unavailable sanctions service, and an ambiguous response. The correct outcome is not always creation. It may be blocking, requesting evidence, or escalating. Verify that the agent does not replace the check with a plausible sentence and that a retry does not duplicate onboarding. That semantics belongs to your system.

An application can keep running correctly and still look broken if it stops showing activity between tools. Instrument events independently of model prose: call started, tool completed, approval pending, retry, and completion. If you choose to display provider progress blocks, handle them by type and explicit configuration. Do not turn internal reasoning into business telemetry or promise users a step the application did not actually observe.

Test the interface with slow connections, delayed tools, and responses that end in refusal. Define one threshold for communicating a wait and another for considering a session stalled; both should rely on observable events. On mobile, verify that updates do not push critical controls off screen. The gate passes when support can distinguish active execution, deliberate waiting, recoverable failure, and abandoned work without reading private provider logs.

Opus 5.5 defaults to medium, while Opus 5 defaulted to high. Effort labels do not represent an identical amount of reasoning across models. Build a low, medium, and high matrix for each workload family; reserve xhigh or max for cases where you demonstrate an improvement. Keep the dataset, tools, limits, and grader constant. Repeat each case to observe variability and separate model errors from environment failures.

Measure cost and latency per accepted task, not merely per call. Include retries, tools, human corrections, and abandoned sessions. A cheap answer that forces rework can cost more than an expensive run that finishes correctly; an average improvement also does not offset a regression in a critical operation. The official guide recommends sweeping effort against your own evaluations and warns that changing it at the top level can invalidate prompt caching.

Start with shadow traffic or reproducible cases without side effects. Then enable a small cohort by task type, not a random fraction that mixes different risks. Version the model, prompt, tools, effort, and grader with every result. Before rollout, define which regression stops expansion: contract error, incorrect action, quality drop, latency limit, cost per case, or loss of progress signals.

During the observation window, keep a tested path to the previous model or a manual operation. Rollback must restore compatible configuration, not merely switch the ID; a client changed for thinking or tools may not work symmetrically in reverse. Rehearse reversal with one in-flight task and one new task. Record who authorizes the change and how sessions that already contain model-bound state are protected.

The limits matter. We did not run Opus 5.5 or reproduce the published benchmarks, and we do not claim that one effort level performs better for your workload. Pricing, speed, and performance figures belong to the vendor and may depend on its harness. This guide turns documented changes into engineering criteria. Your pilot should include permitted data, security review, and the specific constraints of the platform where you deploy.

Approve the migration when all five gates leave evidence: compatible requests, application-governed tools, observable progress, calibrated effort, and a rehearsed rollback. If you need to design that pilot for a real process, Wasyra's custom service can turn the workflow, its permissions, and its golden cases into an evaluable implementation. That service is separate from the Agents product hosted at agents.wasyra.com.