Guia de migração para o Claude Haiku 5.5

Este guia aborda a migração de código que chama o Claude Haiku 4.5 para o Claude Haiku 5.5. Para migrar para um modelo Sonnet ou Opus, consulte Atualizar entre versões de modelos. Para saber por quanto tempo o Claude Haiku 4.5 permanece disponível, consulte Descontinuações de modelos.

Lista de verificação de migração

Cada item é uma alteração a ser feita no código que chama o Claude Haiku 4.5.

1. Substitua o ID do modelo pelo ID do Claude Haiku 5.5 para sua plataforma. Consulte Use o ID do modelo Claude Haiku 5.5.
2. Reconte seus prompts e revise os limites de max_tokens e as estimativas de custo, porque o mesmo texto conta como mais tokens. Consulte Reconte os tokens.
3. Se suas requisições enviam thinking: {"type": "enabled", "budget_tokens": N}, altere thinking para {"type": "adaptive"}. Consulte Configure o pensamento.
4. Se seu código lê o primeiro bloco de conteúdo como a resposta, selecione os blocos por type. Consulte Configure o pensamento.
5. Remova temperature, top_p e top_k de suas requisições. Consulte Remova os parâmetros de amostragem.
6. Se suas requisições terminam messages com um turno do assistente para o modelo continuar, termine-as com um turno do usuário. Consulte Substitua o prefill do assistente.
7. Se você usa a ferramenta de uso de computador na Claude API ou no Google Cloud, migre de computer_20250124 para o toolset computer_toolset_20260801. Consulte Migre o uso de computador para o toolset.
8. Se você reproduz conversas armazenadas por meio de uma conta diferente, reproduza cada uma por meio da conta que a produziu. Consulte Reproduza blocos de pensamento por meio da conta que os produziu.
9. Se seu código altera system, tools ou messages anteriores entre requisições em uma conversa e envia blocos de pensamento de volta, mantenha a conversa somente com acréscimos (append-only). Consulte Mantenha os turnos anteriores inalterados.
10. Trate stop_reason: "refusal". O Claude Haiku 5.5 executa classificadores de segurança que podem recusar uma requisição, e não possui fallback no lado do servidor. Consulte Recusas de salvaguarda.

Se sua organização tem um compromisso de Priority Tier no Claude Haiku 4.5, planeje a capacidade separadamente: o Priority Tier não é suportado no Claude Haiku 5.5.

Use o ID do modelo Claude Haiku 5.5

Substitua o ID do modelo Claude Haiku 4.5 pelo ID do Claude Haiku 5.5 para sua plataforma.

claude-haiku-5-5 é um ID de modelo fixo, sem sufixo de data e sem alias separado.

Reconte os tokens

O Claude Haiku 5.5 usa o mesmo "tokenizer" (tokenizador) mais recente do Claude 4.7 e de modelos posteriores. Como em todos os modelos que usam esse tokenizador, o mesmo texto de entrada produz aproximadamente 30% mais tokens no Claude Haiku 5.5 do que no Claude Haiku 4.5. O aumento exato depende do conteúdo. Requisições, respostas e eventos de streaming mantêm o mesmo formato. O que muda é tudo o que você mede ou orça em tokens:

• Os campos de usage e os resultados de contagem de tokens são maiores para o mesmo texto.
• Um determinado número de tokens comporta menos texto.
• Um limite de max_tokens ajustado para o Claude Haiku 4.5 pode cortar uma saída equivalente.
• Estimativas de custo feitas a partir das contagens de tokens do Claude Haiku 4.5 precisam ser recalculadas com as contagens e os preços do Claude Haiku 5.5.

Conte seus prompts com model definido como claude-haiku-5-5 em vez de reutilizar contagens medidas no Claude Haiku 4.5.

Configure o pensamento

O Claude Haiku 5.5 configura o pensamento de forma diferente do Claude Haiku 4.5. Um valor de thinking igual a {"type": "enabled", "budget_tokens": N} retorna um erro 400, portanto uma requisição que o envia precisa de um novo valor de thinking.

Antes, uma requisição ao Claude Haiku 4.5 definia thinking como enabled com um orçamento de tokens:

{
  "model": "claude-haiku-4-5",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "..." }]
}

Depois, a mesma requisição ao Claude Haiku 5.5 usa "adaptive thinking" (pensamento adaptativo). O valor de thinking muda, e output_config.effort define o quanto o modelo pensa:

{
  "model": "claude-haiku-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

O pensamento adaptativo é ativado por padrão, então uma resposta pode começar com um ou mais blocos thinking mesmo quando a requisição não define thinking. Deixe thinking sem definir ou defina-o como {"type": "adaptive"}, e use o "effort" (esforço) como alavanca: onde o Claude Haiku 4.5 era executado sem pensamento, ou com um orçamento pequeno para economizar tokens, escolha um nível de esforço mais baixo. Em um nível mais baixo, o modelo pensa menos e pode pular o pensamento completamente em requisições mais simples. Para orientações sobre prompts, consulte Use o esforço para controlar o pensamento. Selecione os blocos de conteúdo pelo campo type em vez de pela posição, e envie os blocos thinking de volta sem modificações junto com os resultados das ferramentas.

Os tokens de pensamento contam para max_tokens, então uma requisição com um max_tokens pequeno pode parar com stop_reason: "max_tokens" após um bloco thinking e antes de qualquer texto. Se você definiu um max_tokens pequeno para o Claude Haiku 4.5, aumente-o para deixar espaço para o pensamento, ou escolha um nível de esforço mais baixo.

Por padrão, o Claude Haiku 5.5 retorna cada bloco thinking com um campo thinking vazio e apenas uma signature, enquanto o Claude Haiku 4.5 retornava o pensamento resumido. Para receber o pensamento resumido, defina thinking: {"type": "adaptive", "display": "summarized"}.

O Claude Haiku 5.5 aceita um tool_choice forçado (any ou uma ferramenta nomeada), mas a resposta começa com a chamada da ferramenta e não tem bloco thinking. Para permitir que o modelo pense antes de chamar uma ferramenta, use tool_choice: {"type": "auto"} e diga no prompt quando usar a ferramenta.

Remova os parâmetros de amostragem

O Claude Haiku 4.5 aceita temperature, top_p e top_k. No Claude Haiku 5.5, omita os três e use prompts para orientar o comportamento do modelo. Se uma requisição incluir temperature, ele deve ser 1. Se incluir top_p, ele deve ser 0.99, seu valor padrão. Qualquer outro valor de temperature ou top_p retorna um erro 400, incluindo um top_p igual a 1. O mesmo acontece com qualquer valor de top_k e com uma requisição que inclua tanto temperature quanto top_p.

Substitua o prefill do assistente

Um "prefill" (preenchimento prévio) é um turno final do assistente em messages que o modelo continua. O Claude Haiku 4.5 aceita um quando o pensamento está desativado. O Claude Haiku 5.5 o rejeita com um erro 400, mesmo com o pensamento desativado. Termine messages com um turno do usuário e substitua cada prefill de acordo com sua finalidade:

• Formato de saída: use saídas estruturadas, ou ferramentas com campos enum para classificação. No Claude no Amazon Bedrock, que não suporta saídas estruturadas, use ferramentas.
• Preâmbulos: peça no prompt do sistema uma resposta direta.
• Continuações: mova-as para a mensagem do usuário, por exemplo "Sua resposta anterior foi interrompida e terminou com [previous_response]. Continue de onde parou."
• Lembretes de contexto: coloque-os no turno do usuário.

Migre o uso de computador para o toolset

O Claude Haiku 4.5 suporta o uso de computador por meio da ferramenta computer_20250124, com o cabeçalho beta computer-use-2025-01-24. Na Claude API e no Google Cloud, o Claude Haiku 5.5 suporta o uso de computador apenas por meio do toolset computer_toolset_20260801, e uma requisição que declara computer_20250124 retorna um erro 400.

Para migrar uma integração, remova o cabeçalho beta computer-use-2025-01-24 e substitua a entrada de tools por {"type": "computer_toolset_20260801"}. Em seguida, faça as outras alterações na requisição e no loop do agente descritas em Migrar de computer_20251124: despache com base no name e no toolset_name de cada bloco tool_use membro em vez de input.action, trate todos esses blocos em um turno e repita o toolset_name nos resultados. O zoom é ativado por padrão no toolset; se seu ambiente não o implementa, adicione "configs": {"zoom": {"enabled": false}}. Se você envia o cabeçalho beta fine-grained-tool-streaming-2025-05-14, remova-o. Junto com uma entrada de toolset, ele retorna um erro 400. Para outras plataformas, consulte a seção Compatibilidade da ferramenta de uso de computador.

Na Claude API e no Google Cloud, o Claude Haiku 5.5 também suporta a ferramenta de uso do navegador (browser_toolset_20260801) para tarefas dentro de páginas web. O Claude Haiku 4.5 não a suporta.

Reproduza blocos de pensamento por meio da conta que os produziu

Os blocos de pensamento do Claude Haiku 5.5 funcionam apenas na conta que os produziu, ou em uma conta vinculada a ela. Quando outra conta envia um desses blocos, a API descarta o bloco antes que o modelo o veja, e a requisição é bem-sucedida sem esse raciocínio. Isso afeta código que armazena conversas e as reproduz por meio de uma conta diferente, por exemplo um serviço que atende vários clientes a partir de um único armazenamento de conversas. Reproduza cada conversa por meio da conta que a produziu. Consulte Os blocos de pensamento permanecem com a conta que os produziu.

Mantenha os turnos anteriores inalterados

Um bloco de pensamento do Claude Haiku 5.5 permanece válido apenas enquanto tudo o que foi enviado antes dele permanecer inalterado: uma requisição que envia um bloco de pensamento de volta após uma alteração em system, tools ou messages anteriores retorna um erro 400. O Claude Haiku 4.5 não executa essa verificação. Mantenha as conversas somente com acréscimos. Em contas criadas antes de 31 de agosto de 2026, 00:00 UTC, o erro ocorre apenas em requisições que definem thinking.block_binding.prefix_mismatch_behavior. Para saber quais alterações acionam o erro e o que fazer em vez disso, consulte Quem precisa mudar alguma coisa.