Migração para Claude Sonnet 5.5: corrija erros 400 e atualizações de progresso invisíveis
Valide parâmetros, renderização e histórico do ciclo de ferramentas antes de trocar o tráfego de produção.
Uma atualização pode falhar com HTTP 400 ou parecer parada apesar de a requisição ter funcionado. Claude Sonnet 5.5 muda a compatibilidade de parâmetros e a estrutura de algumas respostas. Na Messages API, substituir o ID é apenas o início.
Este guia é para quem mantém integrações. A documentação diz que Claude Managed Agents exige apenas a troca do nome do modelo. Quem usa o seletor de um produto não precisa editar parâmetros da API. Os exemplos explicam a documentação, não uma execução verificada em produção.
Separe a migração pelo modelo de origem
Vindo do Sonnet 5, verifique pensamento desativado, uso forçado de ferramentas, reprodução do histórico, computer use e pares de advisor. Do Sonnet 4.6 ou anterior, revise também orçamento manual de pensamento, amostragem e contagem de tokens. Do 4.5 ou anterior, confira assistant prefill e headers beta antigos.
O tokenizer é o mesmo do Sonnet 5. Em relação ao Sonnet 4.6, 4.5 e Haiku 4.5, a Anthropic relata cerca de 30% mais tokens para o mesmo texto, dependendo do conteúdo. São caminhos diferentes, não um aumento universal. Salve modelo, plataforma, SDK, definições de ferramentas, configuração de thinking e uma resposta bruta antes de alterar o código.
Remova primeiro os parâmetros incompatíveis
Use claude-sonnet-5-5. Adaptive thinking vem ligado e o esforço padrão da Claude API é High. thinking: {"type":"disabled"} passa a falhar. Para eliminar o pensamento inicial, use between_tools com Low, Medium ou High.
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=4096,
thinking={"type": "between_tools"},
output_config={"effort": "high"},
messages=[{"role": "user", "content": "Summarize the supplied release notes."}],
)
Não acrescente display, budget_tokens ou block_binding a between_tools. Esse modo não aceita Xhigh, Max nem mudança de esforço durante a conversa. Para esses casos, use adaptive e confira os requisitos beta. Sem ferramentas, between_tools responde sem raciocínio inicial; não é uma otimização universal para problemas que exigem raciocínio.
Os tipos any e tool de tool_choice também retornam 400. Use auto, explique quando chamar a ferramenta e aplique schemas strict onde houver suporte. Strict restringe argumentos quando ocorre uma chamada; não obriga a chamada. No Amazon Bedrock, Sonnet 5.5 não oferece strict tool use, portanto valide os argumentos na aplicação.
Ao migrar de modelos antigos, substitua budgets enabled, valores não padrão de temperature/top_p/top_k e assistant prefill. Não existe conversão fixa entre budget e esforço: avalie dois ou três níveis.
Uma interface silenciosa pode ter um problema de renderização
Notas mais longas entre chamadas passam a chegar em thinking blocks; comentários curtos podem continuar em text. Em adaptive, display omitted é o padrão: o bloco existe, mas o texto visível de thinking vem vazio. Um cliente que mostra somente text parece inativo.
Separe transporte, execução e exibição no diagnóstico. Repetir requisições indiscriminadamente pode duplicar efeitos sem recuperar o progresso. Em adaptive, display updates retorna atualizações e exige o header thinking-display-updates-2026-08-18. Summarized mistura atualizações e resumos de raciocínio. Between_tools já retorna resumos, sem campo display.
Leia a resposta por tipo de bloco, não por content[0].text. Devolva os blocos assistant intactos no ciclo de ferramentas, inclusive thinking vazio e assinaturas. O resumo exibido não substitui o bloco do protocolo.
Preserve o histórico e respeite diferenças de plataforma
Thinking blocks do Sonnet 5.5 vinculam-se ao modelo e à conversa anterior. Para contas criadas a partir de 31 de agosto de 2026, 00:00 UTC, a validação de prefixo é padrão. Editar mensagens antigas, instruções ou ferramentas e reenviar o bloco pode produzir 400.
Prefira histórico somente por acréscimo e as atualizações no meio da conversa documentadas. Blocos ilegíveis por outro modelo podem ser descartados mesmo com uma resposta bem-sucedida: HTTP 200 não prova que todo o raciocínio foi preservado.
Claude API e Google Cloud exigem computer_toolset_20260801; Amazon Bedrock ainda aceita computer_20251124. Integrações advisor precisam de pares compatíveis e tratamento de resultados criptografados. Um exemplo da Claude API não é automaticamente portátil.
Um diagnóstico por etapas: pedido, ferramentas e histórico
Este caso foi construído a partir das regras documentadas da API; não é um incidente de produção. Imagine uma integração com Sonnet 5 que desativa thinking, força uma consulta, exibe apenas blocos text e substitui o histórico por um resumo após cada rodada. Trocar o ID pode revelar três problemas diferentes.
Primeiro, corrija a rejeição do pedido. Se ele contém thinking.type=disabled e tool_choice.type=any, corrigir só um pode não bastar. Preserve o erro original, altere thinking para uma configuração suportada em ambiente isolado e depois use auto na seleção de ferramentas. Apagar todas as ferramentas e o histórico para obter 200 testa outro pedido; não valida o fluxo anterior.
Depois, valide a ferramenta separadamente. Auto não garante invocação. Use uma entrada que realmente exija consulta e faça a ferramenta de teste devolver um marcador identificável. Confira nome, argumentos e aproveitamento do resultado na resposta final. Se a tarefa exige estoque atual e o modelo responde sem consultar, sucesso HTTP não é aprovação. Pré-condições de negócio obrigatórias precisam de validação e bloqueio na aplicação; strict não substitui isso.
Por fim, repare progresso e histórico. Com o pedido aceito, inspecione content bruto e eventos de streaming antes de tratar silêncio como falha. Envie atualizações exibíveis à interface e preserve os blocos completos para a próxima rodada. Um array só de texto, sem blocos vazios, não atende às duas funções. Teste compactação de sessões longas separadamente: reescrita arbitrária de histórico por uma integração antiga não é automaticamente um protocolo suportado.
Pedido válido, ciclo de ferramenta concluído e histórico reutilizável são três critérios diferentes. Um não certifica o seguinte. Confira os formatos exatos no SDK e na documentação atuais; o caso não é um adaptador completo pronto para produção.
Guarde evidências que distingam os modos de falha
Os registros precisam identificar modelo e thinking/effort, pedido ou ferramenta que falhou, motivo de parada, tipos de blocos e efeitos já executados. Blocos brutos com assinaturas, dados de clientes ou credenciais exigem controle de acesso, não logs públicos.
| Observação | Primeira evidência a verificar | O que isso não demonstra |
|---|---|---|
| HTTP 400 | Erro completo, thinking/tool_choice antigos e plataforma | Perda de capacidade na tarefa |
| 200 sem progresso visível | Blocos, display, renderização e parser de streaming | Que as ferramentas não rodaram |
| Ferramenta funciona, resposta omite dados | Associação de tool_result e mensagem completa seguinte | Uso correto do resultado |
| Falha após editar histórico | Assinaturas, prefixo, conta e troca de modelo | Que repetir resolve |
| Resposta termina antes da entrega | stop_reason, max_tokens, resultados e estado da tarefa | Que receber texto significa concluir |
A finalidade é evitar recuperação errada. Uma escrita concluída seguida de queda da interface pode ser duplicada ao repetir a rodada inteira. A aplicação precisa consultar seu próprio estado transacional antes de tentar novamente. Migração de modelo não fornece deduplicação ou rollback de negócio.
Faça três grupos de regressão antes da troca
Primeiro, protocolo: texto simples, uma chamada real de ferramenta, progresso, recusas e término por max_tokens. Depois, histórico: turnos acrescentados, troca de modelo, compactação compatível e reprodução de sessões salvas. Por fim, entrega de negócio com entradas fixas e critérios de aceite, registrando qualidade, tempo, consumo e retrabalho.
Comece com ferramentas somente leitura e dados de teste. Amplie para operações com efeitos apenas depois de prevenir duplicações e definir rollback. Calibrar esforço não substitui validar compatibilidade.
FAQ
Trocar o ID basta?
Nem sempre na Messages API. Managed Agents possui um escopo diferente documentado.
Strict substitui a chamada forçada?
Não. Ele restringe os argumentos, não a decisão de chamar.
Posso excluir thinking vazio?
Pode ocultar texto vazio na interface; no ciclo, preserve os blocos do protocolo intactos.
Sem erro 400 a migração terminou?
Não. Valide progresso, histórico, efeitos e entrega aceita.