AI-Agent Beobachtbarkeit bei Werkzeugfehlern: Fünf-Schicht-Test

Ein AI Agent kann ein Werkzeug nicht verwenden, auch wenn sein Modell reagiert, sein Prozess am Leben ist und der Werkzeuganruf in einer Spur erscheint. Die praktische Standardfunktion für AI Agentobservability besteht daher darin, einen Werkzeuganruf in fünf geordneten Schichten zu testen: Transport, Protokoll, Genehmigung, Ausführung und Ergebnis. Haltet an der ersten fehlgeschlagenen Schicht. Diese Regel verwandelt einen zweideutigen Alarm Tool unavailable in eine begrenzte Reparatur und verhindert, dass ein grüner Reaktionsumschlag für ausgelieferte Arbeit verwechselt wird. Dieser Leitfaden gilt für MCP Stil Tools über HTTP und JSON RPC, aber die Diagnoseform funktioniert auch für benutzerdefinierte REST Tools und lokale Kommandoadapter. Das Ziel ist nicht, jede Anforderung oder jede Nutzlast zu sammeln. Es geht darum, die geringsten Beweise zu behalten, die notwendig sind, um zu antworten: Wo hat der Aufruf aufgehört, welche Autorität ist erforderlich und ob das versprochene Ergebnis sein Ziel erreicht hat? Beginnen Sie mit der ersten fehlgeschlagenen Schicht Ein einziger tool call failed Zähler stürzt Fehler ab, die unvereinbar Reaktionen erfordern. Ein DNS Fehler kann einen erneuten Versuch einer begrenzten Verbindung rechtfertigen. Ein abgelaufener Token kann eine Erneuerung rechtfertigen. Die fehlende Reichweite erfordert eine Person oder einen Administrator; erneut zu versuchen, das gleiche Token zu verwenden, ist Verschwendung. Eine gültige Werkzeugreaktion ohne Änderung von Dateien, Tickets, Nachrichten oder Datenbanken erfordert eine Untersuchung des Ergebnisses, nicht eine Transportreparatur. Verwenden Sie diese Priorität: Schicht Mindestbeweise Beispiele für Ausfälle Ein vernünftiger nächster Schritt Verkehr Verbindungsergebnis, HTTP Status, vergangene Zeit DNS Fehler, Verweigerung der Verbindung, HTTP 503 Überprüfung der Reichweite; erneute Versuche nur innerhalb eines festen Budgets Protokoll Anfrage ID, Methode, Fehlercode JSON RPC Fehlende Methode 32601 , ungültige Parameter 32602 Erneuern Sie die Entdeckung oder bearbeiten Sie den Vertrag über die Anfrage Genehmigung HTTP Status, desinfizierter Auth Fehler, erforderlicher Umfang 401 invalid token , 403 insufficient scope einmalig erfrischen oder die fehlende Behörde anfordern Ausführung Werkzeugergebnisstatus, Ausfallzeit, Ausgangsschema Urteil MCP isError: true , Auslaufzeit, fehlerhafte strukturierte Ausgabe die Implementierung oder Eingabe des Instruments überprüfen Ergebnis Bestimmungsprüfer und Frische Die Antwort lautet geschaffen, aber das Artefakt fehlt. Überprüfen Sie die Bestimmung; erklären Sie nicht, dass sie abgeschlossen ist Die Ordnung zählt. Wenn die DNS Auflösung fehlgeschlagen ist, sind die Berechtigung und das Ergebnis unobserved , nicht fehlgeschlagen. Wenn man fünf Versagen für eine frühe Pause ausstrahlt, wird die Anzahl der Vorfälle aufgeblasen und die Reaktionspersonen zu Beweisen geschickt, die nie existiert haben. Halten Sie Protokollfehler getrennt von Werkzeugfehlern Die MCP Tool Invocation verwendet tools/call , während die Tool Definition einen inputSchema trägt und einen outputSchema tragen kann. Der aktuelle Spezifikation von MCP Tools zeigt auch ein Werkzeugergebnis mit isError: false an. Dies sind verschiedene Checkpoints: Der Client kann den Server erreichen, eine gültige JSON RPC Antwort austauschen und trotzdem einen Fehler auf Werkzeugebene erhalten. JSON RPC macht die äußere Unterscheidung explizit. Sein Spezifikation 2.0 behält 32601 für Methode nicht gefunden und 32602 für Invalid Parammer; eine Fehlerreaktion enthält error , während eine erfolgreiche Antwort result enthält. Ein JSON RPC result beweist nur, dass der Protokollwechsel abgeschlossen ist. Es beweist nicht, dass das Werkzeug die Operation akzeptiert hat, dass seine strukturierte Ausgabe dem angekündigten Schema entspricht oder dass der externe Nebenwirkung besteht. Erfassen Sie die Grenze, ohne sensible Argumente zu speichern: Dieses Ereignis lässt bewusst das Träger Token, die Werkzeugargumente, den Antwortkörper, den Tickettext und die absoluten Wege aus. Hash oder Kartenidentifikatoren, wenn Kreuzverbindungen erforderlich sind. Eine Spuren ID ist nur dann nützlich, wenn der Gesundheitsregister die erste fehlerhafte Schicht und das Ergebnisverdikt noch erklären kann, wenn die Rohspuren nicht verfügbar sind. Versuchen Sie kein Autoritätsproblem erneut, als wäre es ein Paketverlust. Die Zulassung verdient eine eigene Schicht, da 401 und 403 verschiedene Aktionen implizieren. Die Spezifikation der Zulassung von MCPs erfordert, dass die Kunden mit 401 Unauthorized umgehen und beschreibt die Entdeckung geschützter Ressourcen durch WWW Authenticate . Es empfiehlt auch Anwendungsbereichsanleitung, damit ein Kunde die für den aktuellen Antrag erforderliche Behörde erfahren kann. RFC 6750 definiert invalid token für ein abgelaufenes, widerrufenes, fehlerhaftes oder anderweitig ungültiges Träger Token und assoziiert es mit HTTP 401. Es definiert insufficient scope für ein Token, das keine erforderlichen Privilegien hat und es mit HTTP 403 assoziiert. Das gibt einem Betreiber eine sichere Entscheidungsregel: 1. Versuchen Sie für invalid token einmal den konfigurierten Refresh Pfad. Wenn die aktualisierte Auskunft fehlschlägt, halten Sie den Auskunftsinhaber auf. 2. Für insufficient scope nicht schleichen. Anzeigen Sie den erforderlichen Umfang, wenn der Server ihn bereitstellt, und fordern Sie eine explizite Autorität an. 3. Setzen Sie niemals das Token, den Refresh Token, den Autorisierungsheader oder die Roh Challenge in allgemeine Telemetrie. Diese Unterscheidung verhindert auch ein schädliches Automatisierungsmuster: Erweiterung der Berechtigungen, wenn ein Tool Aufruf fehlschlägt. Ein Konnektivitätsvorfall darf nicht zu einer Eskalation von Privilegien werden, und eine Umfangsverweigerung darf nicht fixed werden, indem man schweigend zu einer stärkeren Anmeldeinformation wechselt. Wiederholen Sie die Lücke zwischen falschem Erfolg Das Begleitgerät enthält acht synthetische Anrufe: zwei Transportfehler, ein JSON RPC Methodenfehler, zwei Berechtigungsfehler, ein Ausführungsfehler des Werkzeugs, ein falscher Erfolg und eine verifizierte Lieferung. Führen Sie den Klassifikator aus dem Verzeichnis von Artefakten aus: Der entscheidende Ergebnis ist: Drei Anrufe lieferten einen Ergebnisumfang zurück, aber nur einer lieferte ein zielgerichtetes Ergebnis. Ein Umschlag enthielt einen Ausführungsfehler; ein anderer behauptete Erfolg, während sein verheißenes Artefakt nicht vorhanden war. Die Ergebnisse des Zählprotokolls würden eine Erfolgsrate von 37,5% ergeben. Bei der Berechnung der überprüften Ergebnisse werden 12,5% erzielt. Der Unterschied besteht nicht in einem Detektor Score oder einem LLM Urteil: Er entsteht durch eine Änderung des Vollendungskriteriums. Das Gerät ist absichtlich deterministisch. Echte Systeme geben Mehrdeutigkeit hinzu: Eine Ticket API kann eine Aufzeichnung und eine Auszeit vor der Rückgabe ihrer ID verpflichten; ein Zielsuch kann veraltet sein; ein Idempotency Schlüssel kann eine sichere Versöhnungsanfrage ermöglichen. Markieren Sie die Fälle uncertain . Versuchen Sie nicht erneut einen Nebenanspruch, bis Sie wissen, ob der erste Versuch begangen wurde. Verwandeln Sie die Beweise in eine Betriebsregel Instrument ein Gesundheitsereignis pro Versuch eines Werkzeugbetriebs, verbunden mit dem Besitzlauf. Bewahren Sie die erste fehlerhafte Schicht, den sanitierten Code, die Frische der Beweise, den Besitzer erneut ausprobieren und den Ergebnisprüfer. Anschließend werden vier Kontrollen angewendet: Warnung auf Gruppenvorfälle, nicht auf jeden Versuch. Fünf Anrufe, bei denen die gleiche ausgelaufene Zulassung nicht erfolgt, sind ein Zulassungsvorfall. Die Kappe wird nach Schichten erneut ausprobiert. Transportfehler können begrenzt zurückgeführt werden; Protokoll und Umfangfehler benötigen in der Regel einen Vertrag oder eine menschliche Änderung. Unterscheidet zwischen Warten und Stecken. Ein Anruf, der auf einen genehmigten OAuth Fluss wartet, macht keine Fortschritte, aber es ist keine Ausführungsschleife. Der Vorfall wird erst nach dem Übergang der fehlerhaften Schicht durch and beseitigt, wenn das beabsichtigte Ergebnis beobachtet wird. Ein erfolgreicher Wiederversuch ist Aktivität, nicht Erholung. Die nützliche Dashboard Zeile ist folglich klein: betroffene Agentin, erste fehlerhafte Schicht, Einfluss, Beweiszeit, Vertrauen, Wiederversuchszahl, erforderliche Autorität und Verifikationsergebnis. Rohspuren können eine Drilldown bleiben. Dies ist die Gesundheit des Betriebsmittels, nicht eine Verpflichtung, die Laufzeit oder die Routen jeder Modellanfrage durch ein neues Gateway zu ersetzen. Es gibt auch eine harte Beschränkung. Nicht jedes Ergebnis hat einen deterministischen Verifikator. Eine Datei kann nach Pfad und Verdauung überprüft werden; ein Ticket nach stabiler ID; eine Bereitstellung nach Gesundheits Endpunkt und Revision. Die Forschung ist gut kann eine Rubrik oder eine menschliche Überprüfung erfordern. Kennzeichnen Sie die Methode und das Vertrauen neben dem Urteil, anstatt die fehlenden Beweise in gesunde zu verwandeln. Sidewisp befindet sich derzeit in einer privaten Vorschauphase. Die Produktionsüberwachungsadapter und die Wiederherstellungserfahrung werden im Allgemeinen nicht versandt. Die geplante Richtung ist eine gesundheitliche Schicht neben bestehenden Laufzeiten, die die Reichbarkeit, den Fortschritt, den Zugriff auf Werkzeuge und die verifizierten Ergebnisse trennt, während die Menschen die Kontrolle behalten. Wenn das Betriebsmodell mit Ihren Agenten übereinstimmt, Teil der privaten Vorschau. Quellen Modell Kontextprotokoll: Werkzeuge, Spezifikationsversion 2025 11 25 Modell Kontextprotokoll: Zulassung, Spezifikationsversion 2025 11 25 JSON RPC 2.0 Spezifikation RFC 6750, OAuth 2.0 Träger Token Verwendung