Migrando para o Claude 4

Esta página fornece orientações sobre a migração dos modelos Claude 3.7 para os modelos Claude 4 (Opus 4 e Sonnet 4).

Na maioria dos casos, você pode mudar para os modelos Claude 4 com alterações mínimas:

1. Atualize o nome do seu modelo:

   • De: claude-3-7-sonnet-20250219
   • Para: claude-sonnet-4-20250514 ou claude-opus-4-20250514

2. As chamadas de API existentes devem continuar funcionando sem modificação, embora o comportamento da API tenha mudado ligeiramente nos modelos Claude 4 (veja as notas de lançamento da API para detalhes).

​

O que há de novo no Claude 4

​

Nova razão de interrupção por recusa

Os modelos Claude 4 introduzem uma nova razão de interrupção refusal para conteúdo que o modelo se recusa a gerar por motivos de segurança, devido à maior inteligência dos modelos Claude 4:

{"id":"msg_014XEDjypDjFzgKVWdFUXxZP",
"type":"message",
"role":"assistant",
"model":"claude-sonnet-4-20250514",
"content":[{"type":"text","text":"I would be happy to assist you. You can "}],
"stop_reason":"refusal",
"stop_sequence":null,
"usage":{"input_tokens":564,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":22}
}

Ao migrar para o Claude 4, você deve atualizar sua aplicação para lidar com razões de interrupção refusal.

​

Pensamento resumido

Com o pensamento estendido ativado, a API de Mensagens para os modelos Claude 4 retorna um resumo do processo de pensamento completo do Claude. O pensamento resumido fornece todos os benefícios de inteligência do pensamento estendido, enquanto previne o uso indevido.

Embora a API seja consistente entre os modelos Claude 3.7 e 4, as respostas de streaming para pensamento estendido podem retornar em um padrão de entrega “em blocos”, com possíveis atrasos entre os eventos de streaming.

Para mais informações, consulte a documentação de Pensamento Estendido.

​

Pensamento intercalado

Os modelos Claude 4 suportam o intercalamento do uso de ferramentas com o pensamento estendido, permitindo conversas mais naturais onde os usos de ferramentas e respostas podem ser misturados com mensagens regulares.

Para mais informações, consulte a documentação de Pensamento Estendido.

​

Ferramenta de editor de texto atualizada

A ferramenta de editor de texto foi atualizada para os modelos Claude 4 com as seguintes alterações:

• Tipo de ferramenta: text_editor_20250429
• Nome da ferramenta: str_replace_based_edit_tool
• O comando undo_edit não é mais suportado nos modelos Claude 4.

Se você está migrando do Claude Sonnet 3.7 e usando a ferramenta de editor de texto:

# Claude Sonnet 3.7
tools=[
    {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
    }
]

# Claude 4
tools=[
    {
        "type": "text_editor_20250429",
        "name": "str_replace_based_edit_tool"
    }
]

Para mais informações, consulte a documentação da ferramenta de editor de texto.

​

Uso de ferramentas com eficiência de tokens não mais suportado

Uso de ferramentas com eficiência de tokens está disponível apenas no Claude Sonnet 3.7.

Se você está migrando do Claude Sonnet 3.7 e usando ferramentas com eficiência de tokens, recomendamos remover o cabeçalho beta token-efficient-tools-2025-02-19 de suas solicitações.

O cabeçalho beta token-efficient-tools-2025-02-19 ainda pode ser incluído nas solicitações do Claude 4, mas não terá efeito.

​

Saída estendida não mais suportada

O cabeçalho beta output-128k-2025-02-19 para saída estendida está disponível apenas no Claude Sonnet 3.7.

Se você está migrando do Claude Sonnet 3.7, recomendamos remover output-128k-2025-02-19 de suas solicitações.

O cabeçalho beta output-128k-2025-02-19 ainda pode ser incluído nas solicitações do Claude 4, mas não terá efeito.

​

Considerações de desempenho

​

Claude Sonnet 4

• Capacidades de raciocínio e inteligência aprimoradas em comparação ao Claude Sonnet 3.7
• Precisão aprimorada no uso de ferramentas

​

Claude Opus 4

• Modelo mais capaz com raciocínio e inteligência superiores
• Mais lento que os modelos Sonnet
• Melhor para tarefas complexas que exigem análise profunda

​

Lista de verificação para migração

• Atualizar o ID do modelo em suas chamadas de API
• Testar solicitações existentes (devem funcionar sem alterações)
• Remover o cabeçalho beta token-efficient-tools-2025-02-19 se aplicável
• Remover o cabeçalho beta output-128k-2025-02-19 se aplicável
• Lidar com a nova razão de interrupção refusal
• Atualizar o tipo e nome da ferramenta de editor de texto se estiver usando-a
• Remover qualquer código que use o comando undo_edit
• Explorar novos recursos de intercalação de ferramentas com pensamento estendido
• Revisar melhores práticas de engenharia de prompt do Claude 4 para resultados ideais
• Testar em desenvolvimento antes da implantação em produção

​

Precisa de ajuda?

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