Agente de 30 etapas com 1% de falhas por etapa quebra em uma a cada quatro tarefas: como levá-lo à produção

Na demo, o agente se comporta de forma impecável: 10 etapas de 10, e todo mundo satisfeito. Em produção, ele executa milhares de tarefas e os problemas aparecem todos juntos: o modelo confunde as ferramentas, o contexto fica cheio de lixo, a busca não encontra o que precisa, o processo cai no meio da tarefa. A segunda parte da série no Habr trata do que fazer a respeito. Vamos ao principal.

A aritmética que faz a demo ser diferente da produção

Imagine uma tarefa de 30 etapas em que cada etapa falha uma vez em cem: a rede oscilou, a API respondeu «sobrecarregada». Nesse caso, a tarefa chega ao fim em 74% dos casos. Uma a cada quatro falha. Com 3% de falhas por etapa, só 40% chegam ao final. O autor ressalva, com honestidade, que se trata de um cálculo hipotético: ele pressupõe falhas temporárias e independentes. Se o provedor inteiro sair do ar, três retentativas rápidas não ajudam; é preciso uma pausa longa ou um provedor reserva.

Ferramentas e contexto: menos, porém mais precisos

Sobre uma ferramenta, o modelo conhece apenas o nome, a descrição, o esquema de parâmetros e o que ela retornou. Por isso, uma ferramenta para agente é escrita de outro jeito que uma API para programadores. Não crie uma ferramenta para cada endpoint: em vez de list_users, list_events e create_event, é melhor ter um único schedule_event, que encontra o horário e cria a reunião por conta própria.

Mantenha as respostas curtas e use nomes compreensíveis no lugar de uuid. No exemplo da Anthropic, o modo resumido de uma ferramenta do Slack retornou 72 tokens em vez de 206. Escreva os erros pensando no modelo: a frase «a data deve estar no formato 2026-11-09, mas veio 09.

11» é corrigida sozinha no turno seguinte, enquanto um código 400 seco não diz nada.

O mesmo princípio vale para o contexto: mantenha o menor conjunto de tokens que ajude a resolver a tarefa. Carregue os dados ao longo do caminho, deixando no prompt apenas as referências. Comprima o histórico, preservando as decisões e os bugs em aberto. Entregue as partes pesadas a subagentes, que devolvem um resumo de 1–2 mil tokens.

RAG: primeiro decida se você precisa dele

Se a base de conhecimento tem menos de 200 mil tokens (cerca de 500 páginas), dá para colocá-la inteira no prompt e fazer cache. Nesse caso, a busca é desnecessária. Se a base é maior, segundo medições da Anthropic, funciona bem esta combinação: busca semântica mais busca por palavras (BM25), contexto de 50–100 tokens adicionado a cada trecho antes da indexação e reranqueamento.

A taxa de falhas, em que o trecho certo não aparece entre os 20 melhores, caiu de 5,7% para 1,9%. Avalie a busca separadamente da resposta: crie perguntas cuja resposta está em um lugar conhecido e meça com que frequência o trecho aparece nos resultados. Do contrário, não dá para saber se o culpado é a busca ou o modelo.

Loop sob controle: turnos, dinheiro, retentativas

Comece por uma cadeia, não por um agente: o agente paga pela liberdade com latência e dinheiro. Se ele for mesmo necessário, defina três limitadores: limite de turnos, orçamento em dólares e timeout para a tarefa inteira. O custo cresce mais rápido que o número de turnos, porque cada turno relê todo o histórico. Pelo cálculo do autor, uma tarefa de 30 turnos custa $0,51, e um agente travado em 100 turnos sai por $2,68: são 3,3 vezes mais turnos e 5,3 vezes mais dinheiro. Decida de antemão para onde a tarefa vai quando as tentativas acabarem: um modelo reserva, uma cadeia simples ou uma pessoa.

Só vale repetir falhas temporárias, como 429, 500, 504 e 529, com pausa crescente. O detalhe é que o 429 também aparece quando o limite mensal de gastos se esgotou (código enforced_spend_limit_reached). Nesse caso, repetir não adianta, e uma retentativa sem distinção ficará martelando a API por horas.

O perigo não é a falha, é a repetição

Imagine a ferramenta send_email: o e-mail foi enviado, mas a resposta se perdeu, a camada de controle repetiu a chamada e o cliente recebeu dois e-mails. Com charge_card, o dinheiro seria debitado duas vezes do mesmo modo. A solução é conhecida da Stripe: a chave de idempotência.

O servidor memoriza a resposta à primeira requisição com a chave e, na repetição, devolve a resposta salva. O agente já tem essa chave: é o id da chamada da ferramenta, que não muda na repetição. Repasse-o ao sistema externo.

Mas, se o processo cair entre o envio e o registro do resultado, a verificação local não vai pegar a duplicata. Ações sem suporte a chave no sistema externo, além de envio, pagamento e exclusão, entregue a uma pessoa para confirmação.

Se o próprio processo cair, não há o que repetir: o histórico e os resultados estavam na memória. Aqui é preciso execução durável, por exemplo o Temporal. O loop do agente vive em um workflow, e as chamadas ao modelo e às ferramentas viram activities; os eventos são gravados em um log, e outro worker continua do ponto da falha. A condição é que o código do workflow seja determinístico e as activities, idempotentes. O custo da questão: uma queda no 25º turno com reinício do zero resulta em $0,93 em vez de $0,51, ou seja, +81%.

O que fazer na prática

Reduza o conjunto de ferramentas e agrupe-as em ferramentas maiores. Defina limite de turnos, orçamento e um plano B. Verifique se cada ação com consequências é idempotente ou passa por confirmação. Calcule o custo de uma tarefa bem-sucedida, e não de uma única chamada, e rode as verificações a cada mudança no prompt.

Limitações: todos os cálculos de custo são hipotéticos e ligados ao cenário da primeira parte da série, e parte dos números sobre limites e erros depende da documentação em uma data específica. O trecho sobre observabilidade e proteção está cortado no texto disponível, mas o conselho geral é claro: não dar ao agente, ao mesmo tempo, dados privados, conteúdo não confiável e acesso ao exterior.