Migrar para o Claude Opus 5.5: 4 mudanças que quebram seu código (e uma silenciosa)

O Claude Opus 5.5 chegou em 22/09/2026 mais barato ($4 / $20 por milhão de tokens), mais rápido e com nível de Fable 5.1 na maioria das tarefas. A tentação é abrir o código, trocar o ID do modelo e fazer deploy na sexta.

A documentação oficial (What's new in Claude Opus 5.5) lista quatro mudanças que quebram código que funcionava no Opus 5 e uma quinta que muda o formato da resposta sem dar erro — a mais perigosa, porque passa no teste e falha na frente do usuário. As três primeiras também valem para o Claude Fable 5.1.

No Opus 5, o thinking vinha ligado por padrão, mas thinking: {"type": "disabled"} era aceito em esforço high ou menor. No Opus 5.5 ele é sempre ligado. Uma requisição com disabled — ou com orçamento manual {"type": "enabled", "budget_tokens": N} — retorna 400 invalid_request_error:

"thinking.type.disabled" is not supported for this model.
Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Correção: remova o campo thinking (ou envie {"type": "adaptive"}, que é equivalente) e use o effort para controlar profundidade, latência e custo. Onde você desligava o thinking para ganhar velocidade, baixe o esforço.

# antes (Opus 5)
model="claude-opus-5", thinking={"type": "disabled"}

# depois (Opus 5.5)
model="claude-opus-5-5", output_config={"effort": "low"}

Efeito colateral: toda resposta pode começar com um ou mais blocos de thinking. Selecione blocos pelo campo type, não pela posição — código que pega content[0].text vai quebrar — e devolva os blocos de thinking sem modificação nos loops de ferramentas.

O Opus 5.5 não suporta uso forçado de ferramenta. tool_choice com {"type": "any"} ou {"type": "tool", "name": "..."} retorna 400 — e a mesma validação vale para o endpoint de contagem de tokens:

tool_choice: type "tool" and "any" are not supported for this model.

Continuam aceitos {"type": "auto"} (o padrão) e {"type": "none"}.

Correção: muita gente forçava ferramenta só para receber JSON no formato certo. Para isso, mantenha auto e ative strict: true (strict tool use) ou mova o schema para structured outputs. Se você precisa que o modelo chame uma ferramenta em vez de responder em texto, diga no prompt quando a ferramenta se aplica.

Cada bloco de thinking registra qual modelo o produziu, e cada modelo só lê alguns blocos de outros:

• O Opus 5.5 lê blocos do Opus 5 e de Opus, Sonnet e Haiku anteriores — mas não de Fable ou Mythos.
• Na API da Claude, Fable 5.1 e Mythos 5.1 leem blocos do Opus 5.5; nenhum outro modelo lê.
• Se a conversa troca para um modelo que não lê os blocos, a API os descarta antes de o modelo ver: a requisição funciona, os blocos descartados não são cobrados, mas o raciocínio anterior se perde.

A segunda parte pega quem edita histórico. A API verifica se algo antes de um bloco de thinking do Opus 5.5 mudou desde que ele foi gerado — system prompt, ferramentas ou mensagem anterior. Para contas criadas a partir de 31/08/2026 (00:00 UTC), essa checagem é aplicada por padrão e a requisição retorna 400. Para descartar os blocos afetados em vez de falhar, envie o beta header thinking-binding-controls-2026-08-01 com thinking.block_binding.prefix_mismatch_behavior: "drop_block".

Correção: deixe a conversa append-only. Para mudar instruções ou ferramentas no meio do caminho, use mensagens de sistema no meio da conversa em vez de editar o que já foi enviado. Isso também preserva o cache. Esse mecanismo faz parte do preserved thinking, a proteção antidestilação que a Anthropic introduziu com o Fable 5.1.

O Opus 5 aceitava computer use como o toolset computer_toolset_20260801 e, com o beta header computer-use-2025-11-24, como a ferramenta antiga computer_20251124. Na API da Claude e no Google Cloud, o Opus 5.5 só aceita o toolset. A ferramenta antiga retorna 400:

'claude-opus-5-5' does not support tool types: computer_20251124. Did you mean one of ...

Correção: remova o beta header, troque a entrada em tools por {"type": "computer_toolset_20260801"} e atualize o loop do agente para os blocos tool_use de membros do toolset, ações em lote e o campo toolset_name nos resultados. No Amazon Bedrock a ferramenta antiga continua funcionando no Opus 5.5. Quem já usa o toolset, ou a ferramenta de browser use, não precisa mudar nada.

Esta não dá erro nenhum. As notas curtas que o modelo escreve entre uma chamada de ferramenta e outra ("vou checar o arquivo de config", "testes passaram, agora o deploy") agora chegam como blocos de thinking de progresso, não como blocos de texto. No padrão display: "omitted", o texto desses blocos vem vazio.

Resultado: se o seu produto mostra essas mensagens como "progresso" para o usuário, ele simplesmente fica em silêncio entre as ferramentas. O teste automatizado passa, a requisição dá 200, e o cliente acha que travou.

Correção: defina thinking.display com um valor que retorne o texto (o guia de migração oficial mostra como) e ajuste o front para ler blocos de thinking de progresso. A documentação também tem um guia de como pedir mais atualizações de progresso ao modelo.

• Esforço padrão caiu para medium (no Opus 5 era high). Se você não define o esforço, suas respostas mudaram. Defina explicitamente e refaça os testes.
• Mais thinking por turno no mesmo esforço, principalmente em xhigh e max. Deixe folga em max_tokens e reveja custo (veja custo real por tarefa).
• Recusas com HTTP 200: o modelo roda classificadores de cibersegurança e de biologia. Uma recusa volta com stop_reason: "refusal" e um stop_details indicando a área. Trate isso e configure fallback — o beta fallbacks: "default" repete a requisição no modelo que a Anthropic recomenda para aquela categoria.
• Visão mais precisa: lê gráficos densos e screenshots bem melhor sem ferramentas; gambiarras de prompt para visão podem não ser mais necessárias.

Novidades úteis na migração: esforço por mensagem (beta), orçamento por tarefa, compactação sob demanda (beta compact-2026-09-04), definição de ferramenta dentro de mensagem (beta inline-tools-2026-09-15), cache com mínimo de 512 tokens e fast mode (só na API da Claude, com o header fast-mode-2026-02-01).

1. Trocar o ID: claude-opus-5 → claude-opus-5-5 (no Bedrock: anthropic.claude-opus-5-5).
2. Remover thinking: disabled e budget_tokens; escolher effort por rota.
3. Trocar tool_choice any/tool por auto + strict tool use ou structured outputs — inclusive nas chamadas de contagem de tokens.
4. Ler blocos de resposta por type, nunca por posição; devolver thinking sem modificar.
5. Garantir conversa append-only; revisar qualquer código que edita histórico ou troca de modelo no meio da conversa.
6. Migrar computer use para computer_toolset_20260801 (API Claude e Google Cloud).
7. Definir thinking.display se a interface mostra progresso entre ferramentas.
8. Tratar stop_reason: "refusal" e configurar fallback.
9. Rodar a suíte de avaliação com o esforço novo e comparar custo por tarefa.
10. Subir primeiro para uma fração do tráfego, com log das requisições que retornam 400.

Manda para o dev antes do deploy de sexta. E, se quiser a visão de negócio da troca, veja Opus 5.5 vs GPT-6 Astra.

• Claude Platform Docs — What's new in Claude Opus 5.5
• Anthropic — Introducing Claude Opus 5.5 (22/09/2026)