Conceitos principais para observabilidade de agentes
Observabilidade e qualidade do agente é estruturada em torno de um loop repetitivo: encontre um problema em seu agente, meça-o sistematicamente, corrija-o, confirme a correção e monitore para que ele não ocorra novamente. Cada conceito nesta página é parte desse loop.
Esta página explica cada peça e como elas se relacionam.
O loop de qualidade
Cada seção abaixo mapeia para um estágio neste loop.
Rastreamentos e spans
Um rastreamento é um registro estruturado de uma execução completa do seu agente — as entradas e saídas de nível superior, cada etapa intermediária (chamadas de LLM, consultas de recuperador, invocações de ferramentas), a latência e quaisquer erros. Os rastreamentos são a matéria-prima que alimenta todas as outras etapas do ciclo.
Internamente, um rastreamento é uma árvore de spans . Cada span representa uma operação: ele registra o que entrou, o que saiu, quanto tempo demorou e todos os metadados. O span raiz representa a solicitação completa do agente; os spans filhos representam suboperações ocorridas durante essa solicitação.
Os rastreamentos são armazenados no Unity Catalog como tabelas Delta (recomendado). Isso oferece acesso governado, capacidade de consulta em SQL e nenhum limite de armazenamento por experimento — o mesmo modelo de governança de qualquer outra tabela do UC. Uma vez armazenados, você pode explorar rastreamentos na interface do usuário (UI), consultá-los com SQL ou fazer perguntas em linguagem natural usando o Genie Code.
Relacionado: Instrumente seu agente · View rastreamentos na interface do usuário · Pesquise e query de rastreamentos
Sessões
Uma session é uma tag que agrupa rastreamentos relacionados de uma conversa de vários turnos: defina mlflow.trace.session em cada rastreamento. O agrupamento de sessões permite avaliar a qualidade da conversa de ponta a ponta, e não apenas turno a turno.
Avaliações: feedback e expectativas
Uma assessment é uma medição de qualidade associada a um rastreamento. Há dois tipos:
Tipo | Who adds it | O que ele captura |
|---|---|---|
Feedback | Avaliadores, usuários finais, especialistas de domínio | Um julgamento de qualidade: aprovação/reprovação, pontuação numérica ou comentário em texto livre. Exemplos: um |
Expectativas | Domain experts | A saída correta para uma determinada entrada — verdade fundamental. Exemplos: a resposta esperada para uma pergunta; os fatos necessários que uma resposta deve conter. |
O feedback é o sinal principal no trabalho de qualidade de rotina; você não precisa de expectativas para obter valor do MLflow. As expectativas são opcionais, mas permitem a pontuação mais precisa: juízes como Correctness comparam a resposta do agente com uma resposta considerada correta.
Relacionado: Anotações do desenvolvedor · Feedback de especialistas · Coletar feedback do usuário
Avaliadores
Um avaliador é uma função que avalia um rastreamento e retorna uma avaliação de feedback. Todo avaliador segue o mesmo contrato: recebe um rastreamento → extrai os campos relevantes → avalia → retorna Feedback. O mesmo avaliador funciona na avaliação offline e no monitoramento de produção em tempo real — você escreve a lógica de qualidade uma vez e ela se aplica em todos os lugares.
Types of scorers
Tipo | Como avalia | Quando usar |
|---|---|---|
Juízes de LLM integrados | Avaliadores pré-construídos alimentados por LLM para dimensões comuns: correção, relevância, segurança, fundamentação, adesão às diretrizes e muito mais. | Você deseja cobertura de qualidade imediata sem escrever código personalizado. |
Juízes de LLM personalizados | Um juiz de LLM com um prompt de avaliação personalizado e uma rubrica de pontuação definida por você. | Os avaliadores integrados não cobrem seus critérios específicos de domínio ou você precisa de uma pontuação refinada (notas numéricas, categorias personalizadas). |
Avaliadores baseados em código | Uma função Python determinística — correspondência exata, validação de formato, verificações de latência, regras de negócios. | Você precisa de lógica precisa e reproduzível que não exija um modelo de linguagem. |
Juízes vs. avaliadores
Judges (for example, mlflow.genai.judges.is_correct) evaluate text based on specific criteria — but they don't know how to read a trace. Scorers are the adapters: they extract the relevant fields from a trace (request, response, retrieved context, …) and pass them to a judge or to custom logic. Quando você usa um avaliador integrado diretamente em scorers=[Correctness()], o MLflow o encapsula em um pontuador automaticamente.
Relacionado: Visão geral dos pontuadores · Juízes integrados · Juízes de LLM personalizados · Pontuadores baseados em código
Datasets e execuções de avaliação
Conjuntos de dados de avaliação
Um dataset de avaliação é uma coleção curada e versionada de casos de teste. Cada registro possui:
inputs: o que enviar para o agenteexpectations(optional) : the correct output, used by scorers that need ground truth
Você constrói datasets selecionando rastreamentos representativos de produção ou desenvolvimento, escrevendo casos do zero ou importando de fontes externas. Os datasets são versionados para que você possa acompanhar como seu conjunto de testes cresce ao longo do tempo.
Relacionado: Criar um dataset de avaliação
Execuções de avaliação
Uma evaluation execução é o resultado de chamar mlflow.genai.evaluate(). Forneça um dataset e uma lista de avaliadores; ele:
- Executa seu agente em cada entrada no dataset, capturando rastreamentos.
- Aplica cada avaliador a cada rastreamento, produzindo avaliações de feedback.
- Armazena taxas de aprovação agregadas e métricas junto com os rastreamentos individuais.
Use execuções de avaliação para responder: esta alteração melhorou a qualidade? e houve alguma outra regressão? Compare execuções lado a lado para acompanhar o progresso entre as iterações. As execuções de avaliação são um tipo especial de MLflow Run e podem ser consultadas programaticamente.
Relacionado: Executar uma avaliação · Como a avaliação funciona
Monitoramento de produção
Monitoramento de produção programa os avaliadores para executar automaticamente no tráfego de agentes ao vivo. Anexe um avaliador ao seu agente implantado e o serviço de monitoramento pontua o tráfego do agente ativo de forma contínua, gravando avaliações de feedback de volta no mesmo rastreamento.
O formato de feedback é idêntico ao da avaliação offline, portanto as tendências de qualidade são diretamente comparáveis entre dev e prod. O monitoramento da produção fecha o ciclo: ele revela novas falhas no tráfego em tempo real, que você seleciona para o seu dataset de avaliação para corrigir na próxima iteração.
Relacionado: Visão geral do monitoramento de produção · Começar e configurar o monitoramento
Como tudo se encaixa
Each concept serves a specific stage of the quality loop:
Etapa | Conceito(s)-chave |
|---|---|
Rastrear seu agente | Traces, spans |
Encontrar um problema | Rastreamentos, sessões, interface do usuário e consultas SQL, análise em linguagem natural via Genie Code |
Colete feedback e faça a curadoria de um dataset | Assessments (feedback + expectations), evaluation datasets |
Escreva um pontuador, corrija o agente e avalie a correção | Pontuadores, execuções de avaliação |
Monitorar a produção | Monitoramento de produção, avaliadores agendados |
O ciclo os conecta: o monitoramento de produção identifica novos casos de falha → você os seleciona em um dataset → você escreve ou ajusta um avaliador → você avalia para confirmar a correção → o agente aprimorado vai para a produção → o monitoramento observa o próximo problema.
Os passos seguintes
- Instrumente seu agente — adicione rastreamento ao seu agente em poucas linhas
- Observe e encontre problemas — explore e analise rastreamentos capturados
- Criar um dataset de avaliação — organize rastreamentos em casos de teste estruturados
- Execute uma avaliação — pontue seu agente em relação a um dataset
- Configure o monitoramento de produção — detecte regressões de qualidade no tráfego ativo