Observabilidade do Agente de IA: Um Guia Prático para Traços, Metricas e Revisões

Observabilidade do agente IAÉ a capacidade de reconstruir o que um agente tentou, que ferramentas e dados usou, o que cada passo retornou, quanto o custo da execução, e se o resultado final foi aceitável. Um painel que mostre apenas latência e erros não é suficiente. O comportamento dos agentes é variável, por isso as equipes também precisam de rastreamento, avaliações, resultados de negócios e um caminho de revisão para conteúdo sensível.

Pesquisa e transparência: Este guia reflete: Trabalho de observabilidade de agentes da OpenTelemetry,Convenções semânticas OpenTelemetry, e o NIST AI Framework de Gestão de Riscos, revisado em 4 de Setembro de 2026. O modelo operacional abaixo é um quadro editorial original, não um índice de desempenho da Ottermind.

Que observabilidade do agente deve responder

Um sistema útil deve responder a seis perguntas sem pedir a um engenheiro para reconstruir a corrida a partir de registros não relacionados:

1. Que objetivo, instruções, modelo e insumos iniciaram a corrida?
2. Que chamadas modelo, buscas, ferramentas e aprovações ocorreram?
3. O que recebeu e voltou cada passo?
4. Onde a corrida voltou a tentar, parou, sucursalou ou falhou?
5. O resultado atendeu-se a um limiar de qualidade específico da tarefa?
6. Um revisor pode reproduzir as evidências sem expor dados restritos?

O acompanhamento tradicional das aplicações ainda é importante. Disponibilidade, latência e taxas de erro indicam se o serviço funciona. A observabilidade do agente adiciona o contexto de nível de tarefa necessário para dizer se o serviço fez o trabalho certo.

O modelo de observabilidade de quatro camadas

Não colapse estas camadas em uma única pontuação. Uma corrida rápida pode produzir um mau relatório. Um relatório fundamentado ainda pode chegar tarde demais. Um resultado aceito pode ainda expor dados que nunca deveriam ter sido rastreados.

Um esquema mínimo de eventos

Comece com um pequeno contrato de evento que todos os agentes e ferramentas podem emitir:

{
  "run_id": "run_123",
  "step_id": "step_07",
  "parent_step_id": "step_03",
  "operation": "tool.call",
  "tool": "document_search",
  "started_at": "2026-09-04T09:00:00Z",
  "duration_ms": 842,
  "status": "ok",
  "input_classification": "confidential",
  "content_recorded": false,
  "tokens": 0,
  "cost_usd": 0,
  "evaluation_refs": ["eval_19"]
}

A execução estável e os identificadores parentais tornam a sequência reconstruível. Registrar versões para instruções, modelos, ferramentas e políticas para que uma regressão possa ser ligada a uma mudança. Mantenha as instruções e as saídas brutas opcionais: os metadados são frequentemente suficientes para análise operacional, enquanto a captura de conteúdo cria obrigações de privacidade e retenção.

Mantenha quatro identificadores distintos

• workflow_idnomear o produto ou processo comercial duradouro.
• workflow_versionIdentifica a configuração testada de instruções, ferramentas, modelos e regras.
• run_idliga cada passo numa execução.
• thread_idligações relacionadas corre através de uma conversa ou tarefa mais longa.

Não reutilize um ID de usuário como um thread ou ID de execução. Mantenha a identidade num campo controlado separadamente e use referências pseudónimas onde a análise não requer identificação direta. Apegar o artefato ou o documento de identificação dos registros comerciais somente quando a política o permitir.

Adicione versões de implantação, ambiente, experimento e conjunto de fontes. Estas dimensões respondem se um fracasso começou após uma liberação, afeta uma coorte ou depende de uma coleção de conhecimento obsoleta.

Métricas que revelam o comportamento do agente

Rastrear um conjunto compacto antes de adicionar dezenas de gráficos:

• Taxas de conclusão e abandono por tipo de tarefa;
• a latência média e tardia para a execução e para cada ferramenta;
• Taxas de falha da ferramenta, de retomada e de retrocesso;
• Passos, tokens e custo por resultado aceito;
• A base ou a cobertura de citações, caso sejam importantes as provas;
• Tempo de correção humana e razões de rejeição;
• Blocos de políticas, pedidos de aprovação e recusas de permissão.

Segmentar métricas por versão do fluxo de trabalho e tarefa representativa. As médias agregadas podem esconder que um tipo de documento ou uma integração de ferramentas falha repetidamente.

Seguir uma corrida de meta a resultado

Considere um agente de pesquisa que foi convidado a preparar um resumo do concorrente a partir de dez fontes aprovadas. O documento final contém o preço errado para um concorrente. Um rastro útil deve permitir que o revisor avance para trás durante a corrida:

1. O registro de resultados mostra que o relatório foi rejeitado e marca o erro de preços.
2. O período de síntese final identifica a linha de fixação de preços extraída que forneceu a sentença.
3. O período de recuperação mostra que um artigo de ajuda arquivado ficou acima da página de preços atual.
4. Os metadados de origem não mostram nenhum campo de data efetiva e nenhuma regra que prefira páginas oficiais atuais.
5. A versão do fluxo de trabalho mostra que uma mudança recente de recuperação removeu um filtro de data.

A ação corretória não é simplesmente "usar um modelo melhor". Restaurar a regra de prioridade de origem, adicionar a execução rejeitada a um conjunto de avaliação, testar outras alegações sensíveis ao tempo e monitorar a recuperação de páginas arquivadas. A observabilidade cria valor quando liga um defeito visível a uma mudança que pode ser testada.

Sem um rastreamento vinculado, a equipe pode editar o preço único, tentar novamente a tarefa ou modificar o prompt sem saber se a falha de recuperação subjacente permanece.

Desenho abrange decisões

Um traço torna-se ilegível quando cada função auxiliar é um espaço e incompleto quando toda a corrida é um espaço. Unidades de trabalho significativas de instrumentos:

• A admissão dos objetivos e a classificação das políticas;
• Criação de planos ou seleção de rotas;
• cada invocação modelo;
• Cada consulta de recuperação e conjunto de fontes devolvidas;
• Todas as chamadas e resultados das ferramentas externas;
• O estado ou a memória lê e escreve;
• Re-tentar, recuar e parar as decisões;
• Pedidos e respostas de aprovação humana;
• Criação e validação de artefatos;
• Entrega final e resultado do utilizador.

Use relações entre pais e filhos para trabalho aninhado e links para tarefas assíncronas que compartilham uma causa, mas não uma pilha de chamadas diretas. Dê a cada intervalo um nome de operação estável. Coloque valores variáveis como nome da ferramenta, versão do fluxo de trabalho e classe de documento nos atributos para que possam ser filtrados sem criar milhares de nomes métricos.

Registre o contexto suficiente, não o raciocínio oculto

O objetivo é capturar entradas, saídas, decisões e transições de estado observáveis. Não dependa da cadeia privada de pensamento ou do raciocínio interno verbal. Um campo de rota como selected_tool=document_search, mais as alternativas permitidas e o resultado da ferramenta, é mais útil e governável do que uma transcrição de raciocínio sem restrições.

Para uma decisão fracassada, registar a política ou avaliador que deveria tê-la regido, as evidências disponíveis naquele momento e a ação resultante. Isso suporta o depuração sem transformar cada vestígio em uma narrativa sensível.

Construir avaliações a partir de modos de falha reais

As métricas genéricas, como a fluência e a utilidade, raramente são suficientes. Define as dimensões da avaliação do contrato de fluxo de trabalho.

Para o resumo da investigação, as dimensões úteis podem incluir:

Utilize três etapas de avaliação:

1. **Regressão pré-lançamento:**casos fixos executados antes de uma versão do fluxo de trabalho ser enviada.
2. **Amostragem da produção:**Uma percentagem definida de corridas reais recebe uma revisão automática ou humana.
3. **Promoção de falhas:**As corridas rejeitadas, corrigidas ou incomuns tornam-se casos de regressão rotulados.

Manter as instruções de avaliação, os modelos de classificação, as rubricas e os conjuntos de dados em versão. Quando o juiz mudar, não compare suas pontuações com uma linha de base antiga como se a medição permanecesse constante.

Definição dos objetivos de serviço do fluxo de trabalho

O tempo de atividade da aplicação não descreve se um agente termina um trabalho útil. Adicionar indicadores de serviço de nível de tarefa:

• Percentagem de corridas elegíveis que produzam um artefato;
• Percentagem aceite sem correção material;
• Tempo desde a solicitação até ao resultado pronto para revisão;
• percentagem aumentada para o proprietário correto;
• O custo máximo de um resultado aceito;
• Citação ou cobertura de provas para trabalhos apoiados por fontes;
• Taxa de conclusão conforme às políticas.

Criar objetivos por classe de fluxo de trabalho. Um memorando de pesquisa de cinco minutos e uma resposta de apoio de dez segundos não devem compartilhar um objetivo de latência. Excluir entradas inválidas apenas através de uma regra documentada, ou as equipes podem fazer com que a confiabilidade pareça melhor reclassificando falhas difíceis.

Alerta sobre os sintomas que as pessoas podem agir

Evite chamar alguém por cada pontuação de avaliação baixa. Os alertas devem identificar uma resposta operacional limitada.

Use painéis para tendências, bilhetes para defeitos e páginas para incidentes urgentes. Se cada flutuação de avaliação despertar um operador, a fadiga de alerta ocultará o evento que realmente precisa de intervenção.

Escolher uma estratégia de amostragem

A captura completa de metadados pode ser suficientemente barata para cada execução, enquanto a retenção completa de conteúdo e a avaliação baseada em modelos não são. Combinar as regras de amostragem:

• Amostragem aleatóriaEstima a qualidade normal sem selecionar apenas falhas dramáticas;
• Amostragem de riscoRevisão de mais operações a partir de fluxos de trabalho consequentes;
• Amostragem de eventosMantém erros, bloqueios de políticas, ciclos caros e rejeições dos utilizadores;
• Amostragem de mudançasAumente a cobertura após a publicação de um modelo, de um pedido, de uma recuperação ou de uma ferramenta;
• Amostragem de segmentosAssegura a aparição de línguas raras, tipos de documentos, funções de utilizador e casos de ponta;
• Amostragem consistente de rastreamentomantém a corrida completa em várias etapas, em vez de distâncias desconectadas.

Documentar o denominador. Se um painel de instrumentos mostrar uma taxa de aprovação de 95% apenas de corridas concluídas com êxito, o trabalho abandonado e bloqueado desapareceu da medição.

Revisar a amostra em busca de pontos cegos. Uma regra que mantém apenas corridas lentas ou fracassadas não pode estimar a qualidade diária, enquanto a amostragem aleatória pura pode perder raros incidentes de alto impacto. Preservar os incidentes confirmados independentemente da amostragem de rotina no âmbito da política de registros relevante.

Reconciliar a telemetria com os comentários dos utilizadores

Conecte a rejeição explícita, correção, retest, escalada, bilhete de suporte e sinais de artefato aceitos para a corrida. Não deduzir a satisfação de um usuário terminar a conversa; eles podem ter abandonado.

Criar razões estruturadas de feedback, como fonte errada, exigência faltante, informação obsoleta, ação insegura, formato ruim, muito lento ou caro demais. Mantenha o texto livre opcional para o contexto, mas evite que todas as análises dependam da leitura manual.

Quando o feedback contradiz um avaliador automatizado, inspecione o caso. O usuário pode estar errado, o avaliador pode ser mal especificado, ou o fluxo de trabalho pode otimizar uma rubrica técnica que não corresponde ao resultado real. Estes desentendimentos são valiosos casos de avaliação.

Faça uma revisão de incidentes de agentes

A revisão dos incidentes deve ser impecavel e rastreável:

Impacto do utilizador e corridas afetadas:
Tempo e sinal de detecção:
Fluxo de trabalho, prompt, modelo, ferramenta e versões de políticas:
Comportamento esperado:
Seqüência observada:
Fonte, estado ou permissão envolvidos:
Por que as avaliações existentes não o alcançaram:
Contenção imediata:
Mudança corretória e proprietário:
Os casos de regressão foram adicionados:
Monitoramento das alterações:
Data de acompanhamento:

Separar o erro desencadeador dos contribuintes sistémicos. Um modelo pode emitir um argumento inválido, mas o contrato da ferramenta também pode aceitá-lo, o ciclo de retest pode repeti-lo e a avaliação pode ignorar os resultados da ferramenta. A solução apenas da primeira falha visível deixa o sistema frágil.

Realizar observabilidade em quatro etapas

Fase 1: Reconstruir uma única corrida

Instrumento um fluxo de trabalho limitado de ponta a ponta. Confirmar que um engenheiro e um revisor de domínio podem explicar de forma independente uma corrida falhada do rastro.

Fase 2: Conectar a qualidade

Anexar validações deterministas, rótulos de revisores e resultados aceitos ou rejeitados. Construa um pequeno conjunto de regressão a partir de falhas observadas.

Fase 3: Operação a volume de produção

Defina a amostragem, a retenção, a redação, os painéis de controle e as alertas a serem executadas. Medir o custo da telemetria e verificar que o rastreamento não expõe dados restritos.

Fase 4: Melhoria sistemática

Use clusters de falhas para priorizar mudanças, comparar versões em conjuntos de dados fixos e confirmar o efeito na produção. Revisão de métricas obsoletas e remoção de telemetria que já não impulsionam uma decisão.

Um modelo semanal de revisão

Fluxo de trabalho e versão:
Resultados esperados do utilizador:
Corridas representativas bem sucedidas:
Corridas falhadas ou corrigidas:
Modos de falha máximos:
Mudanças desde a revisão anterior:
Latência e mudança de custos:
Mudança de avaliação:
Incidentes de privacidade ou de permissão:
Uma experiência para a semana que vem:
Proprietário e data de revisão:

Falhas de amostra, não apenas médias. Revise pelo menos uma corrida limpa, uma corrida cara, um resultado rejeitado e uma corrida que exigisse intervenção humana. Esse conjunto expõe o comportamento que um painel de status verde não consegue.

Limites de privacidade e segurança

Os dados de observabilidade podem conter instruções, nomes de arquivos, passagens recuperadas, argumentos de ferramentas, credenciais, dados pessoais e decisões comerciais. Classificá-lo como dados de produção. Redigir segredos antes da exportação, separar o conteúdo dos metadados, restringir o acesso, definir a retenção e registrar quem inspecionou vestígios sensíveis.

Criar pelo menos três modos de captura. Um modo com apenas metadados registra o tempo, o status, as versões, as classificações e os hashes. Um modo editado retém um conteúdo limitado após a filtragem automática. Um modo de diagnóstico restrito capta o conteúdo aprovado por um curto período com acesso designado. O fluxo de trabalho, e não um desenvolvedor individual, deve selecionar o modo da classificação dos dados.

Teste de redação antes da telemetria sair do processo. Uma configuração de backend não pode proteger um segredo que já foi transmitido. Verifique também os dados derivados: títulos de documentos, argumentos de ferramentas, incorporações, mensagens de erro e explicações do avaliador podem revelar conteúdo sensível mesmo quando o prompt principal é removido.

Lista de verificação de vencimento

[ ] Cada rodada de produção tem fluxos de trabalho estáveis e identificadores de versões.
[ ] Modelo, recuperação, ferramenta, estado, aprovação e artefatos passos estão conectados.
[ ] A captura de conteúdo sensível segue uma regra documentada de classificação.
[ ] Os resultados aceitos, corrigidos, rejeitados e abandonados juntam-se a vestígios.
[ ] As avaliações refletem o contrato de tarefa e são versionadas.
[ ] As corridas de produção falhadas podem ser promovidas em conjuntos de dados de regressão.
[ ] Alertas têm um proprietário e uma primeira resposta definida.
[ ] A retenção, o acesso, a exportação e a exclusão foram testados.
[ ] O custo inclui o armazenamento e a avaliação de telemetria, e não apenas os tokens de modelo.
[ ] Um revisor de domínio pode reconstruir um resultado sem ajuda de engenharia.

Para um modelo de ameaça mais amplo, use o Lista de verificação de segurança de agentes de IA. Para os limites dos componentes e os contratos de orquestração, ver o Guia de Arquitetura de Agentes de IA.

FAQ

Qual é a diferença entre o monitoramento de agentes de IA e a observabilidade?

Relatórios de monitoramento de sinais conhecidos, como falhas, latência e custo. A observabilidade dá evidências conectadas suficientes para investigar o comportamento que não predizes, incluindo escolhas de ferramentas, retries, contexto, avaliações e correções humanas.

Devíamos armazenar todas as solicitações e respostas?

• Não, não, não. Armazenar o mínimo de dados necessários para efeitos operacionais e de auditoria. Preferir metadados e hashes quando possível, editar segredos, limitar a captura de conteúdo por classificação de tarefa e definir um período de retenção.

Com que métrica deve começar uma nova equipa?

Comece com a taxa de conclusão aceita e o tempo de correção para um fluxo de trabalho limitado. Adicione métricas de custo, latência e modo de falha em torno desse resultado.

A observabilidade substitui a avaliação offline?

• Não, não, não. Testes de avaliação offline de casos conhecidos antes da liberação. A observabilidade da produção mostra como as entradas reais, as ferramentas e os usuários se comportam após a liberação. Equipes confiáveis usam ambas.

Quanto tráfego de produção deve ser recolhido?

Não existe percentagem universal. Capturar metadados de baixo risco em termos gerais, e escolher o conteúdo e a amostragem de avaliação com base no volume, risco, custo e frequência de falhas. Mantém sempre os incidentes confirmados no âmbito da política aprovada.

Quanto tempo devem ser mantidos os vestígios?

Manter-se-ão apenas enquanto for exigido pela depuração, avaliação, auditoria ou finalidade contratual. Utilize períodos mais curtos para conteúdo bruto, períodos mais longos para métricas agregadas e reservas documentadas para incidentes confirmados.

Quem deve verificar os vestígios do agente?

Os engenheiros revisam falhas de execução e integração; os proprietários de domínios revisam a qualidade da tarefa; as equipes de segurança e privacidade revisam incidentes relevantes. O acesso baseado em funções deve impedir a navegação ampla de conteúdos sensíveis.

A observabilidade pode melhorar as indicações por si só?

Ele fornece provas, não uma solução automática. Use aglomerados de falhas para propor uma mudança, teste-a em casos de versão e confirme que ganhos não criam regressões em outros lugares.

Qual é o primeiro painel a ser construído?

Para um fluxo de trabalho, mostre rodadas elegíveis, conclusão aceita, razões de rejeição, tempo de correção, latência, custo, escalação e versão atual do fluxo de trabalho. Ligue todos os agregados a corridas inspecionáveis.

O feedback dos utilizadores é suficiente para medir a qualidade?

• Não, não, não. O feedback é valioso, mas incompleto e auto-selecionado. Combine-o com validações de tarefas, amostragem representativa, revisão de domínio e resultados observados.

Devem sempre ser mantidas corridas falhadas?

Manter as evidências necessárias para investigar e cumprir as políticas, mas ainda aplicar regras de minimização, acesso e retenção de dados. Uma falha não justifica automaticamente o armazenamento indefinido de conteúdos sensíveis.

Use o Ottermind para executar um fluxo de trabalho delimitado e fundamentado em fontes, revisar o artefato resultante e registrar as correções que formarão seu primeiro conjunto de avaliação.