Migrando do Claude Haiku 4.5 para 5.5: Cinco Erros 400 e as Mudanças Silenciosas

Mudar de claude-haiku-4-5 para claude-haiku-5-5 é a menor parte dessa migração. Cinco padrões de solicitação que funcionavam no Haiku 4.5 agora retornam um erro 400, e várias outras mudanças não falham em nenhuma solicitação, mas alteram o que você recebe, o que custa ou como o modelo se comporta 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 solicitação em torno desses prompts é uma história diferente. Este post lista cada problema como você o encontrará: o que você verá, por que isso acontece e como corrigir, seguido por uma lista de verificação. A referência autoritária é o guia de migração do Haiku 5.5 da Anthropic.

Triagem: combine o sintoma

Os primeiros cinco falham de forma barulhenta. O restante falha silenciosamente, o que os torna mais caros de encontrar.

As cinco falhas barulhentas

1. Orçamentos de pensamento manual

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

Por que: O Haiku 4.5 suportava apenas pensamento manual estendido com um orçamento de tokens. O Haiku 5.5 suporta apenas pensamento adaptativo e controla a profundidade com effort.

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

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

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

2. Parâmetros de amostragem

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

Por que: O Haiku 5.5 aceita apenas os padrões: temperature de 1 e top_p de 0.99. Qualquer outro valor de um deles, qualquer top_k, ou enviar ambos temperature e top_p retorna um 400, independentemente de o pensamento ser usado ou não. Um top_p de 1 também é rejeitado.

Correção: remova os três. O caso comum é temperature=0 em um classificador, usado para obter rótulos estáveis. Substitua-o por uma saída estruturada ou uma ferramenta cujo input seja um enum, para que o conjunto de rótulos seja imposto pelo esquema em vez de pela amostragem. Também verifique wrappers de SDK e gateways que adicionam valores padrão de amostragem em seu nome.

3. Preenchimento do assistente

O que você verá: um 400 quando a última entrada em messages for uma vez do assistente, mesmo com o pensamento desligado.

Por que: o preenchimento não é suportado no Haiku 5.5, correspondendo ao restante da linha atual do Claude.

Correção: termine messages com uma vez do usuário e substitua o preenchimento pelo que era. O controle de formato se torna uma saída estruturada (output_config.format). Um preâmbulo preenchido se torna uma instrução de prompt do sistema para responder diretamente. Uma continuação de uma resposta interrompida se move para a mensagem do usuário: "Sua resposta anterior terminou com [texto]. Continue a partir daí."

4. Uso do computador

O que você verá: um 400 na API do Claude ou Google Cloud quando a solicitação declarar a ferramenta computer_20250124.

Por que: nessas plataformas, o Haiku 5.5 suporta o uso do computador apenas através do novo conjunto de ferramentas, computer_toolset_20260801.

Correção: remova o cabeçalho beta computer-use-2025-01-24, substitua a entrada da ferramenta por {"type": "computer_toolset_20260801"}, e atualize o loop do agente: despache em cada bloco tool_use pelo name e toolset_name em vez de input.action, lide com cada bloco desse tipo em uma vez, e ecoe toolset_name nos resultados. O Zoom está ativado por padrão; se seu ambiente não o implementar, desative-o na configuração do conjunto de ferramentas. No Amazon Bedrock, verifique as notas de compatibilidade da ferramenta de uso do computador antes de escolher uma versão. A mesma família de conjuntos de ferramentas também traz o uso do navegador, que o Haiku 4.5 nunca teve.

5. Editando turnos anteriores

O que você verá: um 400 quando uma solicitação envia de volta um bloco de pensamento após algo antes dele ter mudado: o prompt do sistema, a lista de ferramentas ou uma mensagem anterior.

Por que: um bloco de pensamento do Haiku 5.5 permanece válido apenas enquanto tudo enviado antes dele não for alterado. A verificação é aplicada por padrão para contas criadas em ou após 31 de agosto de 2026, e em contas mais antigas apenas quando uma solicitação opta por isso.

Correção: mantenha as conversas apenas para anexação. Os culpados comuns são um prompt do sistema com um timestamp, uma lista de ferramentas que cresce quando um plugin se conecta, truncamento do lado do cliente e lembretes injetados na história e removidos na próxima vez. Para instruções por vez, o Haiku 5.5 suporta mensagens do sistema dentro de messages, sem cabeçalho beta, que adicionam contexto sem editar o que veio antes.

As falhas silenciosas

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

O texto do pensamento está vazio por padrão. O Haiku 4.5 retornava um pensamento resumido. O Haiku 5.5 retorna blocos thinking com um campo de texto vazio e apenas uma assinatura. Se sua interface mostrava resumos de raciocínio, defina thinking: {"type": "adaptive", "display": "summarized"}. De qualquer forma, passe blocos de pensamento de volta inalterados com os resultados da ferramenta; um serializador que remove blocos vazios os exclui.

max_tokens agora precisa cobrir o pensamento. Um limite dimensionado para uma resposta curta pode ser consumido pelo pensamento, encerrando a resposta com stop_reason: "max_tokens" antes de qualquer texto. Aumente o limite ou diminua o esforço.

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

O esforço padrão é médio. O Haiku 4.5 não tinha configuração de esforço. O Haiku 5.5 tem como padrão medium, que pode ser mais pensamento do que uma rota simples precisa. Defina-o explicitamente.

Os blocos de pensamento permanecem com a conta que os criou. Se seu serviço reproduzir conversas armazenadas através de uma conta de API diferente, os blocos de pensamento do Haiku 5.5 são silenciosamente descartados e a solicitação é executada sem esse raciocínio. Reproduza cada conversa através da 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ê depender dele para o Haiku 4.5.

As listagens do gateway podem diferir. A página do Haiku 5.5 no AIHubMix atualmente lista um comprimento de contexto de 200K, enquanto a Anthropic especifica 1M. Confirme o limite na rota que você usa antes de migrar cargas de trabalho de longos prompts.

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

Recusas são novas, e nada as captura para você. O Haiku 5.5 executa classificadores de segurança em quatro categorias: cibernética, biológica, desenvolvimento de LLM de fronteira e danos gerais. Uma recusa retorna como um HTTP 200 normal com stop_reason: "refusal" e uma categoria em stop_details. Ao contrário do Sonnet 5.5 e do Opus 5.5, 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 solicitação recusada. Verifique stop_reason antes de ler content, e decida em seu próprio código se deve reformular, escalar para um modelo maior ou parar. De acordo com o post de lançamento, as salvaguardas cibernéticas permitem uma gama mais ampla de trabalho defensivo do que as do Sonnet 5.5, mas bloqueiam testes de penetração.

Texto do usuário dentro dos resultados da ferramenta pode ser ignorado. O Haiku 5.5 é treinado para resistir à injeção de prompts através dos resultados da ferramenta. Se seu sistema entregar uma mensagem que o usuário digitou durante a 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 da vez em um bloco de texto após o último resultado da ferramenta, e mantenha os avisos do sistema em uma mensagem separada.

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

Forçar uma ferramenta ignora o pensamento. A escolha forçada de tool_choice ainda é aceita, mas o modelo então chama a ferramenta sem pensar primeiro. Para ferramentas com efeitos colaterais, auto mais 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, forneça a data atual no prompt do sistema ou na descrição da ferramenta. Nos testes da Anthropic, isso ancorou respostas em resultados recentes.

Uma solicitação migrada através do AIHubMix

Um classificador do Haiku 4.5 que usava temperature=0, um orçamento de pensamento e um { preenchido para JSON, reescrito para o Haiku 5.5 no endpoint nativo do AIHubMix Claude:

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,                     # espaço para pensamento mais o JSON
    output_config={
        "effort": "low",                 # substitui o antigo orçamento de pensamento
        "format": {                      # substitui o preenchimento e 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: 'Fui cobrado duas vezes por outubro.'"}],
)

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

Se um gateway encaminha campos output_config e novos cabeçalhos beta inalterados vale a pena confirmar em sua primeira execução de teste. Quando a rota migrada passar em suas avaliações, a lista de modelos do AIHubMix facilita apontar o mesmo código para o Sonnet 5.5 para qualquer tipo de tarefa que continue falhando no Haiku.

Lista de verificação de migração

1. Altere o ID do modelo para claude-haiku-5-5, sem sufixo de data.
2. Substitua cada orçamento de pensamento por pensamento adaptativo e um nível de esforço explícito.
3. Remova temperatura, top_p e top_k, incluindo padrões adicionados por wrappers.
4. Substitua preenchimentos de assistente por saída estruturada, instruções do sistema ou continuações de vez do usuário.
5. Mova o uso do computador para o conjunto de ferramentas do computador e atualize o loop do agente.
6. Faça o histórico de conversas apenas para anexação se blocos de pensamento forem reproduzidos.
7. Leia o conteúdo da resposta por tipo de bloco e mantenha blocos de pensamento vazios ao reproduzir.
8. Aumente max_tokens em rotas de resposta curta ou diminua o esforço.
9. Lide com o motivo de parada de recusa antes de ler o conteúdo; não configure fallbacks do lado do servidor.
10. Reconte tokens de prompt no novo modelo e reestabeleça painéis de custo.
11. Verifique quais prompts agora ultrapassam 100K tokens e corte ou divida-os.
12. Defina a exibição como resumida se os usuários viram resumos de raciocínio.
13. Entregue a entrada do usuário no meio da vez fora dos resultados da ferramenta.
14. Dê a agentes habilitados para busca a data de hoje.
15. Verifique novamente os limites de taxa, necessidades do Priority Tier e o limite de contexto do seu gateway antes de mover volume.

FAQ

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

Por que meu classificador falha agora que removi a temperatura 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 a temperatura 0 jamais foi.

Posso ainda desligar o pensamento?
Sim, em baixo, médio e alto esforço. Em xhigh e max, desativar o pensamento retorna um erro. A Anthropic recomenda um nível de esforço mais baixo em vez disso, porque o modelo pode pular o pensamento em solicitaçõ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 deve reformular, enviar a solicitação para um modelo maior ou retornar um erro ao usuário.

Por que meu uso de tokens aumentou após a migração?
Duas razões. O novo tokenizador conta cerca de 30% mais tokens para o mesmo texto, e o pensamento está ativado por padrão, adicionando tokens de saída. Diminua o esforço e reconte seus prompts no novo modelo.

Preciso mudar algo para o cache de prompts?
Geralmente não, e fica mais fácil: o prompt mínimo armazenável cai de 4.096 para 512 tokens, e blocos de pensamento de turnos anteriores permanecem no prefixo armazenado por padrão. Evite editar turnos anteriores, que agora invalidam blocos de pensamento, assim como o cache.

Uma conversa pode passar do Haiku 5.5 para um modelo maior?
Sim. O Sonnet 5.5 e o Opus 5.5 leem os blocos de pensamento do Haiku 5.5, então uma conversa escalada para qualquer um deles mantém seu raciocínio anterior. Para outros modelos-alvo, verifique primeiro a documentação de pensamento preservado.

Continue lendo: a série Claude Haiku 5.5

• Antes de planejar a migração, é útil saber se o novo modelo atende ao seu padrão de qualidade. Para benchmarks contra Haiku 4.5, GPT-6 Luna e Sonnet 5.5, leia Claude Haiku 5.5 vs Haiku 4.5: O que Dez Centavos Agora Compra
• O passo 2 da lista de verificação pede que você escolha um nível de esforço. Para o que cada nível custa em tokens e onde começar, leia Níveis de Esforço do Claude Haiku 5.5: Médio é o Padrão, Baixo é Muitas Vezes Suficiente
• A mudança no tokenizador move a linha de preço, assim como seus painéis. Para ver o que isso faz a uma conta real, leia Precificação do Claude Haiku 5.5: A Linha de 100K Atrás da Redução de 90%

Fontes

• Guia de migração do Claude Haiku 5.5 (Documentos da Plataforma Claude)
• Prompting Claude Haiku 5.5 (Documentos da Plataforma Claude)
• Apresentando o Claude Haiku 5.5 (Anthropic)
• Claude Haiku 5.5 no AIHubMix
• Claude Haiku 5.5 Está Lançado a $0,10 por Milhão de Tokens. Leia a Regra de 100K Antes de Migrar (Newsletter do Roo)