Migrando para o Claude Opus 5

O Claude Opus 5 é uma melhoria de grande salto em relação ao Claude Opus 4.8, forte em raciocínio profundo, tarefas agênticas e de longo horizonte, e escalonamento de computação em tempo de teste. Para diferenças comportamentais e padrões de prompting específicos do modelo, consulte Prompting do Claude Opus 5.

O Claude Opus 5 é uma atualização direta (drop-in) para o Claude Opus 4.8 com o mesmo preço de $5 USD por milhão de tokens de entrada e $25 USD por milhão de tokens de saída; consulte Preços do Claude. Há duas "breaking changes" (mudanças incompatíveis) para código já em execução no Claude Opus 4.8, abordadas em Mudanças incompatíveis. O Claude Opus 5 oferece suporte ao mesmo conjunto de recursos do Claude Opus 4.8, incluindo a "context window" (janela de contexto) de 1M de tokens (o padrão, sem cabeçalho beta), 128k de tokens máximos de saída, "adaptive thinking" (pensamento adaptativo), "prompt caching" (cache de prompt), "batch processing" (processamento em lote), a Files API, suporte a PDF, "vision" (visão) e ferramentas do lado do servidor e do lado do cliente, com duas exceções: web fetch não está disponível no Claude Opus 5, e o Priority Tier não é compatível com o Claude Opus 5. Consulte a página de cada ferramenta para ver a disponibilidade por modelo.

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

Atualize o nome do seu modelo

# Migração para o Opus
model = "claude-opus-4-8"  # Before
model = "claude-opus-5"  # After

claude-opus-5 é um ID de modelo fixo sem sufixo de data, o mesmo esquema de claude-opus-4-8 e claude-sonnet-5.

Mudanças incompatíveis

1. Pensamento ativado por padrão: No Claude Opus 4.8, requisições sem um campo thinking são executadas sem pensamento; no Claude Opus 5, as mesmas requisições são executadas com pensamento adaptativo. max_tokens continua sendo um limite rígido sobre a saída total, pensamento mais texto de resposta, então revise-o para cargas de trabalho que eram executadas sem pensamento no Claude Opus 4.8. Tokens de pensamento são cobrados como tokens de saída mesmo quando o texto do pensamento não é retornado a você; portanto, embora o preço por token permaneça inalterado, uma carga de trabalho que era executada sem pensamento no Claude Opus 4.8 pode produzir mais tokens de saída por requisição no Claude Opus 5; consulte Controle de custos. Para preservar o comportamento antigo, passe thinking: {type: "disabled"}, sujeito ao limite de esforço do próximo item; observe que, com o pensamento desativado, o modelo pode ocasionalmente emitir chamadas de ferramentas como texto simples ou incluir tags XML internas em sua saída visível, então prefira níveis de esforço mais baixos com o pensamento ativado sempre que possível, e consulte Executando com o pensamento desativado para mitigações quando não for possível.

   O formato da resposta muda junto com isso. Com o pensamento ativado, uma resposta pode começar com um ou mais blocos thinking antes do primeiro bloco text e, como thinking.display tem como padrão "omitted" no Claude Opus 5, esses blocos chegam com um campo thinking vazio junto com sua signature. 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, quebra nessas 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. Para receber resumos de pensamento legíveis em vez de um campo thinking vazio, defina display: "summarized"; consulte Controlando a exibição do pensamento.

   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 tal 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 descartados com um erro 400. Consulte Preservando blocos de pensamento.

2. Desativar o pensamento é limitado ao esforço high: Você ainda pode desativar o pensamento com thinking: {type: "disabled"}, mas apenas em um nível de "effort" (esforço) high ou inferior. Uma requisição que combina thinking: {type: "disabled"} com esforço xhigh ou max retorna um erro 400. O Claude Opus 4.8 aceita essa combinação, então audite as requisições que desativam o pensamento antes de migrar.

   A verificação é aplicada em cada requisição: a configuração de esforço e pensamento de cada requisição é validada de forma independente, então uma requisição que eleva o esforço para xhigh ou max enquanto o pensamento está desativado é rejeitada mesmo que requisições anteriores na conversa tenham sido aceitas.

   Antes (aceito no Claude Opus 4.8, rejeitado no Claude Opus 5):

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

   

   Depois (Claude Opus 5), remova o campo thinking para reativar o pensamento:

   client.messages.create(
       model="claude-opus-5",
       max_tokens=16000,
       output_config={"effort": "xhigh"},  # thinking is on by default
       messages=[{"role": "user", "content": "..."}],
   )

   

   ou mantenha o pensamento desativado e reduza o esforço:

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

   

Mudanças recomendadas

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

1. Teste o esforço max para trabalhos críticos em capacidade: O Claude Opus 5 oferece suporte ao conjunto completo de níveis de esforço (low, medium, high, xhigh, max). Onde a capacidade máxima importa mais do que o gasto de tokens, teste o esforço max. Ele pode trazer ganhos nas tarefas mais exigentes, mas pode apresentar retornos decrescentes com o aumento do uso de tokens e pode ser propenso a pensar demais em tarefas mais simples. 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í.

2. Considere fallbacks automáticos: O Claude Opus 5 é lançado com classificadores de segurança de cibersegurança cujas recusas na categoria cyber podem recorrer ao Claude Opus 4.8 como fallback. Para reexecutar automaticamente requisições recusadas em outro modelo, considere o parâmetro fallbacks com o modo "default" (fallbacks: "default"), que seleciona um modelo de fallback recomendado com base na categoria da recusa em vez de uma lista de modelos mantida manualmente. O fallback do lado do servidor está em beta; o modo "default" requer o cabeçalho beta server-side-fallback-2026-07-01. Consulte Recusas e fallback.

3. Faça cache de prompts mais curtos: O comprimento mínimo de prompt armazenável em cache no Claude Opus 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 agora podem criar entradas de cache, sem necessidade de alterações no código. Consulte Cache de prompt para os mínimos por modelo.

4. Altere ferramentas no meio da conversa (beta): Você pode adicionar ou remover ferramentas entre turnos de uma conversa sem invalidar os acertos do cache de prompt em turnos anteriores. Envie o cabeçalho beta mid-conversation-tool-changes-2026-07-01. Isso é útil para cargas de trabalho agênticas que expõem ferramentas progressivamente ou as desativam à medida que uma tarefa avança; sem ele, uma lista de ferramentas alterada invalida o prefixo em cache.

5. Reajuste prompts de comprimento e verbosidade: As respostas visíveis padrão e os entregáveis escritos são mais longos no Claude Opus 5 do que no Claude Opus 4.8, e reduzir o esforço diminui o volume de pensamento sem encurtar de forma confiável a resposta visível. Em vez disso, peça explicitamente concisão ou um comprimento-alvo no prompt. Consulte Comprimento e verbosidade da resposta e Comprimento de entregáveis escritos.

6. Remova instruções de verificação herdadas e restrinja o escopo: O Claude Opus 5 verifica seu próprio trabalho sem que lhe seja pedido, então remova instruções explícitas de verificação ou autoverificação herdadas de prompts ajustados para modelos anteriores; deixá-las causa verificação excessiva. Para tarefas restritas, limite o escopo da tarefa explicitamente. Em frameworks multiagente, forneça orientação explícita sobre quais cenários justificam delegação ou limite o número de subagentes, porque o Claude Opus 5 delega com mais facilidade do que modelos anteriores. Consulte Escopo da tarefa e verificação excessiva e Controlando a criação de subagentes.

Checklist de migração

• Atualize o nome do modelo de claude-opus-4-8 para claude-opus-5.
• Revise cargas de trabalho que eram executadas sem um campo thinking: elas são executadas com pensamento no Claude Opus 5. Revise max_tokens, que continua sendo um limite rígido sobre a saída total (pensamento mais texto de resposta), ou passe thinking: {type: "disabled"} com esforço high ou inferior para preservar o comportamento antigo. Se você desativar o pensamento, revise Executando com o pensamento desativado para conhecer os artefatos de saída que podem aparecer e suas mitigações via prompt.
• Atualize a análise de respostas que lê conteúdo por posição, como content[0].text ou um manipulador de stream que assume que o primeiro bloco de conteúdo é texto: com o pensamento ativado, blocos thinking chegam antes dos blocos text. Em vez disso, selecione os blocos de conteúdo por type.
• Se você executa um loop de uso de ferramentas, passe os blocos thinking de volta completos e sem modificações ao retornar resultados de ferramentas; blocos modificados retornam um erro 400. Consulte Preservando blocos de pensamento.
• Verifique se qualquer código que analisa o campo thinking o trata apenas como texto de exibição. thinking.display tem como padrão "omitted" no Claude Opus 5, o mesmo que no Claude Opus 4.8, então os blocos de pensamento chegam com um campo thinking vazio; defina display: "summarized" para receber resumos legíveis. Consulte Controlando a exibição do pensamento.
• Audite requisições que desativam o pensamento: thinking: {type: "disabled"} com esforço xhigh ou max retorna um erro 400, aplicado em cada requisição. Reative o pensamento ou reduza o esforço para high ou inferior.
• Reavalie sua configuração de effort: execute uma nova varredura de esforço em suas próprias avaliações em vez de herdar uma configuração ajustada para um modelo anterior. Vale a pena testar os esforços low e medium como controles de custo e latência, e teste o esforço max onde a capacidade máxima importa mais do que o gasto de tokens. Se você executa com esforço xhigh ou max, aumente max_tokens para pelo menos 64k como ponto de partida.
• Revise prompts próximos ao mínimo de cache: prompts de 512 tokens ou mais agora podem criar entradas de cache, abaixo dos 1.024 tokens no Claude Opus 4.8.
• Trate stop_reason: "refusal" e considere fallbacks: "default" (beta) para reexecutar automaticamente requisições recusadas em um modelo de fallback recomendado.
• Se sua organização tem um compromisso de Priority Tier, planeje a capacidade separadamente: o Priority Tier não é compatível com o Claude Opus 5, enquanto o Claude Opus 4.8 o mantém.
• Para cargas de trabalho agênticas, considere orçamentos de tarefa (beta) e alterações de ferramentas no meio da conversa (beta).
• Reajuste prompts de comprimento e verbosidade: as respostas visíveis padrão e os entregáveis escritos são mais longos no Claude Opus 5, e reduzir o esforço diminui o volume de pensamento sem encurtar de forma confiável a resposta visível. Peça explicitamente concisão ou um comprimento-alvo no prompt. Consulte Comprimento e verbosidade da resposta e Comprimento de entregáveis escritos.
• Remova instruções de verificação e autoverificação herdadas de prompts ajustados para modelos anteriores (elas causam verificação excessiva no Claude Opus 5), restrinja o escopo da tarefa explicitamente para tarefas restritas e, em frameworks multiagente, direcione ou limite a delegação a subagentes. Consulte Escopo da tarefa e verificação excessiva e Controlando a criação de subagentes.
• Refaça a linha de base de custo e latência em suas próprias cargas de trabalho. O preço por token permanece inalterado em relação ao Claude Opus 4.8, mas tokens de pensamento são cobrados como tokens de saída, então cargas de trabalho que eram executadas sem pensamento podem produzir mais tokens de saída por requisição.

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

O Claude Opus 5 deve ter um forte desempenho imediato em prompts e avaliações existentes do Claude Opus 4.7, com o mesmo preço de $5 USD por milhão de tokens de entrada e $25 USD por milhão de tokens de saída. Ele oferece suporte ao mesmo conjunto de recursos do Claude Opus 4.7, incluindo a janela de contexto de 1M de tokens, 128k de tokens máximos de saída, pensamento adaptativo, cache de prompt, processamento em lote, a Files API, suporte a PDF, visão e ferramentas do lado do servidor e do lado do cliente, com duas exceções: web fetch não está disponível no Claude Opus 5, e o Priority Tier não é compatível com o Claude Opus 5. Ele também adiciona mensagens de sistema no meio da conversa e documenta publicamente os detalhes de parada por recusa. Na Claude API e no Google Cloud, o Claude Opus 5 também oferece suporte a computer use como o toolset estável computer_toolset_20260801 e à ferramenta de uso de navegador para tarefas dentro de páginas web, nenhum dos quais é compatível com o Claude Opus 4.7; integrações existentes na versão anterior computer_20251124 continuam funcionando sem alterações em ambos os modelos. Para atualizar uma integração existente, consulte Migrar de computer_20251124.

Atualize o nome do seu modelo

# Migração para o Opus
model = "claude-opus-4-7"  # Before
model = "claude-opus-5"  # After

Mudanças incompatíveis

1. Pensamento ativado por padrão: No Claude Opus 4.7, requisições sem um campo thinking são executadas sem pensamento; no Claude Opus 5, as mesmas requisições são executadas com pensamento adaptativo. max_tokens continua sendo um limite rígido sobre a saída total, pensamento mais texto de resposta, então revise-o para cargas de trabalho que eram executadas sem pensamento no Claude Opus 4.7. Tokens de pensamento são cobrados como tokens de saída mesmo quando o texto do pensamento não é retornado a você; portanto, embora o preço por token permaneça inalterado, uma carga de trabalho que era executada sem pensamento no Claude Opus 4.7 pode produzir mais tokens de saída por requisição no Claude Opus 5; consulte Controle de custos. Para preservar o comportamento antigo, passe thinking: {type: "disabled"}, sujeito ao limite de esforço do próximo item; observe que, com o pensamento desativado, o modelo pode ocasionalmente emitir chamadas de ferramentas como texto simples ou incluir tags XML internas em sua saída visível, então prefira níveis de esforço mais baixos com o pensamento ativado sempre que possível, e consulte Executando com o pensamento desativado para mitigações quando não for possível.

   O formato da resposta muda junto com isso. Com o pensamento ativado, uma resposta pode começar com um ou mais blocos thinking antes do primeiro bloco text e, como thinking.display tem como padrão "omitted" no Claude Opus 5, esses blocos chegam com um campo thinking vazio junto com sua signature. 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, quebra nessas 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. Para receber resumos de pensamento legíveis em vez de um campo thinking vazio, defina display: "summarized"; consulte Controlando a exibição do pensamento.

   Se você executa um loop de 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 tal 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 descartados com um erro 400. Consulte Preservando blocos de pensamento.

2. Desativar o pensamento é limitado ao esforço high: Você pode desativar o pensamento com thinking: {type: "disabled"}, mas apenas em um nível de esforço high ou inferior. Uma requisição que combina thinking: {type: "disabled"} com esforço xhigh ou max retorna um erro 400. O Claude Opus 4.7 aceita essa combinação, então audite as requisições que desativam o pensamento antes de migrar.

   A verificação é aplicada em cada requisição: a configuração de esforço e pensamento de cada requisição é validada de forma independente, então uma requisição que eleva o esforço para xhigh ou max enquanto o pensamento está desativado é rejeitada mesmo que requisições anteriores na conversa tenham sido aceitas.

   Antes (aceito no Claude Opus 4.7, rejeitado no Claude Opus 5):

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

   

   Depois (Claude Opus 5), remova o campo thinking para executar com pensamento:

   client.messages.create(
       model="claude-opus-5",
       max_tokens=16000,
       output_config={"effort": "xhigh"},  # thinking is on by default
       messages=[{"role": "user", "content": "..."}],
   )

   

   ou mantenha o pensamento desativado e reduza o esforço:

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

   

O que mudou

Os itens a seguir não são mudanças incompatíveis; eles descrevem diferenças de comportamento que vale a pena verificar depois de trocar o ID do modelo.

1. Parâmetros de amostragem (inalterados): Definir temperature, top_p ou top_k com um valor diferente do padrão retorna um erro 400 no Claude Opus 5, o mesmo que no Claude Opus 4.7. A maioria dos SDKs ainda define esses campos para compatibilidade com modelos anteriores, então código que os define passa na verificação de tipos mesmo que a API rejeite a requisição. O SDK Python (v1.0 e posterior) não os define, e passá-los gera um TypeError. Se você removeu esses parâmetros ao migrar para o Opus 4.7, nenhuma alteração adicional é necessária.

2. O padrão de esforço é high: O padrão do parâmetro effort no Claude Opus 5 é high na Claude API e no Claude Code. Se você já define o esforço explicitamente, sua configuração permanece inalterada.

3. 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 em comparação com o Claude Opus 4.7, e o Claude Opus 5 oferece suporte ao conjunto completo de níveis de esforço (low, medium, high, xhigh, max). Execute uma nova varredura de esforço em suas próprias avaliações em vez de herdar uma configuração ajustada para o Claude Opus 4.7. Vale a pena testar os esforços low e medium como controles de custo e latência, e teste o esforço max onde a capacidade máxima importa mais do que o gasto de tokens. 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í. Consulte Esforço.

4. A janela de contexto de 1M é o padrão: O Claude Opus 5 serve a janela de contexto completa de 1M de tokens por padrão, sem cabeçalho beta e sem adicional de contexto longo. Se o seu cliente passa um cabeçalho beta de janela de contexto para compatibilidade com modelos mais antigos, você pode removê-lo no Claude Opus 5.

5. Mensagens de sistema no meio da conversa: O Claude Opus 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 do cache de prompt em turnos anteriores.

6. Detalhes de parada por recusa: O objeto stop_details em respostas de recusa (disponível desde o Claude Opus 4.7) agora está documentado publicamente. Quando o modelo recusa uma requisição, ele identifica a categoria da recusa, além do stop reason refusal existente. Nenhum cabeçalho beta é necessário, e não há como desativar. Consulte Tratando stop reasons.

7. Mínimo de cache de prompt mais baixo: O comprimento mínimo de prompt armazenável em cache no Claude Opus 5 é de 512 tokens, menor do que no Claude Opus 4.7. Prompts que eram curtos demais para cache no Claude Opus 4.7 agora podem criar entradas de cache, sem necessidade de alterações no código. Consulte Cache de prompt para os mínimos por modelo.

8. Fast mode: O Claude Opus 5 oferece suporte ao "fast mode" (modo rápido) (prévia de pesquisa); o fast mode não está disponível no Claude Opus 4.7, onde requisições com speed: "fast" retornam um erro. O parâmetro speed: "fast" e o cabeçalho beta fast-mode-2026-02-01 funcionam sem alterações no Claude Opus 5.

Mudanças recomendadas

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

1. Considere fallbacks automáticos: O Claude Opus 5 é lançado com classificadores de segurança de cibersegurança cujas recusas na categoria cyber podem recorrer ao Claude Opus 4.8 como fallback. Para reexecutar automaticamente requisições recusadas em outro modelo, considere o parâmetro fallbacks com o modo "default" (fallbacks: "default"), que seleciona um modelo de fallback recomendado com base na categoria da recusa em vez de uma lista de modelos mantida manualmente. O fallback do lado do servidor está em beta; o modo "default" requer o cabeçalho beta server-side-fallback-2026-07-01. Consulte Recusas e fallback.

2. Altere ferramentas no meio da conversa (beta): Você pode adicionar ou remover ferramentas entre turnos de uma conversa sem invalidar os acertos do cache de prompt em turnos anteriores. Envie o cabeçalho beta mid-conversation-tool-changes-2026-07-01. Isso é útil para cargas de trabalho agênticas que expõem ferramentas progressivamente ou as desativam à medida que uma tarefa avança; sem ele, uma lista de ferramentas alterada invalida o prefixo em cache.

3. Reajuste prompts de comprimento e verbosidade: As respostas visíveis padrão e os entregáveis escritos são mais longos no Claude Opus 5 do que em modelos Opus anteriores, e reduzir o esforço diminui o volume de pensamento sem encurtar de forma confiável a resposta visível. Em vez disso, peça explicitamente concisão ou um comprimento-alvo no prompt. Consulte Comprimento e verbosidade da resposta e Comprimento de entregáveis escritos.

4. Remova instruções de verificação herdadas e restrinja o escopo: O Claude Opus 5 verifica seu próprio trabalho sem que lhe seja pedido, então remova instruções explícitas de verificação ou autoverificação herdadas de prompts ajustados para modelos anteriores; deixá-las causa verificação excessiva. Para tarefas restritas, limite o escopo da tarefa explicitamente. Em frameworks multiagente, forneça orientação explícita sobre quais cenários justificam delegação ou limite o número de subagentes, porque o Claude Opus 5 delega com mais facilidade do que modelos anteriores. Consulte Escopo da tarefa e verificação excessiva e Controlando a criação de subagentes.

Checklist de migração

• Atualize o nome do modelo de claude-opus-4-7 para claude-opus-5 (ou atualize os aliases).
• Revise cargas de trabalho que eram executadas sem um campo thinking: elas são executadas com pensamento no Claude Opus 5. Revise max_tokens, que continua sendo um limite rígido sobre a saída total (pensamento mais texto de resposta), ou passe thinking: {type: "disabled"} com esforço high ou inferior para preservar o comportamento antigo. Se você desativar o pensamento, revise Executando com o pensamento desativado para conhecer os artefatos de saída que podem aparecer e suas mitigações via prompt.
• Atualize a análise de respostas que lê conteúdo por posição, como content[0].text ou um manipulador de stream que assume que o primeiro bloco de conteúdo é texto: com o pensamento ativado, blocos thinking chegam antes dos blocos text. Em vez disso, selecione os blocos de conteúdo por type.
• Se você executa um loop de uso de ferramentas, passe os blocos thinking de volta completos e sem modificações ao retornar resultados de ferramentas; blocos modificados retornam um erro 400. Consulte Preservando blocos de pensamento.
• Verifique se qualquer código que analisa o campo thinking o trata apenas como texto de exibição. thinking.display tem como padrão "omitted" no Claude Opus 5, o mesmo que no Claude Opus 4.7, então os blocos de pensamento chegam com um campo thinking vazio; defina display: "summarized" para receber resumos legíveis. Consulte Controlando a exibição do pensamento.
• Audite requisições que desativam o pensamento: thinking: {type: "disabled"} com esforço xhigh ou max retorna um erro 400, aplicado em cada requisição. Reative o pensamento ou reduza o esforço para high ou inferior.
• Se você removeu os parâmetros de amostragem durante a migração para o Opus 4.7, nenhuma ação é necessária. Se você os adicionou novamente com um caminho de nova tentativa em caso de 400, remova esse caminho de nova tentativa.
• Reavalie sua configuração de effort: execute uma nova varredura de esforço em suas próprias avaliações em vez de herdar uma configuração ajustada para o Claude Opus 4.7. Teste os esforços low e medium como controles de custo e latência, e o esforço max onde a capacidade máxima importa mais do que o gasto de tokens. Se você executa com esforço xhigh ou max, aumente max_tokens para pelo menos 64k como ponto de partida.
• Remova qualquer cabeçalho beta de janela de contexto. A janela de contexto de 1M é o padrão na Claude API, no Amazon Bedrock, no Google Cloud e no Microsoft Foundry.
• 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 do cache de prompt.
• Verifique se o seu tratamento de stop reason lê stop_details em recusas (disponível desde o Claude Opus 4.7; agora documentado publicamente) e considere fallbacks: "default" (beta) para reexecutar automaticamente requisições recusadas em um modelo de fallback recomendado.
• Revise prompts próximos ao mínimo de cache: prompts de 512 tokens ou mais agora podem criar entradas de cache.
• Se você usa web fetch, planeje uma alternativa: ele não está disponível no Claude Opus 5.
• Se sua organização tem um compromisso de Priority Tier, observe que o Priority Tier não é compatível com o Claude Opus 5.
• Se você usava o fast mode no Claude Opus 4.7, nenhuma alteração de requisição é necessária além do ID do modelo: speed: "fast" e o cabeçalho beta fast-mode-2026-02-01 funcionam sem alterações no Claude Opus 5.
• Para cargas de trabalho agênticas, considere orçamentos de tarefa (beta) e alterações de ferramentas no meio da conversa (beta).
• Reajuste prompts de comprimento e verbosidade e remova instruções de verificação e autoverificação herdadas de prompts ajustados para modelos anteriores.
• Refaça a linha de base de custo e latência no nível de esforço escolhido. O preço por token permanece inalterado em relação ao Claude Opus 4.7, mas tokens de pensamento são cobrados como tokens de saída, então cargas de trabalho que eram executadas sem pensamento podem produzir mais tokens de saída por requisição.

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

O Claude Opus 5 deve ter um forte desempenho imediato em prompts e avaliações existentes do Claude Opus 4.6 com o mesmo preço, mas há algumas mudanças comportamentais e de API que vale a pena conhecer ao migrar. A maioria dessas mudanças entrou em vigor no Claude Opus 4.7; outras duas, pensamento ativado por padrão e um limite de esforço para desativar o pensamento, entram em vigor no Claude Opus 5. Todas elas são abordadas nesta seção, portanto ela é completa para código vindo diretamente do Claude Opus 4.6. O Claude Opus 5 oferece suporte ao mesmo conjunto de recursos do Claude Opus 4.6, incluindo:

• Janela de contexto de 1M de tokens com preço padrão da API, sem adicional de contexto longo
• 128k de tokens máximos de saída
• Pensamento adaptativo
• Cache de prompt
• Processamento em lote
• Files API
• Suporte a PDF
• Visão
• Ferramentas do lado do servidor e do lado do cliente (bash, execução de código, computer use, editor de texto, busca na web, conector MCP, memória)

Duas exceções: web fetch não está disponível no Claude Opus 5, e o Priority Tier não é compatível com o Claude Opus 5. Na Claude API e no Google Cloud, o Claude Opus 5 também oferece suporte a computer use como o toolset estável computer_toolset_20260801 e à ferramenta de uso de navegador para tarefas dentro de páginas web, nenhum dos quais é compatível com o Claude Opus 4.6 ou modelos Opus anteriores; integrações existentes na versão anterior computer_20251124 continuam funcionando sem alterações no Claude Opus 5. Para atualizar uma integração existente, consulte Migrar de computer_20251124.

Atualize o nome do seu modelo

# Migração para o Opus
model = "claude-opus-4-6"  # Before
model = "claude-opus-5"  # After

Mudanças incompatíveis

1. Pensamento estendido removido: thinking: {type: "enabled", budget_tokens: N} não é mais suportado no Claude Opus 4.7 ou modelos posteriores e retorna um erro 400. Mude para o pensamento adaptativo (thinking: {type: "adaptive"}) e use o parâmetro effort para controlar a profundidade do pensamento. No Claude Opus 5, o pensamento adaptativo está ativado por padrão: thinking: {type: "adaptive"} é válido e equivalente a omitir o campo thinking completamente (veja o próximo item).

   Antes (Claude Opus 4.6):

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

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

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

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

   O pensamento adaptativo é direcionável por meio de prompts e do parâmetro effort; consulte Escolhendo um nível de esforço.

2. Pensamento ativado por padrão: No Claude Opus 4.6 e no Claude Opus 4.7, requisições sem um campo thinking são executadas sem pensamento; no Claude Opus 5, as mesmas requisições são executadas com pensamento adaptativo. max_tokens continua sendo um limite rígido sobre a saída total, pensamento mais texto de resposta, portanto 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ê; portanto, embora o preço por token permaneça inalterado, uma carga de trabalho que era executada sem pensamento pode produzir mais tokens de saída por requisição no Claude Opus 5; consulte Controle de custos. Para preservar o comportamento antigo, passe thinking: {type: "disabled"}, sujeito ao limite de esforço do próximo item; observe que, com o pensamento desativado, o modelo pode ocasionalmente emitir chamadas de ferramentas como texto simples ou incluir tags XML internas em sua saída visível, portanto prefira níveis de esforço mais baixos com o pensamento ativado sempre que possível, e consulte Executando com o pensamento desativado para mitigações quando não for possível.

   O formato da resposta muda junto com isso. Com o pensamento ativado, uma resposta pode começar com um ou mais blocos thinking antes do primeiro bloco text e, como o conteúdo do pensamento é omitido por padrão no Claude Opus 5 (item 5 desta lista), esses blocos chegam com um campo thinking vazio junto com sua signature. 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, quebra nessas 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.

   Se você executa um loop de uso de ferramentas, passe os blocos thinking de cada resposta do assistente de volta à API completos e sem modificações ao retornar resultados de 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 descartados com um erro 400. Consulte Preservando blocos de pensamento.

3. Desativar o pensamento é limitado ao esforço high: Você pode desativar o pensamento com thinking: {type: "disabled"}, mas apenas em um nível de esforço high ou inferior. Uma requisição que combina thinking: {type: "disabled"} com esforço xhigh ou max retorna um erro 400 no Claude Opus 5, aplicado em cada requisição. Audite as requisições que desativam o pensamento antes de migrar: reative o pensamento ou reduza o esforço para high ou inferior.

4. Parâmetros de amostragem removidos: Definir temperature, top_p ou top_k com qualquer valor diferente do padrão no Claude Opus 4.7 ou modelos posteriores, incluindo o Claude Opus 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 esses parâmetros completamente dos payloads das requisições. O uso de prompts é a forma recomendada de orientar o comportamento do modelo no Claude Opus 5. Se você usava temperature = 0 para determinismo, observe que isso nunca garantiu saídas idênticas nos modelos anteriores.

5. Conteúdo do pensamento omitido por padrão: Os blocos de pensamento ainda aparecem no stream de resposta no Claude Opus 4.7 e modelos posteriores, mas seu campo thinking fica vazio, a menos que você opte explicitamente por recebê-lo. Esta é uma mudança silenciosa em relação ao Claude Opus 4.6, onde o padrão era retornar o texto de pensamento resumido. Para restaurar o conteúdo de pensamento resumido, defina thinking.display como "summarized":

   PythonTypeScriptC#GoJavaPHPRuby

   

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

   O padrão é "omitted" no Claude Opus 4.7 e modelos posteriores. Se o seu produto transmite o raciocínio aos usuários via streaming, o novo 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 para detalhes.

6. Contagem de tokens atualizada: O Claude Opus 4.7 introduziu um novo tokenizador, que os modelos Opus posteriores, incluindo o Claude Opus 5, também usam. Ele contribui para um desempenho melhor em uma ampla gama de tarefas e pode usar aproximadamente de 1x a 1,35x mais tokens ao processar texto em comparação com 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 do que retornava para o Claude Opus 4.6. A eficiência de tokens pode variar conforme o formato da carga de trabalho.

   Intervenções de prompt, task_budget e effort podem ajudar a controlar custos e garantir o uso apropriado de tokens. Esses controles podem ter como contrapartida a inteligência do modelo. Atualize seus parâmetros max_tokens para dar margem adicional, incluindo gatilhos de compactação. O Claude Opus 5 oferece uma "context window" (janela de contexto) de 1M ao preço padrão da API, sem adicional por contexto longo.

7. Remoção do prefill (herdada do Opus 4.6): O preenchimento prévio (prefill) de mensagens do assistente retorna um erro 400 no Claude Opus 4.7 e modelos posteriores, incluindo o Claude Opus 5. Use saídas estruturadas, instruções no prompt do sistema ou output_config.format em vez disso.

Escolhendo um nível de esforço

O parâmetro effort permite ajustar a inteligência do Claude em relação ao gasto de tokens, trocando capacidade por maior velocidade e custos menores. O Claude Opus 5 suporta o conjunto completo de níveis de esforço e tem high como padrão. Execute uma nova varredura de esforço em suas próprias avaliações em vez de reaproveitar uma configuração ajustada para um modelo anterior:

• max: Pode trazer ganhos nas tarefas mais exigentes, mas pode apresentar retornos decrescentes com o aumento do uso de tokens e pode ser propenso a pensar demais em tarefas mais simples. Teste-o onde a capacidade máxima importa mais do que o gasto de tokens.
• xhigh: Capacidade estendida para trabalhos agênticos e de codificação de longa duração que precisam de mais profundidade do que o padrão.
• high: O padrão. Equilibra uso de tokens e inteligência para a maioria das tarefas.
• medium: Um degrau abaixo do padrão para economia de custos, vale a pena testar como controle de custo e latência.
• low: O mais eficiente. Reserve para tarefas curtas e bem delimitadas e cargas de trabalho sensíveis à latência.

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í. O esforço é mais importante para este modelo do que para qualquer Opus anterior. Experimente com ele ativamente ao fazer o upgrade.

Mudanças de comportamento

O Claude Opus 4.7 introduziu várias diferenças comportamentais em relação ao Claude Opus 4.6 que não são mudanças incompatíveis de API, mas podem exigir atualizações de prompt ou remoção de scaffolding. Elas se mantêm no Claude Opus 5, com os ajustes observados nesta lista.

1. O comprimento da resposta varia conforme o caso de uso: O Claude Opus 4.7 calibra o comprimento da resposta de acordo com o quão complexa ele julga ser a tarefa, em vez de adotar uma verbosidade fixa por padrão. Isso geralmente significa respostas mais curtas em consultas simples e muito mais longas em análises abertas.

   Se o seu produto depende de um certo estilo ou verbosidade de saída, talvez você precise ajustar seus prompts. Por exemplo, para diminuir a verbosidade, adicione: "Forneça respostas concisas e focadas. Pule o contexto não essencial e mantenha os exemplos mínimos." Se você observar tipos específicos de explicação excessiva, adicione instruções direcionadas no seu prompt para evitá-los.

   Exemplos positivos mostrando como o Claude pode se comunicar com o nível apropriado de concisão tendem a ser mais eficazes do que exemplos negativos ou instruções que dizem ao modelo o que não fazer. No Claude Opus 5, as respostas visíveis padrão e os entregáveis escritos são mais longos do que nos modelos Opus anteriores, e reduzir o esforço diminui o volume de pensamento sem encurtar de forma confiável a resposta visível; peça explicitamente no prompt por concisão ou um comprimento-alvo. Consulte Comprimento da resposta e verbosidade.

2. Seguimento de instruções mais literal: O Claude Opus 4.7 interpreta prompts de forma mais literal e explícita do que o Claude Opus 4.6, particularmente em níveis de esforço mais baixos. Ele não generaliza silenciosamente uma instrução de um item para outro e não infere solicitações que você não fez. A vantagem desse literalismo é a precisão e menos idas e vindas. Ele geralmente tem melhor desempenho em casos de uso de API com prompts cuidadosamente ajustados, extração estruturada e pipelines onde você deseja comportamento previsível. Uma revisão de prompts e do harness pode ser especialmente útil para a migração para o Claude Opus 5.

3. Tom mais direto: Como acontece com qualquer novo modelo, o estilo de prosa em textos longos pode mudar. O Claude Opus 4.7 é mais direto e opinativo, com menos frases voltadas à validação e menos emojis do que o estilo mais caloroso do Claude Opus 4.6. Se o seu produto depende de uma voz específica, reavalie os prompts de estilo em relação à nova linha de base.

4. 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 scaffolding para forçar mensagens de status intermediárias ("Após cada 3 chamadas de ferramentas, resuma o progresso"), tente removê-lo. Se você achar que o comprimento ou o conteúdo das atualizações voltadas ao usuário do Claude Opus 4.7 não estão bem calibrados para o seu caso de uso, descreva explicitamente no prompt como essas atualizações devem ser e forneça exemplos.

5. Criação de subagentes alterada: O Claude Opus 4.7 tende a criar menos subagentes por padrão do que o Claude Opus 4.6, enquanto o Claude Opus 5 delega a subagentes mais prontamente do que os modelos anteriores. O comportamento é direcionável por meio de prompts em qualquer direção; dê orientações explícitas sobre quando subagentes são desejáveis ou limite o número de subagentes. Consulte Controlando a criação de subagentes.

6. Calibração de esforço mais rigorosa: Em uma mudança significativa em relação ao Claude Opus 4.6, o Claude Opus 4.7 respeita os níveis de esforço rigorosamente, especialmente na extremidade inferior. Em low e medium, o modelo delimita seu trabalho ao que foi pedido, em vez de fazer mais do que o solicitado.

   Isso é bom para latência e custo, mas em tarefas moderadamente complexas executadas com esforço low há algum risco de pensar de menos. Se você observar raciocínio superficial em problemas complexos, aumente o esforço para high ou xhigh em vez de contornar isso com prompts.

   Se você precisa manter o esforço em low por causa da latência, adicione orientações direcionadas: "Esta tarefa envolve raciocínio em várias etapas. Pense cuidadosamente no problema antes de responder." Consulte Níveis de esforço recomendados para o Claude Opus 4.7.

7. Menos chamadas de ferramentas por padrão: O Claude Opus 4.7 tende a usar ferramentas com menos frequência do que o Claude Opus 4.6 e a usar mais o raciocínio. Isso produz melhores resultados na maioria dos casos.

   Para aumentar o uso de ferramentas, aumente a configuração de esforço. As configurações de esforço high ou xhigh mostram substancialmente mais uso de ferramentas em busca agêntica e codificação. Você também pode ajustar seu prompt para instruir explicitamente o modelo sobre quando e como usar suas ferramentas adequadamente.

8. Salvaguardas de cibersegurança em tempo real: Recém-adicionadas no Claude Opus 4.7, requisições que envolvem 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. O caminho de inscrição depende de como você acessa o Claude.

9. 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 na borda mais longa, acima dos 1.568 pixels dos modelos anteriores. Isso libera 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.

Mudanças recomendadas

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

1. Reavalie max_tokens: Como o mesmo texto produz uma contagem de tokens maior no Claude Opus 4.7 e modelos posteriores, atualize seus parâmetros max_tokens para dar margem adicional, incluindo gatilhos de compactação. Intervenções de prompt, task_budget e effort podem ajudar a controlar custos e garantir o uso apropriado de tokens.

2. Audite as expectativas de contagem de tokens: Qualquer caminho de código que estime tokens do lado do cliente ou assuma uma proporção fixa de tokens por caractere deve ser testado novamente com o Claude Opus 5. Use o endpoint de contagem de tokens para verificar.

3. Adote orçamentos de tarefa (beta): O Claude Opus 4.7 introduz os "task budgets" (orçamentos de tarefa). Esses orçamentos permitem informar ao Claude quantos tokens ele tem para um loop agêntico completo, incluindo pensamento, chamadas de ferramentas, resultados de ferramentas e saída final. O modelo vê uma contagem regressiva contínua e a usa para priorizar o trabalho e concluir a tarefa de forma adequada à medida que o orçamento é consumido. Para usar, defina o cabeçalho beta task-budgets-2026-03-13 e adicione o seguinte à sua configuração de saída:

   PythonTypeScriptC#GoJavaPHPRuby

   

   output_config = {
       "effort": "high",
       "task_budget": {"type": "tokens", "total": 128000},
   }

   Talvez você precise experimentar diferentes orçamentos de tarefa para o seu caso de uso. Se o modelo receber um orçamento de tarefa muito restritivo, ele pode concluir a tarefa de forma menos completa, citando seu orçamento como a restrição.

   Para tarefas agênticas abertas em que a qualidade importa mais do que a velocidade, não defina um orçamento de tarefa. Reserve os orçamentos de tarefa para cargas de trabalho em que você precisa que o modelo delimite seu trabalho a uma cota de tokens. O valor mínimo para um orçamento de tarefa é de 20k tokens.

   Um orçamento de tarefa não é um limite rígido; é uma sugestão da qual o modelo está ciente. Ele difere de max_tokens:

   • task_budget: um limite consultivo ao longo de todo o loop agêntico. O modelo o vê e o usa para dosar seu ritmo.
   • max_tokens: um teto rígido por requisição sobre os tokens gerados. Ele não é passado ao modelo, portanto o modelo não está ciente dele.

   Use task_budget quando quiser que o modelo se automodere, e max_tokens como um teto rígido para limitar o uso.

4. Defina um max_tokens grande com esforço max ou xhigh: Se você está executando o Claude Opus 4.7 ou um modelo posterior com esforço max ou xhigh, defina um orçamento grande de tokens máximos de saída para que o modelo tenha espaço para pensar e agir em seus subagentes e chamadas de ferramentas. Comece com 64k tokens e ajuste a partir daí.

5. Reduza a resolução das imagens se a alta resolução for desnecessária: O Claude Opus 4.7 e modelos posteriores suportam imagens de até 2576px / 3,75MP. Imagens de alta resolução usam mais tokens. Se a fidelidade adicional da imagem for desnecessária, reduza a resolução das imagens antes de enviá-las ao Claude para evitar aumentos no uso de tokens. Consulte Imagens e visão.

6. Considere fallbacks automáticos: O Claude Opus 5 é lançado com classificadores de segurança de cibersegurança cujas recusas na categoria cyber podem recorrer ao Claude Opus 4.8 como fallback. Para reexecutar automaticamente requisições recusadas em outro modelo, considere o parâmetro fallbacks com o modo "default" (fallbacks: "default"), que seleciona um modelo de fallback recomendado com base na categoria da recusa, em vez de uma lista de modelos mantida manualmente. O fallback do lado do servidor está em beta; o modo "default" requer o cabeçalho beta server-side-fallback-2026-07-01. Consulte Recusas e fallback.

7. Faça cache de prompts mais curtos: O comprimento mínimo de prompt que pode ser armazenado em cache no Claude Opus 5 é de 512 tokens, menor do que nos modelos Opus anteriores. Prompts que eram curtos demais para cache agora podem criar entradas de cache, sem necessidade de alterações no código. Consulte Cache de prompt para os mínimos por modelo.

8. Altere ferramentas no meio da conversa (beta): Você pode adicionar ou remover ferramentas entre turnos de uma conversa sem invalidar os acertos do cache de prompt em turnos anteriores. Envie o cabeçalho beta mid-conversation-tool-changes-2026-07-01. Isso é útil para cargas de trabalho agênticas que expõem ferramentas progressivamente ou as desativam à medida que uma tarefa avança; sem ele, uma lista de ferramentas alterada invalida o prefixo em cache.

9. Remova instruções de verificação herdadas e restrinja o escopo: O Claude Opus 5 verifica seu próprio trabalho sem que lhe seja pedido, portanto remova instruções explícitas de verificação ou autoverificação herdadas de prompts ajustados para modelos anteriores; deixá-las causa verificação excessiva. Para tarefas restritas, delimite o escopo da tarefa explicitamente. Consulte Escopo da tarefa e verificação excessiva.

Checklist de migração

• Atualize o nome do modelo de claude-opus-4-6 para claude-opus-5 (ou atualize os aliases).
• Remova temperature, top_p e top_k dos payloads das requisiçõ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á ativado por padrão no Claude Opus 5.
• Revise as cargas de trabalho que eram executadas sem um campo thinking: elas são executadas com pensamento no Claude Opus 5. Revise max_tokens, que continua sendo um limite rígido sobre a saída total (pensamento mais texto de resposta), ou passe thinking: {type: "disabled"} com esforço high ou inferior para preservar o comportamento antigo.
• Atualize a análise de respostas que lê o conteúdo por posição, como content[0].text ou um manipulador de stream que assume que o primeiro bloco de conteúdo é texto: com o pensamento ativado, os blocos thinking chegam antes dos blocos text. Em vez disso, selecione os blocos de conteúdo por type.
• Se você executa um loop de uso de ferramentas, passe os blocos thinking de volta completos e sem modificações ao retornar resultados de ferramentas; blocos modificados retornam um erro 400. Consulte Preservando blocos de pensamento.
• Audite as requisições que desativam o pensamento: thinking: {type: "disabled"} com esforço xhigh ou max retorna um erro 400, aplicado em cada requisição. Reative o pensamento ou reduza o esforço para high ou inferior.
• Remova quaisquer prefills de mensagens do assistente.
• Se a 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 sob a tokenização atualizada; tokens de pensamento são cobrados como tokens de saída, portanto cargas de trabalho que eram executadas sem pensamento também podem produzir mais tokens de saída por requisição.
• Reajuste max_tokens para levar em conta a tokenização atualizada.
• Teste novamente quaisquer estimativas de contagem de tokens do lado do cliente.
• Se a 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 precisa 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 modelos posteriores.
• Revise os prompts quanto às mudanças de comportamento (comprimento da resposta, literalismo, tom, atualizações de progresso, subagentes, calibração de esforço, acionamento de ferramentas, salvaguardas cyber, tratamento de imagens de alta resolução).
• Refaça a linha de base do comprimento da resposta com os prompts de controle de comprimento existentes removidos e, em seguida, ajuste explicitamente.
• Se estiver usando esforço xhigh ou max, aumente max_tokens para pelo menos 64k como ponto de partida.
• Considere adotar orçamentos de tarefa (beta) e alterações de ferramentas no meio da conversa (beta) para fluxos de trabalho agênticos.
• Trate stop_reason: "refusal" e considere fallbacks: "default" (beta) para reexecutar automaticamente requisições recusadas em um modelo de fallback recomendado.
• Revise os prompts próximos ao mínimo de cache: prompts de 512 tokens ou mais agora podem criar entradas de cache no Claude Opus 5.
• Se você usa web fetch, planeje uma alternativa: ele não está disponível no Claude Opus 5.
• Se a sua organização tem um compromisso de Priority Tier, observe que o Priority Tier não é suportado no Claude Opus 5.
• Remova instruções de verificação e autoverificação herdadas de prompts ajustados para modelos anteriores; elas causam verificação excessiva no Claude Opus 5.
• Se o seu produto realiza trabalho de segurança legítimo, inscreva-se no Cyber Verification Program para ter acesso a restrições menores sobre conteúdo cyber.

Migrando do Claude Opus 4.5 ou anterior

Se você está migrando do Claude Opus 4.5, Opus 4.1 ou um modelo anterior diretamente para o Claude Opus 5, aplique todas as mudanças anteriores desta seção mais as seguintes mudanças cumulativas, que entraram em vigor entre o Opus 4.5 e o Opus 4.7. Se você está migrando do Opus 4.6, as mudanças anteriores desta seção são tudo o que você precisa.

Atualize o nome do seu modelo

# Migração para o Opus
model = "claude-opus-4-5"  # Before
model = "claude-opus-5"  # After

Mudanças incompatíveis

1. A remoção do prefill é abordada nas mudanças incompatíveis para migração 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

Estas mudanças melhoram sua experiência no Claude Opus 4.7 e modelos posteriores. Os itens marcados como (obrigatório no Opus 4.7) eram recomendações opcionais quando o Opus 4.6 foi lançado, mas agora são obrigatórios; os demais continuam recomendados.

1. Migre para o pensamento adaptativo (obrigatório no Opus 4.7): thinking: {type: "enabled", budget_tokens: N} retorna um erro 400 no Claude Opus 4.7 e modelos posteriores. Mude para thinking: {type: "adaptive"} e use o parâmetro effort para controlar a profundidade do pensamento; no Claude Opus 5, thinking: {type: "adaptive"} é equivalente a omitir o campo thinking, o que executa com pensamento adaptativo por padrão. Consulte Pensamento.

   cURLBeforeAfterCLITypeScriptC#GoJavaPHPRuby

   

   response = client.beta.messages.create(
       model="claude-opus-4-5",
       max_tokens=16000,
       thinking={"type": "enabled", "budget_tokens": 32000},
       betas=["interleaved-thinking-2025-05-14"],
       messages=[{"role": "user", "content": "Your prompt here"}],
   )

   Observe que a migração também passa de client.beta.messages.create para client.messages.create. O pensamento adaptativo e o esforço não requerem 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 betas=["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 betas=["fine-grained-tool-streaming-2025-05-14"] das suas requisições.

4. Remova o cabeçalho beta de pensamento intercalado: O pensamento adaptativo ativa automaticamente o pensamento intercalado no Claude Opus 4.7, Opus 4.6 e Sonnet 4.6. Remova betas=["interleaved-thinking-2025-05-14"] das suas requisições. O cabeçalho ainda funciona no Sonnet 4.6 com pensamento estendido manual, mas o modo manual está descontinuado.

5. Migre para output_config.format: Se estiver usando saídas estruturadas, atualize output_format={...} para output_config={"format": {...}}. A API ainda aceita o parâmetro descontinuado output_format, mas ele será removido em um lançamento de modelo futuro. O SDK Python (v1.0 e posteriores) não aceita output_format={...} em client.beta.messages.create() ou 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 Opus 4.1 ou modelos anteriores diretamente para o Claude Opus 5, aplique todas as mudanças anteriores desta seção, mais as mudanças adicionais desta subseção.

# Do Opus 4.1
model = "claude-opus-4-1-20250805"  # Before
model = "claude-opus-5"  # After

# Do Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # Before
model = "claude-opus-5"  # After

Mudanças incompatíveis adicionais

1. Remova os parâmetros de amostragem

   A partir do Claude Opus 4.7, definir temperature, top_p ou top_k com qualquer valor diferente do padrão 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 esses parâmetros completamente das requisições e usar prompts para orientar o comportamento do modelo. Se você usava temperature = 0 para determinismo, observe que isso nunca garantiu saídas idênticas.

   PythonTypeScriptC#GoJavaPHPRuby

   

   # Antes - Isso causará erro nos modelos Claude 4+
   response = client.messages.create(
       model="claude-3-7-sonnet-20250219",
       temperature=0.7,
       top_p=0.9,  # Non-default sampling params return 400 on Opus 4.7
       # ...
   )
   
   # Depois
   response = client.messages.create(
       model="claude-opus-5",
       # ...
   )

2. Atualize as versões das ferramentas

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

   PythonTypeScriptC#GoJavaPHPRuby

   

   # 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 detalhes.
   • Execução de código: Faça o upgrade para code_execution_20260521. Consulte a documentação da ferramenta de execução de código para instruções de migração.

3. Trate o motivo de parada refusal

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

   PythonTypeScriptC#GoJavaPHPRuby

   

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

4. Trate o motivo de parada model_context_window_exceeded

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

   PythonTypeScriptC#GoJavaPHPRuby

   

   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+ 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 os parâmetros de chamadas de ferramentas, verifique se sua lógica trata corretamente as quebras de linha finais.

6. Atualize seus prompts para as mudanças comportamentais

   Os modelos Claude 4+ têm um estilo de comunicação mais conciso e direto e exigem direcionamento explícito. Revise as melhores práticas de prompts para 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+ têm uso de ferramentas eficiente em tokens integrado e esses cabeçalhos não têm efeito.

Checklist de migração (a partir do Claude Opus 4.5 ou anterior)

• Atualize o ID do modelo para claude-opus-5
• Aplique todas as mudanças incompatíveis para migração a partir do Claude Opus 4.6 (pensamento estendido removido, pensamento ativado por padrão, limite de esforço ao desativar o pensamento, parâmetros de amostragem removidos, exibição do pensamento omitida por padrão, tokenização atualizada)
• INCOMPATÍVEL: Remova prefills de mensagens do assistente (retorna erro 400); use saídas estruturadas ou output_config.format em vez disso
• INCOMPATÍVEL no Opus 4.7: Substitua thinking: {type: "enabled", budget_tokens: N} por thinking: {type: "adaptive"} mais o parâmetro effort (retorna 400 no Opus 4.7)
• Verifique se a análise de JSON das chamadas de ferramentas usa um parser JSON padrão
• 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)
• Se estiver migrando do Claude 4.1 ou anterior: remova temperature, top_p e top_k (valores não padrão retornam 400 no Opus 4.7)
• Se estiver migrando do Claude 4.1 ou anterior: atualize as versões das ferramentas (text_editor_20250728, code_execution_20260521)
• Se estiver migrando do Claude 4.1 ou anterior: trate o motivo de parada refusal
• Se estiver migrando do Claude 4.1 ou anterior: trate o motivo de parada model_context_window_exceeded
• Se estiver migrando do Claude 4.1 ou anterior: verifique o tratamento de parâmetros string de ferramentas quanto a quebras de linha finais
• Se estiver migrando do Claude 4.1 ou anterior: 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
• Teste em ambiente de desenvolvimento antes da implantação em produção

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

O Claude Opus 5 e o Claude Sonnet 5 compartilham a mesma superfície de API: ambos executam com pensamento adaptativo ativado por padrão, ambos definem o parâmetro effort como high por padrão na Claude API e no Claude Code, ambos oferecem uma janela de contexto de 1M de tokens por padrão com 128k tokens máximos de saída, e nenhum dos dois oferece suporte ao Priority Tier. O pensamento estendido manual e parâmetros de amostragem não padrão retornam um erro 400 em ambos os modelos, assim como o prefill do assistente.

Atualize o nome do seu modelo

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

O que mudou

1. Preços: O Claude Opus 5 custa $5 USD por milhão de tokens de entrada e $25 USD por milhão de tokens de saída. O Claude Sonnet 5 custa $2/$10 USD por milhão de tokens de entrada/saída. Consulte preços do Claude para ver os preços completos.

2. Desativar o pensamento é limitado ao esforço high: No Claude Sonnet 5, thinking: {type: "disabled"} é aceito em qualquer nível de esforço. No Claude Opus 5, é aceito apenas em um nível de effort (esforço) high ou inferior; uma requisição que combine thinking: {type: "disabled"} com esforço xhigh ou max retorna um erro 400, aplicado a cada requisição. Audite as requisições que desativam o pensamento antes de migrar.

3. Mensagens de sistema no meio da conversa: O Claude Opus 5 aceita mensagens role: "system" imediatamente após um turno do usuário no array messages (sujeito às regras de posicionamento). Esse 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.

4. Web fetch não está disponível: A ferramenta web fetch está disponível no Claude Sonnet 5, mas não no Claude Opus 5.

Checklist de migração

• Atualize o nome do modelo de claude-sonnet-5 para claude-opus-5.
• Audite as requisições que desativam o pensamento: thinking: {type: "disabled"} com esforço xhigh ou max retorna um erro 400 no Claude Opus 5. Reative o pensamento ou reduza o esforço para high ou inferior.
• Se você usa web fetch, planeje uma alternativa: ela não está disponível no Claude Opus 5.
• Execute novamente a contagem de tokens no Claude Opus 5 em vez de reutilizar contagens medidas no Claude Sonnet 5, e refaça a linha de base de custo e latência nas suas próprias cargas de trabalho; o preço por token é diferente.