Autor
Kaique Nogueira · Engenharia · Capim
Quando eu colocava um software tradicional em produção, tinha uma ideia muito clara do que esperar. Minha suíte de testes iria cobrir a maior parte dos caminhos do código e minha rotina de monitoramento era previsível. Mas agora, desde que comecei a trabalhar com agentes (LLMs), minha rotina mudou drasticamente. A maior lição que aprendi no meu dia a dia é simples: você não sabe o que o seu agente fará até que ele esteja em produção, diante de uma infinitude de cenários possíveis.
O Conforto do Software Tradicional
No passado, lidávamos com um espaço de entrada finito e restrito. Os usuários interagem com os sistemas por meio de botões, formulários e chamadas de API com formatos muito específicos. Se eu desenhasse um fluxo de cadastro, conhecia a sequência exata de telas.
Meu monitoramento era baseado em ferramentas tradicionais de monitoramento, e meu foco era olhar para logs estruturados, rastreamentos de pilha (stack traces) e métricas de sistema. Quando um web request retornava “POST /api/checkout 200 OK em 200ms”, eu sabia que estava tudo bem. O tratamento de falhas era exaustivo simplesmente porque os modos de falha podiam ser enumerados com antecedência.
O Território não mapeado
Hoje, a realidade é completamente outra. Os agentes aceitam linguagem natural como entrada principal, o que torna o espaço de possibilidades infinito. O usuário não clica mais em “Solicitar Reembolso”; ele pode ser vago, específico, casual ou formal, e escrever coisas como “meu pedido chegou quebrado, o que eu faço?” ou apenas “reembolso pedido #12345”.
Além das entradas ilimitadas, temos que lidar diariamente com o comportamento não-determinístico dos LLMs. Pequenas variações no modo como o usuário escreve podem gerar saídas diferentes. Durante as conversas, o agente muitas vezes toma decisões usando cadeias de raciocínio de múltiplas etapas e chamadas de ferramentas que eu simplesmente não consigo prever na fase de desenvolvimento. Um prompt que funcionou perfeitamente nos meus testes locais pode falhar em casos extremos na produção.
Tentar usar as antigas ferramentas de monitoramento para isso se provou frustrante. Elas não foram feitas para armazenar a enorme escala de conversas em texto livre com contexto de múltiplos turnos (várias idas e vindas na conversa), nem possuem recursos de busca semântica para analisar trajetórias completas. Mais do que isso: um código HTTP de “200 OK” não me diz absolutamente nada sobre a qualidade da resposta do agente. A qualidade agora vive nas próprias conversas.
A Busca pela Melhor Forma de Monitoramento
Determinar se uma resposta foi útil, se o tom estava certo ou se o agente não inventou informações exige julgamento humano. Mas como eu poderia revisar manualmente milhares de interações por dia? Isso não escala e foi tentando resolver esse problema que cheguei à estrutura que usamos hoje.
O primeiro passo foi mudar o que eu monitorava. Saí das métricas de infraestrutura para capturar o comportamento completo do agente: o prompt enviado, a resposta gerada, o contexto utilizado, as ferramentas acionadas e a cadeia de raciocínio quando disponível. Esses dados ficam armazenados como traces estruturados no Langfuse, o que me dá auditabilidade real sobre o que aconteceu em cada interação. Um “200 OK” continua aparecendo nos meus logs, mas aprendi que ele não me diz absolutamente nada sobre qualidade.
Para escalar o julgamento sem escalar a equipe, configuramos 1 agente avaliador baseado em LLM que roda automaticamente sobre uma amostra do tráfego de produção, geralmente entre 10% e 20%. Ele não é perfeito, mas me entrega métricas contínuas que seriam impossíveis de obter manualmente.
A pergunta que imagino que estão fazendo agora é: por que só 1?
Já testamos LLM-as-a-judge o suficiente para entender que cada novo avaliador cria um grau adicional de complexidade, e eles não nascem prontos, mesmo quando bem delimitados no seu papel. Para que sejam realmente efetivos, a métrica pela qual serão responsáveis precisa estar refinada antes. Só depois que uma métrica amadurece é que faz sentido criar um agente dedicado para monitorá-la. É um processo gradual, não uma decisão de arquitetura tomada de uma vez.
E justamente porque esses avaliadores não são perfeitos, aprendi que não posso depender só deles. Hoje temos filas de revisão humana com critérios pré-definidos, alimentadas por metadados gerados junto com os traces. É um trabalho cirúrgico, não exaustivo — especialistas olham para os casos que realmente importam, não para tudo. É dessa revisão que identificamos novos problemas, amadurecemos métricas existentes e, eventualmente, decidimos quando faz sentido criar um novo agente de monitoramento.
O quarto pilar foi o que mais mudou minha rotina de desenvolvimento: parei de ajustar prompts “no feeling”. Hoje trato prompts como código, versionados no GitHub, testados com o Promptfoo em um pipeline de CI/CD e publicados de forma controlada via Langfuse. Qualquer mudança passa por testes unitários, testes de cenário e verificação de regressão antes de chegar à produção.
Fechando o Ciclo
O que tornou essa estrutura realmente valiosa foi perceber que o monitoramento alimenta o desenvolvimento. Quando uma falha aparece em produção, não descarto aquela interação, eu a uso. Ferramentas de análise agrupam padrões de erro, as interações problemáticas entram no dataset, novos testes são criados no Promptfoo, o prompt é corrigido e a mudança passa pela pipeline de novo antes de ir ao ar. Erros de produção viram casos de teste permanentes. O sistema aprende com o que quebra.
O fluxo completo ficou assim:
- Desenvolvimento local
- Criação de cenários de teste (Promptfoo)
- Commit no GitHub
- Evals em CI/CD
- Publicação no Langfuse
- Coleta de logs e traces
- Avaliação automática + revisão humana
- Ajuste de prompt → novo ciclo
Esse processo me deu algo que eu sentia falta desde que comecei a trabalhar com agentes: reprodutibilidade, auditabilidade e rastreabilidade, atributos que o software tradicional sempre teve no código, mas que sistemas de LLM precisaram aprender a construir.
Conclusão
No fim do dia, a mudança do software tradicional para os agentes é uma mudança de paradigma. Saímos de sistemas determinísticos, onde validávamos se o código rodou sem quebrar, para sistemas probabilísticos, onde o foco do monitoramento precisa ser entender as interações em linguagem natural e melhorar continuamente as respostas.
A ferramenta importa menos do que a técnica. O que aprendi na prática é que o sucesso de um agente em produção não está no modelo que você escolhe, mas na arquitetura de validação e na engenharia de dados que o suportam. Unir a escala das avaliações automáticas com a revisão humana cirúrgica é, até o momento, o caminho mais sustentável que encontrei para escalar agentes com qualidade e segurança.