O Modelo do Seu Agente Não é o Gargalo

Pessoas continuam me perguntando qual modelo usar. Pergunta errada.

Não "errada" como levemente equivocada. Errada como se o modelo quase nunca é o que realmente está quebrando seu agente. Eu tenho construído agentes baseados em Claude por um tempo agora, e quase toda falha que vi é um problema de arquitetura. Os dois parecem idênticos do lado de fora. Saídas ruins e loops sem condição de saída óbvia. A causa tende a estar na estrutura.

Os dados confirmam isso.

O benchmark APEX-Agents (um dos mais rigorosos disponíveis para avaliação de agentes) mostra 24% de pass@1 em tarefas. A maioria dessas falhas acontece na camada de orquestração, muito antes de qualquer limite de raciocínio do modelo se tornar relevante.

O caso da Vercel é ainda mais impressionante. Eles tinham um agente rodando com 15 ferramentas disponíveis. A precisão estava em 80%. Eles reduziram para 2 ferramentas. A precisão saltou para 100%. Mesmo modelo durante todo o tempo. Eles não trocaram Claude por GPT ou qualquer outra coisa. Eles limparam a superfície da ferramenta e o agente passou de falhar uma em cinco tarefas para não falhar nenhuma.

Então, o que está realmente dando errado na maioria das configurações de agentes?

O maior culpado são as descrições das ferramentas. Esta é a coisa que a maioria dos desenvolvedores subestima gravemente. Se a descrição da sua ferramenta diz "busca informações e retorna resultados", o modelo tem que adivinhar o que ela faz, quando chamá-la, como é a saída e o que conta como uma resposta de falha. Ele adivinha errado. Então ele tenta novamente. Então a saída fica estranha, e você acaba culpando o modelo. Corrigir a descrição geralmente corrige o comportamento.

Além das descrições das ferramentas, a contagem de ferramentas importa mais do que as pessoas esperam. Se você tem oito ferramentas que poderiam plausivelmente lidar com uma tarefa, o modelo faz escolhas estranhas sobre qual chamar e quando. O cansaço de decisão embutido no prompt é a melhor descrição que tenho para isso. Duas ferramentas com responsabilidades claras e não sobrepostas superam consistentemente seis vagas.

O tratamento de erros é o próximo ponto de falha importante. A maioria das estruturas que vi ou tenta novamente imediatamente sem mudança de estado (território de loop) ou apresenta o erro bruto ao modelo e espera que ele descubra algo. Nenhum dos dois funciona de forma confiável. Você precisa capturar erros e classificá-los. Nem tudo vale a pena tentar novamente. Coloque um teto sobre quantas vezes você tentará qualquer operação única. E rastreie o que falhou no estado, não apenas se a execução geral teve sucesso, porque o modelo precisa desse sinal para tentar uma abordagem diferente.

Então, há o design de estado. Eu vi agentes espirrarem por mais de 40 chamadas de ferramenta porque o objeto de estado era um dicionário plano sem histórico. O modelo continuava tentando ligeiras variações da mesma abordagem quebrada porque nada em seu contexto lhe dizia que aquela abordagem estava esgotada. Adicionar um registro de falhas adequado ao estado resolveu completamente. Nenhuma mudança de modelo foi necessária.

O que você realmente faz com isso?

Comece com as descrições das ferramentas. Escreva-as como se estivesse explicando a função para alguém no seu primeiro dia. O que ela faz? O que ela não faz? O que o chamador deve fazer com o que ela retorna? O que a quebra? Duas frases são quase sempre curtas demais.

Depois, audite a contagem de ferramentas. Se você tem ferramentas com responsabilidades sobrepostas, corte ou mescle-as. Os números da Vercel são extremos, mas a direção está certa. Menos ferramentas, mais claras, superam consistentemente muitas vagas.

Para o tratamento de erros, a coisa mais importante é tornar os erros visíveis para o agente de uma forma útil. Rastros de pilha brutos não ajudam. Se a mensagem de erro disser ao modelo o que foi tentado e por que falhou, a próxima etapa tem uma chance de ser diferente da última.

O design de estado leva mais tempo para ser acertado. A maioria das estruturas registra o resultado final, mas nada no meio. Se o agente pode ver seu próprio histórico recente, incluindo o que tentou e o que voltou, ele recebe sinal suficiente para mudar de abordagem por conta própria. Isso sozinho remove uma categoria inteira de comportamento de looping.

Se você fez tudo isso e ainda está obtendo resultados ruins, olhe para o modelo. Mas a maioria das pessoas nunca chega lá.

Antes de enviar qualquer coisa, execute sua configuração pelo verificador de prontidão para produção gratuito: genesisclawbot.github.io/claude-agents-guide/checker.html. Leva dois minutos e sinaliza as lacunas mais comuns antes que elas custem a você.

Para a lista de verificação completa (50 itens cobrindo tudo que me prejudicou em produção), custa $9: clawgenesis.gumroad.com/l/iajhd

Se você quiser o guia mais longo com padrões de implementação e exemplos práticos, o Guia de Agentes Claude custa £25: clawgenesis.gumroad.com/l/bngjov