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 código que chama o Claude Haiku 3.5 ou o Claude Haiku 3, faça também as alterações em Migrando para o Claude Haiku 5.5 a partir do Claude Haiku 3.5 e de modelos Haiku anteriores. Para migrar para um modelo Sonnet ou Opus, consulte Atualizar entre versões de modelo. Para saber por quanto tempo o Claude Haiku 4.5 permanece disponível, consulte Descontinuações de modelos.

Checklist de migração por modelo de origem

Percorra os grupos de cima para baixo e pare após aquele que menciona seu modelo atual. Se você usa o Claude Haiku 4.5, o primeiro grupo é a lista completa. Cada item é uma alteração a ser feita no seu código.

Todos os modelos de origem

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 e imagens grandes contam como mais tokens visuais. 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, substitua computer_20250124: na Claude API e no Google Cloud, pelo toolset computer_toolset_20260801; no Amazon Bedrock, por computer_20251124 e o cabeçalho beta computer-use-2025-11-24. 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.
11. Se você usa saídas estruturadas (output_config.format ou ferramentas com strict: true) no Amazon Bedrock, descreva o formato no prompt ou use uma ferramenta sem strict, e valide a saída no seu código. Saídas estruturadas não estão disponíveis para o Claude Haiku 5.5 no Amazon Bedrock.

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.

Claude Haiku 3.5 ou anterior

1. Substitua o ID de modelo do Claude Haiku 3.5 ou do Claude Haiku 3 pelo ID do Claude Haiku 5.5 para sua plataforma. Consulte Migrando para o Claude Haiku 5.5 a partir do Claude Haiku 3.5 e de modelos Haiku anteriores.
2. Se você usa a ferramenta legada code_execution_20250522, migre para code_execution_20250825 ou posterior.
3. Se você usa a ferramenta de editor de texto, migre para text_editor_20250728.
4. Trate os motivos de parada refusal e model_context_window_exceeded.
5. Se seu código compara exatamente parâmetros de string de chamadas de ferramenta, leve em conta quebras de linha finais.
6. Revise seus prompts.

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 da 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, incluindo seus preços mais altos para prompts longos. Consulte Preços de contexto longo.

Imagens grandes também podem custar mais tokens. O Claude Haiku 5.5 usa o nível de imagem de alta resolução, que reduz imagens acima de 2.576 pixels no lado maior ou de 4.784 tokens visuais. O Claude Haiku 4.5 e os modelos Haiku anteriores usam o nível padrão, que reduz imagens acima de 1.568 pixels no lado maior ou de 1.568 tokens visuais. Uma imagem de 2.000 por 1.500 pixels custa cerca de 2,5 vezes mais tokens visuais no Claude Haiku 5.5 do que no Claude Haiku 4.5. Consulte Resolução e custo em tokens.

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.

Os blocos de pensamento de turnos anteriores do assistente permanecem no contexto e contam como tokens de entrada, enquanto o Claude Haiku 4.5 mantinha apenas os do turno mais recente. Conversas com vários turnos, portanto, carregam mais tokens de entrada do que a mudança de tokenizador sozinha explica. Para remover blocos mais antigos, use a limpeza de blocos de pensamento. Consulte Preservação de blocos de pensamento por modelo.

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.

O Claude Haiku 5.5 lê blocos de pensamento do Claude Sonnet 5, do Claude Opus 4.8, do Claude Haiku 4.5 e de modelos anteriores, então uma conversa que você muda do Claude Haiku 4.5 para o Claude Haiku 5.5 mantém seu raciocínio. Ele não lê blocos do Claude Opus 5, do Claude Opus 5.5, do Claude Sonnet 5.5 nem de qualquer modelo Claude Fable ou Claude Mythos; a API os descarta sem erro. Na Claude API e no Google Cloud, o Claude Opus 5.5 e o Claude Sonnet 5.5 leem os blocos do Claude Haiku 5.5. Consulte Trocar de modelo no meio da conversa.

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 Amazon Bedrock, saídas estruturadas não estão disponíveis para o Claude Haiku 5.5. Nesse caso, descreva o formato no prompt ou use uma ferramenta sem strict, e valide a saída no seu código.
• 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. No Amazon Bedrock, o Claude Haiku 5.5 também não aceita computer_20250124; use a versão de ferramenta computer_20251124 com o cabeçalho beta computer-use-2025-11-24.

Para migrar uma integração para o toolset, remova o cabeçalho beta computer-use-2025-01-24 e substitua a entrada em tools por {"type": "computer_toolset_20260801"}. Em seguida, faça as demais alterações na requisição e no loop do agente descritas em Migrar de computer_20251124: despache com base em name e toolset_name de cada bloco tool_use membro em vez de input.action, trate todos esses blocos em um turno e repita toolset_name nos resultados. O zoom vem 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.

Migrando para o Claude Haiku 5.5 a partir do Claude Haiku 3.5 e de modelos Haiku anteriores

O Claude Haiku 3.5 está desativado na Claude API e no Amazon Bedrock, e o Claude Haiku 3 está desativado na Claude API e no Google Cloud. Requisições a um modelo desativado falham. O Google Cloud lista o Claude Haiku 3.5 como descontinuado e disponível apenas para clientes existentes. Consulte Descontinuações de modelos.

A partir de qualquer um desses modelos, primeiro aplique todas as seções anteriores e, em seguida, estas alterações:

• ID do modelo: Substitua claude-3-5-haiku-20241022, seu alias claude-3-5-haiku-latest, ou claude-3-haiku-20240307 por claude-haiku-5-5. No Google Cloud, substitua claude-3-5-haiku@20241022 por claude-haiku-5-5. No Amazon Bedrock, use o ID do Claude Haiku 5.5 de Use o ID do modelo Claude Haiku 5.5.
• Execução de código: O Claude Haiku 5.5 aceita code_execution_20250825 e versões posteriores. Se você usa a ferramenta legada code_execution_20250522, exclusiva para Python, migre para uma delas. Consulte Atualizar para a versão mais recente da ferramenta.
• Editor de texto: Se você usa a ferramenta de editor de texto, migre para text_editor_20250728 (nome da ferramenta str_replace_based_edit_tool), que não tem o comando undo_edit. Consulte Ferramenta de editor de texto.
• Motivos de parada: Trate refusal e model_context_window_exceeded. Consulte Tratando motivos de parada.
• Quebras de linha finais: O Claude 4.5 e modelos posteriores mantêm quebras de linha finais em parâmetros de string de chamadas de ferramenta. Se seu código compara essas strings exatamente, leve-as em conta.
• Prompts: O Claude 4 e modelos posteriores têm um estilo de comunicação mais conciso e direto e precisam de instruções explícitas. Revise seus prompts com base em Prompting do Claude Haiku 5.5 e nas melhores práticas de prompting.