Semana passada, um colega me mostrou orgulhoso o agente que ele tinha montado para organizar tarefas de um repositório. Eu perguntei: "E como você sabe que ele fez direito?". Ele respondeu: "Ué, o resultado saiu certo". Aí eu perguntei: "Mas o que ele fez para chegar lá?". Silêncio. Essa conversa é a razão deste texto.
Quando a gente trabalha com agentes de IA, existe uma tentação enorme de olhar só para a saída final. Deu certo? Ótimo, próximo. Só que um agente não é uma função que recebe uma entrada e devolve uma saída. Ele toma decisões em sequência, chama ferramentas, lê arquivos, tenta de novo, muda de ideia. O caminho importa tanto quanto o destino. E é aí que entra a observabilidade.
Por que "deu certo" não basta
Imagine um agente que corrige um teste que estava falhando. O teste passa. Parece vitória. Mas e se ele passou porque o agente apagou a asserção? Ou porque alterou um arquivo de configuração que não deveria tocar? Ou porque rodou o mesmo comando quarenta vezes até algo funcionar por sorte? O resultado final é idêntico nos três casos: verde. A diferença está na trajetória.
Existem pelo menos quatro problemas que um resultado correto pode esconder:
- Efeitos colaterais: o agente alterou ou apagou algo fora do escopo da tarefa.
- Desperdício: chegou ao resultado certo, mas por um caminho caro, cheio de voltas.
- Sorte: acertou desta vez, mas o processo é frágil e vai falhar na próxima.
- Atalhos indesejados: cumpriu a letra do pedido violando o espírito dele.
Se você não enxerga o caminho, não consegue distinguir um agente confiável de um agente sortudo. E sorte não escala.
Logs: o básico que quase todo mundo faz mal
Todo mundo diz que tem logs. Poucos têm logs que respondem perguntas úteis. Um log que diz apenas "tarefa iniciada" e "tarefa concluída" é decoração. O que realmente ajuda é registrar cada passo do agente com contexto suficiente para reconstruir a história depois.
Na prática, eu gosto de guardar, para cada passo:
- um identificador da tarefa e outro do passo, para amarrar tudo;
- o que o agente decidiu fazer e, quando disponível, a justificativa dele;
- qual ferramenta foi chamada, com quais argumentos;
- o que a ferramenta devolveu (ou um resumo, se for muito grande);
- quanto tempo levou e se houve erro.
Dica de quem já se queimou: use logs estruturados, em formato como JSON, e não texto solto. Texto livre é ótimo para ler uma vez e péssimo para consultar. Com campos bem definidos, você consegue perguntar coisas como "mostre todas as tarefas em que o agente chamou a ferramenta de escrita em arquivo mais de dez vezes".
Outro cuidado: segredos. Argumentos de ferramentas e respostas podem conter tokens, senhas e dados pessoais. Decida cedo o que será mascarado antes de gravar, não depois.
Traces das chamadas de ferramentas
Logs contam eventos. Traces contam a estrutura. Se você já usou tracing distribuído em sistemas web, a ideia é a mesma: cada tarefa vira um trace, e cada decisão ou chamada de ferramenta vira um span dentro dele, com início, fim e relação de pai e filho.
Por que isso é tão valioso para agentes? Porque o comportamento deles é aninhado. Uma tarefa gera um plano, o plano gera várias chamadas, uma chamada falha e dispara uma nova tentativa, e talvez o agente delegue um pedaço para outro agente. Em uma lista plana de logs, isso vira um novelo. Em uma visualização de trace, você vê a árvore inteira e aponta rápido onde o tempo foi gasto e onde as coisas desandaram.
Com traces, algumas perguntas ficam fáceis de responder:
- Qual etapa consumiu mais tempo nesta tarefa?
- Houve repetição de chamadas idênticas, sinal clássico de agente andando em círculos?
- Em que ponto exato o agente tomou o rumo errado?
- Alguma ferramenta falhou em silêncio e o agente seguiu como se nada tivesse acontecido?
Esse último ponto merece destaque. Já vi agente receber um erro de uma ferramenta, ignorar e inventar uma resposta plausível. Sem o registro da chamada e da resposta crua, você nunca descobriria.
Custo por tarefa: a métrica que ninguém olha até a fatura chegar
Existe uma pergunta simples que muda a conversa em qualquer time: quanto custou essa tarefa? Não o custo médio do mês, mas o custo daquela tarefa específica, com seus tokens de entrada, tokens de saída e chamadas de ferramentas externas.
Medir custo por tarefa, e não só no agregado, revela coisas que a média esconde. Uma tarefa que custa dez vezes mais que as parecidas quase sempre tem uma história: um laço de tentativas, um contexto gigante carregado sem necessidade, uma ferramenta chamada em excesso. O custo vira um detector de anomalias bem barato.
Algumas boas práticas:
- Atribua o custo ao identificador da tarefa, no mesmo lugar onde estão os traces.
- Defina um teto por tarefa. Ao atingir, o agente para e pede ajuda, em vez de continuar gastando.
- Compare custo com valor entregue. Tarefa barata que falha continua sendo desperdício.
- Acompanhe a evolução ao longo do tempo: mudou o modelo, o prompt ou as ferramentas, e o custo subiu? Você precisa saber.
Revisão de trajetórias: o hábito que separa times maduros
Coletar dados é metade do trabalho. A outra metade é olhar para eles. Chamo de revisão de trajetórias o hábito de sentar, de vez em quando, e ler como o agente resolveu algumas tarefas, do começo ao fim, como quem lê o histórico de um colega.
Parece trabalhoso, mas rende muito. Você aprende onde o agente hesita, que ferramentas ele usa mal, quais instruções ele interpreta de forma diferente da que você pretendia. Muitas melhorias de prompt e de ferramentas nascem dessas leituras, não de métricas agregadas.
Um roteiro simples que funciona:
- Amostre com intenção. Pegue algumas tarefas que deram certo, algumas que falharam e as mais caras. Só olhar as falhas vicia o seu julgamento.
- Leia o passo a passo. Pergunte, a cada passo, se um humano competente faria igual.
- Anote padrões. Erros isolados são ruído. O mesmo erro três vezes é um problema de projeto.
- Transforme em ação. Cada padrão vira um ajuste de instrução, uma nova validação ou um teste.
E atenção às tarefas que deram certo. É nelas que moram os acertos por sorte, e são justamente as que ninguém pensa em revisar.
Do rastro ao teste
Uma consequência bonita de ter bons registros é poder transformar trajetórias reais em casos de teste. Aquela tarefa em que o agente se perdeu? Guarde a entrada, descreva o comportamento esperado e rode de novo depois de cada mudança. Você deixa de depender da memória e passa a ter uma coleção viva de situações difíceis.
Também ajuda definir verificações automáticas sobre a trajetória, e não só sobre o resultado. Por exemplo: "o agente nunca deve escrever fora desta pasta", "nenhuma tarefa deve passar de tantas chamadas" ou "toda alteração deve ser precedida de uma leitura do arquivo". Regras assim pegam o atalho indesejado antes que ele vire hábito.
Por onde começar sem se afogar
Se tudo isso parece muito, comece pequeno. Você não precisa de uma plataforma sofisticada no primeiro dia. Um bom começo é:
- gerar um identificador por tarefa e carregá-lo em todos os registros;
- gravar toda chamada de ferramenta com argumentos, resposta e duração;
- somar o custo ao final de cada tarefa;
- reservar um horário fixo, talvez meia hora por semana, para ler algumas trajetórias.
Só isso já coloca você muito à frente de quem confia apenas no "deu certo". Depois, quando as perguntas ficarem mais sofisticadas, você evolui as ferramentas. Observabilidade é um hábito antes de ser um produto.
Confiança se constrói com evidência
No fim das contas, a questão é confiança. Delegar trabalho a um agente é como delegar a uma pessoa nova no time: no começo você acompanha de perto, depois vai soltando conforme ela mostra consistência. A diferença é que, com o agente, a evidência não vem de conversa de corredor. Ela vem dos registros que você tomou o cuidado de guardar.
Então, da próxima vez que alguém disser que o agente funcionou, faça a pergunta que fiz ao meu colega: o que ele fez para chegar lá? Se você tiver a resposta na ponta dos dedos, parabéns, você está operando um agente. Se não tiver, está torcendo. E torcida é ótima para futebol, mas péssima para sistemas em produção.