Migrando para o Claude Sonnet 5.5

Este guia lista as alterações de código necessárias para migrar para o Claude Sonnet 5.5 a partir do Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Sonnet 4, Claude 3.7 Sonnet ou Claude Haiku 4.5. Leia as duas primeiras seções e depois continue lendo até a seção do seu modelo atual. A lista de verificação de migração lista todas as alterações por modelo de origem.

O Claude Sonnet 5.5 tem os mesmos preços do Claude Sonnet 5. Consulte Preços do Claude. Para a "context window" (janela de contexto) e os limites de saída, consulte a página do modelo Claude Sonnet 5.5. Para recursos e prompts, consulte Novidades do Claude Sonnet 5.5 e Criando prompts para o Claude Sonnet 5.5.

Envie uma solicitação ao Claude Sonnet 5.5

Esta solicitação funciona no Claude Sonnet 5.5 como está escrita. Ela define um "effort level" (nível de esforço), e as abas de SDK leem a resposta por tipo de bloco. Ela omite cinco configurações que retornam um erro 400: orçamentos de pensamento, parâmetros de amostragem, "assistant prefill" (preenchimento prévio do assistente), escolha forçada de ferramenta e thinking: {"type": "disabled"}.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

print(f"Stop reason: {response.stop_reason}")
for block in response.content:
    if block.type == "text":
        print(block.text)

O pensamento é executado por padrão

No Claude Sonnet 5.5, uma solicitação sem o campo thinking é executada com "adaptive thinking" (pensamento adaptativo), assim como thinking: {"type": "adaptive"}. No Claude Sonnet 4.6 e modelos anteriores, e no Claude Haiku 4.5, essa solicitação era executada sem pensamento. Para continuar executando sem pensamento antecipado, consulte Desative o pensamento antecipado.

Trate o pensamento nas respostas

Código que era executado sem pensamento precisa dos três itens. Código vindo do Claude Sonnet 5 provavelmente já tem os dois primeiros.

• Leia os blocos de conteúdo por type. Uma resposta pode começar com blocos thinking, então código que lê content[0].text deixa de funcionar.
• Devolva os blocos thinking sem alterações em loops de "tool use" (uso de ferramentas), incluindo os vazios. Consulte Preservando blocos de pensamento.
• Revise max_tokens. Ele abrange pensamento mais texto, e os tokens de pensamento são cobrados como tokens de saída. Consulte Controle de custos.

O texto do pensamento é omitido por padrão. Os blocos thinking chegam com um campo thinking vazio e uma signature. Para obter resumos legíveis, defina display: "summarized", o padrão no Claude Sonnet 4.6 e modelos anteriores, e no Claude Haiku 4.5. Consulte Controlando a exibição do pensamento.

Desative o pensamento antecipado

Para desativar o pensamento antecipado no Claude Sonnet 5.5, envie thinking: {"type": "between_tools"}. Essa é a configuração de pensamento mais baixa. Suas atualizações de progresso entre chamadas de ferramentas ainda retornam como blocos thinking com seu texto de resumo. Sem ferramentas, a resposta contém apenas texto. O Claude Sonnet 5, por sua vez, desativa o pensamento com thinking: {"type": "disabled"}, e os modelos anteriores são executados sem pensamento por padrão. No Claude Sonnet 5.5, disabled retorna um invalid_request_error 400:

"thinking.type.disabled" is not supported for this model. Use "thinking.type.between_tools" for the lowest thinking setting, or "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

between_tools funciona em todas as plataformas que oferecem o Claude Sonnet 5.5, sem cabeçalho beta. Ele é aceito nos esforços low, medium e high. Em xhigh ou max, ele retorna um erro 400. Para executar nesses níveis, use o pensamento adaptativo: omita o campo thinking ou envie thinking: {"type": "adaptive"}. between_tools não aceita nenhum outro campo: display, budget_tokens ou block_binding enviados com ele retornam um erro 400. Com o fallback no lado do servidor, uma solicitação between_tools que recorre ao Claude Sonnet 5 é executada lá com thinking: {"type": "disabled"}.

Com between_tools, o esforço não pode mudar no meio da conversa: um output_config.effort por mensagem que difira do nível em vigor retorna um erro 400. Para variar o esforço a cada turno, use o pensamento adaptativo. Para orientações sobre prompts, consulte Executando sem pensamento antecipado.

Em versões de SDK que não definem between_tools, os exemplos em Python e TypeScript falham na verificação de tipos. Atualize o SDK ou passe o valor como JSON bruto, como fazem os exemplos em C#, Go e Java.

Antes (Claude Sonnet 5):

client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "..."}],
)

Depois (Claude Sonnet 5.5):

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "between_tools"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

Lista de verificação de migração por modelo de origem

Percorra os grupos de cima para baixo e pare após aquele que nomeia o seu modelo. No Claude Haiku 4.5, aplique todos os grupos, exceto "Claude Sonnet 4 ou anterior", terminando com "Somente Claude Haiku 4.5".

Todos os modelos de origem

• Altere o ID do modelo para claude-sonnet-5-5.
• Leia os blocos de conteúdo por type e devolva os blocos thinking sem alterações.
• Para continuar executando sem pensamento antecipado, envie a configuração de pensamento mais baixa com esforço high ou inferior.
• Substitua o uso forçado de ferramentas por auto e ferramentas estritas, ou apenas por auto no Amazon Bedrock.
• Mantenha as conversas somente com acréscimos.
• Na Claude API e no Google Cloud, migre o uso do computador para o toolset, sem o cabeçalho beta fine-grained-tool-streaming-2025-05-14.
• Combine a ferramenta advisor com um advisor compatível e espere conselhos criptografados.
• Leia o texto entre chamadas de ferramentas a partir dos blocos thinking.
• Lide com recusas e configure o fallback.
• Execute novamente sua varredura de esforço e restabeleça a linha de base de custo.

Claude Sonnet 4.6 ou anterior

• Espere pensamento em solicitações sem o campo thinking e revise max_tokens.
• Substitua os orçamentos de pensamento por um nível de esforço.
• Remova valores não padrão de temperature, top_p e top_k.
• Se você exibe o texto do pensamento, defina display: "summarized".
• Reconte os tokens e refaça o orçamento de tokens de imagem.

Claude Sonnet 4.5 ou anterior

• Substitua os preenchimentos prévios do assistente.
• Analise a entrada das chamadas de ferramentas com um parser JSON padrão.
• No Amazon Bedrock, migre o uso do computador de computer_20250124 para computer_20251124.
• Defina output_config.effort explicitamente.
• Remova qualquer cabeçalho beta de janela de contexto.
• Remova interleaved-thinking-2025-05-14 e substitua fine-grained-tool-streaming-2025-05-14 por eager_input_streaming.
• Mova output_format para output_config.format.

Claude Sonnet 4 ou anterior

• Atualize as versões das ferramentas para text_editor_20250728 e code_execution_20260521.
• Trate os motivos de parada refusal e model_context_window_exceeded.
• Verifique se há quebras de linha finais nos parâmetros de string das ferramentas.
• Remova token-efficient-tools-2025-02-19 e output-128k-2025-02-19.
• Revise seus prompts.

Somente Claude Haiku 4.5

• Substitua claude-haiku-4-5-20251001 ou seu alias.
• Restabeleça a linha de base de custos com o preço por token mais alto.
• Revise os prompts que eram curtos demais para cache no Claude Haiku 4.5.

Migrando para o Claude Sonnet 5.5 a partir do Claude Sonnet 5

Todos os modelos de origem precisam das alterações desta seção. Substitua o ID do seu modelo por claude-sonnet-5-5, que não tem sufixo de data. Em outras plataformas, use o ID listado em Disponibilidade.

O uso forçado de ferramentas não é suportado

Todos os modelos anteriores desta página aceitam um tool_choice do tipo any ou tool. O Claude Sonnet 5.5 rejeita ambos com um erro 400, inclusive no endpoint de contagem de tokens:

tool_choice: type "tool" and "any" are not supported for this model.

Envie tool_choice: {"type": "auto"} e marque a ferramenta com strict: true para que sua entrada corresponda ao schema. O modelo pode então responder sem chamar a ferramenta, então diga no prompt quando usá-la. O uso estrito de ferramentas suporta um subconjunto do JSON Schema e exige additionalProperties: false em todos os objetos. Consulte Limitações do JSON Schema. No Amazon Bedrock, as saídas estruturadas, que incluem o uso estrito de ferramentas, não estão disponíveis para o Claude Sonnet 5.5. Lá, envie auto sem strict, diga no prompt quando chamar a ferramenta e valide a entrada da ferramenta no seu código.

Antes (Claude Sonnet 5):

client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

Depois (Claude Sonnet 5.5):

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    # uso de ferramentas estrito: toda chamada corresponde ao input_schema da ferramenta
    tools=[{**tool, "strict": True} for tool in tools],
    tool_choice={"type": "auto"},
    messages=[
        {
            "role": "user",
            "content": "What's the weather in Paris? Use the get_weather tool.",
        }
    ],
)

O exemplo marca todas as ferramentas da lista como estritas. Uma solicitação pode ter no máximo 20 ferramentas estritas, e as entradas de toolset de MCP, uso do computador e uso do navegador não aceitam strict. Em uma lista de ferramentas mais longa, marque apenas as ferramentas que precisam disso.

Os blocos de pensamento estão vinculados ao modelo e à conversa

O Claude Sonnet 5.5 lê blocos de pensamento do Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 e modelos anteriores. Ele não lê blocos do Claude Opus 5, Claude Opus 5.5 ou de qualquer modelo Claude Fable ou Claude Mythos. A API descarta os blocos que o modelo não consegue ler. A solicitação ainda retorna 200, e os blocos descartados não são cobrados. Consulte Trocando de modelo no meio da conversa.

Cada bloco de pensamento do Claude Sonnet 5.5 também é assinado sobre a conversa que o precede. Para contas criadas a partir de 31 de agosto de 2026, 00:00 UTC, a API aplica isso por padrão, na API do Claude, no Amazon Bedrock e no Google Cloud. Nessas contas, uma solicitação que reenvia um bloco após uma edição no histórico anterior retorna um erro 400. Mantenha as conversas somente com acréscimos e altere instruções ou ferramentas com mensagens do sistema no meio da conversa. Os blocos de pensamento produzidos pelo Claude Sonnet 5.5 funcionam apenas na conta que os produziu ou em uma conta vinculada a ela. Consulte Pensamento preservado.

O uso do computador exige o toolset na API do Claude e no Google Cloud

Na API do Claude e no Google Cloud, o Claude Sonnet 5.5 suporta o uso do computador apenas por meio do toolset computer_toolset_20260801. Nessas plataformas, computer_20251124 retorna um erro 400. O Claude Sonnet 5.5 não aceita computer_20250124 em nenhuma plataforma. Encontre a versão que você envia hoje:

Se você envia o cabeçalho beta fine-grained-tool-streaming-2025-05-14, remova-o ao migrar para o toolset. Junto com uma entrada de toolset, ele retorna um erro 400. Em vez disso, defina eager_input_streaming: true em cada ferramenta que precisar.

Código que já envia o toolset não precisa de alterações. Migrar de computer_20251124 lista as alterações na solicitação e no loop do agente. Para outras plataformas, consulte Compatibilidade.

A ferramenta advisor aceita menos advisors

Com a ferramenta advisor, um executor Claude Sonnet 5.5 precisa de um destes advisors: Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5, Claude Fable 5.1, Claude Mythos 5 ou Claude Mythos 5.1. Advisors Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 e Claude Sonnet 4.6 retornam um erro 400. O conselho retorna criptografado como um bloco advisor_redacted_result, portanto seu texto não é legível na resposta. Consulte Compatibilidade de modelos.

O texto entre chamadas de ferramentas é retornado em blocos de pensamento

No Claude Sonnet 5.5, as notas com mais de uma ou duas frases que o modelo escreve entre chamadas de ferramentas retornam como blocos thinking de atualização de progresso, vazios com o display padrão. Comentários mais curtos continuam como text. No Claude Sonnet 5 e modelos anteriores, todo o texto entre chamadas de ferramentas retorna como blocos text. Nenhuma solicitação falha, mas uma interface que exibe essas notas fica em silêncio.

Com o pensamento adaptativo, defina display como "updates" (beta, cabeçalho thinking-display-updates-2026-08-18) para obter apenas as atualizações, ou como "summarized" para obtê-las misturadas com o raciocínio. Renderize cada bloco thinking não vazio antes do bloco tool_use que o segue. Com between_tools, o texto retorna sem display. Consulte Atualizações de progresso voltadas ao usuário.

Classificadores de segurança e fallback

O Claude Sonnet 5.5 recusa em mais categorias do que o Claude Sonnet 5. Uma recusa retorna stop_reason: "refusal", e seu stop_details pode indicar uma destas categorias:

• "cyber": A solicitação poderia possibilitar danos cibernéticos, como o desenvolvimento de malware ou exploits.
• "bio": A solicitação poderia possibilitar danos biológicos, como métodos laboratoriais perigosos.
• "frontier_llm": A solicitação poderia auxiliar o desenvolvimento de modelos de IA concorrentes.
• "reasoning_extraction": A solicitação pede ao modelo que reproduza seu raciocínio interno no texto da resposta.
• "general_harms": A solicitação se enquadra em outra área da política de uso. Trabalhos benignos também podem acionar essa categoria.

O fallback no lado do servidor (fallbacks: "default", beta, somente na API do Claude) tenta novamente as recusas "cyber" e "frontier_llm" no Claude Sonnet 5. Ele não tenta novamente as recusas "bio", "reasoning_extraction" ou "general_harms". Consulte Recusas e fallback e Como as recusas são cobradas.

As salvaguardas cibernéticas em tempo real são novidade para código vindo do Claude Sonnet 4.6, Claude Sonnet 4.5 e Claude Haiku 4.5. Para trabalhos legítimos de segurança, inscreva-se no Cyber Verification Program.

Outras alterações

• "Prompt caching" (cache de prompt): O prompt mínimo armazenável em cache é de 512 tokens, abaixo dos 1.024 no Claude Sonnet 5, Claude Sonnet 4.6 e Claude Sonnet 4.5. Consulte Cache de prompt.
• Novos recursos: Para mensagens do sistema no meio da conversa, alterações de ferramentas no meio da conversa e esforço por mensagem, consulte Novidades do Claude Sonnet 5.5. Com between_tools, o esforço não pode mudar no meio da conversa.

Alterações recomendadas

Execute novamente sua varredura de esforço. O Claude Sonnet 5.5 tem cinco níveis de esforço: low, medium, high, xhigh e max. O padrão na API do Claude é high. Os níveis foram recalibrados, portanto um nível não produz a mesma quantidade de pensamento que no Claude Sonnet 5. Comece em high, a menos que sua carga de trabalho seja agêntica ou sensível à "latency" (latência). Para programação agêntica e uso de ferramentas em várias etapas, comece em medium para tarefas bem especificadas e passe para high para tarefas mais difíceis ou mais longas. Para chat e outros trabalhos sensíveis à latência, comece em medium ou low. Defina o nível em output_config.effort. Consulte Níveis de esforço recomendados para o Claude Sonnet 5.5. Em seguida, reavalie as instruções de prompt específicas do modelo com base em Criando prompts para o Claude Sonnet 5.5.

Migrando para o Claude Sonnet 5.5 a partir do Claude Sonnet 4.6 e modelos Sonnet anteriores

Primeiro, aplique todas as seções anteriores, substituindo claude-sonnet-4-6. Depois, faça estas alterações. No Claude Sonnet 4.5 ou anterior, continue com as subseções a seguir.

Alterações incompatíveis

O pensamento é executado em solicitações que o omitiam. Consulte O pensamento é executado por padrão e Desative o pensamento antecipado.

Orçamentos de pensamento retornam um erro. O Claude Sonnet 4.6 aceita thinking: {"type": "enabled", "budget_tokens": N} como uma configuração descontinuada. O Claude Sonnet 4.5 e o Claude Haiku 4.5 a usam para todo o pensamento. O Claude Sonnet 5.5 retorna um erro 400:

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Remova o orçamento e defina um nível de esforço. Não há um mapeamento fixo de um orçamento para um nível de esforço, então execute suas avaliações em dois ou três níveis.

Antes (Claude Sonnet 4.6):

client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "..."}],
)

Depois (Claude Sonnet 5.5):

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

Parâmetros de amostragem retornam um erro. O Claude Sonnet 4.6 e modelos anteriores, e o Claude Haiku 4.5, aceitam temperature, top_p e top_k. No Claude Sonnet 5.5, um valor não padrão retorna um erro 400. Remova-os.

O texto do pensamento é omitido por padrão. Consulte Trate o pensamento nas respostas.

Outras alterações

• Cerca de 30% mais tokens: O Claude Sonnet 5.5 usa o tokenizador do Claude Sonnet 5. Em comparação com o Claude Sonnet 4.6, Claude Sonnet 4.5 e Claude Haiku 4.5, o mesmo texto produz cerca de 30% mais tokens, dependendo do conteúdo. Reconte com a contagem de tokens e revise max_tokens e os custos.
• Esforço: xhigh é novo, e os níveis foram recalibrados. Consulte Alterações recomendadas.
• Imagens: O Claude Sonnet 5.5 usa o nível de imagem de alta resolução, com até 2576 pixels no lado maior e 4.784 tokens visuais por imagem. O Claude Sonnet 4.6, Claude Sonnet 4.5 e Claude Haiku 4.5 param em 1568 pixels e 1.568 tokens. Uma imagem de 2000×1500 custa cerca de 2,5 vezes mais tokens no Claude Sonnet 5.5. Consulte Resolução e custo em tokens.

Migrando a partir do Claude Sonnet 4.5 ou anterior

No Claude Sonnet 4.5, Claude Sonnet 4 ou Claude 3.7 Sonnet, primeiro aplique todas as seções anteriores e depois estas alterações.

O preenchimento prévio retorna um erro. O Claude Sonnet 5.5 rejeita um último turno do assistente preenchido previamente com um erro 400, assim como o Claude Sonnet 4.6 e o Claude Sonnet 5. O Claude Sonnet 4.5, o Claude Haiku 4.5 e modelos mais antigos o aceitam. O erro diz:

This model does not support assistant message prefill. The conversation must end with a user message.

Substitua cada preenchimento prévio de acordo com sua finalidade:

• Formato de saída: use saídas estruturadas ou ferramentas com campos enum para classificação.
• Preâmbulos: peça no prompt do sistema uma resposta direta.
• Recusas indesejadas: instruções claras na mensagem do usuário geralmente são suficientes.
• Continuações: mova-as para a mensagem do usuário, por exemplo "Your previous response was interrupted and ended with [previous_response]. Continue from where you left off."
• Lembretes de contexto: coloque-os no turno do usuário.

Escape na entrada das ferramentas. O escape nos argumentos das chamadas de ferramentas pode ser diferente. Analise input com um parser JSON padrão.

Uso do computador. O Claude Sonnet 5.5 não aceita computer_20250124. Consulte a tabela de uso do computador.

Esforço. O Claude Sonnet 4.5 não tem parâmetro de esforço. Defina um nível de esforço explicitamente, conforme descrito em Alterações recomendadas.

Contexto e saída. O Claude Sonnet 5.5 tem uma janela de contexto maior, sem cabeçalho beta, e um limite de saída mais alto. Consulte a página do modelo. Remova qualquer cabeçalho beta de janela de contexto.

Cabeçalhos beta. Remova interleaved-thinking-2025-05-14, já que o pensamento adaptativo se intercala automaticamente. Substitua fine-grained-tool-streaming-2025-05-14 por eager_input_streaming: true em cada ferramenta que precisar. Esse cabeçalho retorna um erro 400 junto com uma entrada de toolset de uso do computador ou de uso do navegador. Consulte Streaming de ferramentas refinado.

Saídas estruturadas. O parâmetro output_format está descontinuado e será removido no futuro. Para usá-lo mesmo assim, adicione o cabeçalho beta structured-outputs-2025-11-13. Sem ele, a API retorna um erro 400. Use output_config.format em vez disso.

Migrando a partir do Claude Sonnet 4 ou anterior

O Claude Sonnet 4 está desativado na API do Claude e ainda disponível no Amazon Bedrock e no Google Cloud. O Claude 3.7 Sonnet está desativado. A partir de qualquer um desses modelos, primeiro aplique todas as seções anteriores e depois estas alterações:

• Versões das ferramentas: Use text_editor_20250728, com o nome de ferramenta str_replace_based_edit_tool e sem o comando undo_edit. Use code_execution_20260521. Consulte a ferramenta de editor de texto e a ferramenta de execução de código.
• Motivos de parada: Trate refusal. O Claude 4.5 e modelos posteriores também param com model_context_window_exceeded no limite da janela de contexto. Consulte Tratando motivos de parada.
• Quebras de linha finais: O Claude 4.5 e modelos posteriores as mantêm nos parâmetros de string das chamadas de ferramentas.
• Cabeçalhos beta legados: Remova token-efficient-tools-2025-02-19 e output-128k-2025-02-19.
• Prompts: Revise-os com base nas melhores práticas de prompts.

Migrando para o Claude Sonnet 5.5 a partir do Claude Haiku 4.5

Primeiro, aplique todas as seções até Migrando a partir do Claude Sonnet 4.5 ou anterior, inclusive, pulando a subseção do Claude Sonnet 4. Depois, faça estas alterações:

• ID do modelo: Substitua claude-haiku-4-5-20251001, ou o alias claude-haiku-4-5, por claude-sonnet-5-5.
• Custo: O preço por token é mais alto, e o mesmo texto produz mais tokens. Reconte os tokens e restabeleça a linha de base de custos. Consulte Preços do Claude.
• Cache de prompt: O prompt mínimo armazenável em cache cai de 4.096 tokens para o mínimo do Claude Sonnet 5.5.
• Pensamento intercalado: O pensamento adaptativo é executado entre chamadas de ferramentas automaticamente, sem cabeçalho beta.
• Roteamento: O Claude Sonnet 5.5 lê blocos de pensamento do Claude Haiku 4.5. Uma conversa que sobe de modelo mantém seu raciocínio. Uma que volta para o Claude Haiku 4.5 descarta os blocos do Claude Sonnet 5.5.