Como migrar do Opus 5 para o Claude Opus 5.5 na API sem quebrar produção?

Trocar o identificador do modelo é a parte fácil

A parte difícil é descobrir em produção, às 3 da manhã, que metade das suas chamadas agora volta com erro 400

A Anthropic lançou o Claude Opus 5.5 em 22/09/2026 como sucessor do Opus 5, posicionado como modelo de ponta pra raciocínio, código e trabalho agêntico de longo prazo

E aqui vai o aviso que dá o tom deste post: essa migração tem breaking changes de verdade

Thinking mudou, uso forçado de ferramenta mudou, computer use mudou, o padrão de effort mudou

Se tu tem chamadas rodando hoje com claude-opus-5, não troca a string e reza 🙂

Bora montar o checklist direito?

O que ter em mãos antes de tocar na configuração

Antes de qualquer coisa, respira: o Opus 5 continua disponível na API, com aposentadoria comprometida pra não antes de 24 de janeiro de 2027

Ou seja, tu tem tempo

Migração boa é migração com rollback na mão, e não com a faca no pescoço

O que precisa estar pronto antes de mexer:

• Inventário das chamadas atuais com claude-opus-5: quais rotas, quais serviços, quais jobs em background, quais scripts esquecidos num cron
• Ambiente de staging que consiga receber tráfego espelhado ou pelo menos rodar a suíte de avaliação inteira
• Conjunto de avaliação com casos reais, não com prompts de brinquedo: pega entradas de produção que já deram problema antes
• Baseline de custo por rota: tokens de entrada, tokens de saída e custo médio por requisição, medidos hoje, com o modelo atual
• Baseline de latência por rota, incluindo p50 e p95, porque média engana
• Log de stop_reason já ligado, salvando o motivo de parada de cada resposta

Esse último item é o mais ignorado e o que mais salva pele

Sem log de stop_reason tu não tem como saber se o modelo terminou, estourou limite ou recusou a tarefa

E se a sua dor hoje já é tempo de resposta, vale revisar antes por que o Opus 5 fica lento, porque trocar de modelo em cima de um gargalo que é seu não resolve nada

Checklist de migração para o Claude Opus 5.5 passo a passo

A ordem aqui importa

Cada passo tem o erro clássico que aparece quando alguém pula ele

1. Troque o identificador para claude-opus-5-5 em staging

O identificador do modelo é fixo, sem sufixo de data, mesmo esquema do claude-opus-5

{
  "model": "claude-opus-5-5",
  "max_tokens": 8192,
  "messages": [
    { "role": "user", "content": "..." }
  ]
}

O erro comum deste passo: trocar em um lugar só

Quase todo time tem o nome do modelo hardcoded em mais de um arquivo, mais uma variável de ambiente, mais um fallback esquecido

Busca no repositório inteiro pela string antiga antes de dar deploy

2. Remova qualquer thinking budget e qualquer desativação de thinking

Esse é o breaking change mais brusco: no Claude Opus 5.5 o thinking é sempre adaptativo e não pode ser desligado

Desativar thinking ou definir um thinking budget é rejeitado

O controle agora é o effort, que mexe em profundidade, latência e custo ao mesmo tempo

3. Defina o effort explicitamente

Os níveis disponíveis são low, medium, high, xhigh e max

E presta atenção nisso: o padrão do Claude Opus 5.5 é medium, enquanto o padrão do Opus 5 era high

A própria documentação recomenda definir effort explícito na migração

{
  "model": "claude-opus-5-5",
  "effort": "high",
  "max_tokens": 8192,
  "messages": [
    { "role": "user", "content": "..." }
  ]
}

O erro comum deste passo: não definir nada, cair no medium sem perceber e achar que o modelo novo "ficou burro"

Ele não ficou, tu que baixou o effort sem querer 😛

4. Revise todo tool_choice forçado

Uso forçado de ferramenta é rejeitado: tool_choice dos tipos any e tool retornam erro 400

A recomendação é usar auto combinado com strict tool use ou structured outputs, e sinalizar no prompt quando a ferramenta se aplica

{
  "model": "claude-opus-5-5",
  "tool_choice": { "type": "auto" },
  "tools": [ /* suas ferramentas aqui */ ]
}

O erro comum deste passo: assumir que "auto" significa "talvez chame, talvez não" e deixar o prompt vago

Se a ferramenta é obrigatória naquele cenário, escreve isso no prompt de forma explícita: quando usar, com quais dados, e o que fazer se faltar informação

5. Atualize o computer use

A ferramenta computer_20251124 não é aceita pelo Claude Opus 5.5 na Claude API

A migração é remover o header beta e trocar a entrada da ferramenta:

{
  "tools": [
    { "type": "computer_toolset_20260801" }
  ]
}

O erro comum deste passo: trocar a entrada e esquecer de tirar o header beta antigo que ficou no cliente HTTP

6. Trate os blocos de thinking preservados

Entra em cena o preserved thinking, uma salvaguarda antidestilação

Cada bloco de thinking fica amarrado ao modelo e ao prefixo da conversa que o produziu: system prompt, lista de ferramentas e todas as mensagens anteriores

Traduzindo: aquele seu cache espertinho de reaproveitar raciocínio entre conversas diferentes não vai funcionar

O erro comum deste passo: montar transcript sintético, colando blocos de thinking de uma sessão em outra com system prompt diferente

7. Trate stop_reason: "refusal"

O modelo pode retornar recusa como motivo de parada, com stop_details de categoria, incluindo valores como bio, cyber e reasoning_extraction

São categorias mais amplas que as do Opus 5

O erro comum deste passo: o parser assumir que toda resposta tem conteúdo útil e estourar exceção quando vem recusa

Trata isso como caminho esperado, com mensagem clara pro usuário final e log da categoria

8. Revalide o parsing de saída

O Claude Opus 5.5 mudou o estilo de comunicação: menos jargão e informação importante no começo das mensagens

Se o seu código faz regex procurando um bloco no fim da resposta, ou corta os primeiros N caracteres como "introdução descartável", isso quebra

O erro comum deste passo: ninguém testa parsing na migração porque "é só o modelo que mudou"

9. Revise batch e saída estendida

Na Message Batches API dá pra pedir saída estendida com header beta: até 300 mil tokens de saída com output-300k-2026-03-24

Fora disso, contexto e limite de saída seguem iguais ao Opus 5

O erro comum deste passo: assumir que a saída estendida vale em qualquer chamada

Esse comportamento é da Message Batches API

Se tu já passou por checklist de troca de modelo em produção em outro provedor, a lógica é a mesma: inventário, staging, avaliação, rollout por rota

Opus 5 x Claude Opus 5.5: o que muda em preço, limites e parâmetros

Tabela na lata, pra colar no card da task:

Repara que contexto e saída máxima não mudaram

Então qualquer estratégia sua de chunking e de limite de janela continua valendo igual

O que muda de verdade é preço, parâmetros e comportamento

Como recalcular custo e latência antes de apontar o tráfego

A conta não é só "20% mais barato por token"

A Anthropic afirma que o Opus 5.5 custa cerca de 40% menos para rodar que o Opus 5: são 20% a menos por token, somados a menos tokens usados por tarefa e a uma geração de saída mais de 30% mais rápida

Ou seja, parte da economia vem do preço de tabela e parte vem do modelo ser menos prolixo

Como referência de ordem de grandeza, dois resultados de parceiro citados no lançamento:

• A Box relatou que o Opus 5.5 usou cerca de um terço dos tokens do Opus 5 nas avaliações dela, com respostas 40% menos verbosas e sem perda de acurácia
• O GitHub testou o modelo no Copilot CLI e no VS Code e concluiu mais tarefas de terminal que o Opus 5 em menos da metade dos passos

Esses são números de quem testou no cenário deles, não garantia pro seu

O jeito honesto de estimar é rodar sua própria avaliação e medir três coisas por rota: tokens de entrada, tokens de saída e latência p95

E tem um detalhe que muda TUDO na conta: o effort

Se tu subir de medium pra xhigh ou max pra recuperar qualidade em alguma rota, o custo por tarefa sobe junto

A economia de 20% por token não sobrevive a um effort mal calibrado

Então a ordem certa é: primeiro acha o effort mínimo que passa na sua avaliação, depois calcula custo

E não esquece do cache de prompt: com leitura a US$ 0,20 por milhão, system prompt grande e estável é dinheiro na mesa

Erros e comportamentos inesperados na migração (e como prevenir)

Aqui é onde a galera se ferra

Cada caso com sintoma, causa e prevenção

Erro 400 ao chamar com tool_choice forçado

Sintoma: requisições que funcionavam no Opus 5 voltam com 400 assim que tu troca o identificador

Causa: tool_choice do tipo any ou tool, que é rejeitado

Prevenção: antes do deploy, faz um grep por tool_choice no código inteiro e migra pra auto com strict tool use ou structured outputs, deixando claro no prompt quando a ferramenta se aplica

Requisição rejeitada por thinking budget

Sintoma: erro em toda chamada de uma rota específica, normalmente a que alguém "otimizou" limitando raciocínio

Causa: thinking é sempre adaptativo no Claude Opus 5.5, e desativar thinking ou definir budget é rejeitado

Prevenção: remove o parâmetro e substitui o controle por effort

Fluxo quebrando com bloco de thinking reaproveitado

Sintoma: conversa multiturno falhando de forma esquisita depois de um reload de histórico

Causa: preserved thinking amarra o bloco ao modelo e ao prefixo exato do transcript (system prompt, lista de ferramentas e todas as mensagens anteriores)

Prevenção: nunca remonta transcript trocando system prompt ou lista de ferramentas no meio

Se precisa mudar o system prompt, começa conversa nova

Recusa com categorias novas

Sintoma: stop_reason: "refusal" aparecendo em prompts que antes passavam

Causa: o Claude Opus 5.5 roda um classificador de segurança de biologia além do de cibersegurança, com mais categorias de salvaguarda que o Opus 5

Os stop_details trazem a categoria, com valores como bio, cyber e reasoning_extraction

Prevenção: tratar recusa como caminho esperado no código e logar a categoria

Sem isso, tu vira refém de "às vezes falha" sem conseguir explicar por quê

Roteamento silencioso para modelo anterior

Esse aqui é sorrateiro e merece atenção redobrada

Sintoma: resultado inconsistente dentro de um mesmo fluxo agêntico longo, sem erro nenhum aparecendo

Causa: os classificadores de segurança podem redirecionar requisições individuais dentro de um fluxo agêntico multiturno para o modelo anterior, o Opus 5, em vez do Opus 5.5

Prevenção: avaliação que assume "um único modelo do começo ao fim" não captura isso

Então monta sua avaliação com fluxos multiturno completos e observa variação entre execuções, não só chamada isolada

Tome cuidado! É exatamente o tipo de coisa que passa batido em staging e aparece em produção

O que a mudança de verbosidade muda no dia a dia de quem usa Claude Code

Aqui eu falo de uso em ferramenta, não de benchmark de API, beleza?

No vídeo eu peguei o Opus 4.7 e criei 5 projetos, cada um com um prompt só: clone do Trello, app de flashcards com autenticação e IA, um joguinho de nave, um jogo de kart e um blog com markdown, mais uma dashboard extra pra avaliar UI

O resultado foi bem misto

O clone do Trello ficou bonito e moderno na interface, mas várias funções não funcionaram: edição de cards, um dos filtros e a busca

O app de flashcards foi dos que eu mais gostei: login funcionando, geração via IA funcionando, sem bug aparecendo

O jogo de nave ficou funcional, com bug no game over (às vezes não aparece, a nave só bate) e me deixou com gosto de mediano, esperava mais

O jogo de kart rodou, sem som e com um carro girando sem parar em certo momento, mas achei o resultado legal

O blog com login admin, publicação e troca de tema funcionou redondo

E a dashboard ficou visualmente ótima, só que fiquei em dúvida se aquilo era mérito do modelo ou reflexo de muito dado de treinamento em dashboard padronizada 🙂

Uma coisa que eu notei naquela época e que casa direto com o assunto deste post: a opção antiga de ativar "raciocínio avançado" na interface foi substituída por um modo de pensamento adaptativo, que decide sozinho quando pensar mais

Na API do Claude Opus 5.5 esse caminho virou regra: thinking sempre adaptativo, sem budget, com effort como controle

E aí entra o novo estilo de comunicação: menos jargão e informação importante no começo da mensagem

No dia a dia isso é ótimo pra quem lê a resposta, e chato pra quem escreveu parser assumindo que o resumo vem no fim

Minha leitura honesta na época do 4.7 foi de evolução incremental, tipo um "4.6.1", e não de salto revolucionário

Segui usando o Opus no dia a dia porque já tenho assinatura que resolve meus problemas, mas se fosse balancear custo e qualidade pra vibe coding naquele momento, eu escolheria o Codex

Dito isso, os números de preço e de verbosidade do 5.5 mudam a conversa de custo, e isso merece teste novo

Quando migrar agora e quando esperar

Nem toda rota tem a mesma urgência

Migra agora:

• Rotas de código agêntico e tarefas longas, que é exatamente onde a Anthropic posiciona o modelo e onde o GitHub relatou mais tarefas concluídas em menos da metade dos passos
• Pipelines assíncronos, que podem ir direto pela Batch API a US$ 2 de entrada e US$ 10 de saída por milhão de tokens
• Rotas com system prompt grande e estável, onde o cache de leitura a US$ 0,20 por milhão faz diferença real na fatura

Refatora antes de migrar:

• Qualquer fluxo que dependia de uso forçado de ferramenta, porque any e tool retornam 400
• Qualquer rota com thinking budget fixo, que agora é rejeitada
• Automação de computer use, que precisa trocar pra computer_toolset_20260801 sem header beta

Pode esperar:

• Rotas de custo baixo e tarefa simples, onde Opus é overkill de qualquer jeito

A Anthropic diz que este é o primeiro lançamento da leva 5.5, e que Claude Sonnet 5.5 e Claude Haiku 5.5 vêm em seguida

Se a sua rota é de volume alto e complexidade baixa, faz sentido segurar e avaliar os irmãos menores quando saírem

Vale registrar também o posicionamento oficial: a Anthropic coloca o Opus 5.5 no nível do Claude Fable 5.1 na maior parte do trabalho, saindo à frente em vários benchmarks de código agêntico

E o modelo passou por avaliação externa antes do lançamento, com Frontier Design e METR

Agora, posicionamento de fabricante é ponto de partida, não prova

A prova é a sua avaliação com os seus casos

Próximo passo: migre por rota, não de uma vez

A receita que eu seguiria, na ordem:

1. Espelha a configuração em staging com claude-opus-5-5, effort explícito e os parâmetros proibidos já removidos
2. Roda a avaliação comparativa com casos reais, medindo qualidade, tokens de entrada, tokens de saída e latência p95, sempre incluindo fluxos multiturno completos
3. Faz rollout gradual por rota, começando pela de menor risco, com rollback para claude-opus-5 disponível a um deploy de distância
4. Monitora stop_reason, custo por requisição e latência por pelo menos alguns dias antes de avançar pra próxima rota

O Opus 5 não vai sumir amanhã, a aposentadoria está comprometida pra não antes de 24 de janeiro de 2027

Então não tem motivo pra fazer big bang num sábado à noite e torcer

Migração boa é chata, previsível e reversível

E se tu tá segurando rota de custo baixo esperando Sonnet 5.5 e Haiku 5.5, eu acho uma decisão sensata

Vou acompanhar por aqui quando saírem…

até o próximo post!