Observabilidade do agente AI: Medir o progresso útil, não apenas a atividade

A observabilidade do agente AI é a capacidade de explicar o que um agente fez a partir de evidências externas: vestígios, registros, métricas, eventos de ferramentas, chamadas de modelo, latência, tokens e custo. Essa prova é necessária, mas não é um veredicto de saúde. Um rastreamento pode ser completo enquanto o ficheiro solicitado estiver ausente. Uma chamada de ferramenta pode ser bem sucedida enquanto o agente repete o mesmo passo. Uma corrida silenciosa pode estar à espera de aprovação. A resposta prática é manter a telemetria e adicionar uma pequena camada de decisão acima dela. Para cada tarefa, observe cinco coisas juntas: acessibilidade, delta de progresso útil, dependências declaradas, verificações deterministas de resultados e custo na mesma janela. Avalia os nessa ordem antes de alertar ou recuperar qualquer coisa. Este guia transforma essa regra em uma fixação executável de cinco casos. É intencionalmente neutro no tempo de execução: o mesmo raciocínio pode ficar acima dos intervalos de OpenTelemetry, eventos do código Claude, um registro de execução OpenClaw ou um agente personalizado. Um rastro prova o que correu, não o que mudou. O Convenções semânticas OpenTelemetry para os espaços de agentes da GenAI atual define operações para criar e invocar agentes, invocando fluxos de trabalho, planejamento e execução de ferramentas. O documento é marcado Development , o que importa quando você deseja um esquema de longa duração: use as convenções onde elas se encaixam, mas isola atributos sensíveis à versão por trás da sua própria camada de normalização. A telemetria do tempo de execução já está a tornar se mais detalhada. Documentação de acompanhamento do Código Claude descreve métricas, eventos e traços distribuídos beta. Sua árvore de rastreamento pode incluir uma interação, pedidos de modelo, chamadas de ferramentas, tempo bloqueado em uma decisão do usuário e execução de ferramentas. Os campos documentados incluem duração, tokens, custo estimado, tamanho do resultado da ferramenta e success . Esses campos respondem a perguntas valiosas: O tempo de corrida respondeu? Que modelo e ferramentas funcionaram? Um corpo específico de ferramentas devolveu um erro? Quanto tempo demorou a espera da permissão e a execução? Quantos tokens e dólares consumiu a corrida? Não definem o sucesso da sua tarefa. Um comando shell que retorna o código de saída 0 prova que o comando foi concluído sob seu próprio contrato. Não prova que um artigo seja público, que um sitemap contenha o seu URL, que uma solicitação de puxamento seja aprovada pela CI ou que um registro de clientes tenha chegado ao sistema pretendido. As aplicações podem adicionar esses controles, mas um campo genérico de sucesso de ferramentas não pode inventar los. A actividade e o progresso podem, portanto, avançar em direções opostas. 19 chamadas de ferramenta bem sucedidas sem delta de saída podem ser um loop. Duas chamadas de ferramentas seguidas de silêncio podem ser uma espera saudável para um crítico. Uma última mensagem dizendo done pode ser um falso sucesso se o artefato prometido estiver ausente. Construir uma janela de saúde a partir de cinco sinais Escolha uma janela de observação específica da tarefa antes de analisar o resultado. Cinco minutos podem ser adequados para uma pequena edição de código; uma hora pode ser razoável para um trabalho de pesquisa programado. Evite um limiar global que marque todas as operações longas como presas. Dentro dessa janela, recolha cinco sinais: O sinal Evidências mínimas O que impede Accessibilidade Idade de batimento cardíaco, resposta ao processo/sessão, ou recibo de execução do agendador Tratar um tempo de execução inacessível como uma falha de raciocínio Progresso útil um delta monótono específico de tarefa confundir atividade repetida com movimento Dependência A razão de espera, o proprietário e o prazo de devolução Reaproveitar um trabalho que necessite legitimamente de uma pessoa ou de um sistema externo Resultados Predicado determinista para o resultado prometido aceitação de uma mensagem de conclusão sem entrega Custo tokens, chamadas, tempo ou dinheiro na mesma janela Ignorando os costosos retestes que não criam progresso. Os progressos úteis devem ser concretos. Para um agente de codificação, pode ser um resultado de teste alterado, um novo compromisso ou uma redução do número de falhas de teste. Para um editor, pode ser um ID de projeto do CMS, depois uma correspondência de API pública, depois um URL ao vivo no sitemap. Para um agente de apoio, pode ser uma transição de bilhete validada e não outro modelo de resposta. Preferimos um predicado de resultado determinista quando existe: Use um avaliador apenas quando o resultado não possa ser verificado mecanicamente, e armazenar sua rubrica, versão e incerteza. Não coletem a cadeia oculta de pensamentos como atalho. As seleções de ferramentas, planos explícitos, saídas, timestamps e mudanças de estado fornecem evidências operacionais sem exigir raciocínio privado. O custo pertence à janela, mas o custo por si só não é saúde. Pode se esperar dez dólares que produzam uma migração verificada. Cinquenta centavos gastados repetindo uma busca inalterada pode ser a anomalia. Uma medida derivada útil é: O max evita a divisão por zero; não torna o progresso zero saudável. Alerta separadamente quando o progress delta == 0 e o custo continuarem a aumentar. Classifique o trabalho, a espera, o bloqueio, o sucesso inacessível e o falso A ordem da decisão é importante. Verifique a acessibilidade primeiro. Então, honre uma dependência explícita que ainda está dentro do seu tempo devido. Verifique uma conclusão pretendida com o resultado predado antes de aceitá lo. Só então interpretar o progresso e o tempo passado. Aqui está uma fixação completa do NDJSON. Salva o como health window fixture.ndjson : Execute este classificador com Node.js: Output esperado: A fixação torna a tese falsificável. Uma regra ingênua como a tool calls 0 marca tanto a run stuck quanto a run false success como ativa. Uma regra baseada apenas no silêncio marca o run waiting como insalubre. A regra dos cinco sinais os separa porque preserva a dependência e a evidência do resultado. O exemplo é um esqueleto de decisão, não um modelo de pontuação universal. O código de produção também precisa de frescura, confiança, identidade fonte e um caminho uncertain quando os sinais discordam. Mapa de cada estado para uma resposta limitada A classificação existe para evitar a ação errada, não para decorar um painel. Estado Requisitos de prova Resposta por defeito Trabalhar Recentemente alcançável e progresso positivo delta Deixe o em paz; amostra novamente mais tarde Esperando dependência, proprietário e prazo de vencimento não expirado notificar a pessoa responsável uma vez; não retomar a etapa bloqueada Enfiado . Acessível, além da sua janela, sem dependência, sem progresso delta inspeccionar o passo repetitivo; preparar uma reversível tentativa ou empurro dentro dos limites Falso sucesso conclusão declarada, resultado determinista falhado reabrir a tarefa e relatar o predicado faltante; não chamá lo completo Inalcançável batimentos cardíacos obsoletos ou falha no contato com o tempo de execução Verificar a disponibilidade do host/tipo de execução antes de alterar as instruções Incerto Evidências faltantes ou contraditórias recolher o sinal ausente ou pedir; não automatizar a recuperação Esta separação tem um precedente útil fora dos sistemas AI. Kubernetes distingue as sondas de inicialização, vitalidade e prontidão porque o processo existe e o serviço deve receber tráfego são decisões diferentes. A sua documentação também adverte que sondas de vida mal projetadas podem causar falhas em cascata através de reinicializações desnecessárias. A analogia tem um limite: um agente AI não é um Pod, e o progresso útil é dependente da tarefa. A lição transferível é mais estreita. Não permita que um sinal verde ou vermelho ambíguo autorize todas as intervenções. Para a recuperação ativa, fixar limites à ação: Uma reapreciação, não um ciclo de reapreciação ilimitado; um prazo e um custo máximos transcurridos; um passo reversível; Um limite de aprovação explícita para ações destrutivas ou externas; Uma verificação pós ação do progresso ou do resultado. A conclusão do comando não é recuperação. Limpar o incidente só depois das mudanças de estado esperadas. Instrumentar o contrato, não todos os pensamentos Um registo de saúde normalizado compacto pode ficar ao lado dos seus dados de rastreamento existentes: Mantenha as referências de evidências controladas pelo acesso e redige segredos, instruções, cargas úteis de ferramentas brutas e caminhos locais absolutos, a menos que sejam estritamente exigidos. O registo médico deve indicar o que foi verificado e onde os operadores autorizados podem inspecioná lo; não deve tornar se uma segunda cópia de telemetria sensível. Versão quatro coisas explícitamente: 1. O adaptador de tempo de execução que normalizou as provas; 2. A definição do progresso; 3. o predicado de resultado; 4. As regras e os limiares do classificador. Sem essas versões, um comando de teste alterado ou um entregable renomeado pode parecer uma regressão súbita do agente. Saber onde o método termina A parte difícil é não recolher outro espaço. É a definição honesta de progressos úteis e do resultado prometido. Algumas tarefas não têm uma medida monótona de progresso. Um agente de pesquisa pode descartar uma hipótese fraca e retornar a um estágio anterior; isso pode ser um trabalho valioso mesmo que um contador cai. Algumas dependências não revelam um prazo de entrega confiável. Alguns resultados exigem um julgamento, em vez de uma soma de verificação. Nesses casos, preserve as provas e informe o uncertain . Não fabrique precisão com uma pontuação de saúde universal. Também separar os controlos de saúde on line da avaliação offline. Os conjuntos de dados offline podem revelar se uma nova versão de agente é mais precisa em casos conhecidos. A janela de saúde ao vivo responde a uma pergunta diferente: esta corrida em particular é acessível, em movimento, à espera legítima, ou está perdendo seu resultado agora? Normalmente, precisas de ambos. Comece com um fluxo de trabalho consequente. Defina um delta de progresso e um predicado de resultado determinista. Reproduzir casos conhecidos de trabalho, espera, presos, inacessíveis e falsos sucessos. Só depois que as classificações coincidem com a realidade deve depender delas uma alerta ou uma acção de recuperação limitada. A Sidewisp está atualmente em prévia privada. Seu site público e sistema de artigos estão ao vivo, mas a coleta de agentes de produção saúde, adaptadores de tempo de execução e recuperação geralmente não são enviados. A direção do produto é uma camada de saúde que torna mais fácil agir sobre as fronteiras de evidência, frescura, confiança e aprovação sem substituir o tempo de execução do agente. Referências primárias OpenTelemetry: Convenções semânticas para agentes e abrangências quadro da GenAI trazido 24 de julho de 2026; status do documento: Desenvolvimento. Código Claude: Monitoramento campos e configuração oficiais de telemetria, obtidos em 24 de julho de 2026. Kubernetes: Vivulidade, prontidão e sondas iniciais finalidades oficiais da sonda e advertências de recuperação, obtidas em 24 de julho de 2026.