Sonnet 5 vs 5.5: should you upgrade your application?

Sonnet 5.5 is an upgrade candidate for Sonnet 5 applications, not a drop-in change to approve solely from the model name. Official token prices remain the same, but accepted request fields, effort behavior and response handling have changed. Upgrade when your own acceptance checks pass and the new behavior improves the work you need it to do.

This guide is for teams already running Sonnet 5. It focuses on rollout decisions rather than a general model ranking. Documentation was checked September 29, 2026, after Sonnet 5.5’s September 28 release. It does not claim that every Sonnet 5 application needs an immediate production migration.

What remains familiar, and what changes

Sources: Sonnet 5.5 model page and what changed. An unchanged tokenizer means the same input text is tokenized consistently; it does not mean both models will generate the same number of output tokens.

Choose an upgrade hypothesis

Write one specific reason to try the new model. For example: “reduce the number of retries on our bounded bug-fix tasks while preserving regression-test pass rate.” Another might be “produce document drafts with fewer missing required sections.” These are hypotheses to test, not improvements established by the release announcement.

Avoid changing the prompt, retrieval pipeline, tools and model at the same time. If the result improves, you will not know which change caused it. Keep the old configuration available and compare the same task set. If you need to change request fields to make Sonnet 5.5 valid, record that compatibility change as part of the new configuration.

Choose tasks from actual use cases, with private information removed where necessary. Include common requests, a few difficult cases, and the failure modes your users care about. Do not construct only examples that resemble the vendor’s best demonstration.

Compatibility comes before performance

The highest-priority checks are supported thinking mode, forced tool use, preserved thinking history, computer use and advisor compatibility. Sonnet 5.5 does not accept thinking.type: disabled; the documented low-thinking alternative is between_tools at high effort or below. Forced tool_choice values also need migration.

Use the detailed 400-error migration guide for request examples and platform caveats. This article intentionally does not reproduce the entire troubleshooting guide. Your upgrade checklist should include successful responses too: an application can return HTTP 200 while its progress display or expected tool call is missing.

Test parser behavior for ordinary text, tool calls, thinking blocks and refusals. If you switch models mid-conversation, confirm what happens to incompatible blocks. If you edit earlier messages, check binding behavior. A one-turn “hello” response does not validate a production agent loop.

Measure quality and cost together

Keep acceptance criteria stable. For coding, that may mean the targeted test and full regression suite pass with no unrelated changes. For extraction, validate the schema and factual values. For documents, check required sections and every claim that refers to input data.

Record request count, billed usage categories, time to accepted output and review effort. A faster stream is not necessarily a faster completed task. Similarly, the unchanged rate card cannot guarantee an unchanged bill if the model uses more output or takes more tool turns.

Artificial Analysis’s launch report is useful context for deciding what to test, but it identifies a pre-release deployment issue and planned reruns. Do not treat its results as a measured upgrade outcome for your application. Keep those external findings in a separate column from your own results.

Roll out with a reversible decision

First run the updated configuration in an isolated test environment. If checks pass, choose an approved limited rollout appropriate to your product. Record the exact model, configuration and release time so you can distinguish later traffic from the old version. Avoid silently mixing both versions in one performance summary.

Keep a rollback configuration and define the condition that triggers it: for example, invalid responses above your accepted threshold or a regression in a critical task. A rollback is not a claim the model is globally worse; it can mean your integration or workload needs more investigation.

Do not remove the old model on the assumption that a new release means immediate retirement. Check official lifecycle commitments separately. Access and deprecation can vary across services. A migration plan should be based on actual supported dates and current platform behavior, not urgency created by a headline.

Make the upgrade decision by integration type

A text-only application with a simple response parser has a smaller compatibility surface than an agent that switches models, stores signed thinking history and streams tool progress. Classify the application before changing the model ID. This identifies the tests you need; it does not prove the simpler application will produce identical answers.

Do not treat a valid JSON response as proof of factual extraction. A schema can enforce the presence of invoice_total, but the number still needs checking against the document. Likewise, a tool call with valid arguments can target the wrong record. Compatibility tests establish that the application can run; task tests establish whether the result is useful.

The platform matters. The current migration documentation states that Sonnet 5.5 on Bedrock does not support structured outputs, including strict tool use. It also treats the older computer-use tool differently across platforms. A result from one vendor endpoint should not be copied into another service’s readiness checklist. Record the exact endpoint family alongside the model ID.

Use a minimum regression pack that reflects your app

Prepare fixtures before generating new answers. A practical starter pack includes a normal request, a long input near your application’s own limit, an intentionally incomplete input, a refusal or unsupported request, a tool failure, and a multi-turn continuation. Add your highest-impact historical bug. This is a coverage checklist, not a claim that seven cases prove production safety.

For each fixture, record required behavior and an explicit failure. An extraction fixture might require an exact amount, currency and source reference, and fail if missing data is invented. A coding fixture might require the regression test to fail on the baseline and pass after the patch, with no edits to the acceptance test. A document fixture can require all source facts to appear in the correct sections and prohibit invented citations.

For the parser fixture, save the raw response shape and the app-visible result. Check that text is extracted from the correct block, that thinking is not displayed as a final answer, and that an empty progress display does not make the interface appear hung. Sonnet 5.5 can change intermediate response shapes while the request still succeeds. This is why a status-code-only health check misses an important class of regressions.

For the tool fixture, deliberately return an error once. Verify that the application passes the result to the model correctly, stays within the retry limit, and does not repeat an external action whose first outcome is uncertain. Use a sandboxed substitute for destructive actions. The purpose is to test your orchestration under failure, not to find out whether a real payment or email was executed twice.

Specify the two configurations, including defaults

Keep a small configuration record with model ID, endpoint, SDK/client version, thinking mode, effort, output limit, system prompt hash, tool-schema hash and retrieval version. Defaults belong in that record even when you omit the corresponding field from a request. Sonnet 5.5’s API default is high, while its Claude Code default is medium; the same model name can therefore start with different behavior in two clients.

Use an immutable baseline commit or configuration version. If the new model requires different fields, create a separate 5.5 adapter configuration rather than editing the only copy of the old request. Rolling back a model ID while leaving incompatible 5.5-only fields in place is not a reliable rollback. Keep secrets outside the report; hashes and non-sensitive settings are enough to identify the configuration.

The official documentation says Sonnet 5 and 5.5 use the same tokenizer and rate card. This helps compare identical input, but it leaves output length and tool-loop behavior open. Start with the present prompt unless a documented incompatibility requires a change. If you later tune the prompt, save that as another configuration so improvements are not all attributed to the model upgrade.

Turn a test result into a rollout decision

A useful report separates compatibility failures, task failures and operational failures. A rejected request field is a compatibility problem. A well-formed answer with an incorrect amount is a task failure. A timeout or unavailable dependency is operational. Each can block rollout, but the remedy differs; merging them into one “accuracy” number makes the next action unclear.

Here is a synthetic example of a release gate, not a universal threshold: all critical fixtures must pass; no duplicated side effects are allowed; routine-task acceptance must meet the team’s existing standard; and cost and completion time must stay within a predeclared budget. The critical subset is a hard gate even if the overall average improves. Choose numerical thresholds from product requirements and existing measurements, not from a model announcement.

Suppose a 20-task evaluation produces 18 accepted results for each version. That does not establish equivalence if the old version failed two low-impact drafts while the new one failed a financial extraction and a migration. Compare task IDs and failure severity, not just 90% versus 90%. Inspect any new failure, repeat ambiguous cases and keep the small sample size visible in the decision record.

Rollback must restore behavior, not just a label

For an approved limited rollout, assign requests to a recorded configuration and avoid switching models in the middle of an in-flight task unless that path was explicitly tested. Store enough metadata to separate old and new traffic in logs. Shadow evaluation can be useful for read-only outputs, but never execute duplicate side-effecting tool calls just because two models are being compared.

When a rollback condition is met, stop sending new tasks to the new configuration, restore the known working adapter and handle in-flight work according to its saved state. Reconcile uncertain external actions before retrying them. Retain failed responses and usage records for diagnosis, with sensitive content protected. Do not erase the new-version data merely because you reverted production.

The final release record should say which fixtures passed, which failures remain, who or what performs acceptance, and which configuration is the fallback. If access to a model or platform prevents an actual run, label the migration as prepared but unverified. Documentation review and locally validated request shapes are useful preparation; they cannot honestly be reported as a successful end-to-end upgrade.

Where to go next

Use the pricing worksheet for arithmetic and effort sweep for configuration testing. If your actual question is whether to move to a larger model, use Sonnet versus Opus rather than combining an upgrade test with a model-tier switch.