Por que eu decidi criar uma ferramenta própria de observabilidade para agentes de IA

Um agente de IA não é apenas mais um endpoint.

Em uma API tradicional, boa parte da observabilidade começa com perguntas conhecidas: a requisição terminou? Quanto tempo levou? Houve uma exceção? O serviço estava disponível?

Essas perguntas continuam importantes, mas não dizem se a resposta faz sentido.

Uma interação pode terminar sem erro, com latência aceitável e uma resposta que parece convincente. Ainda assim, o agente pode ter usado o contexto errado, deixado de considerar um dado importante, alucinado uma conclusão ou falhado silenciosamente ao usar uma ferramenta.

Foi essa diferença que nos levou, na Cobli, a construir uma ferramenta interna de observabilidade para agentes de IA. O problema não era descobrir se o sistema estava de pé. Era dar a mais pessoas uma forma simples de entender se uma conversa estava realmente correta.

Eu tentei as ferramentas que já existiam

Antes de construir algo próprio, eu tentei Datadog, Langfuse, Mastra Studio, Braintrust e outras ferramentas de observabilidade e avaliação para IA.

E elas entregavam muita coisa boa.

Eu encontrava traces detalhados, hierarquias de spans, entradas e saídas, chamadas de ferramentas, scores, avaliações automáticas e recursos de LLM as a judge. Em diferentes níveis, quase todas tinham boa parte dos componentes técnicos que eu imaginava precisar.

Isso é importante porque a decisão de construir não veio da conclusão de que essas ferramentas eram ruins. Pelo contrário. Elas me ajudaram a entender melhor o problema.

Continuo usando o Datadog para analisar traces profundos de APM. Um agente atravessa APIs, serviços e integrações, e eu ainda preciso enxergar latência, erros, dependências e o caminho técnico completo de uma execução. Para esse tipo de investigação, a visão de APM continua essencial.

Mas observar infraestrutura e analisar a qualidade de uma resposta são trabalhos diferentes.

O trace podia estar completo. O score podia estar calculado. A avaliação podia ter rodado. Mesmo assim, ainda era difícil responder, visualmente e com confiança: qual foi a pergunta, qual foi a resposta, que contexto foi usado e tudo o que foi dito realmente faz sentido?

Não faltava trace. Faltava uma leitura.

Um ótimo trace ainda pode ser uma interface ruim para revisão

Um trace é uma excelente representação da execução para quem está depurando software. Ele mostra causalidade, duração, dependências e as etapas percorridas pelo sistema.

Só que uma árvore de spans não é, necessariamente, uma boa representação de uma conversa para revisão humana.

Para avaliar uma resposta, eu precisava abrir spans, localizar entradas e saídas em estruturas diferentes, separar telemetria de conteúdo e correlacionar tudo isso com outros dados autorizados. Parte do que importava aparecia como texto. Parte estava em atributos. Parte estava em eventos posteriores. A resposta final era apenas uma peça no meio de muita informação técnica.

Esse formato exige que a pessoa saiba como o agente foi instrumentado. Ela precisa entender nomes de spans, hierarquia, metadados e, muitas vezes, a linguagem de consulta da ferramenta. Isso funciona para uma investigação profunda de engenharia. Funciona muito menos quando o objetivo é revisar o comportamento de forma frequente e compartilhada.

O problema ficava ainda mais evidente fora da engenharia. Eu queria que pessoas de suporte, produto e UI/UX também conseguissem abrir uma conversa, entender o que aconteceu e avaliar se faltou contexto, se houve alucinação, se uma ferramenta falhou ou se a resposta simplesmente não resolveu a pergunta.

Ninguém deveria precisar aprender a navegar por uma árvore de traces para fazer essa revisão.

Exemplo visual recriado com dados inteiramente fictícios para demonstrar a experiência de investigação.

Evals ajudam, mas não substituem contexto

Avaliações automáticas são parte importante da solução. Nós podemos aplicar regras determinísticas, métricas específicas e LLM as a judge para procurar sinais de relevância, completude ou consistência.

Mas uma avaliação também é um modelo sobre o problema.

O resultado depende da rubrica, do contexto disponível e daquilo que decidimos medir. Um score pode apontar onde investigar, mas não transforma uma situação complexa em certeza. Até uma avaliação feita por outro LLM pode deixar passar uma nuance, aceitar uma premissa errada ou analisar apenas parte da evidência necessária.

Eu não queria trocar a dificuldade de ler traces por uma confiança cega em scores.

O que eu buscava era uma forma de combinar as duas coisas: usar sinais automáticos para priorizar e organizar a investigação, mas manter a conversa, a execução e o contexto visíveis para uma revisão humana responsável.

A conversa como unidade de investigação

O modelo mental que funcionou foi inverter a interface.

Em vez de começar pelo trace e pedir que a pessoa reconstrua a conversa, começamos pela interação que precisa ser entendida. A pergunta e a resposta ficam no centro. O trace, os spans, os eventos, as avaliações e o feedback aparecem como evidências conectadas a ela.

Um trace ainda representa o caminho de uma execução. Cada span representa uma etapa desse caminho. Um evento registra um fato relevante ocorrido durante ou depois da execução. A diferença é que esses elementos deixam de ser o destino da análise e passam a sustentar uma leitura maior.

O ponto central é a correlação. Entrada, etapas de execução, saída, avaliações automáticas, feedback humano e outros sinais permitidos precisam compartilhar uma identidade técnica. Assim, a investigação não depende de aproximar registros por horário, texto ou ordem de chegada.

Esse desenho começa antes da interface. O contrato de telemetria é parte da arquitetura do agente. Se os eventos não carregam contexto suficiente e chaves de correlação estáveis, nenhum dashboard consegue reconstruir essa história depois.

ClickHouse não é apenas uma tabela de logs

Escolhemos o ClickHouse como base analítica para eventos, traces, spans, avaliações e feedbacks. O tipo de investigação que queríamos fazer envolve filtros por tempo, agregações, recortes por atributos e correlação entre registros produzidos em etapas diferentes.

Seria possível colocar tudo em uma tabela grande e oferecer uma busca textual. Mas isso repetiria o problema dos logs soltos em uma escala maior.

No nosso caso, o ClickHouse funciona como uma base orientada a eventos e relações. Os registros têm estrutura, dimensões consultáveis e identificadores que permitem reconstruir uma interação sem depender do formato visual de um trace específico.

As consultas acontecem no servidor. Isso protege credenciais, permite aplicar regras de acesso antes de qualquer resposta e evita enviar ao navegador mais dados do que aquela investigação precisa. A interface recebe um recorte correlacionado, não acesso direto à base analítica.

O banco não é a interface e também não é uma segunda fonte de verdade para o produto. Ele é a base que permite transformar telemetria em uma leitura investigável.

Visão analítica ilustrativa com métricas e categorias fictícias.

Uma interface operacional para diferentes especialidades

A aplicação usa Next.js, React e TypeScript, mas o framework foi a parte menos difícil da decisão.

O trabalho principal estava em desenhar uma interface que não parecesse um painel genérico de métricas e também não exigisse conhecimento da instrumentação. Uma média pode indicar que algo merece atenção, mas não explica uma resposta específica. Uma lista de traces pode mostrar execuções, mas não organiza a pergunta que alguém precisa responder.

A interface precisava permitir que uma pessoa encontrasse uma conversa, lesse pergunta e resposta em sequência, consultasse os sinais relacionados e registrasse sua análise. Quando necessário, a engenharia ainda poderia descer até spans e eventos. Para outras especialidades, a complexidade técnica deveria aparecer apenas quando ajudasse a explicar o comportamento.

Isso mudou o objetivo do dashboard. Ele não existe para mostrar quantos gráficos conseguimos produzir. Existe para reduzir a distância entre uma suspeita e uma explicação verificável.

Qualidade precisa de sinais automáticos e julgamento humano

Confiabilidade técnica e qualidade percebida são dimensões relacionadas, mas diferentes.

Uma métrica automática ajuda a encontrar padrões, priorizar casos e comparar recortes. O feedback humano ajuda a perceber ausência de contexto, conclusões frágeis, respostas pouco úteis e problemas que não geraram exceção técnica.

Nenhum dos dois funciona bem sozinho.

Por isso, tratamos evals, scores e classificações como sinais para investigação, não como vereditos. LLM as a judge ajuda a ampliar a cobertura. Regras determinísticas ajudam a encontrar falhas objetivas. A revisão humana conecta esses sinais à intenção e ao contexto que nem sempre cabem em uma métrica.

Uma boa ferramenta de observabilidade precisa mostrar evidência suficiente para que alguém possa discordar do score. Essa possibilidade de contestar a avaliação é uma característica, não uma falha.

Exemplo fictício de como sinais automáticos e revisão humana podem aparecer na mesma investigação.

Privacidade e acesso fazem parte da arquitetura

Tornar a análise mais acessível não significa tornar os dados amplamente acessíveis.

Observabilidade de agentes pode envolver conteúdo e metadados sensíveis. Autenticação protege a entrada, mas a aplicação também precisa controlar autorização, limitar cada pessoa ao mínimo acesso necessário e decidir quais campos realmente precisam aparecer.

Consultas server-side, uma interface protegida e regras explícitas de acesso reduzem exposição. A mesma correlação que melhora uma investigação também aumenta a responsabilidade sobre como os dados são reunidos e apresentados.

Nem tudo que pode ser coletado deve ser exibido. Nem todo detalhe disponível precisa estar em uma tela. A melhor ferramenta não é a que mostra mais dados, e sim a que mostra o contexto necessário para uma decisão legítima e segura.

A camada própria resolve a última milha

Construir uma ferramenta própria não significou abandonar as outras.

Continuo precisando de APM para entender profundamente a execução técnica. Continuo valorizando tracing, evals, scores e LLM as a judge. Esses recursos resolvem partes importantes do problema.

A camada própria existe para resolver a parte que permaneceu aberta: transformar esses sinais em uma experiência de investigação que suporte, produto, UI/UX e engenharia consigam usar para olhar a mesma conversa e construir entendimento compartilhado.

Foi isso que mudou minha forma de pensar sobre observabilidade para IA. Ela não é apenas um recurso para quando algo quebra. É parte da capacidade do time de aprender com o comportamento real do agente, corrigir o que não aparece como exceção e evoluir o sistema com mais confiança.

Quando execução, contexto, resposta, avaliação e feedback podem ser lidos juntos, observabilidade deixa de ser um espelho passivo. Ela se torna parte do produto e do processo de engenharia.