Guia de migração para o Claude Opus 5.5

Esta página lista as alterações de código para migrar para o Claude Opus 5.5 a partir do Claude Opus 5, do Claude Opus 4.8, do Claude Opus 4.7, do Claude Opus 4.6 e modelos Opus anteriores ou do Claude Sonnet 5. Todo leitor precisa de O que toda requisição ao Claude Opus 5.5 deve atender e de Lidar com o pensamento em todas as respostas. Em seguida, vá para a seção do seu modelo atual: a primeira frase dela indica as outras seções que se aplicam a você. O checklist de migração lista todas as alterações por modelo de origem.

O Claude Opus 5.5 custa menos que o Claude Opus 5 ($4 / $20 USD por milhão de tokens de entrada / saída, em comparação com $5 / $25; consulte preços do Claude). Para o suporte a recursos, consulte O que há de novo no Claude Opus 5.5. Para diferenças de comportamento e padrões de prompting específicos do modelo, consulte Prompting do Claude Opus 5.5.

O que toda requisição ao Claude Opus 5.5 deve atender

Seja qual for o modelo de origem, uma requisição para claude-opus-5-5 deve atender aos itens a seguir. Quando um item diz que uma configuração é rejeitada, a API retorna um erro 400.

• ID do modelo: Use claude-opus-5-5, um ID de modelo fixo sem sufixo de data. No Amazon Bedrock, na Claude Platform on AWS, no Google Cloud e no Microsoft Foundry, use o ID de modelo dessa plataforma; consulte Disponibilidade.
• Pensamento: Não envie nenhum campo thinking, ou envie thinking: {"type": "adaptive"}, que é equivalente: o adaptive thinking (pensamento adaptativo) está sempre ativado. thinking: {"type": "disabled"} e orçamentos manuais de pensamento (thinking: {"type": "enabled", "budget_tokens": N}) são rejeitados. Consulte o antes e depois para o pensamento.
• Esforço: Controle a profundidade do pensamento com o parâmetro "effort" (esforço), o único parâmetro de requisição que a controla. Todos os cinco níveis (low, medium, high, xhigh, max) são suportados, e o padrão é medium. Consulte Níveis de esforço recomendados para o Claude Opus 5.5.
• Escolha de ferramenta: Use tool_choice {"type": "auto"} (o padrão) ou {"type": "none"}. Forçar uma chamada de ferramenta com {"type": "any"} ou {"type": "tool", "name": "..."} é rejeitado. Consulte o antes e depois para a escolha de ferramenta.
• Parâmetros de amostragem: Omita temperature, top_p e top_k, ou deixe-os em seus valores padrão: qualquer outro valor é rejeitado. Use prompts para orientar o comportamento do modelo.
• Prefill: Não termine messages com um turno do assistente pré-preenchido ("prefill"): isso é rejeitado. Use saídas estruturadas ou instruções no prompt do sistema. No Amazon Bedrock, as saídas estruturadas não estão disponíveis para o Claude Opus 5.5, então use instruções no prompt do sistema nessa plataforma.
• Uso de computador: Na Claude API e no Google Cloud, declare o "computer use" (uso de computador) como o toolset computer_toolset_20260801; a ferramenta anterior computer_20251124 é rejeitada nessas plataformas. Consulte a mudança incompatível do uso de computador.
• Janela de contexto: Nenhum cabeçalho beta de "context window" (janela de contexto) é necessário. A janela de contexto de 1M tokens é o padrão, e um cabeçalho enviado para modelos mais antigos não tem efeito.

A requisição a seguir atende a todos os itens da lista: o esforço está definido e não há campo thinking. As abas de SDK que imprimem texto o selecionam pelo tipo de bloco, porque os blocos thinking vêm primeiro.

client = anthropic.Anthropic()

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

for block in response.content:
    if block.type == "text":
        print(block.text)

Lidar com o pensamento em todas as respostas

O pensamento é executado em toda requisição ao Claude Opus 5.5, então toda resposta pode começar com blocos thinking, e max_tokens abrange o pensamento mais o texto. Se o seu código já é executado com o pensamento ativado, os itens 1 a 3 provavelmente já estão implementados: verifique os itens 4 e 5. Se ele era executado sem pensamento, em qualquer modelo anterior, cada item é uma alteração.

1. max_tokens abrange o pensamento mais o texto: No Claude Opus 4.8 e em modelos Opus anteriores, requisições sem um campo thinking são executadas sem pensamento. O Claude Opus 5 e o Claude Sonnet 5 aceitam thinking: {"type": "disabled"}. No Claude Opus 5.5, toda requisição é executada com pensamento adaptativo. max_tokens continua sendo um limite rígido para a saída total, pensamento mais texto da resposta, então revise-o para cargas de trabalho que eram executadas sem pensamento. Tokens de pensamento são cobrados como tokens de saída mesmo quando o texto do pensamento não é retornado a você, então essa carga de trabalho pode produzir mais tokens de saída por requisição. Consulte Controle de custo. Para gastar menos tokens com pensamento, reduza o nível de esforço. Se você executa com esforço xhigh ou max, defina um max_tokens grande para que o modelo tenha espaço para pensar e agir; comece com 64k tokens e ajuste a partir daí. Se seus prompts foram ajustados para execução sem pensamento, consulte Prompts escritos para pensamento desativado.

2. As respostas começam com blocos de pensamento: Uma resposta pode começar com um ou mais blocos thinking antes do primeiro bloco text. Código que lê a resposta por posição, como content[0].text ou um manipulador de stream que trata o primeiro evento content_block_start como texto, falha nessas respostas. Em vez disso, selecione os blocos de conteúdo pelo campo type: leia text dos blocos cujo type é "text" e ramifique com base no tipo de bloco ao lidar com eventos de stream.

3. Retorne os blocos de pensamento sem modificações em loops de uso de ferramentas: Se você executa um loop de "tool use" (uso de ferramentas), passe os blocos thinking de cada resposta do assistente de volta para a API completos e sem modificações ao retornar resultados de ferramentas, incluindo blocos cujo campo thinking está vazio. Reenvie a mensagem do assistente como foi recebida, em vez de filtrar seus blocos de conteúdo por tipo ou reconstruí-la: a API rejeita blocos de pensamento editados, reordenados ou parcialmente descartados com um erro 400. Consulte Preservando blocos de pensamento.

4. O texto do pensamento é omitido por padrão: thinking.display tem como padrão "omitted", então os blocos thinking chegam com um campo thinking vazio junto com sua signature. Trate o campo thinking apenas como texto de exibição. Para receber resumos legíveis, defina thinking.display como "summarized":

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   thinking = {
       "type": "adaptive",
       "display": "summarized",
   }

   Se o seu produto transmite o raciocínio aos usuários via streaming, o padrão aparece como uma longa pausa antes do início da saída; defina display: "summarized" para restaurar o progresso visível durante o pensamento. Consulte Controlando a exibição do pensamento.

5. O texto entre chamadas de ferramentas chega em blocos de pensamento: As notas curtas que o modelo escreve entre chamadas de ferramentas retornam como blocos thinking, que ficam vazios na exibição padrão. Consulte O texto entre chamadas de ferramentas é retornado em blocos de pensamento.

Checklist de migração por modelo de origem

Percorra os grupos de cima para baixo e pare após aquele que nomeia seu modelo atual: todos os itens até esse ponto se aplicam a você. Se você está no Claude Opus 5, o primeiro grupo é a lista completa. Se você está no Claude Sonnet 5, aplique o primeiro grupo e o último.

Todos os modelos de origem

• Atualize o ID do modelo para claude-opus-5-5.
• Remova thinking: {"type": "disabled"} e thinking: {"type": "enabled", ...}; em vez disso, escolha um nível de esforço.
• Defina effort explicitamente: o padrão é medium, enquanto o do Claude Opus 5 é high.
• Substitua os tipos de tool_choice any e tool por auto mais uso estrito de ferramentas ou saídas estruturadas, ou apenas por auto no Amazon Bedrock.
• Se você usa a ferramenta de uso de computador na Claude API ou no Google Cloud, declare computer_toolset_20260801 (sem cabeçalho beta) em vez de computer_20251124 e atualize seu loop de agente para o toolset. No Amazon Bedrock, mantenha computer_20251124; verifique a seção Compatibilidade da ferramenta de uso de computador para outras plataformas.
• Se um roteador ou fallback puder mover uma conversa do Claude Opus 5.5 para outro modelo, espere que esse modelo seja executado sem os blocos de pensamento do Claude Opus 5.5 (o Claude Fable 5.1 e o Claude Mythos 5.1 na Claude API são a exceção e os mantêm). O próprio Claude Opus 5.5 lê o pensamento do Claude Opus 5, de modelos Opus, Sonnet e Haiku anteriores e, na Claude API e no Google Cloud, do Claude Sonnet 5.5 e do Claude Haiku 5.5, mas não de modelos Claude Fable ou Claude Mythos.
• Leia os blocos de conteúdo por type e passe os blocos thinking de volta sem modificações em loops de uso de ferramentas.
• Se sua interface renderiza texto entre chamadas de ferramentas, defina display: "updates" (beta) ou "summarized" e renderize os blocos thinking não vazios.
• Se seu código edita turnos anteriores, o prompt system ou tools no meio da conversa, siga Pensamento preservado.
• Trate stop_reason: "refusal" e configure o fallback.
• Restabeleça a linha de base de custo e latência no nível de esforço escolhido.
• Se seu código desativava o pensamento, revise max_tokens, que abrange o pensamento mais o texto da resposta; com esforço xhigh ou max, comece com 64k. Consulte Lidar com o pensamento em todas as respostas.

Claude Opus 4.8 ou anterior

• Revise as cargas de trabalho que eram executadas sem um campo thinking: no Claude Opus 5.5 elas são executadas com pensamento, e o pensamento não pode ser desativado. Revise max_tokens, que continua sendo um limite rígido para a saída total (pensamento mais texto da resposta), e reduza effort onde você quiser menos pensamento. Tokens de pensamento são cobrados como tokens de saída, então essas cargas de trabalho podem produzir mais tokens de saída por requisição.
• Verifique se qualquer código que analisa o campo thinking o trata apenas como texto de exibição. Defina display: "summarized" para receber resumos legíveis.
• Revise os prompts próximos ao mínimo de cache: prompts de 512 tokens ou mais podem criar entradas de cache.
• Se sua organização tem um compromisso de Priority Tier, planeje a capacidade separadamente: o Priority Tier não é suportado no Claude Opus 5.5.
• Se você executa com esforço xhigh ou max, aumente max_tokens para pelo menos 64k como ponto de partida.
• Para cargas de trabalho agênticas, considere orçamentos de tarefa (beta) e alterações de ferramentas no meio da conversa (beta).

Claude Opus 4.7 ou anterior

• Execute uma nova varredura de esforço em suas próprias avaliações em vez de manter uma configuração ajustada para um modelo anterior.
• Remova qualquer cabeçalho beta de janela de contexto.
• Se você reconstrói o histórico da conversa para atualizar instruções, considere mudar para uma mensagem de sistema no meio da conversa para preservar os acertos de cache de prompt.
• Verifique se o seu tratamento de motivos de parada lê stop_details em recusas.
• Se você quiser o modo rápido, que o Claude Opus 4.7 rejeita, defina speed: "fast" com o cabeçalho beta fast-mode-2026-02-01 na Claude API.

Claude Opus 4.6 ou anterior

• Remova temperature, top_p e top_k dos payloads de requisição.
• Substitua thinking: {"type": "enabled", "budget_tokens": N} por thinking: {"type": "adaptive"} mais o parâmetro effort, ou remova o campo thinking inteiramente; o pensamento adaptativo está sempre ativado.
• Se sua UI exibe conteúdo de pensamento, opte explicitamente pela sumarização do pensamento.
• Refaça o benchmark de custo e latência de ponta a ponta com a tokenização atualizada.
• Reajuste max_tokens para levar em conta a tokenização atualizada, incluindo os gatilhos de compactação.
• Teste novamente quaisquer estimativas de contagem de tokens do lado do cliente.
• Se sua aplicação envia imagens, refaça o orçamento para o suporte a imagens de alta resolução (até aproximadamente 3x mais tokens de imagem por imagem em resolução total). Reduza a resolução antes de enviar se você não precisar da fidelidade adicional.
• Se você consome coordenadas de apontamento ou de caixas delimitadoras do modelo, remova qualquer conversão de fator de escala; as coordenadas são 1:1 com os pixels reais da imagem no Claude Opus 4.7 e em modelos posteriores.
• Revise as mudanças de comportamento que começaram no Claude Opus 4.7.
• Se seu produto realiza trabalho legítimo de segurança, inscreva-se no Cyber Verification Program para ter acesso a restrições menores sobre conteúdo cibernético.

Claude Opus 4.5 ou anterior

• Remova quaisquer prefills de mensagem do assistente; o Claude Opus 4.6 já os rejeita.
• Verifique se a análise do JSON de chamadas de ferramentas usa um parser JSON padrão.
• Migre de client.beta.messages.create() para client.messages.create(): o pensamento adaptativo e o esforço não precisam de namespace beta.
• Remova o cabeçalho beta effort-2025-11-24 (o parâmetro effort não o exige).
• Remova o cabeçalho beta fine-grained-tool-streaming-2025-05-14.
• Remova o cabeçalho beta interleaved-thinking-2025-05-14 (o pensamento adaptativo ativa o pensamento intercalado automaticamente).
• Migre output_format para output_config.format (se aplicável).

Claude 4.1 ou anterior

• Atualize as versões das ferramentas (text_editor_20250728, code_execution_20260521).
• Trate o motivo de parada refusal.
• Trate o motivo de parada model_context_window_exceeded.
• Verifique o tratamento de parâmetros de string de ferramentas quanto a quebras de linha finais.
• Remova cabeçalhos beta legados (token-efficient-tools-2025-02-19, output-128k-2025-02-19).
• Revise e atualize os prompts seguindo as melhores práticas de prompting.

Somente Claude Sonnet 5

• Se você reconstrói o histórico da conversa para atualizar instruções, considere mudar para uma mensagem de sistema no meio da conversa para preservar os acertos de cache de prompt.
• Revise os prompts próximos ao mínimo de cache: prompts de 512 tokens ou mais podem criar entradas de cache.

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

Primeiro, percorra O que toda requisição ao Claude Opus 5.5 deve atender e Lidar com o pensamento em todas as respostas. Todo modelo de origem precisa das alterações desta seção. Elas são as configurações de requisição que o Claude Opus 5.5 rejeita e as mudanças de resposta que vêm com ele. O checklist desta seção é o primeiro grupo do checklist de migração.

Atualize o nome do seu modelo

model = "claude-opus-5"  # Before
model = "claude-opus-5-5"  # After

claude-opus-5-5 é um ID de modelo fixo sem sufixo de data, o mesmo esquema de claude-opus-5. No Amazon Bedrock, Claude Platform on AWS, Google Cloud e Microsoft Foundry, use o ID de modelo dessa plataforma; consulte Disponibilidade.

Mudanças incompatíveis

Cada mudança é explicada em O que há de novo no Claude Opus 5.5; esta seção apresenta a alteração de código para cada uma.

O pensamento não pode ser desativado

thinking: {"type": "disabled"} e thinking: {"type": "enabled", "budget_tokens": N} retornam um erro 400 ("thinking.type.disabled" is not supported for this model. ou "thinking.type.enabled" is not supported for this model.). Remova o campo thinking e escolha um nível de "effort" (esforço); onde você desativava o "thinking" (pensamento) para economizar tokens, use um nível mais baixo. As respostas então começam com blocos thinking, portanto selecione os blocos de conteúdo por type e devolva os blocos thinking sem modificações junto com os resultados de ferramentas. Consulte O pensamento não pode ser desativado.

Antes. O Claude Opus 5 aceita esta requisição, e o Claude Opus 5.5 a rejeita com um erro 400:

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

Depois:

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    output_config={"effort": "low"},  # thinking is always on; effort is the control
    messages=[{"role": "user", "content": "..."}],
)

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

Os tipos de tool_choice any e tool retornam um erro 400 (tool_choice: type "tool" and "any" are not supported for this model.), inclusive no endpoint de contagem de tokens. Use auto com uso estrito de ferramentas ou saídas estruturadas e diga no prompt quando a ferramenta se aplica. O uso estrito de ferramentas aceita um subconjunto do JSON Schema, então verifique o input_schema de cada ferramenta antes de adicionar strict: true. Todo objeto no schema deve definir additionalProperties: false; 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 Opus 5.5. Nessa plataforma, envie auto sem strict, diga no prompt quando a ferramenta se aplica e valide a entrada da ferramenta no seu código. Consulte O uso forçado de ferramentas não é suportado.

Antes. O Claude Opus 5 aceita esta requisição, e o Claude Opus 5.5 a rejeita com um erro 400:

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

Depois:

client.messages.create(
    model="claude-opus-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.",
        }
    ],
)

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

Na Claude API, o Claude Fable 5.1 e o Claude Mythos 5.1 leem os blocos de pensamento do Claude Opus 5.5; nenhum outro modelo os lê. Um roteador ou fallback que move uma conversa do Claude Opus 5.5 para qualquer outro modelo executa esses turnos sem eles. Na outra direção, o Claude Opus 5.5 lê blocos de pensamento do Claude Opus 5, de modelos Opus, Sonnet e Haiku anteriores e, na Claude API e no Google Cloud, do Claude Sonnet 5.5 e do Claude Haiku 5.5, mas não de modelos Claude Fable ou Claude Mythos. Mantenha a conversa somente com acréscimos (sem edições no prompt system, em tools ou em mensagens anteriores no meio da conversa) para que os blocos continuem válidos; o Claude Code, o claude.ai, o Claude Managed Agents e o Claude Agent SDK já fazem isso. A aplicação dessa regra é igual à do Claude Fable 5.1 em todas as plataformas: para contas criadas a partir de 31 de agosto de 2026, 00:00 UTC, reenviar um bloco de pensamento após tal edição retorna um erro 400 por padrão. Não há alteração de código para integrações somente com acréscimos. Consulte Os blocos de pensamento estão vinculados ao modelo e à conversa e Pensamento preservado.

A ferramenta de uso de computador computer_20251124 não é suportada na Claude API e no Google Cloud

Na Claude API e no Google Cloud, uma entrada em tools do tipo computer_20251124 retorna um erro 400 ('claude-opus-5-5' does not support tool types: computer_20251124., seguido dos tipos de ferramenta que o modelo aceita). Em vez disso, declare o "toolset" (conjunto de ferramentas) computer_toolset_20260801: remova o cabeçalho beta e envie a entrada sem name nem dimensões de exibição. No seu loop de agente, trate os blocos tool_use dos membros (a ação é o name do bloco, não input.action), vários deles por turno, e repita toolset_name em cada resultado. A alteração na requisição é mostrada abaixo; as alterações no loop de agente estão listadas em Migrar de computer_20251124. No Amazon Bedrock, a ferramenta anterior computer_20251124 continua funcionando no Claude Opus 5.5 como funciona no Claude Opus 5, portanto nenhuma alteração é necessária lá; para outras plataformas, consulte a seção Compatibilidade da ferramenta de "computer use" (uso de computador). Consulte A ferramenta de uso de computador computer_20251124 não é suportada na Claude API e no Google Cloud.

Antes. O Claude Opus 5 aceita esta requisição e, na Claude API e no Google Cloud, o Claude Opus 5.5 a rejeita com um erro 400:

client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["computer-use-2025-11-24"],
    tools=[
        {
            "type": "computer_20251124",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
        }
    ],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

Depois:

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    # sem header beta; a entrada do toolset não recebe nome nem tamanho de exibição
    tools=[{"type": "computer_toolset_20260801"}],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

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

No Claude Opus 5, o texto que o modelo escreve entre chamadas de ferramentas volta como blocos text. No Claude Opus 5.5, assim como no Claude Fable 5.1, essa narração volta como blocos thinking de atualização de progresso, no máximo um antes de cada chamada de ferramenta. Com o valor padrão "omitted" de thinking.display, o campo thinking desses blocos fica vazio. Nenhuma requisição falha, mas uma aplicação que faz streaming desse texto para seus usuários como atualizações de progresso fica em silêncio entre as chamadas de ferramentas. Para restaurar as atualizações, leia-as dos blocos thinking e defina um valor de display que retorne o texto delas: "updates" (beta, cabeçalho thinking-display-updates-2026-08-18) retorna as atualizações de progresso enquanto o raciocínio permanece oculto, e "summarized" retorna ambos, misturados. Em seguida, renderize cada bloco thinking não vazio antes do bloco tool_use que ele precede e devolva os blocos inalterados com o restante do turno do assistente. Consulte Atualizações de progresso voltadas ao usuário.

Classificadores de segurança e fallback

O Claude Opus 5.5 pode retornar stop_reason: "refusal" com uma categoria em stop_details. Seus classificadores cobrem um conjunto mais amplo de categorias do que os do Claude Opus 5, então espere valores de stop_details.category como "bio" além de "cyber" e "reasoning_extraction"; consulte a tabela de categorias de recusa. Lide com as recusas e configure o fallback no lado do servidor ou sua própria nova tentativa (o fallback no lado do servidor não tenta novamente requisições recusadas com "reasoning_extraction"; essa recusa é retornada a você); consulte Recusas e fallback e Recusas de salvaguardas.

Mudanças recomendadas

1. Execute novamente sua varredura de esforço. O esforço é o único controle de pensamento no Claude Opus 5.5, e seu padrão é medium, enquanto o do Claude Opus 5 é high; portanto, uma requisição que omite effort agora é executada em medium. Reduza o nível onde a qualidade se mantiver e aumente-o para o trabalho mais exigente. Consulte Esforço.
2. Reavalie as instruções de prompt específicas do modelo. Instruções ajustadas para o comportamento do Claude Opus 5 podem não ser mais necessárias; consulte Prompting do Claude Opus 5.5. Se você executava com o pensamento desativado, consulte também Prompts escritos para pensamento desativado.
3. Teste em um ambiente de desenvolvimento antes de migrar o tráfego de produção.

Migrando para o Claude Opus 5.5 a partir do Claude Opus 4.8

Primeiro, percorra O que toda requisição ao Claude Opus 5.5 deve atender, Lidar com o pensamento em todas as respostas e Migrando para o Claude Opus 5.5 a partir do Claude Opus 5. Use claude-opus-4-8 como o ID de modelo que você substitui. Essa última seção se aplica ao código no Claude Opus 4.8 tal como está escrita, porque o Claude Opus 4.8, assim como o Claude Opus 5:

• Aceita thinking: {"type": "disabled"}, escolha forçada de ferramenta e a ferramenta computer_20251124.
• Retorna o texto entre chamadas de ferramentas como blocos text.
• Tem esforço high como padrão.

Esta seção acrescenta o que mudou entre o Claude Opus 4.8 e o Claude Opus 5. Para um checklist, consulte os dois primeiros grupos do checklist de migração.

O que mudou

1. O pensamento é executado em requisições que o omitiam: No Claude Opus 4.8, o pensamento fica desativado a menos que você o solicite. No Claude Opus 5.5, uma requisição sem campo thinking é executada com pensamento, então cada item em Lidar com o pensamento em todas as respostas é uma alteração para esse código. Se seu código nunca enviou um campo thinking, não há nada a remover no antes e depois para o pensamento.

2. Mínimo menor de "prompt caching" (cache de prompt): O comprimento mínimo de prompt armazenável em cache no Claude Opus 5.5 é de 512 tokens, abaixo dos 1.024 tokens do Claude Opus 4.8. Prompts que eram curtos demais para cache no Claude Opus 4.8 podem criar entradas de cache, sem necessidade de alterações de código. Consulte Cache de prompt para os mínimos por modelo.

3. O Priority Tier não é suportado: O Priority Tier não é suportado no Claude Opus 5.5, enquanto o Claude Opus 4.8 o mantém. Se sua organização tem um compromisso de Priority Tier, planeje a capacidade separadamente.

Mudanças recomendadas

Estas alterações não são obrigatórias, mas melhorarão sua experiência:

1. Considere orçamentos de tarefa (beta): Para cargas de trabalho agênticas, os orçamentos de tarefa informam ao modelo quantos tokens ele tem para um loop agêntico completo. Eles exigem o cabeçalho beta task-budgets-2026-03-13.

2. Considere alterações de ferramentas no meio da conversa (beta): As alterações de ferramentas no meio da conversa permitem adicionar ou remover ferramentas entre os turnos de uma conversa sem invalidar os acertos do cache de prompt em turnos anteriores. Alterar o próprio array tools invalida o prefixo em cache. Na Claude API, envie o cabeçalho beta inline-tools-2026-09-15. O cabeçalho mais antigo mid-conversation-tool-changes-2026-07-01 ainda funciona para alterações que referenciam uma ferramenta pelo nome, na Claude API, no Amazon Bedrock e no Google Cloud.

Migrando para o Claude Opus 5.5 a partir do Claude Opus 4.7

Primeiro, percorra O que toda requisição ao Claude Opus 5.5 deve atender, Lidar com o pensamento em todas as respostas, Migrando para o Claude Opus 5.5 a partir do Claude Opus 5 e Migrando para o Claude Opus 5.5 a partir do Claude Opus 4.8. Use claude-opus-4-7 como o ID de modelo que você substitui. Essas seções se aplicam ao código no Claude Opus 4.7 tal como estão escritas. Assim como o Claude Opus 4.8, ele aceita thinking: {"type": "disabled"}, escolha forçada de ferramenta e a ferramenta computer_20251124. Ele tem esforço high como padrão e é executado sem pensamento a menos que você o solicite.

Esta seção acrescenta o que mudou após o Claude Opus 4.7. Se seu código está no Claude Opus 4.6 ou anterior, continue com Migrando para o Claude Opus 5.5 a partir do Claude Opus 4.6 e modelos Opus anteriores após esta seção. A seção do Claude Opus 4.6 acrescenta as mudanças incompatíveis que entraram em vigor no Claude Opus 4.7. Para um checklist, consulte os três primeiros grupos do checklist de migração.

O que mudou

Nenhum destes itens acrescenta uma mudança incompatível às das seções anteriores; vale a pena verificá-los depois de trocar o ID do modelo.

1. Níveis de esforço recalibrados: A alocação de tokens por trás de cada nível de esforço muda no Claude Opus 5.5 em comparação com o Claude Opus 4.7. O padrão é medium, enquanto o do Claude Opus 4.7 é high. Execute uma nova varredura de esforço em suas próprias avaliações em vez de manter uma configuração ajustada para o Claude Opus 4.7. Consulte Esforço.

2. A janela de contexto de 1M é o padrão: O Claude Opus 5.5 oferece a janela de contexto completa de 1M tokens por padrão, sem cabeçalho beta. Se seu cliente passa um cabeçalho beta de janela de contexto para compatibilidade com modelos mais antigos, remova-o.

3. Mensagens de sistema no meio da conversa: Na Claude API, no Amazon Bedrock e no Google Cloud, o Claude Opus 5.5 aceita mensagens role: "system" imediatamente após um turno do usuário no array messages (sujeito às regras de posicionamento). Use o campo system de nível superior para instruções que se aplicam desde o início. O Claude Opus 4.7 rejeita role: "system" em messages com um erro 400. Se você mantém caminhos de código que reconstroem todo o histórico de mensagens para atualizar instruções, pode simplificá-los e preservar os acertos de cache de prompt em turnos anteriores.

4. Detalhes de parada em recusas: Quando o modelo recusa uma requisição, o Claude Opus 5.5 retorna um objeto stop_details que nomeia a categoria da recusa, junto com o motivo de parada refusal. O Claude Opus 4.7 retorna o mesmo objeto, então isso só importa se o seu tratamento de motivos de parada ainda não o lê. Nenhum cabeçalho beta é necessário, e não há opção de desativação. Se o seu tratamento de motivos de parada ainda não o lê, consulte Tratando motivos de parada. O Claude Opus 5.5 recusa em mais categorias; consulte Classificadores de segurança e fallback.

5. Modo rápido: O Claude Opus 5.5 suporta o modo rápido (prévia de pesquisa) na Claude API. O modo rápido não está disponível no Claude Opus 4.7, onde requisições com speed: "fast" retornam um erro. Defina speed: "fast" com o cabeçalho beta fast-mode-2026-02-01.

6. Toolset de uso de computador e ferramenta de uso do navegador: Na Claude API e no Google Cloud, o Claude Opus 5.5 suporta o uso de computador como o toolset computer_toolset_20260801 e a ferramenta de uso do navegador para tarefas dentro de páginas web. O Claude Opus 4.7 não suporta nenhum dos dois. Nessas plataformas, o Claude Opus 5.5 não aceita a ferramenta anterior computer_20251124; consulte a mudança incompatível do uso de computador.

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

Primeiro, percorra todas as seções anteriores, na ordem da página. Elas são O que toda requisição ao Claude Opus 5.5 deve atender, Lidar com o pensamento em todas as respostas e as seções do Claude Opus 5, do Claude Opus 4.8 e do Claude Opus 4.7. Essas seções se aplicam ao código no Claude Opus 4.6 tal como estão escritas. Assim como o Claude Opus 4.7, ele aceita thinking: {"type": "disabled"}, escolha forçada de ferramenta e a ferramenta computer_20251124. Ele tem esforço high como padrão e é executado sem pensamento a menos que você o solicite. O Claude Opus 4.5 e modelos Opus anteriores também aceitam thinking: {"type": "disabled"} e escolha forçada de ferramenta, e são executados sem pensamento a menos que você o solicite, então essas seções também se aplicam a eles.

Esta seção acrescenta o que mudou no Claude Opus 4.7, com claude-opus-4-6 como o ID de modelo que você substitui. Suas duas subseções acrescentam o que mudou antes disso, para leitores no Claude Opus 4.5 ou anterior e no Claude 4.1 ou anterior. Para um checklist, consulte o checklist de migração até o grupo que nomeia seu modelo.

Mudanças incompatíveis

1. "Extended thinking" (pensamento estendido) removido: thinking: {"type": "enabled", "budget_tokens": N} não é mais suportado no Claude Opus 4.7 e em modelos posteriores e retorna um erro 400. Mude para o "adaptive thinking" (pensamento adaptativo) (thinking: {"type": "adaptive"}) e use o "effort parameter" (parâmetro de esforço) para controlar a profundidade do pensamento. No Claude Opus 5.5, o pensamento adaptativo está sempre ativado: thinking: {"type": "adaptive"} é válido e equivale a omitir completamente o campo thinking.

   Antes (Claude Opus 4.6):

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

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

   Depois (Claude Opus 5.5), em que as linhas do ID do modelo, de thinking e de output_config diferem:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

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

   O pensamento adaptativo pode ser direcionado por meio de prompts e do parâmetro de esforço, que substitui o orçamento de pensamento como a forma de controlar o quanto o modelo raciocina. Execute uma varredura de níveis de esforço nas suas próprias avaliações em vez de converter um valor de budget_tokens. A tabela de níveis de esforço descreve quando usar cada nível, e Níveis de esforço recomendados para o Claude Opus 5.5 aborda este modelo.

2. Parâmetros de amostragem removidos: Definir temperature, top_p ou top_k com qualquer valor diferente do padrão no Claude Opus 4.7 e em modelos posteriores, incluindo o Claude Opus 5.5, retorna um erro 400. O SDK Python (v1.0 e posteriores) não os define, e passá-los gera um TypeError. O caminho de migração mais seguro é omitir completamente esses parâmetros dos payloads das requisições. O uso de prompts é a forma recomendada de orientar o comportamento do modelo no Claude Opus 5.5. Se você estava usando temperature = 0 para obter determinismo, observe que isso nunca garantiu saídas idênticas nos modelos anteriores.

3. Conteúdo do pensamento omitido por padrão: Os blocos de pensamento ainda aparecem no stream de resposta no Claude Opus 4.7 e em modelos posteriores, mas o campo thinking deles fica vazio, a menos que você opte explicitamente por recebê-lo. Esta é uma mudança silenciosa em relação ao Claude Opus 4.6, em que o padrão era retornar o texto resumido do pensamento. Para restaurá-lo, consulte o item 4 de Lidar com o pensamento em todas as respostas.

4. Contagem de tokens atualizada: O Claude Opus 4.7 introduziu um novo tokenizador, que os modelos Opus posteriores, incluindo o Claude Opus 5.5, também usam. Ele contribui para um desempenho melhor em uma ampla variedade de tarefas e pode usar aproximadamente de 1x a 1,35x mais tokens ao processar texto em comparação com os modelos anteriores ao Claude Opus 4.7 (até ~35% a mais, variando conforme o conteúdo).

   /v1/messages/count_tokens retorna um número de tokens diferente para o Claude Opus 5.5 do que retornava para o Claude Opus 4.6. A eficiência de tokens pode variar conforme o formato da carga de trabalho.

   Atualize seus parâmetros max_tokens para dar margem adicional, incluindo os gatilhos de compactação, e teste novamente qualquer caminho de código que estime tokens no lado do cliente ou que presuma uma proporção fixa entre tokens e caracteres. Use o endpoint de contagem de tokens para verificar. Intervenções nos prompts, task_budget e effort podem ajudar a controlar os custos; esses controles podem ter como contrapartida a inteligência do modelo.

5. Remoção do prefill (já em vigor no Claude Opus 4.6): Preencher previamente mensagens do assistente retorna um erro 400 no Claude Opus 4.6 e em modelos Opus posteriores, incluindo o Claude Opus 5.5, portanto isso só é uma mudança se você vier do Claude Opus 4.5 ou anterior. Em vez disso, use saídas estruturadas ou instruções no prompt do sistema. No Amazon Bedrock, as saídas estruturadas não estão disponíveis para o Claude Opus 5.5, então use instruções no prompt do sistema nesse caso.

Mudanças de comportamento

O Claude Opus 4.7 introduziu diferenças de comportamento em relação ao Claude Opus 4.6 que não são mudanças incompatíveis da API. Estas três afetam o código ou a estrutura de suporte:

1. Atualizações de progresso integradas em rastros agênticos: O Claude Opus 4.7 fornece atualizações mais regulares e de maior qualidade ao usuário ao longo de rastros agênticos longos. Se você adicionou estruturas de suporte para forçar mensagens de status intermediárias ("Após cada 3 chamadas de ferramenta, resuma o progresso"), experimente removê-las. No Claude Opus 5.5, essas atualizações chegam em blocos thinking, que ficam vazios com o thinking.display padrão. Para recebê-las, consulte O texto entre chamadas de ferramentas é retornado em blocos de pensamento. Para definir o tamanho e o conteúdo delas, consulte Atualizações de progresso voltadas ao usuário.

2. Salvaguardas de cibersegurança em tempo real: Adicionadas no Claude Opus 4.7, requisições que envolvem tópicos proibidos ou de alto risco podem resultar em recusas. Para trabalhos de segurança legítimos, como testes de penetração, pesquisa de vulnerabilidades ou red-teaming, inscreva-se no Cyber Verification Program para solicitar restrições reduzidas. A forma de inscrição depende de como você acessa o Claude.

3. Suporte a imagens de alta resolução: O Claude Opus 4.7 é o primeiro modelo Claude com suporte a imagens de alta resolução. A resolução máxima de imagem é de 2.576 pixels no lado maior, acima dos 1.568 pixels dos modelos anteriores. Isso gera ganhos em cargas de trabalho com uso intenso de visão e é particularmente valioso para uso de computador, compreensão de capturas de tela e análise de documentos.

   O suporte a alta resolução é automático e não requer cabeçalho beta nem opt-in do lado do cliente. Duas coisas para planejar:

   • Imagens em resolução total podem usar até aproximadamente 3x mais tokens de imagem do que nos modelos anteriores (até 4.784 tokens por imagem, em comparação com o limite anterior de aproximadamente 1.600 tokens por imagem). Refaça o orçamento de max_tokens e as expectativas de custo para cargas de trabalho com muitas imagens, ou reduza a resolução antes de enviar se você não precisa da fidelidade adicional.
   • As coordenadas de apontamento e de caixas delimitadoras retornadas pelo modelo são 1:1 com os pixels reais da imagem no Claude Opus 4.7, portanto nenhuma conversão de fator de escala é necessária.

   Consulte Suporte a imagens de alta resolução no Claude Opus 4.7 para detalhes.

Para diferenças relacionadas aos prompts, consulte Prompting do Claude Opus 5.5 e Melhores práticas de prompting.

Migrando do Claude Opus 4.5 ou anterior

Se você está migrando do Claude Opus 4.5, do Claude Opus 4.1 ou de um modelo anterior diretamente para o Claude Opus 5.5, leia esta página desde o início: primeiro, percorra todas as seções anteriores, na ordem da página. Em seguida, percorra as mudanças incompatíveis para migrar do Claude Opus 4.6, apresentadas anteriormente nesta seção. Depois, aplique as seguintes mudanças cumulativas, que entraram em vigor entre o Claude Opus 4.5 e o Claude Opus 4.7. Se você está no Claude Opus 4.1 ou anterior, continue com Migrando do Claude 4.1 ou anterior após esta subseção.

Mudanças incompatíveis

1. A remoção do prefill é abordada nas mudanças incompatíveis para migrar do Claude Opus 4.6.

2. Aspas em parâmetros de ferramentas: O Claude Opus 4.6 e modelos posteriores podem produzir escape de strings JSON ligeiramente diferente nos argumentos de chamadas de ferramentas (por exemplo, tratamento diferente de escapes Unicode ou escape de barras). Se você analisa o input da chamada de ferramenta como uma string bruta em vez de usar um parser JSON, verifique sua lógica de análise. Parsers JSON padrão (como json.loads() ou JSON.parse()) lidam com essas diferenças automaticamente.

Mudanças recomendadas

O primeiro item é obrigatório no Claude Opus 5.5; os demais são recomendados.

1. Migre para o pensamento adaptativo (obrigatório): thinking: {"type": "enabled", "budget_tokens": N} retorna um erro 400 no Claude Opus 4.7 e em modelos posteriores. O antes e depois está no item 1 das mudanças incompatíveis para migrar do Claude Opus 4.6. A migração também passa de client.beta.messages.create() para client.messages.create(): o pensamento adaptativo e o esforço não exigem o namespace beta do SDK nem quaisquer cabeçalhos beta.

2. Remova o cabeçalho beta de effort: O parâmetro effort não requer um cabeçalho beta. Remova o beta effort-2025-11-24 das suas requisições.

3. Remova o cabeçalho beta de streaming de ferramentas de granularidade fina: O streaming de ferramentas de granularidade fina não requer um cabeçalho beta. Remova o beta fine-grained-tool-streaming-2025-05-14 das suas requisições.

4. Remova o cabeçalho beta de pensamento intercalado: Com o pensamento adaptativo, o pensamento intercalado é automático em todos os modelos que suportam pensamento adaptativo. Remova o beta interleaved-thinking-2025-05-14 das suas requisições.

5. Migre para output_config.format: Se estiver usando saídas estruturadas, atualize output_format={...} para output_config={"format": {...}}. 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. O SDK Python (v1.0 e posteriores) não aceita output_format={...} em client.beta.messages.create() nem em count_tokens(). O argumento output_format=Model dos helpers parse() e stream() permanece inalterado.

Migrando do Claude 4.1 ou anterior

Se você está migrando do Claude Opus 4.1 ou de modelos anteriores diretamente para o Claude Opus 5.5, primeiro aplique tudo o que está em Migrando do Claude Opus 4.5 ou anterior. Essa subseção começa com todas as seções anteriores, então, na prática, você lê esta página desde o início. Em seguida, aplique as mudanças adicionais desta subseção.

Mudanças incompatíveis adicionais

1. Remova os parâmetros de amostragem: Abordado em Parâmetros de amostragem removidos.

2. Atualize as versões das ferramentas

   Atualize para as versões atuais das ferramentas. Remova qualquer código que use o comando undo_edit.

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   # Antes
   tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
   
   # Depois
   tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]

   • Editor de texto: Use text_editor_20250728 e str_replace_based_edit_tool. Consulte a documentação da ferramenta de editor de texto para obter detalhes.
   • Execução de código: Atualize para code_execution_20260521. Consulte a documentação da ferramenta de execução de código para obter instruções de migração.
   • Uso de computador: Na Claude API e no Google Cloud, o Claude Opus 5.5 aceita o uso de computador apenas como o toolset computer_toolset_20260801: as ferramentas anteriores computer_20250124 e computer_20251124 são rejeitadas nessas plataformas. Consulte a mudança incompatível do uso de computador.

3. Trate o motivo de parada refusal

   Atualize sua aplicação para tratar motivos de parada refusal:

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   response = client.messages.create(...)
   
   if response.stop_reason == "refusal":
       # Trate a recusa adequadamente
       pass

4. Trate o motivo de parada model_context_window_exceeded

   O Claude 4.5 e modelos posteriores retornam um motivo de parada model_context_window_exceeded quando a geração é interrompida por atingir o limite da "context window" (janela de contexto), e não o limite de max_tokens solicitado. Atualize sua aplicação para lidar com esse novo motivo de parada:

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   response = client.messages.create(...)
   
   if response.stop_reason == "model_context_window_exceeded":
       # Trate o limite da janela de contexto adequadamente
       pass

5. Verifique o tratamento de parâmetros de ferramentas (quebras de linha finais)

   O Claude 4.5 e modelos posteriores preservam as quebras de linha finais nos parâmetros de string das chamadas de ferramenta, que antes eram removidas. Se suas ferramentas dependem de correspondência exata de strings com os parâmetros das chamadas de ferramenta, verifique se sua lógica lida corretamente com as quebras de linha finais.

6. Atualize seus prompts para as mudanças comportamentais

   O Claude 4 e modelos posteriores têm um estilo de comunicação mais conciso e direto e exigem orientações explícitas. Revise as melhores práticas de prompting para obter orientações de otimização.

Mudanças recomendadas adicionais

• Remova cabeçalhos beta legados: Remova token-efficient-tools-2025-02-19 e output-128k-2025-02-19. Todos os modelos Claude 4 e posteriores têm "tool use" (uso de ferramentas) eficiente em tokens integrado, e esses cabeçalhos não têm efeito.

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

Percorra O que toda requisição ao Claude Opus 5.5 deve atender, Lidar com o pensamento em todas as respostas e Migrando para o Claude Opus 5.5 a partir do Claude Opus 5. Use claude-sonnet-5 como o ID do modelo que você substitui. Essa última seção se aplica ao código no Claude Sonnet 5 tal como está escrito, porque o Claude Sonnet 5, assim como o Claude Opus 5:

• É executado com o pensamento ativado por padrão e aceita thinking: {"type": "disabled"}, no caso dele em qualquer nível de esforço.
• Aceita escolha forçada de ferramenta e a ferramenta computer_20251124.
• Retorna o texto entre chamadas de ferramentas como blocos text.
• Usa o esforço high por padrão.

O pensamento estendido manual, parâmetros de amostragem diferentes do padrão e o prefill do assistente retornam um erro 400 em ambos os modelos, portanto nada muda nesse aspecto. Nenhuma das mudanças obrigatórias nas seções do Claude Opus 4.8, do Claude Opus 4.7 e do Claude Opus 4.6 se aplica a você.

O que mudou

1. Mensagens de sistema no meio da conversa: Na Claude API, no Amazon Bedrock e no Google Cloud, o Claude Opus 5.5 aceita mensagens role: "system" imediatamente após um turno do usuário no array messages (sujeito às regras de posicionamento). Este recurso não está disponível no Claude Sonnet 5. Se você mantém caminhos de código que reconstroem todo o histórico de mensagens para atualizar instruções, pode simplificá-los e preservar os acertos de "prompt cache" (cache de prompt) em turnos anteriores.

2. Mínimo menor para cache de prompt: O tamanho mínimo de prompt armazenável em cache no Claude Opus 5.5 é de 512 tokens, abaixo dos 1.024 tokens do Claude Sonnet 5. Prompts que eram curtos demais para serem armazenados em cache no Claude Sonnet 5 podem criar entradas de cache, sem necessidade de alterações no código. Consulte Cache de prompt para ver os mínimos por modelo.