Migrando para o Claude 4

Esta página fornece orientação sobre como migrar 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 mudanças 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 parada por recusa

Os modelos Claude 4 introduzem uma nova razão de parada refusal para conteúdo que o modelo se recusa a gerar por razões de segurança, devido à inteligência aumentada 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 parada refusal.

​

Pensamento resumido

Com o pensamento estendido habilitado, a API Messages para modelos Claude 4 retorna um resumo do processo completo de pensamento 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 “fragmentado”, com possíveis atrasos entre eventos de streaming.

Para mais informações, veja a documentação de Pensamento estendido.

​

Pensamento intercalado

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

Para mais informações, veja 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 mudanças:

• Tipo de ferramenta: text_editor_20250728
• 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_20250728",
        "name": "str_replace_based_edit_tool"
    }
]

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

​

Uso de ferramenta eficiente em tokens não é mais suportado

Uso de ferramenta eficiente em tokens está disponível apenas no Claude Sonnet 3.7.

Se você está migrando do Claude Sonnet 3.7 e usando uso de ferramenta eficiente em 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 em 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 em 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 comparadas 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 requerem análise profunda

​

Lista de verificação de migração

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

​

Precisa de ajuda?

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