PulseFlow Tecnologia
← Insights
·7 min de leitura·framework-playbook·observabilidade·mlflow·logs
PulseFlow Tecnologia

Playbook de observabilidade para agentes

Observabilidade de agente não é dashboard de latência de API. É a capacidade de reconstruir, depois do fato, o que um agente viu, decidiu, chamou e gastou - para qualquer execução específica, não só em agregado. A pesquisa State of AI Agents, da LangChain, confirma que isso já é o controle mais citado entre empresas com agentes em produção; o que falta na maioria dos casos é organizar isso em camadas, não só coletar log de tudo sem estrutura.

Logs de prompt e de contexto: separados, não misturados

O prompt final que chega ao modelo e o contexto que foi selecionado para compor esse prompt são duas coisas diferentes, e vale registrar separadamente: o prompt mostra o que foi perguntado; o log de contexto mostra por que aquela informação específica foi incluída (ou excluída). Sem essa separação, depurar por que um agente respondeu errado vira adivinhação.

Tool calls e decisões: o rastro que realmente importa

Cada chamada de ferramenta - qual foi chamada, com quais argumentos, o que retornou - precisa de log próprio, junto com a decisão que levou a essa chamada. Um agente que responde bem mas chama a ferramenta errada é um problema que só aparece nesse nível de detalhe, nunca no log da resposta final.

Custos e latência: por execução, não por agregado mensal

A pesquisa da LangChain reforça isso indiretamente: qualidade de execução é a maior preocupação relatada, mas sem instrumentação de custo e latência por execução individual, não há como saber se um problema pontual é exceção ou padrão. O MLflow recomenda capturar a distribuição no lançamento e monitorar desvio estatístico - isso só é possível com dado granular por execução.

Falhas: registradas como dado, não como exceção descartada

Toda falha - erro de ferramenta, timeout, resposta rejeitada por avaliação - precisa virar dado estruturado, não apenas um log de erro genérico. Padrões de falha recorrente são o sinal mais direto de que algo no design do agente precisa mudar.

Evals como camada contínua, não checkpoint isolado

A avaliação incorporada ao fluxo que o MLflow descreve - "avaliação probes... em workflows agentic ativos", com resultado em trilha de auditoria legível por máquina - é o que transforma eval de checkpoint pontual em camada de observabilidade contínua. A pesquisa da LangChain mostra que avaliação offline (39,8%) já é mais comum que avaliação online (32,5%) entre as empresas pesquisadas - mas ambas deveriam coexistir, não competir.

Segurança como observabilidade, não módulo separado

Eventos de segurança - tentativa de acesso fora de escopo, padrão de uso anômalo - pertencem à mesma camada de observabilidade que custo e latência, não a um sistema paralelo que ninguém olha no dia a dia.

Feedback humano: o dado que fecha o ciclo

Quando um humano corrige, aprova ou rejeita uma ação do agente, esse feedback precisa ser capturado como dado estruturado, associado à execução específica - é o que permite, depois, calibrar avaliação automatizada contra julgamento humano real.

As dez camadas do playbook

  1. Logs de prompt - o que foi efetivamente perguntado ao modelo
  2. Logs de contexto - por que essa informação específica entrou
  3. Tool calls - ferramenta, argumentos, retorno
  4. Decisões - o raciocínio que levou a cada tool call
  5. Custos - por execução, não só agregado
  6. Latência - por execução e por etapa
  7. Falhas - estruturadas, não descartadas como exceção
  8. Evals - contínuos, incorporados ao fluxo
  9. Segurança - mesma camada, não sistema paralelo
  10. Feedback humano - capturado e associado à execução

Fontes