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.
