Claude Platform Docs
Modelos e preçosClaude Opus 5.5

Guia de migração para o Claude Opus 5.5

Migre para o Claude Opus 5.5 a partir de modelos Opus anteriores ou do Claude Sonnet 5 com este guia de migração. As orientações para habilitar o Claude Opus 5.5 incluem configurações de solicitação que retornam erros, blocos de pensamento em todas as respostas e uma checklist para cada modelo de origem.

Claude Code

Deixe o Claude Code migrar seu código para você

/claude-api migrate este projeto para 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 solicitação ao Claude Opus 5.5 deve atender e Lide 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ê. A 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 USD; consulte Preços do Claude). Para o suporte a recursos, consulte Novidades do Claude Opus 5.5. Para diferenças de comportamento e padrões de prompting específicos do modelo, consulte Fazendo prompts para o Claude Opus 5.5.

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

Independentemente do modelo de origem, uma solicitação a 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, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Claude Models on Google Cloud (Google managed) e 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 pensamento.
  • Esforço: Controle a profundidade do pensamento com o “effort parameter” (parâmetro de esforço), o único parâmetro de requisição que o 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 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 escolha de ferramenta.
  • Parâmetros de amostragem: Omita temperature, top_p e top_k. Use prompts para orientar o comportamento do modelo.
  • Preenchimento prévio: Não termine messages com um turno de assistente pré-preenchido: isso é rejeitado. Use saídas estruturadas ou instruções no prompt do sistema em vez disso.
  • Uso de computador: Declare o uso de computador como o toolset computer_toolset_20260801. No Amazon Bedrock, computer_20251124 também funciona. Consulte a alteração incompatível de uso de computador.
  • Janela de contexto: Nenhum cabeçalho beta de janela de contexto é necessário. A “context window” (janela de contexto) de 1M de tokens é o padrão, e um cabeçalho enviado para modelos mais antigos não tem efeito.

A solicitação a seguir atende a todos os itens da lista: o esforço está definido e não há campo thinking. Onde o exemplo imprime texto, ele encontra o bloco de texto pelo seu tipo, 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)

Lide com o pensamento em todas as respostas

O pensamento é executado em toda solicitação ao Claude Opus 5.5, então toda resposta pode começar com blocos thinking, e max_tokens cobre 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 cobre o pensamento mais o texto: No Claude Opus 4.8 e em modelos Opus anteriores, solicitações sem o 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 solicitaçã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. Os 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 solicitação. Consulte Controle de custos. 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 com essas respostas. Em vez disso, selecione os blocos de conteúdo pelo campo type: leia text dos blocos cujo type é "text" e ramifique pelo tipo de bloco ao tratar eventos de stream.

  3. Retorne 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 quando retornar os resultados das ferramentas, incluindo blocos cujo campo thinking está vazio. Reenvie a mensagem do assistente como 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 removidos 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":

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

    Se o seu produto faz streaming do raciocínio para os usuários, 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 voltam como blocos thinking, que ficam vazios com a 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 cita 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", ...}; escolha um nível de esforço em vez disso.
  • Defina effort explicitamente: o padrão é medium, enquanto o do Claude Opus 5 é high.
  • Substitua os tipos any e tool de tool_choice por auto mais uso estrito de ferramentas ou saídas estruturadas.
  • Se você usa uma versão anterior da ferramenta de uso de computador, declare computer_toolset_20260801 (sem cabeçalho beta) em vez disso e atualize seu loop de agente para o toolset. No Amazon Bedrock, computer_20251124 também funciona.
  • 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 (Claude Fable 5.1 e 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 Claude Models on Google Cloud (Google managed), 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 devolva os blocos thinking 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 Trate o pensamento em todas as respostas.

Claude Opus 4.8 ou anterior

  • Revise as cargas de trabalho que eram executadas sem o 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 quiser menos pensamento. Os 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 solicitaçã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 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

  • Faça uma nova varredura de esforço nas 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 stop reason lê stop_details em recusas.
  • Se você quer o modo rápido, que o Claude Opus 4.7 rejeita, defina speed: "fast" nas suas solicitações à Claude API. O Claude Opus 5.5 não precisa de cabeçalho beta.

Claude Opus 4.6 ou anterior

  • Remova temperature, top_p e top_k dos payloads das solicitações.
  • Substitua thinking: {"type": "enabled", "budget_tokens": N} por thinking: {"type": "adaptive"} mais o parâmetro effort, ou remova o campo thinking completamente; o pensamento adaptativo está sempre ativado.
  • Se sua interface exibe o conteúdo do pensamento, ative explicitamente a 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 considerar a tokenização atualizada, incluindo os gatilhos de compactação.
  • Teste novamente quaisquer estimativas de contagem de tokens no 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 caixa delimitadora do modelo, remova qualquer conversão por 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, candidate-se ao Cyber Verification Program para obter acesso a restrições mais baixas 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 das chamadas de ferramentas usa um parser JSON padrão.
  • Mude 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 habilita 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 das ferramentas quanto a quebras de linha no final.
  • Remova os cabeçalhos beta token-efficient-tools-2025-02-19 e output-128k-2025-02-19.
  • Revise e atualize os prompts seguindo as melhores práticas de prompting.

Apenas 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 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 solicitação ao Claude Opus 5.5 deve atender e Lide com o pensamento em todas as respostas. Todos os modelos de origem precisam das alterações desta seção. Elas são as configurações de solicitação que o Claude Opus 5.5 rejeita e as mudanças nas respostas que vêm com ele. A checklist desta seção é o primeiro grupo da 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, no Claude Platform on AWS, no Claude Models on Google Cloud (Anthropic managed), no Claude Models on Google Cloud (Google managed) e no Microsoft Foundry, use o ID de modelo dessa plataforma; consulte Disponibilidade.

Alterações incompatíveis

Cada alteração é explicada em Alterações incompatíveis em Novidades do 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 esforço; onde você desativava o pensamento para economizar tokens, use um nível mais baixo. As respostas passam então a começar com blocos thinking, então selecione os blocos de conteúdo por type e passe os blocos thinking de volta sem modificações com os resultados das ferramentas. Consulte O pensamento não pode ser desativado.

Antes. O Claude Opus 5 aceita esta solicitaçã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 any e tool de tool_choice 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 indique 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. Consulte O uso forçado de ferramentas não é suportado.

Antes. O Claude Opus 5 aceita esta solicitaçã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 estrito de ferramentas: toda chamada segue o 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, Claude Fable 5.1 e Claude Mythos 5.1 leem os blocos de pensamento do Claude Opus 5.5; nenhum outro modelo faz isso. Um roteador ou uma alternativa de contingência que move uma conversa do Claude Opus 5.5 para qualquer outro modelo executa esses turnos sem eles. Na direção oposta, 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 Claude Models on Google Cloud (Google managed), do Claude Sonnet 5.5 e do Claude Haiku 5.5, mas não de modelos Claude Fable ou Claude Mythos. Mantenha a conversa “append-only” (somente acréscimo), sem edições no prompt do sistema (system), em tools ou em mensagens anteriores no meio da conversa, para que os blocos continuem válidos; Claude Code, claude.ai, Claude Managed Agents e o Claude Agent SDK já fazem isso. Em contas criadas em ou após 31 de agosto de 2026, 00:00 UTC, na Claude API e em plataformas de nuvem, uma solicitação que reenvia um bloco de pensamento após uma edição desse tipo e deixa thinking.block_binding.prefix_mismatch_behavior sem definir recebe um erro 400. Não há alteração de código para integrações append-only. Consulte Os blocos de pensamento estão vinculados ao modelo e à conversa e Pensamento preservado.

Algumas versões da ferramenta de uso de computador não são suportadas

O Claude Opus 5.5 suporta uso de computador por meio do toolset computer_toolset_20260801. No Amazon Bedrock, o Claude Opus 5.5 também aceita a ferramenta computer_20251124 com o cabeçalho beta computer-use-2025-11-24. O Claude Opus 5.5 retorna um erro 400 para qualquer versão da ferramenta de uso de computador que ele não aceita, como computer_20251124 na Claude API. Ele não aceita computer_20250124 em nenhuma plataforma. Na Claude API, a mensagem de erro começa com 'claude-opus-5-5' does not support tool types: computer_20251124. e então lista os tipos de ferramenta que o modelo aceita.

Integrações que usam o toolset não precisam de alteração. Para mover uma integração computer_20251124 para o toolset, remova o cabeçalho beta e envie a entrada computer_toolset_20260801 sem name nem dimensões de tela. No seu loop de agente, trate todos os blocos tool_use de membros em um turno e repita toolset_name em cada resultado. Leia a ação a partir do name de cada bloco, não de input.action. Migrar de computer_20251124 lista as alterações no loop de agente.

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

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 cabeçalho 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 thinking.display padrão de "omitted", o campo thinking deles fica vazio. Nenhuma solicitaçã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 passe os blocos de volta sem alterações 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 de categorias mais amplo 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. Trate 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 solicitações recusadas com "reasoning_extraction"; essa recusa é retornada a você); consulte Recusas e fallback e Recusas de salvaguarda.

  1. Refaça 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, então uma solicitação que omite effort agora é executada com medium. Reduza onde a qualidade se mantém e aumente 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 Fazendo prompts para o 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 mudar 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 solicitação ao Claude Opus 5.5 deve atender, Lide 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 como está escrita, porque o Claude Opus 4.8, assim como o Claude Opus 5:

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

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

O que mudou

  1. O pensamento é executado em solicitaçõ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 solicitação sem o campo thinking é executada com pensamento, então cada item em Lide com o pensamento em todas as respostas é uma alteração para esse código. Se o 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 para 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 no 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.

Estas não são obrigatórias, mas vão melhorar sua experiência:

  1. Considere orçamentos de tarefa (beta): Para cargas de trabalho agênticas, os “task budgets” (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 de “prompt cache” (cache de prompt) em turnos anteriores. Alterar o próprio array tools invalida o prefixo em cache. Na Claude API, no Claude Platform on AWS e no Claude Models on Google Cloud (Anthropic managed), envie o cabeçalho beta inline-tools-2026-09-15. O cabeçalho mid-conversation-tool-changes-2026-07-01 funciona para alterações que nomeiam uma ferramenta por referência, na Claude API, no Amazon Bedrock, no Claude Platform on AWS, no Claude Models on Google Cloud (Anthropic managed) e no Claude Models on Google Cloud (Google managed).

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

Primeiro, percorra O que toda solicitação ao Claude Opus 5.5 deve atender, Lide 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 como estão escritas. Assim como o Claude Opus 4.8, ele aceita thinking: {"type": "disabled"}, a escolha forçada de ferramenta e a ferramenta computer_20251124. Ele tem high como esforço 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 o 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. Ela acrescenta as alterações incompatíveis que entraram em vigor no Claude Opus 4.7. Para uma checklist, consulte os três primeiros grupos da checklist de migração.

O que mudou

Nenhum destes itens acrescenta uma alteração 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 “effort” (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 reaproveitar uma configuração ajustada para o Claude Opus 4.7. Consulte Esforço.

  2. Janela de contexto de 1M é o padrão: O Claude Opus 5.5 oferece a “context window” (janela de contexto) completa de 1M tokens por padrão, sem cabeçalho beta. Se o seu cliente envia um cabeçalho beta de janela de contexto para compatibilidade com modelos mais antigos, remova-o.

  3. Mensagens do sistema no meio da conversa: Na Claude API, no Amazon Bedrock, no Claude Platform on AWS, no Claude Models on Google Cloud (Anthropic managed) e no Claude Models on Google Cloud (Google managed), 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 por recusa: Quando o modelo recusa uma solicitação, o Claude Opus 5.5 retorna um objeto stop_details que nomeia a categoria da recusa, junto com o “stop reason” (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 Tratamento de 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 oferece suporte ao “fast mode” (modo rápido) na Claude API. O modo rápido não está disponível no Claude Opus 4.7, onde solicitações com speed: "fast" retornam um erro. Defina speed: "fast" em suas solicitações. O Claude Opus 5.5 não precisa de cabeçalho beta.

  6. Conjunto de ferramentas de uso de computador e ferramenta de uso de navegador: O Claude Opus 5.5 oferece suporte ao “computer use” (uso de computador) como o conjunto de ferramentas computer_toolset_20260801 e à “browser use tool” (ferramenta de uso de navegador) para tarefas dentro de páginas da web. O Claude Opus 4.7 não oferece suporte a nenhum dos dois. Para migrar uma integração computer_20251124 para o conjunto de ferramentas, consulte a alteração incompatível do uso de computador.

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

Primeiro, percorra todas as seções anteriores, na ordem da página. São elas O que toda solicitação ao Claude Opus 5.5 deve atender, Lide com o pensamento em toda resposta e as seções para o Claude Opus 5, o Claude Opus 4.8 e o 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 usa por padrão o esforço high e é executado sem pensamento, a menos que você o solicite. O Claude Opus 4.5 e os 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, portanto 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 uma lista de verificação, consulte a lista de verificação de migração até o grupo que menciona o seu modelo.

Mudanças incompatíveis

  1. 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 parâmetro effort para controlar a profundidade do pensamento. No Claude Opus 5.5, o pensamento adaptativo está sempre ativado: thinking: {"type": "adaptive"} é válido e equivalente a omitir totalmente o campo thinking.

    Antes (Claude Opus 4.6):

    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:

    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 effort, que substitui o orçamento de pensamento como a forma de controlar o quanto o modelo raciocina. Execute uma varredura 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: Omita temperature, top_p e top_k. O uso de prompts é a forma recomendada de orientar o comportamento do modelo no Claude Opus 5.5. Se você usava temperature = 0 para obter determinismo, observe que isso nunca garantiu saídas idênticas nos modelos anteriores.

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

  4. Contagem de tokens atualizada: O Claude Opus 4.7 introduziu um novo “tokenizer” (tokenizador), que os modelos Opus posteriores, incluindo o Claude Opus 5.5, também usam. Ele contribui para um desempenho aprimorado em uma ampla gama de tarefas e pode usar aproximadamente de 1x a 1,35x tokens ao processar texto em comparação com os modelos anteriores ao Claude Opus 4.7 (até cerca de 35 por cento 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 perfil 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 presuma uma proporção fixa entre tokens e caracteres. Use o endpoint de Contagem de tokens para verificar. Intervenções de prompt, task_budget e effort podem ajudar a controlar custos; esses controles podem comprometer a inteligência do modelo.

  5. Remoção do prefill (já em vigor no Claude Opus 4.6): Fazer “prefill” (preenchimento prévio) de 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. Use saídas estruturadas ou instruções no prompt do sistema em vez disso.

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 apoio:

  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 estrutura de apoio para forçar mensagens de status intermediárias (“Após cada 3 chamadas de ferramenta, resuma o progresso”), experimente removê-la. 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 ferramenta é retornado em blocos de pensamento. Para moldar seu tamanho e conteúdo, consulte Atualizações de progresso voltadas ao usuário.

  2. Salvaguardas de cibersegurança em tempo real: Essas salvaguardas são novas no Claude Opus 4.7: solicitações que envolvam tópicos proibidos ou de alto risco podem levar a 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 proporciona 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 ativação no lado do cliente. Dois pontos a 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 cerca de 1.600 tokens). Reavalie 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 caso não precise 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 por fator de escala é necessária.

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

Para diferenças relacionadas a prompts, consulte Criando prompts para o Claude Opus 5.5 e Melhores práticas de prompts.

Migrando a partir 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 a migração a partir 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 a partir 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 a migração a partir do Claude Opus 4.6.

  2. Aspas em parâmetros de ferramentas: O Claude Opus 4.6 e modelos posteriores podem produzir um escape de strings JSON ligeiramente diferente nos argumentos das chamadas de ferramenta (por exemplo, tratamento diferente de escapes Unicode ou do 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.

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 a migração a partir 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 esforço: O parâmetro effort não requer um cabeçalho beta. Remova o beta effort-2025-11-24 das suas solicitações.

  3. Remova o cabeçalho beta de streaming de ferramentas refinado: O streaming de ferramentas refinado não requer um cabeçalho beta. Remova o beta fine-grained-tool-streaming-2025-05-14 das suas solicitaçõ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 solicitaçõ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 a partir 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 em Migrando a partir 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.

    # 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 mais detalhes.
    • Execução de código: Atualize para code_execution_20260521. Consulte a documentação da ferramenta de execução de código para instruções de migração.
    • Uso de computador: Use o toolset computer_toolset_20260801 no lugar de computer_20250124, que o Claude Opus 5.5 não aceita. No Amazon Bedrock, computer_20251124 também funciona. Consulte a alteração incompatível de uso de computador.

  3. Trate o motivo de parada refusal

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

    response = client.messages.create(...)

if response.stop_reason == "refusal":
    # Trate a recusa de forma apropriada
    pass

  4. Trate o motivo de parada model_context_window_exceeded

    Os modelos Claude 4.5 e posteriores retornam um motivo de parada model_context_window_exceeded quando a geração para por atingir o limite da janela de contexto, em vez do limite max_tokens solicitado. Atualize sua aplicação para tratar este novo motivo de parada:

    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)

    Os modelos Claude 4.5 e posteriores preservam quebras de linha finais em parâmetros de string de chamadas de ferramentas que antes eram removidas. Se suas ferramentas dependem de correspondência exata de strings com parâmetros de chamadas de ferramentas, verifique se sua lógica trata quebras de linha finais corretamente.

  6. Atualize seus prompts para as mudanças de comportamento

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

  • Cabeçalhos beta: Remova token-efficient-tools-2025-02-19 e output-128k-2025-02-19. Todos os modelos Claude 4 e posteriores têm uso de ferramentas com eficiência de 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 solicitação ao Claude Opus 5.5 deve atender, Lide com o pensamento em toda resposta e Migrando para o Claude Opus 5.5 a partir do Claude Opus 5. Use claude-sonnet-5 como o ID de modelo que você substitui. Essa última seção se aplica ao código no Claude Sonnet 5 tal como está escrita, 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 ferramenta como blocos text.
  • Usa por padrão o esforço high.

O pensamento estendido manual, os parâmetros de amostragem 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 para o Claude Opus 4.8, o Claude Opus 4.7 e o Claude Opus 4.6 se aplica a você.

O que mudou

  1. Mensagens do sistema no meio da conversa: Na Claude API, no Amazon Bedrock, no Claude Platform on AWS, no Claude Models on Google Cloud (Anthropic managed) e no Claude Models on Google Cloud (Google managed), 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 cache de prompt em turnos anteriores.

  2. Mínimo de cache de prompt mais baixo: O comprimento mínimo de prompt armazenável em cache no Claude Opus 5.5 é de 512 tokens, abaixo dos 1.024 tokens no 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 os mínimos por modelo.

Esta página foi útil?