Migrando para o 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 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) e mantém a "context window" (janela de contexto) de 1M de tokens e o máximo de 128k tokens de saída do Claude Opus 5. Há quatro "breaking changes" (mudanças incompatíveis) para código que já roda no Claude Opus 5, abordadas em Mudanças incompatíveis. Para o suporte a recursos, consulte O que há de novo no Claude Opus 5.5.

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

Atualize o nome do 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 (aceito no Claude Opus 5, rejeitado no Claude Opus 5.5):

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 "structured outputs" (saídas estruturadas) e indique no prompt quando a ferramenta se aplica. Consulte O uso forçado de ferramentas não é suportado.

Antes:

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 faz isso. Um roteador ou "fallback" (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 e de modelos Opus, Sonnet e Haiku anteriores, mas não de modelos Claude Fable ou Claude Mythos. Mantenha a conversa "append-only" (somente com acréscimos), sem edições no prompt system, em tools ou em mensagens anteriores no meio da conversa, para que os blocos permaneçam válidos; Claude Code, claude.ai, Claude Managed Agents e o Claude Agent SDK já fazem isso. A aplicação dessa regra corresponde à do Claude Fable 5.1 em todas as plataformas: para contas criadas em ou após 31 de agosto de 2026, 00:00 UTC, reenviar um bloco de pensamento após uma edição desse tipo retorna um erro 400 por padrão. 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.

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:

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, portanto espere valores de stop_details.category como "bio" e "reasoning_extraction", além de "cyber"; consulte a tabela de categorias de recusa. Trate as recusas e configure o fallback do lado do servidor ou sua própria nova tentativa (o fallback do 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.

Checklist de migração

• 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 any e tool de tool_choice por auto combinado com uso estrito de ferramentas ou saídas estruturadas.
• 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 e de modelos Opus, Sonnet e Haiku anteriores, 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 o 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.

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

Siga primeiro Migrando para o Claude Opus 5 a partir do Claude Opus 4.8: esse guia aborda o pensamento ativado por padrão e as mudanças no formato da resposta que vêm com ele. Em seguida, aplique Migrando a partir do Claude Opus 5. A segunda alteração incompatível do Claude Opus 5 descrita ali (o pensamento só pode ser desativado com esforço high ou inferior) não se aplica: no Claude Opus 5.5, o pensamento não pode ser desativado de forma alguma.

Checklist de migração

• Tudo o que está no checklist Claude Opus 4.8 → Claude Opus 5, exceto que thinking: {"type": "disabled"} não é uma opção.
• Tudo o que está no checklist Claude Opus 5 → Claude Opus 5.5.

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

O guia de migração do Claude Opus 5 aborda as alterações incompatíveis entre seu modelo atual e o Claude Opus 5: parâmetros de amostragem rejeitados, pensamento estendido manual rejeitado, prefill removido e o tokenizador mais recente. Siga a seção correspondente ao seu modelo nesse guia, usando claude-opus-5-5 como destino em vez de claude-opus-5, e depois aplique Migrando a partir do Claude Opus 5. Onde esse guia diz que o pensamento pode ser desativado com esforço high ou inferior, isso não é possível no Claude Opus 5.5; e onde ele diz que as integrações existentes com computer_20251124 continuam funcionando, na Claude API e no Google Cloud elas não funcionam no Claude Opus 5.5, que nessas plataformas aceita uso de computador apenas como o toolset computer_toolset_20260801 (consulte a alteração incompatível); no Amazon Bedrock, elas continuam funcionando.

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

Consulte Migrando para o Claude Opus 5 a partir do Claude Sonnet 5 para saber o que muda ao subir de classe de modelo e, em seguida, aplique Migrando a partir do Claude Opus 5.