A pergunta que toda operação de agente recebe, mais cedo ou mais tarde: "por que ele fez isso?". Um cliente recebeu uma resposta errada, um pedido foi cancelado, uma cobrança saiu com valor estranho. Se a resposta for uma reconstrução por aproximação, o projeto está em risco, não pelo erro em si, mas por não conseguir explicá-lo.
Observabilidade de agente é a capacidade de responder essa pergunta com evidência. Este texto trata do que precisa ser registrado para isso ser possível, e do que se mede com o que foi registrado.
Por que log de aplicação não serve
Software tradicional é determinístico: a mesma entrada produz a mesma saída, e o log registra o que aconteceu porque o "por quê" está no código. Agente não é assim. A mesma entrada pode seguir caminhos diferentes, e o caminho escolhido depende do contexto montado, do modelo usado, da versão da instrução e do resultado de cada ferramenta ao longo do percurso.
Em agente, a decisão é o dado. Registrar só a entrada e a saída é como guardar a pergunta e a resposta de uma prova sem guardar o raciocínio: dá para ver que errou, não dá para ver onde. E sem saber onde, a correção vira tentativa e erro sobre um sistema que muda de comportamento a cada rodada.
Os onze itens da trilha
Uma execução de agente precisa deixar registrado, no mínimo, isto. A ordem é a ordem em que as coisas acontecem.
- A entrada original, como chegou, antes de qualquer tratamento.
- O contexto montado: o que foi recuperado da memória e da base de conhecimento, e o que foi enviado ao modelo. É onde se descobre que o agente respondeu com um documento desatualizado.
- O modelo e a versão usados naquela chamada. Provedor troca versão sem aviso, e o comportamento muda junto.
- A versão da instrução (do prompt). Sem isso, não dá para saber se o erro veio de uma mudança de texto feita na semana anterior.
- Cada decisão de roteamento: qual especialista recebeu o pedido, e com base em quê.
- Cada chamada de ferramenta, com parâmetro e retorno. É o item mais importante e o mais frequentemente ausente. "Consultou o pedido" não basta; precisa ser "consultou o pedido 4471 e recebeu status: cancelado".
- Falhas e retentativas: o que falhou, quantas vezes tentou, o que fez em seguida.
- Tokens e custo por chamada. É o que permite custo por caso resolvido, e não por chamada.
- Latência por passo, não só total. O passo lento é o que se otimiza.
- A saída final e para quem foi.
- Transferência para humano, com o motivo: fora de escopo, baixa confiança, pedido do cliente, risco.
Os onze juntos permitem a propriedade que decide tudo: reprodutibilidade. Dado o registro, é possível reconstruir a execução passo a passo e apontar onde o caminho divergiu do esperado. Sem ela, observabilidade é um painel de resumo, e painel de resumo não explica um caso.
O que medir com o que foi registrado
| Métrica | O que revela |
|---|---|
| Resolução sem transferência, por tipo de caso | O que o agente de fato tira da fila. É a métrica de valor. |
| Transferências por motivo | Fora de escopo pede ajuste de escopo; baixa confiança pede ajuste de instrução; risco pede revisão de régua. Cada motivo é uma correção diferente. |
| Custo por caso resolvido | Chamada barata que não resolve é a mais cara. Custo por chamada engana. |
| Acerto de roteamento na primeira tentativa | Se cai, o problema está no supervisor, não nos especialistas. |
| Saltos por execução | Revela laço entre agentes antes de aparecer na fatura. |
| Taxa de falha de ferramenta, por ferramenta | Sistema integrado instável aparece aqui primeiro. |
| Variação semanal da resolução | Queda lenta é o sinal de que catálogo ou política mudaram e o agente não. É a métrica que ninguém olha até ser tarde. |
Os três usos da trilha
Depurar
Um caso saiu errado. Com a trilha, você abre a execução, vê o contexto que foi montado, a ferramenta que retornou dado desatualizado, a decisão que o modelo tomou a partir disso. A correção é pontual: atualizar a base, ajustar a ferramenta, mudar a instrução. Sem a trilha, a correção é reescrever a instrução inteira e torcer.
Auditar
A área de risco pergunta por que o agente aprovou aquela condição em agosto. A trilha responde com a execução inteira: quem pediu, o que foi consultado, qual regra foi aplicada, quem aprovou. É o que transforma "o modelo decidiu" em uma resposta aceitável, e é condição para operar agente em setor regulado. A trilha, porém, contém dado pessoal e é ela própria tratamento; o post sobre governança e LGPD trata do que isso exige.
Melhorar
Revisão semanal de uma amostra das execuções, com as transferências por motivo na frente. É o ciclo que mantém a qualidade quando o processo muda, e é o trabalho que precisa ter dono depois do go-live. Agente sem esse ciclo degrada em silêncio, e a trilha é o que torna a revisão possível em vez de ser leitura de conversa solta.
Três erros comuns
- Registrar a saída e não o caminho. É o padrão de quem adapta log de aplicação. Mostra que errou, esconde onde.
- Painel sem execução. Gráfico de volume e taxa média, sem a capacidade de abrir um caso específico. Serve para relatório, não para operação.
- Trilha sem retenção definida. Guardar tudo para sempre cria uma base de dados pessoais sem inventário; apagar cedo demais tira a evidência quando a auditoria chega. O prazo é decisão, e precisa ser tomada antes do go-live.
Como a Runflow registra
Na plataforma, cada execução, decisão e chamada de ferramenta fica registrada e é reproduzível: você audita o passado e depura o presente a partir da mesma trilha. A definição de ferramentas com tipo no SDK é o que permite que parâmetro e retorno sejam registrados com estrutura, e não como texto solto. O custo é visível por área e por usuário, e os dashboards de Metrics são construídos em código, sobre a mesma base. Quando pedir uma demonstração, peça para ver uma execução real aberta, com as chamadas de ferramenta: é o teste que separa trilha de painel.
Perguntas frequentes
O que é observabilidade de agentes de IA?
É a capacidade de responder "por que o agente fez isso" com evidência, a partir de um registro reproduzível de cada execução. Diferente de software determinístico, em que o log registra o que aconteceu porque o porquê está no código, em agente a decisão é o dado: o caminho escolhido depende do contexto montado, do modelo, da versão da instrução e do retorno de cada ferramenta, e tudo isso precisa ser registrado.
O que um agente de IA precisa registrar em cada execução?
Onze itens: a entrada original, o contexto montado e enviado ao modelo, o modelo e a versão usados, a versão da instrução, cada decisão de roteamento, cada chamada de ferramenta com parâmetro e retorno, falhas e retentativas, tokens e custo por chamada, latência por passo, a saída final e a transferência para humano com o motivo. Juntos, eles permitem reconstruir a execução passo a passo.
Quais métricas acompanhar em um agente de IA em produção?
Resolução sem transferência por tipo de caso, transferências separadas por motivo, custo por caso resolvido em vez de por chamada, acerto de roteamento na primeira tentativa, saltos por execução, taxa de falha por ferramenta e a variação semanal da resolução, que é o sinal precoce de que o processo mudou e o agente não.
Por que log de aplicação comum não serve para agentes de IA?
Porque registra entrada e saída sem registrar o caminho. Em agente, a mesma entrada pode seguir caminhos diferentes, e é no caminho que o erro acontece: um documento desatualizado recuperado da base, uma ferramenta que retornou dado errado, uma decisão de roteamento equivocada. Sem o caminho, dá para ver que errou, não onde, e a correção vira tentativa e erro.
Como a observabilidade de agentes de IA apoia a LGPD?
A trilha é o que permite responder ao titular por que uma decisão automatizada foi tomada e reconstruir o caminho, o que o art. 20 da lei exige na prática. Ao mesmo tempo, a trilha contém dado pessoal e é ela própria tratamento: precisa de inventário, prazo de retenção definido antes do go-live, acesso restrito e capacidade de eliminação quando o titular pede.