Migrando do Claude Haiku 4.5 para o 5.5: cinco erros 400 e as mudanças silenciosas

AIHubMix9 min de leitura
Migrando do Claude Haiku 4.5 para o 5.5: cinco erros 400 e as mudanças silenciosas

Trocar claude-haiku-4-5 por claude-haiku-5-5 é a parte menor desta migração. Cinco padrões de requisição que funcionavam no Haiku 4.5 agora retornam um erro 400, e várias outras mudanças não falham nenhuma requisição, mas alteram o que você recebe de volta, o custo ou o comportamento do modelo dentro de um agente.

A Anthropic afirma que os prompts existentes do Haiku 4.5 devem funcionar bem no Haiku 5.5 sem alterações. O código de requisição em torno desses prompts é outra história. Este post lista cada problema da forma como você vai encontrá-lo: o que você verá, por que acontece e como corrigir, seguido de uma checklist. A referência oficial é o guia de migração do Haiku 5.5 da Anthropic.

Triagem: associe o sintoma

O que você vê Causa Correção
400 em uma requisição com orçamento de thinking Thinking manual removido Thinking adaptativo mais effort
400 com temperature, top_p ou top_k Parâmetros de amostragem travados Remova-os
400 quando as mensagens terminam em um turno do assistente Prefill removido Termine em um turno do usuário
400 em uso de computador Ferramenta de computador antiga rejeitada Migre para o toolset de computador
400 após editar turnos anteriores Thinking vinculado ao histórico Mantenha o histórico somente com acréscimos
O parser retorna texto vazio ou errado O bloco de thinking vem primeiro Selecione os blocos pelo tipo
Resposta cortada ou ausente O thinking conta para o limite Aumente o max_tokens ou reduza o effort
Contagem de tokens e cobrança sobem cerca de 30% Novo tokenizador Recalcule no novo modelo
Resposta com stop reason refusal Novos classificadores de segurança Trate no seu cliente

As cinco primeiras falham de forma ruidosa. As demais falham em silêncio, o que as torna mais caras de encontrar.

As cinco falhas ruidosas

1. Orçamentos de thinking manuais

O que você verá: um 400 em qualquer requisição que envie thinking: {"type": "enabled", "budget_tokens": N}.

Por quê: o Haiku 4.5 só suportava extended thinking manual com um orçamento de tokens. O Haiku 5.5 suporta apenas thinking adaptativo e controla a profundidade com effort.

Correção: envie {"type": "adaptive"} ou omita thinking, e escolha um nível de effort. Quando o orçamento antigo era pequeno para economizar tokens, escolha um nível baixo.

# Before: Haiku 4.5
thinking={"type": "enabled", "budget_tokens": 8000}

# After: Haiku 5.5
thinking={"type": "adaptive"},
output_config={"effort": "medium"},

2. Parâmetros de amostragem

O que você verá: um 400 quando uma requisição define temperature, top_p ou top_k.

Por quê: o Haiku 5.5 aceita apenas os valores padrão: temperature igual a 1 e top_p igual a 0,99. Qualquer outro valor de um dos dois, qualquer top_k, ou o envio de temperature e top_p juntos retorna um 400, com ou sem thinking. Um top_p igual a 1 também é rejeitado.

Correção: remova os três. O caso mais comum é temperature=0 em um classificador, usado para obter rótulos estáveis. Substitua por saída estruturada ou por uma ferramenta cuja entrada seja um enum, de modo que o conjunto de rótulos seja imposto pelo schema, e não pela amostragem. Verifique também wrappers de SDK e gateways que adicionam valores de amostragem padrão em seu nome.

3. Prefill do assistente

O que você verá: um 400 quando o último item de messages é um turno do assistente, mesmo com thinking desativado.

Por quê: o prefill não é suportado no Haiku 5.5, seguindo o restante da linha atual do Claude.

Correção: termine messages com um turno do usuário e substitua o prefill pelo que ele fazia. O controle de formato passa a ser saída estruturada (output_config.format). Um preâmbulo pré-preenchido vira uma instrução no system prompt para responder diretamente. A continuação de uma resposta interrompida vai para a mensagem do usuário: "Sua resposta anterior terminou em [texto]. Continue a partir daí."

4. Uso de computador

O que você verá: um 400 na Claude API ou no Google Cloud quando a requisição declara a ferramenta computer_20250124.

Por quê: nessas plataformas, o Haiku 5.5 suporta uso de computador apenas pelo toolset mais novo, computer_toolset_20260801.

Correção: remova o header beta computer-use-2025-01-24, substitua a entrada da ferramenta por {"type": "computer_toolset_20260801"} e atualize o loop do agente: despache com base no name e no toolset_name de cada bloco tool_use, em vez de em input.action, trate todos esses blocos em um turno e devolva toolset_name nos resultados. O zoom fica ativado por padrão; se o seu ambiente não o implementar, desative-o na configuração do toolset. No Amazon Bedrock, verifique as notas de compatibilidade da ferramenta de uso de computador antes de escolher uma versão. A mesma família de toolsets também traz uso de navegador, que o Haiku 4.5 nunca teve.

5. Edição de turnos anteriores

O que você verá: um 400 quando uma requisição devolve um bloco de thinking depois que algo anterior mudou: o system prompt, a lista de ferramentas ou uma mensagem anterior.

Por quê: um bloco de thinking do Haiku 5.5 só continua válido enquanto tudo enviado antes dele permanecer inalterado. A verificação é aplicada por padrão para contas criadas em ou após 31 de agosto de 2026, e em contas mais antigas somente quando a requisição opta por ela.

Correção: mantenha as conversas somente com acréscimos. Os principais culpados são um system prompt com timestamp, uma lista de ferramentas que cresce quando um plugin se conecta, truncamento no lado do cliente e lembretes injetados no histórico e removidos no turno seguinte. Para instruções por turno, o Haiku 5.5 suporta mensagens de sistema dentro de messages, sem header beta, que adicionam contexto sem editar o que veio antes.

As falhas silenciosas

Os blocos de thinking vêm primeiro. O thinking vem ativado por padrão, então uma resposta pode começar com um ou mais blocos thinking. Código que lê response.content[0].text como a resposta quebra ou retorna texto vazio. Selecione os blocos pelo type.

O texto do thinking vem vazio por padrão. O Haiku 4.5 retornava o thinking resumido. O Haiku 5.5 retorna blocos thinking com o campo de texto vazio e apenas uma assinatura. Se sua interface mostrava resumos do raciocínio, defina thinking: {"type": "adaptive", "display": "summarized"}. De qualquer forma, devolva os blocos de thinking sem alterações junto com os resultados de ferramentas; um serializador que descarta blocos vazios os remove.

O max_tokens agora precisa cobrir o thinking. Um limite dimensionado para uma resposta curta pode ser consumido pelo thinking, encerrando a resposta com stop_reason: "max_tokens" antes de qualquer texto. Aumente o limite ou reduza o effort.

O mesmo texto consome cerca de 30% mais tokens. O novo tokenizador altera os campos de usage, os resultados de count_tokens, os orçamentos de contexto e qualquer max_tokens ajustado para o Haiku 4.5. Ele também desloca o limite de preço de 100K tokens para cerca de 77K tokens, na contagem que o Haiku 4.5 fazia. Recalcule prompts reais com o modelo definido como claude-haiku-5-5 antes de confiar em um painel de custos.

O effort padrão é medium. O Haiku 4.5 não tinha configuração de effort. O Haiku 5.5 usa medium por padrão, o que pode ser mais thinking do que uma rota simples precisa. Defina explicitamente.

Os blocos de thinking ficam com a conta que os gerou. Se o seu serviço reproduz conversas armazenadas por meio de outra conta de API, os blocos de thinking do Haiku 5.5 são descartados silenciosamente e a requisição roda sem esse raciocínio. Reproduza cada conversa pela conta que a produziu.

O Priority Tier não é transferido. O Haiku 5.5 não suporta o Priority Tier, então planeje a capacidade separadamente se você depende dele para o Haiku 4.5.

Mudanças de comportamento que importam para agentes com permissões reais

Recusas são novidade, e nada as captura por você. O Haiku 5.5 executa classificadores de segurança em quatro categorias: cyber, bio, desenvolvimento de LLMs de fronteira e danos gerais. Uma recusa volta como um HTTP 200 normal com stop_reason: "refusal" e uma categoria em stop_details. O Haiku 5.5 não tem fallback do lado do servidor: uma lista de modelos de fallback retorna um 400, e o modo de fallback padrão deixa a requisição recusada. Verifique stop_reason antes de ler content e decida no seu próprio código se deve reformular, escalar para um modelo maior ou parar. Segundo o post de lançamento, as salvaguardas de cyber permitem uma gama mais ampla de trabalho defensivo do que o Sonnet 5.5, mas bloqueiam testes de penetração.

Texto do usuário dentro de resultados de ferramentas pode ser ignorado. O Haiku 5.5 é treinado para resistir a prompt injection por meio de resultados de ferramentas. Se o seu harness entrega uma mensagem que o usuário digitou no meio da tarefa dentro de um bloco tool_result, o modelo pode tratá-la como não confiável e ignorá-la. Coloque a entrada do usuário no meio do turno em um bloco de texto após o último resultado de ferramenta, e mantenha os avisos do harness em uma mensagem de sistema separada.

Com effort baixo, agentes podem parar cedo ou pular verificações. Com um system prompt longo de agente de código em low, o Haiku 5.5 às vezes devolve a tarefa antes de concluí-la, e em low e medium às vezes informa uma mudança de código como concluída sem executar um teste. O guia de prompting do Haiku 5.5 da Anthropic traz instruções curtas para ambos os casos. Para um agente que pode escrever arquivos ou executar comandos, um "concluído" não verificado é o mais perigoso dos dois.

Forçar uma ferramenta pula o thinking. O tool_choice forçado ainda é aceito, mas o modelo então chama a ferramenta sem pensar antes. Para ferramentas com efeitos colaterais, auto combinado com uma instrução clara permite que o modelo raciocine antes de agir.

Ferramentas de busca precisam da data de hoje. Quando o Haiku 5.5 tem uma ferramenta de busca, informe a data atual no system prompt ou na descrição da ferramenta. Nos testes da Anthropic, isso fundamentou as respostas em resultados recentes.

Uma requisição migrada pelo AIHubMix

Um classificador do Haiku 4.5 que usava temperature=0 e um { pré-preenchido para JSON, reescrito para o Haiku 5.5 no endpoint nativo do Claude do AIHubMix:

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["AIHUBMIX_API_KEY"],
    base_url="https://aihubmix.com",
)

r = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=2000,                     # room for thinking plus the JSON
    output_config={
        "effort": "low",                 # thinking is on by default; keep it light
        "format": {                      # replaces the prefill and temperature=0
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "label": {"type": "string", "enum": ["billing", "bug", "other"]}
                },
                "required": ["label"],
                "additionalProperties": False,
            },
        },
    },
    messages=[{"role": "user", "content": "Ticket: 'I was charged twice for October.'"}],
)

if r.stop_reason == "refusal":
    raise RuntimeError(f"declined: {r.stop_details}")
text = next(b.text for b in r.content if b.type == "text")
print(text)

Vale confirmar, na primeira execução de teste, se um gateway repassa os campos de output_config e os headers beta mais novos sem alterações. Quando a rota migrada passar nas suas avaliações, a lista de modelos do AIHubMix facilita apontar o mesmo código para o Sonnet 5.5 em qualquer tipo de tarefa que continue falhando no Haiku.

Checklist de migração

  1. Troque o ID do modelo para claude-haiku-5-5, sem sufixo de data.
  2. Substitua cada orçamento de thinking por thinking adaptativo com um nível de effort explícito.
  3. Remova temperature, top_p e top_k, incluindo padrões adicionados por wrappers.
  4. Substitua os preenchimentos do assistente por saída estruturada, instruções de sistema ou continuações no turno do usuário.
  5. Mova o uso de computador para o conjunto de ferramentas de computador e atualize o loop do agente.
  6. Torne o histórico da conversa somente de acréscimo se os blocos de thinking forem reenviados.
  7. Leia o conteúdo da resposta por tipo de bloco e mantenha os blocos de thinking vazios ao reenviar.
  8. Aumente o max_tokens nas rotas de respostas curtas ou reduza o effort.
  9. Trate o motivo de parada refusal antes de ler o conteúdo; não configure fallbacks do lado do servidor.
  10. Recalcule os tokens dos prompts no novo modelo e refaça a linha de base dos painéis de custo.
  11. Verifique quais prompts agora ultrapassam 100K tokens e reduza-os ou divida-os.
  12. Defina display como summarized se os usuários viam resumos de raciocínio.
  13. Entregue a entrada do usuário no meio do turno fora dos resultados de ferramentas.
  14. Informe a data de hoje aos agentes com pesquisa habilitada.
  15. Verifique novamente os limites de taxa e a necessidade do Priority Tier antes de migrar o volume.

FAQ

Meus prompts do Haiku 4.5 vão funcionar no Haiku 5.5?
A Anthropic diz que os prompts existentes devem funcionar bem sem alterações. Os parâmetros da requisição em torno deles são o que quebra: orçamentos de thinking, configurações de amostragem, preenchimentos e a antiga ferramenta de uso de computador retornam erros.

Por que meu classificador falha agora que removi temperature 0?
Não deveria falhar, mas os rótulos podem variar mais. Use saída estruturada ou uma ferramenta com um campo enum para que os rótulos permitidos sejam impostos pelo esquema. Isso é mais confiável do que temperature 0 jamais foi.

Ainda posso desativar o thinking?
Sim, nos níveis de effort low, medium e high. Em xhigh e max, desativar o thinking retorna um erro. A Anthropic recomenda um nível de effort mais baixo, porque o modelo pode pular o thinking em requisições simples por conta própria.

O que meu código deve fazer quando o Haiku 5.5 recusa?
Verifique o motivo de parada antes de ler o conteúdo. O Haiku 5.5 não tem fallback do lado do servidor, então seu código decide se reformula, envia a requisição para um modelo maior ou retorna um erro ao usuário.

Por que meu uso de tokens aumentou após a migração?
Dois motivos. O novo tokenizador conta cerca de 30% mais tokens para o mesmo texto, e o thinking vem ativado por padrão, adicionando tokens de saída. Reduza o effort e recalcule seus prompts no novo modelo.

Preciso mudar algo para o cache de prompts?
Geralmente não, e fica mais fácil: segundo o guia de migração da Anthropic, o prompt mínimo cacheável cai de 4.096 para 512 tokens, e os blocos de thinking de turnos anteriores permanecem no prefixo em cache por padrão. Evite editar turnos anteriores, pois isso invalida os blocos de thinking e também o cache.

Uma conversa pode passar do Haiku 5.5 para um modelo maior?
Sim, a própria conversa é transferida. Se os blocos de thinking anteriores do Haiku 5.5 também são transferidos depende do modelo de destino, então consulte a documentação de thinking preservado da Anthropic antes de depender disso.

Continue lendo: a série Claude Haiku 5.5

Fontes

Um só gateway para vários provedores de IA. Feito para produção.

Acessar AIHubMix