Quando Seu Agente de IA Quebra Às 3 da Manhã: Manual de Debug em Produção

Rodar um agente autônomo em produção não é como rodar um web service. Web service ou responde ou não responde. Um agente pode estar totalmente online, queimando token, batendo nas suas APIs, e ainda assim fazendo algo completamente inútil — ou pior, algo destrutivo — e você não percebe até a fatura chegar.

Vi agentes saírem do trilho de uns quinze jeitos diferentes no último ano. Algumas falhas se repetem. Os padrões abaixo são os que eu agora checo primeiro, mais ou menos na ordem em que costumam morder.

Modo de Falha 1: O Loop Silencioso

O agente decide que precisa "checar status" antes do próximo passo. O check de status falha de jeito ambíguo. O agente tenta de novo. O check falha de novo. Duas horas depois você gastou quarenta dólares em token e nada aconteceu.

Loops são a falha mais comum que vejo em produção e quase nunca logam erro, porque do ponto de vista do agente nada está errado. Ele está progredindo. Só não consegue passar do passo três.

Como pegar:

• Alerta de taxa de token. Coloca teto duro de tokens-por-hora por agente. Se passar do baseline, te chama. O meu dispara em 3x da média numa janela de 30 min.
• Diversidade de ação. Loga toda chamada de ferramenta. Se a mesma ferramenta for chamada mais de N vezes numa janela com argumentos parecidos, mata o run e levanta. Uso N=5 em 10 minutos.
• Marcadores de progresso forçados. Exige que o agente escreva numa tabela progress_log em cada passo significativo. Se nenhuma linha aparecer em 15 minutos, algo está errado.

A correção quase sempre é fazer o passo que falha retornar erro mais claro pro agente saber que tem que perguntar pra um humano em vez de tentar de novo.

Modo de Falha 2: O Lock Travado

Você usa lockfile ou linha em banco pra garantir que só um tick do agente roda por vez. Bom instinto. Aí um tick crasha, o lock não é liberado, e todo tick depois sai imediatamente porque o lock parece preso.

O agente parece estar rodando no horário (cron está disparando) mas nada de fato está acontecendo. Você descobre horas ou dias depois quando se pergunta por que tal projeto não andou.

Como pegar:

• Linhas de lock sempre devem incluir um timestamp started_at.
• No checkout, ignore locks mais velhos que sua duração máxima de tick (a minha é 15 minutos).
• Loga todo acquire e release de lock numa tabela separada pra ver o padrão.

É um fix de cinco linhas quando você sabe. É outage de quatro horas se você não sabe.

Modo de Falha 3: Chamada de Ferramenta Inventada

O agente chama uma ferramenta que não existe, com parâmetros que não batem com schema nenhum. O servidor MCP retorna erro. O agente lê o erro, tenta de novo com parâmetros levemente diferentes, falha, e ou entra em loop (ver #1) ou desiste e te conta que a tarefa "está completa" sem estar.

Acontece mais quando você tem muitos servidores MCP carregados e o agente pega nome de ferramenta do lugar errado, ou quando você renomeou uma ferramenta recentemente e contexto antigo de conversa ainda referencia o nome velho.

Como pegar:

• Loga o resultado de toda chamada de ferramenta. Filtra por exit code não-zero ou resposta de erro.
• Roda auditoria periódica do tipo "o agente fez mesmo o que disse que fez". No meu content engine, eu confiro que arquivos que ele alegou ter criado existem mesmo e têm tamanho não-zero.
• Valida claim de conclusão contra efeito colateral, não contra o relato do agente.

O agente não é confiável pra te dizer se teve sucesso. O sistema de arquivos é.

Modo de Falha 4: Mismatch de Permissão

Cron roda como um usuário. O agente roda como outro. O script roda como um terceiro. Um deles é dono do arquivo, o outro não consegue ler, e você recebe um permission denied que aparece como genérico "não consegui acessar esse recurso" na resposta do agente.

Esse é fácil de debugar quando você suspeita e quase impossível de descobrir de dentro do raciocínio do agente, porque LLMs são ruins de distinguir "arquivo não existe" de "arquivo existe mas não consigo ler".

Como pegar:

• Roda seu agente sob um único usuário dedicado, não root.
• Todos os paths que o agente toca devem ser desse usuário.
• Quando o agente disser "não achei X", seu primeiro movimento é ls -la X como o usuário do agente, não assumir que o agente está errado.

Modo de Falha 5: A Bomba de Contexto

O agente carrega um arquivo de log de 50 mil linhas no contexto pra "investigar o problema". O próximo prompt custa $4. Aí carrega outro arquivo. O próximo prompt custa $7.

Modelos modernos de contexto longo pioram isso, não melhoram, porque o agente vai alegremente preencher 200K tokens de contexto se você deixar.

Como pegar:

• Budget de token por conversa. Teto duro de uns 500K tokens totais antes do agente ter que começar sessão nova.
• Monitora custo de input separado de custo de output. Custo de input subindo é o canário.
• Ensina o agente (no system prompt) a usar grep ou head antes de ler arquivo inteiro.

Modo de Falha 6: O Write no Banco Confiantemente Errado

O agente decide atualizar uma linha do banco. Pega o WHERE errado. Agora você tem um projeto marcado status='done' que não está, ou um cliente flagado como pago que não pagou.

Esse é o que mais me assusta, porque pode ficar silencioso por semanas.

Como pegar:

• Use trigger de banco pra escrever todo UPDATE numa tabela de auditoria com old_values e new_values.
• Periodicamente faz diff das ações que o agente alegou (do log dele) contra a tabela de auditoria.
• Pra tabelas de alto risco, exige processo de dois passos: agente prepara mudança, agente validador separado ou humano aprova.

Não dá acesso de write irrestrito a um único agente nas suas tabelas de cobrança. Eu não deveria precisar dizer isso. Estou dizendo porque já vi acontecer.

O Que Funciona Pra Monitorar

De todos os dashboards e alertas que tentei, três sinais carregam 80% do valor:

1. Tokens por hora, por agente. Detecção de anomalia nisso pega loop, bomba de contexto e retry descontrolado.
2. Tempo desde a última ação significativa. Definido como tempo desde o último write na sua tabela progress_log. Se exceder seu intervalo de tick, algo está errado.
3. Verificação de efeito colateral. Um cron separado que checa se o agente fez o que disse. Arquivos existem, linhas foram inseridas, mensagens foram enviadas.

Você constrói os três com algumas centenas de linhas de código e uma tabela Postgres. Não precisa de produto de fornecedor.

A Virada Mental

O maior upgrade de debug que eu fiz não foi ferramenta. Foi internalizar que o agente é um narrador não-confiável sobre o próprio comportamento. Vai te dizer que teve sucesso quando não teve. Vai te dizer que tentou algo quando não tentou. Vai explicar o raciocínio dele de um jeito que soa plausível mas não bate com o que ele de fato fez.

Confia no efeito colateral. A linha do banco, o arquivo no disco, a mensagem que chegou (ou não). Tudo o resto é o agente te contando uma história sobre o que ele acha que aconteceu, e essa história às vezes é ficção.

Constrói seu monitoramento em torno do que é verificável de fora do raciocínio do próprio agente. Essa é a disciplina. Quando você tem isso, debugar em produção para de ser assustador e vira problema normal de engenharia.