Skip to main content

Migrate from Claude Opus 5 to Opus 5.5

Claude Opus 5.5 is not a one-line model-ID replacement. Anthropic's official documentation lists several behavior changes that can affect production code. Replay a set of real requests before changing the default model.

1. Update the model ID​

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": prompt}],
)

Platform IDs:

PlatformModel ID
Claude APIclaude-opus-5-5
Amazon Bedrockanthropic.claude-opus-5-5
Google Cloudclaude-opus-5-5
Microsoft Foundryclaude-opus-5-5

2. Remove the old thinking configuration​

Adaptive thinking is always on for Opus 5.5. Do not continue sending:

{"thinking": {"type": "disabled"}}

Do not carry over the old fixed-budget pattern either:

{"thinking": {"type": "enabled", "budget_tokens": 32000}}

Use effort to control reasoning depth:

{"effort": "medium"}

The available range runs from low to max. Opus 5.5 defaults to medium, while Opus 5 defaulted to high, so re-evaluate quality, latency, and cost instead of inheriting the old default.

3. Check tool choice​

On Opus 5.5, forced tool_choice types any and tool return an error. Migrate to auto and use strict tool use to constrain schemas and call behavior.

{
  "tool_choice": {"type": "auto"},
  "tools": [
    {
      "name": "lookup_issue",
      "description": "Look up a tracked issue",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {"id": {"type": "string"}},
        "required": ["id"],
        "additionalProperties": false
      }
    }
  ]
}

4. Migrate computer use​

On the Claude API and Google Cloud, Opus 5.5 does not accept the older computer_20251124 tool. Remove the old beta header, use computer_toolset_20260801, and update the agent loop to handle tool-use blocks, batch actions, and toolset_name on results.

The older computer_20251124 tool remains supported on Amazon Bedrock, but cross-platform applications should not assume identical behavior. Integrations that already use the new toolset or the browser-use tool do not need this migration.

5. Check text between tool calls​

Opus 5.5 may return text between tool calls inside thinking blocks. With the default display setting, the text in those blocks may be empty. If your product displays that text as live progress, users may see a silent gap after the upgrade.

Check whether:

  • your UI depends on natural-language progress between tool calls;
  • your stream parser reads only text blocks;
  • you need a thinking.display setting that returns the text;
  • an empty thinking block is incorrectly treated as a failure.

6. Re-run the effort and cost evaluation​

Anthropic says Opus 5.5 tends to think more at the same effort setting than Opus 5. Test at least three bands:

SettingGood test workload
lowHigh-volume, low-latency, simple changes
mediumDefault production workflows
high / xhigh / maxComplex migrations, debugging, research, and high-risk tasks

Record:

  • completion and human-acceptance rate;
  • total input, output, and thinking tokens;
  • tool calls and retries;
  • time to first useful output and total latency;
  • cache hit rate;
  • cost per accepted result;
  • whether refusal or fallback changed the actual responding model.
  1. Change only the model ID in staging;
  2. remove old thinking parameters;
  3. set effort explicitly instead of relying on defaults;
  4. fix tool-choice and computer-use integrations;
  5. verify streaming, thinking blocks, and progress UI;
  6. run an effort and cost sweep on real tasks;
  7. roll out gradually with Opus 5 or another model retained as a fallback.

Official migration resources​