Observabilidade do Agente: Captar o Sucesso Falso com um Contrato de Resultado

A observabilidade do agente deve responder a uma pergunta mais difícil do que fez o final da corrida?: existia o resultado esperado, pertencia a esta corrida e passou a sua verificação de aceitação? O padrão prático é definir esse resultado antes da execução, observá lo fora da própria mensagem de conclusão do agente e gravar um recibo de resultado compacto. Um evento terminal pode desencadear a verificação; não pode substituir a verificação. Esta distinção atinge um falso sucesso sem exigir que um segundo modelo leia novamente toda a transcrição. Também evita o erro oposto: tratar uma aprovação legítima de esperar como uma corrida quebrada. O recibo descrito abaixo registra um identificador opaco de artefatos, a frescura, uma digestão do conteúdo quando apropriado e um resultado de validação determinista. Falta evidência permanece unverified ou um estado de falha específico em vez de ser redondeado para saudável. Um evento terminal é prova de execução, não de entrega. Os vestígios são o lugar certo para entender como foi o trabalho. Não constituem automaticamente uma prova de que o estado externo solicitado já existe. O Convenções semânticas OpenTelemetry para os espaços de agentes da GenAI atual descreve operações como invoke agent , plan e execute tool , além de atributos de agente, fornecedor, modelo, cronograma e erro. O documento é explicitamente marcado Desenvolvimento. Esses sinais podem mostrar que uma operação ocorreu e se relatou um erro. Eles não podem saber que a sua fatura específica foi armazenada, o seu pedido de retirada contém a alteração solicitada, ou o seu relatório corresponde a um esquema aprovado. Essa regra de aceitação pertence ao pedido. O Referência de rastreamento do SDK OpenAI Agents faz o mesmo concreto de fronteira. Seu rastro padrão pode incluir gerações de modelos, chamadas de função, guardrails, entregas e extensões personalizadas. Isto é uma rica evidência de execução. O SDK também adverte que os intervalos de geração e função podem conter entradas e saídas sensíveis, e permite que os operadores desativem essa captura. Um recibo de resultados pode, portanto, ser mais restrito e mais decisivo: manter a prova necessária para julgar o entregue, e não uma segunda cópia de cada pedido e carga útil de ferramentas. Um bom modelo operacional utiliza ambas as coisas: O rastreamento explica o caminho, as tentativas de repetição, as ferramentas e a localização da falha; O recibo do resultado provará o resultado pretendido ou nomeará a prova ausente; Um sinal de espera registra uma dependência ou aprovação conhecida, em vez de fingir que a tarefa foi concluída; um sinal de progresso mostra um movimento útil enquanto o trabalho ainda está ativo. A confusão destes sinais cria maus alertas. A atividade não é um progresso útil. Um evento terminal limpo não é um resultado verificado. Uma espera declarada não é uma parada. Escreva o contrato final antes da corrida Um contrato final é pequeno o suficiente para ser revisado na criação de tarefas e rigoroso o suficiente para ser avaliado sem perguntar ao agente o que significava. Comece com a verificação determinista mais barata que corresponda ao resultado real. Campo Propósito Exemplo artifact id Nomear o resultado esperado sem expor um caminho secreto ou absoluto monthly report run started at Estabelece o limite de frescura 2026 07 25T14:00:00Z observed at Indica quando as provas foram recolhidas 2026 07 25T14:08:12Z modified at Rejeita um artefato deixado por uma corrida anterior 2026 07 25T14:07:55Z expected sha256 Pins bytes exatos quando byte importa identidade Digestão de 64 caracteres validator Nomes da verificação de aceitação report schema v3 validator exit code Registo do veredicto determinista 0 evidence source Diz de onde veio a observação local file stat Não exija todos os campos para todos os trabalhos. Uma migração de banco de dados pode precisar de uma consulta de esquema em vez de um digest de arquivo. Uma página implementada pode precisar de status HTTP, conteúdo canônico e uma afirmação do navegador. Uma tarefa de aprovação humana deve permanecer waiting até à chegada do evento da autoridade. O contrato deve representar o resultado, não forçar todas as cargas de trabalho a um modelo em forma de ficheiro. A ordem de classificação por defeito é importante. Verifique primeiro se há evidências, depois identidade, frescura, digestão e resultado de validação. Isto produz estados acionáveis: 1. missing não existem artefatos observados; 2. wrong artifact a observação pertence a um alvo diferente; 3. stale o artefato é anterior à corrida; 4. hash mismatch Bytes exatos foram exigidos e diferem; 5. validator failed o artefato existe, mas não atende aos critérios de aceitação; 6. unverified a verificação requerida não foi efetuada ou as suas provas não estão disponíveis; 7. verified todas as condições exigidas aprovadas. Mantenha o recibo privado. Os identificadores opacos são mais seguros do que os nomes de clientes ou os caminhos do sistema de arquivos. Um digesto pode provar a identidade de byte, mas um hash simples não esconde um segredo previsível da enumeração. Use um HMAC com teclado quando o valor é sensível e baixa entropia, ou evite manter o valor inteiramente. A coleta de provas deve ocorrer perto do artefato para que o conteúdo bruto não precise sair do hospedeiro. Realizar o teste de falha de sucesso de seis casos Testei a regra contra um dispositivo sintético de seis corridas. Todas as corridas têm o mesmo estado terminal de tempo de execução: completed . Duas observações são novas e válidas. Quatro representam um modo diferente de falso sucesso: nenhum artefato, um artefato mais antigo do que a corrida, uma desatividade de conteúdo e uma falha do validador. O classificador é deliberadamente chato. Avalia os factos numa ordem fixa: A execução do dispositivo incluído produz: A alegação falsificável é estreita: para esta fixação fornecida, uma regra de status terminal aceita seis corridas, enquanto o contrato final verifica duas e rejeita quatro com estados de evidência específicos. Esta não é uma taxa de falha de produção medida. É um teste de fronteira que mostra que os mesmos estados terminais podem ocultar resultados materialmente diferentes. A métrica útil não é % das corridas que disseram ser completas. É verified outcomes / runs expected to deliver an outcome , relatado ao lado da cobertura dos controlos. Se apenas metade dos seus tipos de tarefas tiver validadores deterministas, mostre essa limitação. Não classifique silenciosamente a metade sem instrumentos como saudável. Anexar a verificação no limite de conclusão O recibo funciona melhor quando o tempo de execução expõe um limite de conclusão, mas o cheque permanece independente. Nessa fronteira, recolha evidências, executa o validador, persista no recebimento e só depois atualiza o estado operacional. O Código Claude fornece um ponto concreto de aplicação. Seu Anéis de referência atual diz que TaskCompleted é executado quando uma tarefa está sendo marcada como completa. Um gancho de comando pode sair com o código 2 para evitar a conclusão e retorno de feedback quando os testes ou outra verificação de aceitação falham. Isso torna possível um portal determinista sem confiar em uma afirmação em prosa. É um mecanismo específico do código Claude, não um padrão de agente universal, e um gancho que funcionou com sucesso ainda precisa testar o artefato certo. Para os tempos de execução sem um gancho de conclusão de bloqueio, utilizar uma transição de estado de dois estágios: Não tente novamente automaticamente todos os estados não verificados. O missing , após um atraso conhecido no carregamento, pode precisar de uma janela de observação limitada curta. A validator failed pode justificar uma tentativa de reparação reversível se o utilizador já a autorizou. O unverified significa que o canal de prova falhou; não prova que o entregue seja ruim. Uma tarefa que aguarda uma decisão irreversível pertence ao waiting ou ao needs human , não a um ciclo de recuperação. Também separar o sucesso do comando do sucesso do resultado. Um processo de validador que sai da 0 prova apenas o que esse validador realmente verifica. Versionar o nome do validador, registar a sua fonte de evidência e o tempo de observação, e rever o contrato quando as entregas mudarem. Uma regra de aceitação obsoleta pode produzir um falso positivo perfeitamente documentado. Escala a incerteza; não fabrique sucesso Um contrato final é apenas tão completo quanto as suas expectativas declaradas. Pode perder um artefato não listado, aceitar um validador fraco, ou ler de uma fonte de evidências obsoleta. Estas são razões para expor a cobertura e a confiança, não razões para adicionar um juiz modelo por defeito. Use uma avaliação LLM apenas para critérios que não possam ser verificados deterministicamente, mantenha visível a sua rubrica e versão e evite deixar o mesmo agente produzir e classificar definitivamente o seu próprio trabalho. Quando as evidências conflitem, prefira o uncertain e peça autoridade antes de alterar o estado externo. A Sidewisp está atualmente em prévia privada. O site público e a biblioteca de artigos estão ao vivo; a coleta de agentes de produção saúde, os adaptadores de tempo de execução e a recuperação geralmente não são enviados. O Sidewisp é concebido como uma camada de saúde ao lado dos tempos de execução existentes, e não como um corretor de reposição ou fixador autônomo. A regra operacional é simples: deixe o evento terminal de execução iniciar a verificação, deixe a evidência externa decidir o resultado e deixe que a evidência faltante permaneça desconhecida. Se esse modelo de saúde coincidir com a forma como se administra agentes, o registo de pré visualização privada é o próximo passo apropriado.