Observabilidade do agente AI para as falhas das ferramentas: um teste de cinco camadas

Um agente AI pode não usar uma ferramenta mesmo quando seu modelo é responsivo, seu processo está vivo e a chamada de ferramenta aparece em um rastro. O padrão prático para a observabilidade do agente AIZ é, portanto, testar uma chamada de ferramenta em cinco camadas ordenadas: transporte, protocolo, autorização, execução e resultado. Parem na primeira camada falhada. Essa regra transforma um alerta ambíguo ferramenta indisponível em uma reparação limitada, e evita que um envelope de resposta verde seja confundido com o trabalho entregue. Este guia aplica a regra às ferramentas de estilo MCP sobre HTTP e JSON RPC, mas a forma de diagnóstico também funciona para ferramentas REST personalizadas e adaptadores de comandos locais. O objetivo não é coletar todos os pedidos ou cargas úteis. É conservar a menor evidência necessária para responder: onde parou a chamada, que autoridade é necessária e o resultado prometido chegou ao seu destino? Comece com a primeira camada falhada Um único contador tool call failed cai em falhas que exigem respostas incompatíveis. Um erro DNS pode justificar uma nova tentativa de conectividade limitada. Um token expirado pode justificar uma atualização. O escopo faltante requer uma pessoa ou um administrador; tentar novamente o mesmo token é desperdício. Uma resposta de ferramenta válida sem alteração de arquivo, bilhete, mensagem ou banco de dados precisa de investigação do resultado, não de reparação de transporte. Use esta prioridade: Capa Evidências mínimas Exemplos de falhas Próximo passo razoável Transportes Resultado da conexão, status HTTP, tempo passado Falha DNS, conexão recusada, HTTP 503 Verificar a acessibilidade; tentar novamente apenas dentro de um orçamento fixo Protocolo Identificação de pedido, método, código de erro JSON RPC Falta o método 32601 , parâmetros inválidos 32602 Refrescar a descoberta ou corrigir o contrato de solicitação Autorização Estatuto HTTP, erro de autoria desinfectado, escopo requerido 401 invalid token , 403 insufficient scope Refrescar uma vez ou solicitar à autoridade ausente Execução Status do resultado da ferramenta, tempo de espera, veredicto do esquema de saída MCP isError: true , tempo de execução, saída estruturada malformada inspecionar a implementação ou entrada da ferramenta Resultados Verificador de destino e frescura A resposta diz "criado", mas o artefato está ausente. Verificar o destino; não declarar a conclusão A ordem importa. Se a resolução DNS falhar, a autorização e o resultado são unobserved , não falharam. Emitir cinco falhas por uma pausa precoce aumenta a contagem de incidentes e envia os responsáveis em direção a evidências que nunca existiam. Mantenha a falha do protocolo separada da falha da ferramenta A invocação da ferramenta MCP utiliza tools/call , enquanto a definição da ferramenta tem uma inputSchema e pode ter uma outputSchema . O Especificação de ferramentas MCP atual também mostra um resultado de ferramenta com isError: false . Estes são pontos de verificação distintos: o cliente pode chegar ao servidor, trocar uma resposta válida JSON RPC, e ainda assim receber uma falha no nível da ferramenta. A JSON RPC torna explícita a distinção externa. A sua Especificação 2.0 reserva 32601 para Método não encontrado e 32602 para Parâmetros inválidos; uma resposta de erro contém error , enquanto uma resposta bem sucedida contém result . Um JSON RPC result só prova que o intercâmbio de protocolo foi concluído. Não prova que a ferramenta tenha aceitado a operação, que a sua saída estruturada corresponda ao esquema anunciado ou que exista o efeito colateral externo. Registrar o limite sem armazenar argumentos sensíveis: Este evento omite deliberadamente o token do portador, os argumentos das ferramentas, o corpo de resposta, o texto do bilhete e os caminhos absolutos. Identificadores de hash ou mapa quando são necessárias conjuntos de execução cruzada. Uma identificação de rastreamento só é útil se o registo médico ainda puder explicar a primeira camada falhada e o veredicto final quando o rastreamento bruto não estiver disponível. Não tente novamente um problema de autoridade como se fosse perda de pacotes A autorização merece a sua própria camada porque 401 e 403 implicam ações diferentes. O Especificação da autorização do MCP exige que os clientes lidem com o 401 Unauthorized e descreve a descoberta de recursos protegidos através do WWW Authenticate . Além disso, recomenda orientações sobre o âmbito de aplicação para que o cliente possa conhecer a autoridade necessária para o pedido em curso. O RFC 6750 define o invalid token como um token portador expirado, revogado, mal formado ou de outra forma inválido e o associa ao HTTP 401. Ele define insufficient scope para um token que carece de privilégios necessários e o associa ao HTTP 403. Isso dá ao operador uma regra de decisão segura: 1. Para o invalid token , tente o caminho de atualização configurado uma vez. Se a credencial atualizada falhar, pára e surfaça o proprietário da credencial. 2. No caso do insufficient scope , não fechar. Indicar o escopo necessário se o servidor o fornecer e solicitar autoridade explícita. 3. Nunca coloque o token, o token de atualização, o cabeçalho de autorização ou o desafio bruto em telemetria de uso geral. Esta distinção também impede um padrão de automação prejudicial: alargar as permissões sempre que uma chamada de ferramenta falha. Um incidente de conectividade não deve se tornar uma escalada de privilégios, e uma negação de alcance não deve ser "fixada" mudando silenciosamente para uma credencial mais poderosa. Reproduzir a diferença entre o falso sucesso O dispositivo de acompanhamento contém oito chamadas sintéticas: duas falhas de transporte, um erro do método JSON RPC, duas falhas de autorização, um erro de execução da ferramenta, um falso sucesso e uma entrega verificada. Execute o classificador do diretório de artefatos: O resultado decisivo é: Três chamadas devolveram um envelope de resultados, mas apenas uma produziu um resultado verificado pelo destino. Um envelope contou com um erro de execução; outro alegou sucesso enquanto seu artefato prometido estava ausente. Os resultados do protocolo de contagem relatariam uma taxa de sucesso de 37,5%. O conteúdo dos resultados verificados é de 12,5%. A diferença não é uma pontuação do detector ou um julgamento do LLM: vem da alteração do critério de conclusão. A fixação é intencionalmente determinista. Os sistemas reais adicionam ambiguidade: uma API de bilhetes pode cometer um registro e um tempo de ausência antes de devolver sua identificação; uma busca de destino pode ser obsoleta; uma chave de idempotencia pode permitir uma consulta de reconciliação segura. Marque esses casos uncertain . Não tente novamente uma chamada de efeitos colaterais até saber se a primeira tentativa foi cometida. Transformar as provas numa regra de funcionamento Instrumento um evento de saúde por tentativa de operação de ferramenta, ligado à corrida de propriedade. Preserva a primeira camada falhada, o código desinfectado, a frescura das provas, retestar o proprietário e o verificador de resultados. Em seguida, aplicar quatro controles: Alerta sobre incidentes em grupo, não todas as tentativas. Cinco chamadas que falham na mesma credencial expirada são um incidente de autoridade. O cap retrata se por camada. As falhas de transporte podem receber um retorno limitado; as falhas de protocolo e de âmbito geralmente precisam de um contrato ou de uma alteração humana. Diferenciar a espera de ficar preso. Uma chamada que espera um fluxo OAuth aprovado não está a progredir, mas não é um ciclo de execução. Limpar o incidente somente após a camada falhada passar por and , o resultado pretendido é observado. Um comando de retomada bem sucedido é atividade, não recuperação. A linha útil do painel de instrumentos é, consequentemente, pequena: agente afetado, primeira camada falhada, impacto, tempo de prova, confiança, contagem de retest, autoridade requerida e resultado do verificador. Os vestígios crus podem continuar a ser um exercício. Esta é a saúde do agente operacional, não é uma exigência para substituir o tempo de execução ou a rota de cada pedido de modelo através de um novo gateway. Há também uma dura limitação. Nem todos os resultados têm um verificador determinista. Um arquivo pode ser verificado por caminho e digestão; um bilhete por ID estável; uma implantação por ponto final de saúde e revisão. A investigação é boa pode exigir uma rubrica ou uma revisão humana. Marque o método e a confiança ao lado do veredicto, em vez de transformar as provas faltantes em evidências saudáveis. A Sidewisp está atualmente em prévia privada. Os seus adaptadores de monitorização da produção e execução de recuperação não são geralmente enviados. A direção planejada é uma camada de saúde ao lado dos tempos de execução existentes que separa a acessibilidade, o progresso, o acesso às ferramentas e os resultados verificados, mantendo os seres humanos no controle. Se esse modelo de operação coincidir com os seus agentes, Junte se à pré visualização privada. Fontes Modelo de protocolo de contexto: Ferramentas, versão de especificações 2025 11 25 Modelo de Protocolo Contextual: Autorização, versão de especificações 2025 11 25 Especificação JSON RPC 2.0 RFC 6750, OAuth 2.0 Utilização do Token do Portador