Este é um dos artigos de uma série que estamos publicando como parte da Langfuse Academy, onde percorremos todo o ciclo de vida da engenharia de IA. Se você é novo na série, The AI Engineering Loop é o melhor lugar para começar.
Um breve resumo do AI Engineering Loop
O AI Engineering Loop é como as equipes melhoram continuamente os sistemas de IA. Ele conecta o que está acontecendo em produção (tracing, monitoramento) à iteração estruturada durante o desenvolvimento (datasets, experimentos, avaliação). Cada melhoria implantada gera novos dados, e as equipes percorrem esse processo continuamente.
Você pode ler mais sobre isso aqui.
Como o tracing se encaixa no loop
O software tradicional é amplamente determinístico, as execuções seguem um formato predefinido. Para aplicações LLM, esse não é o caso. As execuções de agentes podem ser confusas, estamos lidando com comportamento emergente com entradas e saídas ricas e inesperadas, e ordem de execução. Você precisa de algo mais para acompanhar o comportamento do seu agente: traces.
O tracing é central para todo o loop de melhoria. Cada outra etapa (revisão, construção de datasets, execução de experimentos, avaliação) opera sobre traces.
Se você já está familiarizado com conceitos tradicionais de observabilidade, parte do que segue pode parecer repetitivo. Sinta-se à vontade para folhear ou pular adiante.
A anatomia de um trace
Um trace pode ser tão complexo ou simples quanto sua aplicação exigir, mas todos os traces compartilham a mesma estrutura básica. É composto por um conjunto de observations que mapeiam o caminho que seu agente percorreu.
Uma observation é uma única etapa no processo. Ela tem uma entrada, uma saída, tempo de início/fim e metadados sobre o que aconteceu durante essa etapa.
Hierarquia
Um trace tem uma estrutura hierárquica em árvore. Aninhadas dentro dele estão observations que podem conter outras observations, formando uma estrutura pai-filho que espelha a execução real da sua aplicação de IA.
Você pode ver o que aconteceu em qual ordem e quais etapas fizeram parte de qual etapa maior.
Dados da observation
Entrada e saída. Toda observation pode ter uma entrada e uma saída. Na maioria das vezes terá ambas; em alguns casos específicos pode ter apenas uma das duas. É importante para a interpretabilidade que você defina uma entrada e/ou saída que faça sentido para o tipo de ação que está ocorrendo naquela observation.
Tipos de observation. Para facilitar a diferenciação entre operações, você verá diferentes tipos de observations. Cada tipo de observation é usado para capturar diferentes tipos de interações de um agente.
Os tipos de observation facilitam a leitura de traces e a filtragem. Em um trace com 20 observations, conseguir identificar rapidamente as chamadas LLM economiza tempo.
Custo, latência, uso de tokens
Além da entrada e saída, existem alguns atributos nas observations que são requisitos básicos em qualquer aplicação LLM: custo, latência e uso de tokens. Eles são registrados por observation e agregados no nível do trace.
Traces vs sessões
Na maioria das vezes, você não veria a execução completa do ciclo de vida de um agente em um único trace. Traces podem ser agrupados em sessions. Mas onde traçar a linha entre um trace e uma session?
Uma regra geral é: um trace corresponde a uma invocação do seu sistema, tipicamente uma chamada de API ou uma execução de agente. Uma session então agrupa múltiplos traces, por exemplo, todas as rodadas em uma conversa de múltiplas rodadas.
Por onde começar
Se você está apenas começando, concentre-se em instrumentar um fluxo de trabalho real de ponta a ponta antes de tentar cobrir todos os caminhos possíveis.
- Configure o tracing para um caminho de requisição importante em sua aplicação.
- Certifique-se de que cada observation capture entrada, saída e metadados úteis para a etapa que representa.
- Revise manualmente alguns traces reais para confirmar que a estrutura é fácil de seguir e útil para depuração.
O que vem a seguir
Depois que você vir traces, pode passar para a próxima etapa: monitoramento. O monitoramento é o que conecta traces ao loop de melhoria e iteração do seu agente.
