Guia de migração

Migrando para Claude 4.6

Claude Opus 4.6 é um substituto praticamente direto para Claude 4.5, com algumas mudanças significativas a serem observadas. Para uma lista completa de novos recursos, consulte O que há de novo no Claude 4.6.

Atualize seu nome de modelo

# Migração do Opus
model = "claude-opus-4-5"  # Antes
model = "claude-opus-4-6"  # Depois

Mudanças significativas

Remoção de prefill: Preencher previamente mensagens do assistente retorna um erro 400 nos modelos Claude 4.6. Use saídas estruturadas, instruções de prompt do sistema ou output_config.format em vez disso.
Citação de parâmetro de ferramenta: Os modelos Claude 4.6 podem produzir escape de string JSON ligeiramente diferente em argumentos de chamada de ferramenta (por exemplo, tratamento diferente de escapes Unicode ou escape de barra invertida). Se você analisar a input de chamada de ferramenta como uma string bruta em vez de usar um analisador JSON, verifique sua lógica de análise. Os analisadores JSON padrão (como json.loads() ou JSON.parse()) lidam com essas diferenças automaticamente.

Mudanças recomendadas

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

Migre para pensamento adaptativo: thinking: {type: "enabled", budget_tokens: N} está descontinuado nos modelos Claude 4.6 e será removido em uma versão futura do modelo. Mude para thinking: {type: "adaptive"} e use o parâmetro de esforço para controlar a profundidade do pensamento. Consulte Pensamento adaptativo.

Migrando de Claude 4.1 ou anterior para Claude 4.6

Se você está migrando de Opus 4.1, Sonnet 4 ou modelos anteriores diretamente para Claude 4.6, aplique as mudanças significativas do Claude 4.6 acima mais as mudanças adicionais nesta seção.

# De Opus 4.1
model = "claude-opus-4-1-20250805"  # Antes
model = "claude-opus-4-6"  # Depois

# De Sonnet 4
model = "claude-sonnet-4-20250514"  # Antes
model = "claude-opus-4-6"  # Depois

# De Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # Antes
model = "claude-opus-4-6"  # Depois

Mudanças significativas adicionais

Atualize parâmetros de amostragem

Esta é uma mudança significativa ao migrar de modelos Claude 3.x.

Use apenas temperature OU top_p, não ambos:

# Antes - Isto resultará em erro nos modelos Claude 4+
response = client.messages.create(
    model="claude-3-7-sonnet-20250219",
    temperature=0.7,
    top_p=0.9,  # Não é possível usar ambos
    # ...
)

# Depois
response = client.messages.create(
    model="claude-opus-4-6",
    temperature=0.7,  # Use temperature OU top_p, não ambos
    # ...
)

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 ferramenta eficiente em tokens integrado e esses cabeçalhos não têm efeito.

Lista de verificação de migração Claude 4.6

Atualize o ID do modelo para claude-opus-4-6
SIGNIFICATIVA: Remova prefills de mensagem do assistente (retorna erro 400); use saídas estruturadas ou output_config.format em vez disso
Recomendado: Migre de thinking: {type: "enabled", budget_tokens: N} para thinking: {type: "adaptive"} com o parâmetro de esforço (budget_tokens está descontinuado e será removido em uma versão futura)
Verifique se a análise JSON de chamada de ferramenta usa um analisador JSON padrão
Remova o cabeçalho beta effort-2025-11-24 (esforço agora é GA)
Remova o cabeçalho beta fine-grained-tool-streaming-2025-05-14

Migrando para Claude Sonnet 4.6

Claude Sonnet 4.6 combina inteligência forte com desempenho rápido, apresentando recursos de busca agêntica melhorados e execução de código gratuita quando usado com busca na web ou busca na web. É ideal para tarefas cotidianas de codificação, análise e conteúdo.

Para uma visão geral completa de capacidades, consulte a visão geral de modelos.

O preço do Sonnet 4.6 é $3 por milhão de tokens de entrada, $15 por milhão de tokens de saída. Consulte Preços do Claude para detalhes.

Atualize seu nome de modelo:

# De Sonnet 4.5
model = "claude-sonnet-4-5"  # Antes
model = "claude-sonnet-4-6"  # Depois

# De Sonnet 4
model = "claude-sonnet-4-20250514"  # Antes
model = "claude-sonnet-4-6"  # Depois

Mudanças significativas

Ao migrar de Sonnet 4.5

Preenchimento prévio de mensagens do assistente não é mais suportado

Esta é uma mudança significativa ao migrar de Sonnet 4.5 ou anterior.

Preencher previamente mensagens do assistente retorna um erro 400 no Sonnet 4.6. Use saídas estruturadas, instruções de prompt do sistema ou output_config.format em vez disso.

Casos de uso de prefill comuns e migrações:
- Controlando formatação de saída (forçando saída JSON/YAML): Use saídas estruturadas ou ferramentas com campos enum para tarefas de classificação.
- Eliminando preâmbulos (removendo frases "Aqui está..."): Adicione instruções diretas no prompt do sistema: "Responda diretamente sem preâmbulo. Não comece com frases como 'Aqui está...', 'Com base em...', etc."
- Evitando recusas ruins: Claude é muito melhor em recusas apropriadas agora. Prompting claro na mensagem do usuário sem prefill deve ser suficiente.

Ao migrar de Claude 3.x

Atualize parâmetros de amostragem

Esta é uma mudança significativa ao migrar de modelos Claude 3.x.

Use apenas temperature OU top_p, não ambos.
Atualize versões de ferramentas

Esta é uma mudança significativa ao migrar de modelos Claude 3.x.

Atualize para as versões mais recentes de ferramentas (text_editor_20250728, code_execution_20250825). Remova qualquer código usando o comando undo_edit.
Trate o motivo de parada refusal

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

Mudanças recomendadas

Remova o cabeçalho beta fine-grained-tool-streaming-2025-05-14 — O streaming de ferramenta refinado agora é GA no Sonnet 4.6 e não requer mais um cabeçalho beta.
Migre output_format para output_config.format — O parâmetro output_format está descontinuado. Use output_config.format em vez disso.

Migrando de Sonnet 4.5

Encorajamos fortemente a migração de Sonnet 4.5 para Sonnet 4.6, que oferece mais inteligência pelo mesmo preço.

Sonnet 4.6 usa como padrão um nível de esforço de high, em contraste com Sonnet 4.5 que não tinha parâmetro de esforço. Recomendamos ajustar o parâmetro de esforço conforme você migra de Sonnet 4.5 para Sonnet 4.6. Se não for definido explicitamente, você pode experimentar latência mais alta com o nível de esforço padrão.

Se você não estiver usando pensamento estendido

Se você não estiver usando pensamento estendido no Sonnet 4.5, você pode continuar sem ele no Sonnet 4.6. Você deve definir explicitamente o esforço para o nível apropriado para seu caso de uso. Com esforço low e pensamento desabilitado, você pode esperar desempenho similar ou melhor em relação ao Sonnet 4.5 sem pensamento estendido.

Se você estiver usando pensamento estendido

Se você estiver usando pensamento estendido no Sonnet 4.5, ele continua a ser suportado no Sonnet 4.6 sem mudanças necessárias em sua configuração de pensamento. Recomendamos manter um orçamento de pensamento em torno de 16k tokens. Na prática, a maioria das tarefas não usa tanto, mas fornece espaço para problemas mais difíceis sem risco de uso de token descontrolado.

Casos de uso de codificação e agêntico

Para codificação agêntica, design de frontend, fluxos de trabalho pesados em ferramentas e fluxos de trabalho empresariais complexos, recomendamos começar com esforço medium. Se você achar que a latência é muito alta, considere reduzir o esforço para low. Se você precisar de inteligência mais alta, considere aumentar o esforço para high ou migrar para Opus 4.6.

Casos de uso de chat e não-codificação

Para chat, geração de conteúdo, busca, classificação e outras tarefas não-codificação, recomendamos começar com esforço low com pensamento estendido. Se você precisar de mais profundidade, aumente o esforço para medium.

Quando tentar pensamento adaptativo

Os caminhos de migração acima usam pensamento estendido com budget_tokens para uso de token previsível. Se sua carga de trabalho se encaixa em um dos seguintes padrões, considere tentar pensamento adaptativo em vez disso:

Agentes multi-etapa autônomos: agentes de codificação que transformam requisitos em software funcionando, pipelines de análise de dados e descoberta de bugs onde o modelo funciona independentemente em muitas etapas. O pensamento adaptativo permite que o modelo calibre seu raciocínio por etapa, mantendo o caminho em trajetórias mais longas. Para essas cargas de trabalho, comece com esforço high. Se latência ou uso de token for uma preocupação, reduza para medium.
Agentes de uso de computador: Sonnet 4.6 alcançou a melhor precisão em avaliações de uso de computador usando modo adaptativo.
Cargas de trabalho bimodais: uma mistura de tarefas fáceis e difíceis onde adaptativo pula pensamento em consultas simples e raciocina profundamente em complexas.

Ao usar pensamento adaptativo, avalie esforço medium e high em suas tarefas. O nível certo depende da compensação de sua carga de trabalho entre qualidade, latência e uso de token.

Se você ver comportamento inconsistente ou regressões de qualidade com pensamento adaptativo, mude para pensamento estendido com budget_tokens. Isso fornece resultados mais previsíveis com um limite nos custos de pensamento.

Lista de verificação de migração Sonnet 4.6

Atualize o ID do modelo para claude-sonnet-4-6
SIGNIFICATIVA: Remova preenchimento prévio de mensagem do assistente; use saídas estruturadas ou output_config.format em vez disso
SIGNIFICATIVA: Verifique se a análise JSON de parâmetro de ferramenta trata diferenças de escape
SIGNIFICATIVA: Atualize versões de ferramentas para as mais recentes (text_editor_20250728, code_execution_20250825); versões legadas não são suportadas (se migrando de 3.x)
SIGNIFICATIVA: Remova qualquer código usando o comando undo_edit (se aplicável)
SIGNIFICATIVA: Atualize parâmetros de amostragem para usar apenas temperature OU top_p, não ambos (se migrando de 3.x)

Migrando para Claude Sonnet 4.5

Claude Sonnet 4.5 combina inteligência forte com desempenho rápido, tornando-o ideal para tarefas cotidianas de codificação, análise e conteúdo.

Para uma visão geral completa de capacidades, consulte a visão geral de modelos.

O preço do Sonnet 4.5 é $3 por milhão de tokens de entrada, $15 por milhão de tokens de saída. Consulte Preços do Claude para detalhes.

Atualize seu nome de modelo:

# De Sonnet 4
model = "claude-sonnet-4-20250514"  # Antes
model = "claude-sonnet-4-5-20250929"  # Depois

# De Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # Antes
model = "claude-sonnet-4-5-20250929"  # Depois

Mudanças significativas

Essas mudanças significativas se aplicam ao migrar de modelos Claude 3.x Sonnet.

Atualize parâmetros de amostragem

Esta é uma mudança significativa ao migrar de modelos Claude 3.x.

Use apenas temperature OU top_p, não ambos.
Atualize versões de ferramentas

Esta é uma mudança significativa ao migrar de modelos Claude 3.x.

Atualize para as versões mais recentes de ferramentas (text_editor_20250728, code_execution_20250825). Remova qualquer código usando o comando undo_edit.
Trate o motivo de parada refusal

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

Lista de verificação de migração Sonnet 4.5

Atualize o ID do modelo para claude-sonnet-4-5-20250929
SIGNIFICATIVA: Atualize versões de ferramentas para as mais recentes (text_editor_20250728, code_execution_20250825); versões legadas não são suportadas (se migrando de 3.x)
SIGNIFICATIVA: Remova qualquer código usando o comando undo_edit (se aplicável)
SIGNIFICATIVA: Atualize parâmetros de amostragem para usar apenas temperature OU top_p, não ambos (se migrando de 3.x)
Trate novo motivo de parada refusal em sua aplicação
Revise e atualize prompts seguindo práticas recomendadas de prompting

Migrando para Claude Haiku 4.5

Claude Haiku 4.5 é o modelo Haiku mais rápido e inteligente com desempenho próximo à fronteira, oferecendo qualidade de modelo premium para aplicações interativas e processamento de alto volume.

Para uma visão geral completa de capacidades, consulte a visão geral de modelos.

O preço do Haiku 4.5 é $1 por milhão de tokens de entrada, $5 por milhão de tokens de saída. Consulte Preços do Claude para detalhes.

Atualize seu nome de modelo:

# De Haiku 3.5
model = "claude-3-5-haiku-20241022"  # Antes
model = "claude-haiku-4-5-20251001"  # Depois

Revise novos limites de taxa: Haiku 4.5 tem limites de taxa separados de Haiku 3.5. Consulte Documentação de limites de taxa para detalhes.

Para melhorias significativas de desempenho em tarefas de codificação e raciocínio, considere habilitar pensamento estendido com thinking: {type: "enabled", budget_tokens: N}.

Pensamento estendido impacta a eficiência do cache de prompt.

Pensamento estendido está descontinuado em modelos Claude 4.6 ou mais recentes. Se estiver usando modelos mais recentes, use pensamento adaptativo em vez disso.

Explore novas capacidades: Consulte a visão geral de modelos para detalhes sobre consciência de contexto, capacidade de saída aumentada (64K tokens), inteligência mais alta e velocidade melhorada.

Mudanças significativas

Essas mudanças significativas se aplicam ao migrar de modelos Claude 3.x Haiku.

Atualize parâmetros de amostragem

Esta é uma mudança significativa ao migrar de modelos Claude 3.x.

Use apenas temperature OU top_p, não ambos.
Atualize versões de ferramentas

Esta é uma mudança significativa ao migrar de modelos Claude 3.x.

Atualize para as versões mais recentes de ferramentas (text_editor_20250728, code_execution_20250825). Remova qualquer código usando o comando undo_edit.
Trate o motivo de parada refusal

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

Lista de verificação de migração Haiku 4.5

Atualize o ID do modelo para claude-haiku-4-5-20251001
SIGNIFICATIVA: Atualize versões de ferramentas para as mais recentes (text_editor_20250728, code_execution_20250825); versões legadas não são suportadas
SIGNIFICATIVA: Remova qualquer código usando o comando undo_edit (se aplicável)
SIGNIFICATIVA: Atualize parâmetros de amostragem para usar apenas temperature OU top_p, não ambos
Trate novo motivo de parada refusal em sua aplicação
Revise e ajuste para novos limites de taxa (separados de Haiku 3.5)
Revise e atualize prompts seguindo

Precisa de ajuda?

Consulte a documentação da API para especificações detalhadas
Revise capacidades de modelo para comparações de desempenho
Revise notas de lançamento da API para atualizações de API
Entre em contato com o suporte se encontrar algum problema durante a migração

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=[...],
)

Atualize versões de ferramentas

Esta é uma mudança significativa ao migrar de modelos Claude 3.x.

Atualize para as versões mais recentes de ferramentas. Remova qualquer código usando 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 Documentação da ferramenta editor de texto para detalhes.
Execução de código: Atualize para code_execution_20250825. Consulte Documentação da ferramenta de execução de código para instruções de migração.

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 apropriadamente
    pass

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 para devido ao 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 apropriadamente
    pass

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16384,
    thinking={"type": "enabled", "budget_tokens": 16384},
    output_config={"effort": "medium"},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{"role": "user", "content": "Your prompt here"}],
)

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=8192,
    thinking={"type": "enabled", "budget_tokens": 16384},
    output_config={"effort": "low"},
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{"role": "user", "content": "Your prompt here"}],
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Your prompt here"}],
)