Como configurar Claude Sonnet 5 como padrão dos seus agentes e cortar custo sem perder performance

A Anthropic lançou o Claude Sonnet 5 no dia 30 de junho e a promessa é direta: performance próxima do Opus 4.8, preço bem menor. Para quem roda agentes em produção, isso muda a conta rapidamente. Um pipeline que fazia dezenas de chamadas por tarefa e sangrava crédito no Opus agora pode rodar quase inteiro no Sonnet 5, reservando o modelo caro só para os passos que realmente exigem raciocínio pesado.

Este tutorial mostra como migrar (ou configurar do zero) um agente para usar Sonnet 5 como padrão, com roteamento inteligente para Opus quando fizer sentido, e como validar que a troca não degradou a qualidade das respostas.

1. Entenda onde o Sonnet 5 se encaixa

Antes de trocar tudo, vale saber o que a própria documentação da Anthropic diz sobre o modelo. O system card do Sonnet 5 explica que parte do ganho de custo vem de otimizações no roteamento interno do modelo para tarefas agentic (uso de ferramentas, chamadas de função, loops de raciocínio curto). Ou seja: ele foi pensado especificamente para agentes, não é só um Opus “capado”.

Na prática isso significa que tarefas como:

• Chamadas de ferramentas (tool use) e parsing de resultados
• Sumarização de contexto entre etapas de um agente
• Decisões de roteamento dentro do próprio fluxo (qual sub-agente chamar)
• Geração de código de complexidade média

tendem a rodar bem no Sonnet 5. Já tarefas que exigem raciocínio longo em múltiplas etapas com alta ambiguidade (planejamento complexo, análise jurídica detalhada, matemática avançada) ainda se beneficiam de Opus.

2. Troque o modelo padrão na configuração do agente

Se você usa o SDK oficial da Anthropic, a troca é literalmente uma linha. Exemplo em Python:

from anthropic import Anthropic

client = Anthropic(api_key="sua-chave-aqui")

response = client.messages.create(
    model="claude-sonnet-5-20260630",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Liste os arquivos modificados no último commit e resuma as mudanças."}
    ],
    tools=[...]  # suas definições de ferramentas
)

Se você já tinha model="claude-opus-4-8" hardcoded, o primeiro passo é extrair isso para uma variável de ambiente ou arquivo de config. Isso facilita testar os dois modelos em paralelo antes de decidir a migração completa.

# .env
CLAUDE_MODEL_DEFAULT=claude-sonnet-5-20260630
CLAUDE_MODEL_HEAVY=claude-opus-4-8

3. Implemente roteamento por complexidade de tarefa

O ganho real de custo não vem de trocar 100% para Sonnet 5, vem de rotear cada chamada para o modelo certo. Uma abordagem simples é classificar a tarefa antes de chamar o modelo principal:

def escolher_modelo(tarefa: str) -> str:
    palavras_chave_pesadas = [
        "analise profunda", "plano de arquitetura",
        "prova matemática", "revisão jurídica"
    ]
    if any(p in tarefa.lower() for p in palavras_chave_pesadas):
        return "claude-opus-4-8"
    return "claude-sonnet-5-20260630"

modelo = escolher_modelo(tarefa_atual)
response = client.messages.create(model=modelo, ...)

Essa heurística é simples de propósito. Se o seu agente já tem um passo de planejamento (bem comum em arquiteturas ReAct ou de multi-agente), use o próprio Sonnet 5 para classificar a complexidade da tarefa e decidir se escala para Opus. Isso custa poucos tokens e evita chamadas caras desnecessárias.

prompt_classificador = """
Classifique a tarefa abaixo como SIMPLES ou COMPLEXA.
Responda apenas com uma palavra.

Tarefa: {tarefa}
"""

4. Ajuste o orçamento de tokens e o número de passos do agente

Como o Sonnet 5 é mais barato por token, muita gente comete o erro de manter os mesmos limites de max_tokens e número de iterações que usava no Opus, achando que está economizando automaticamente. Na verdade, o ganho de custo permite dar mais folga ao agente sem estourar o orçamento total. Por exemplo:

• Se antes você limitava o agente a 5 iterações no Opus por causa do custo, agora pode testar 8 a 10 iterações no Sonnet 5 pelo mesmo preço.
• Mais iterações geralmente significam mais chances de o agente se autocorrigir sem intervenção humana.

Vale reconfigurar isso explicitamente em vez de herdar os limites antigos:

AGENTE_CONFIG = {
    "max_iteracoes": 10,   # era 5 no Opus
    "max_tokens_por_chamada": 4096,
    "modelo_padrao": "claude-sonnet-5-20260630",
}

5. Valide a qualidade antes de migrar em produção

Não troque o modelo em produção sem comparar resultados. O jeito mais prático é rodar um conjunto de tarefas reais (10 a 20 exemplos representativos do seu caso de uso) nos dois modelos e comparar lado a lado:

tarefas_teste = carregar_casos_de_teste("testes_agente.jsonl")

for tarefa in tarefas_teste:
    resp_opus = client.messages.create(model="claude-opus-4-8", messages=[...])
    resp_sonnet = client.messages.create(model="claude-sonnet-5-20260630", messages=[...])
    salvar_comparacao(tarefa, resp_opus, resp_sonnet)

Depois, revise manualmente ou use um terceiro prompt de avaliação (um “juiz”) para pontuar as respostas em critérios como correção, completude e uso correto das ferramentas. Só migre a etapa do pipeline para Sonnet 5 quando a diferença de qualidade for irrelevante para o seu caso de uso.

6. Monitore custo e taxa de escalonamento para Opus

Depois de colocar o roteamento em produção, acompanhe duas métricas principais:

• Taxa de escalonamento: qual porcentagem das chamadas está sendo redirecionada para Opus. Se estiver muito alta (acima de 30 a 40%), sua heurística de classificação provavelmente está conservadora demais.
• Custo médio por tarefa completa: não custo por chamada isolada, mas o custo total do fluxo do agente do início ao fim, incluindo retries e escalonamentos.

Logue essas informações desde o primeiro dia:

import logging

logging.info(f"modelo={modelo} tarefa_id={tarefa_id} tokens_entrada={tokens_in} tokens_saida={tokens_out} custo_usd={custo}")

Dicas finais

• Comece migrando as etapas de tool use e parsing, que costumam ser as mais numerosas em um agente e onde o Sonnet 5 já entrega resultado equivalente ao Opus.
• Deixe o roteamento para Opus como fallback explícito, não como padrão. Isso evita gasto invisível.
• Reavalie os limites de iteração do agente depois da troca, o barateamento por token muda o cálculo de quantos passos valem a pena.
• Rode a validação lado a lado antes de qualquer migração em produção, mesmo que pareça óbvio que o Sonnet 5 vai se sair bem.