Ein Benutzer meldet, dass der Agent gestern Nachmittag „etwas Seltsames getan hat“. Sie öffnen die Protokolle und finden Folgendes:
INFO agent run started
INFO calling tool: updateOrder
INFO tool returned 200
INFO agent run completed
Der Agent hat updateOrder aufgerufen. Sie wissen nicht, mit welchen Argumenten, für welche Bestellung, warum er dieses Tool gewählt hat oder was zurückkam. Der Lauf war nach jeder von Ihnen aufgezeichneten Metrik erfolgreich, und Sie können keine einzige Entscheidung rekonstruieren, die er getroffen hat.
Agentensysteme versagen auf eine Weise, die erst im Nachhinein Sinn ergibt, was bedeutet, dass das Protokoll das Produkt ist. Dieser Leitfaden behandelt, was bei jedem Tool-Aufruf aufgezeichnet werden sollte, wie eine Modellentscheidung mit der von ihr erzeugten HTTP-Anfrage korreliert werden kann, was geschwärzt werden muss und wie Traces in Tests umgewandelt werden können. Unser Beitrag über API-Observability behandelt die Service-Seite; dieser hier behandelt die Agenten-Ebene, die darüber liegt.
Apidog ist nützlich, sobald Sie einen Trace haben, denn der schnellste Weg, einen fehlerhaften Aufruf zu verstehen, besteht darin, ihn gegen denselben Endpunkt erneut abzuspielen und zu beobachten, was passiert.
Drei Schichten, ein Trace
Ein Agent erzeugt Ereignisse auf drei Ebenen, und die meisten Teams protokollieren nur die mittlere.
Die Argumentationsschicht ist dort, wo das Modell seine Entscheidungen trifft. Was im Kontext war, welche Tools angeboten wurden, welches es ausgewählt hat und mit welchen Argumenten.
Die Tool-Schicht ist Ihr Executor. Sie validiert Argumente, wendet Richtlinien an, ordnet den Aufruf einer HTTP-Anfrage zu und verarbeitet das Ergebnis.
Die HTTP-Schicht ist das Übertragungsmedium. Methode, URL, Header, Body, Status, Latenz.
Das Debugging überschreitet fast immer die Ebenen. „Der Agent hat die falsche Kunden-ID gesendet“ ist ein Argumentationsproblem, das erst auf der HTTP-Schicht sichtbar wird. „Die API hat einen 200er-Status mit leerem Body zurückgegeben“ ist ein HTTP-Problem, das drei Schritte später als seltsame Argumentation auftaucht. Wenn die drei Schichten nicht durch einen gemeinsamen Bezeichner miteinander verbunden sind, sind Sie auf die Korrelation nach Zeitstempel angewiesen, was in dem Moment aufhört zu funktionieren, in dem sich zwei Läufe überschneiden.
Also die erste Regel: eine Trace-ID pro Agentenlauf, eine Span-ID pro Tool-Aufruf und beide auf jedem Datensatz auf jeder Schicht vermerkt. OpenTelemetry-Traces modellieren bereits genau diese Form, und es gibt eine wachsende Anzahl von GenAI-semantischen Konventionen zur Benennung der Attribute, damit Ihre Daten portabel sind.
Was bei jedem Tool-Aufruf aufgezeichnet werden sollte
Ein Datensatz, der echte Fragen beantwortet, hat ungefähr diese Form:
{
"trace_id": "run_01J8ZK3M2Q",
"span_id": "call_004",
"parent_span_id": "call_003",
"timestamp": "2026-08-26T14:03:11.482Z",
"agent": "billing",
"step": 4,
"tool_name": "refundOrder",
"tool_args": { "orderId": "ord_92", "amount": 1200, "reason": "duplicate" },
"tools_available": ["getOrder", "listOrders", "refundOrder", "voidInvoice"],
"http": {
"method": "POST",
"url": "/v1/orders/ord_92/refund",
"request_body_hash": "sha256:1f4c...",
"status": 200,
"duration_ms": 412,
"retry_count": 1,
"idempotency_key": "9f2b7c14-6d3a-4b18"
},
"outcome": "success",
"tokens": { "prompt": 8420, "completion": 96 },
"policy": { "approval_required": true, "approved_by": "user_31", "dry_run": false }
}
Fünf Felder leisten überproportional viel Arbeit.
tool_args fehlt am häufigsten, und es ist das, das Sie immer haben möchten. Protokollieren Sie die vom Modell erzeugten Argumente, bevor Ihr Executor sie normalisiert. Wenn ein Agent die falsche ID sendet, ist dies hier sichtbar.
tools_available erklärt die Auswahl. Wenn das Modell ein seltsames Tool gewählt hat, ist die erste Frage, welche anderen Optionen es zur Auswahl hatte. Dieses Feld kostet nur wenige Bytes und beantwortet es sofort.
retry_count trennt „die API war langsam“ von „die API schlug zweimal fehl und funktionierte dann.“ Ohne dies sehen drei Versuche wie ein einziger Aufruf aus.
outcome sollte ein expliziter Enum sein, nicht etwas, das aus einem Statuscode abgeleitet wird. success, failed, timed_out, blocked_by_policy, rejected_by_human. Die letzten beiden sind wichtig, denn ein blockierter Aufruf ist eine funktionierende Schutzmaßnahme, kein Fehler, und deren Vermischung verfälscht Ihre Fehlerrate.
policy ist Ihr Audit-Trail. Wenn jemand fragt, ob eine destruktive Aktion genehmigt wurde, ist dies die Antwort. Es passt zur Durchsetzung, die in unserem Beitrag über KI-Agenten-Schutzmaßnahmen beschrieben wird.
Protokollieren Sie die Entscheidung, nicht nur die Aktion
Die schwierigsten Agentenfehler sind Entscheidungen, protokollieren Sie also genug, um sie zu rekonstruieren.
Behalten Sie die Tool-Definitionen, die für den Lauf verwendet wurden, oder einen Hash davon. Wenn die Auswahlgenauigkeit sich verschiebt, ist der erste Verdächtige eine Beschreibung, die jemand bearbeitet hat, und ein Hash sagt Ihnen sofort, ob sich der Tool-Satz zwischen einem guten und einem schlechten Lauf geändert hat. Unser Beitrag über Tool-Schema-Design behandelt, warum dieser Text das Verhalten so stark beeinflusst.
Zeichnen Sie das Modell und seine Einstellungen auf. Modell-ID, Temperatur und Prompt-Version gehören zum Laufdatensatz. Das Verhalten ändert sich über Modellversionen hinweg, und ohne dieses Feld werden Sie einen Tag damit verbringen, Ihren eigenen Code zu untersuchen.
Zeichnen Sie auf, was das Modell gesehen hat, oder zumindest dessen Größe. Ein vollständiger Prompt-Dump ist teuer zu speichern und oft sensibel. Eine Token-Zählung plus ein Hash gibt Ihnen den größten Teil des diagnostischen Werts: ein Lauf, dessen Prompt doppelt so groß ist wie üblich, ist ein Lauf, bei dem etwas angehängt wurde, das nicht hätte angehängt werden dürfen.
Zeichnen Sie das rohe Tool-Ergebnis vor dem Trimmen auf. Wenn Ihr Executor Antworten reduziert, bevor er sie an das Modell übergibt, wie in unserem Beitrag über das Entfernen von Tool-Antworten aus dem Kontextfenster, speichern Sie die vollständige Nutzlast im Trace. Andernfalls können Sie nicht feststellen, ob die Daten fehlten oder ob Sie sie verworfen haben.
Schwärzen Sie, bevor Sie speichern
Agenten-Traces sind ungewöhnlich gefährlich, da sie sowohl die Anfrage als auch die Begründung enthalten, und Prompts neigen dazu, persönliche Daten zu sammeln.
Vier Regeln halten dies überschaubar.
Speichern Sie niemals Anmeldeinformationen. Entfernen Sie Authorization, API-Schlüssel, Cookies und jede signierte URL. Protokollieren Sie den Bezeichner der Anmeldeinformationen, wie z.B. eine Schlüssel-ID, und nicht den Wert. Unser Beitrag über API-Schlüssel mit geringsten Rechten für Agenten behandelt, warum Sie diesen Bezeichner wünschen: er sagt Ihnen, welcher Agent gehandelt hat.
Schwärzen Sie an der Grenze, nicht in der Abfrage. Das Filtern zur Lesezeit bedeutet, dass das Geheimnis auf die Festplatte geschrieben, repliziert und gesichert wurde. Schwärzen Sie in der Logging-Middleware, bevor der Datensatz den Prozess verlässt.
Hashen Sie Bodies, die Sie nicht speichern können. Ein Anfrage-Body-Hash ermöglicht es Ihnen immer noch, zu beweisen, dass zwei Aufrufe identisch waren, was das meiste ist, was Sie für Duplikatsuntersuchungen benötigen, ohne die Nutzlast zu speichern.
Legen Sie die Aufbewahrungsfrist nach Sensibilität fest. Volle Traces für eine Woche, geschwärzte Zusammenfassungen für ein Jahr. Die meisten Debugging-Vorgänge finden innerhalb weniger Tage statt; die meisten Audit-Fragen kommen innerhalb weniger Monate.
Wandeln Sie Traces in Tests um
Der Lohn für gutes Tracing ist nicht nur schnelleres Debugging. Es ist eine Quelle realistischer Testfälle.
Jeder fehlgeschlagene Lauf ist ein Szenario. Nehmen Sie die Tool-Aufrufe aus einem fehlerhaften Trace, spielen Sie sie gegen Ihre API ab, und Sie haben eine Reproduktion. Wenn die Korrektur erfolgt ist, behalten Sie die Wiedergabe als Regressionstest. In Apidog können Sie die fehlschlagende Anfrage als gespeicherten Fall neu erstellen, das korrigierte Verhalten bestätigen und sie in CI ausführen, wodurch ein einmaliger Vorfall zu einer dauerhaften Abdeckung wird.
Traces sagen Ihnen auch, was Sie mocken sollen. Die Endpunkte, die Ihr Agent am häufigsten aufruft, und die Fehlerstatus, die er tatsächlich trifft, stammen direkt aus den Daten statt aus Vermutungen. Bauen Sie die Mocks darum herum, gemäß unserem Beitrag über das Ausführen von Agenten gegen Mocks statt gegen Produktion.
Und sie decken die langsame Drift auf, die Sie sonst übersehen würden. Verfolgen Sie wöchentlich einige Zahlen: Verteilung der Tool-Auswahl, Wiederholungsrate pro Endpunkt, Aufrufe pro abgeschlossener Aufgabe und der Prozentsatz der Läufe, die durch Richtlinien blockiert werden. Eine Verschiebung bei einem davon ist ein Signal, bevor es zu einem Vorfall wird. Vertragliche Prüfungen, wie in unserem API-Vertragstesting-Leitfaden, fangen die vorgelagerte Änderung ab, die dies normalerweise verursacht hat.
Drei Untersuchungen, die der Trace überstehen muss
„Der Agent hat den falschen Kunden belastet.“ Sie benötigen die Argumente, die das Modell erzeugt hat, die aufgelöste URL und den Schritt davor. Neun von zehn Malen kam die ID von einem früheren Tool-Ergebnis, das mehr als eine Übereinstimmung zurückgab und das Modell wählte die erste. Der Trace zeigt das frühere Ergebnis, die Mehrdeutigkeit und die Wahl. Ohne tool_args haben Sie einen 200er und einen sehr unzufriedenen Kunden.
„Es hat am Dienstag aufgehört zu funktionieren.“ Vergleichen Sie einen guten und einen schlechten Lauf Feld für Feld. Modell-ID, Toolset-Hash, Prompt-Version, durchschnittliche Antwortgröße. Etwas hat sich geändert, und eine dieser vier benennt es normalerweise. Deshalb enthält der Laufdatensatz Konfiguration und nicht nur Ereignisse: ein Diff ist nur möglich, wenn beide Seiten dieselben Felder aufgezeichnet haben.
„Hat das jemand genehmigt?“ Der Policy-Block ist die gesamte Antwort, und er muss zum Zeitpunkt der Entscheidung geschrieben werden, nicht später rekonstruiert. approval_required, approved_by und ein Zeitstempel verwandeln ein angespanntes Gespräch in eine Nachschlageaktion.
Beachten Sie, was diese gemeinsam haben. Keine von ihnen wird durch „das Tool gab 200 zurück“ beantwortet. Alle drei werden durch Felder beantwortet, die fast nichts kosten, um geschrieben zu werden, und nach dem Fakt nicht wiederherstellbar sind.
Sampling und was niemals gesampelt werden sollte
Full-Fidelity-Tracing bei jedem Lauf wird bei hohem Volumen teuer, daher sampeln Teams. Sampeln Sie sorgfältig, denn der Agentenverkehr ist nicht gleichmäßig.
Behalten Sie immer jeden fehlgeschlagenen Lauf, jeden Lauf, der auf einen Policy-Block gestoßen ist, und jeden Lauf, der einen Schreibvorgang enthielt. Das sind die Läufe, nach denen jemand fragen wird. Sampeln Sie die erfolgreichen schreibgeschützten Läufe, da sie den Großteil des Volumens ausmachen und einzeln am wenigsten interessant sind, obwohl Sie immer noch genug davon benötigen, um Ihre Baselines zu berechnen.
Googles SRE-Buchkapitel zum Monitoring ist immer noch die klarste Aussage darüber, warum Sie für das Signal und nicht für das Volumen sampeln, und die Argumentation lässt sich direkt übertragen.
Behalten Sie den Laufdatensatz auch dann, wenn Sie die Nutzlasten verwerfen. Ein Skelett-Trace mit Tool-Namen, Ergebnissen und Dauern ist klein und unterstützt immer noch die vier oben genannten Metriken. Die teuren Teile sind Bodies und Prompts, und das sind die Teile, die Sie zuerst verwerfen können.
Eine Warnung zum Tail-Sampling: Wenn Sie entscheiden, was Sie nach Abschluss eines Laufs behalten möchten, stellen Sie sicher, dass die Entscheidung getroffen wird, nachdem das Ergebnis bekannt ist. Ein Lauf, der in Schritt drei gut aussieht und in Schritt neun fehlschlägt, muss vollständig beibehalten werden, was bedeutet, dass gepuffert und nicht verworfen wird, während Sie fortfahren.
Wo der Trace leben sollte
Alles oben Genannte geht davon aus, dass Sie den Speicher besitzen. Das ist die richtige Annahme, wenn der Agent Ihr eigener Dienst ist, der Ihre eigenen APIs aufruft. Es ist eine schlechte Passung, wenn die Agenten Laufzeitumgebungen auf Entwicklermaschinen sind, denn der Trace lebt dann in dem Terminal, das ihn gerade ausgeführt hat.
Sharkly verfolgt den anderen Ansatz: Der Ausführungs-Trace wird an die Aufgabe angehängt, die dem Agenten zugewiesen wurde. Der Verlauf des Laufs, das Ausführungsprotokoll und das Ergebnis befinden sich neben dem Ziel, dem Status und dem Kommentar-Thread, in dem ein Mensch die Arbeit überprüft hat. Der praktische Unterschied ist der Abruf. „Warum hat der Agent das getan“ wird zu einer Frage, die Sie durch Öffnen der Aufgabe beantworten, anstatt die Maschine, die Sitzung und den Scrollback zu finden.
Es ersetzt weder das hier beschriebene Tracing noch die Laufzeitumgebung; Claude Code und Codex erledigen immer noch die Arbeit. Was es ändert, ist, wo der Datensatz landet, wenn der Agent kein Dienst ist, den Sie bereitgestellt haben.
Beobachten Sie vier Zahlen
Traces sind nur nützlich, wenn jemand sie betrachtet. Diese vier verdienen ihren Platz auf einem Dashboard.
Aufrufe pro abgeschlossener Aufgabe. Das klarste Effizienzmaß. Wenn es steigt, exploriert der Agent mehr, normalerweise weil eine Beschreibung schlechter wurde oder ein Endpunkt begann zu scheitern.
Wiederholungsrate pro Endpunkt. Zeigt Ihre am wenigsten zuverlässigen Abhängigkeiten und wann sich eine verschlechtert. Unser Beitrag zur Fehlerbehebung von Agenten behandelt, was am oberen Ende dieser Liste zu tun ist.
Durch Richtlinien blockierte Rate. Sollte niedrig und stabil sein. Ein Anstieg bedeutet entweder, dass der Agent Dinge versucht, die er nicht sollte, oder dass eine Richtlinie zu streng ist und nun der Engpass ist.
Zeit bis zum ersten Tool-Aufruf. Ein langsamer Start bedeutet normalerweise einen aufgeblähten Prompt, und die Prompt-Größe ist das, was wächst, ohne dass jemand dies entscheidet.
Eine Checkliste
- Eine Trace-ID pro Lauf, eine Span-ID pro Tool-Aufruf, auf allen drei Schichten vermerkt.
- Modellargumente vor der Normalisierung protokolliert.
- Die Liste der verfügbaren Tools bei jedem Aufruf aufgezeichnet.
- Ergebnis als expliziter Enum aufgezeichnet, einschließlich Richtlinienblockaden.
- Wiederholungsanzahl getrennt von Aufrufsanzahl.
- Modell, Temperatur, Prompt-Version und Toolset-Hash im Laufdatensatz.
- Rohe Tool-Ergebnisse gespeichert, nicht nur die gekürzte Version, die an das Modell übergeben wurde.
- Anmeldeinformationen in der Middleware entfernt, Bodies gehasht, wo sie nicht gespeichert werden können.
- Aufbewahrung nach Sensibilität gestaffelt.
- Fehlerhafte Traces in wiederholbare Testfälle umwandelbar.
Das Ziel ist einfach zu formulieren: Wenn jemand fragt, warum der Agent das getan hat, können Sie aus den Aufzeichnungen statt aus einer Vermutung antworten. Laden Sie Apidog herunter, um die Aufrufe in einem Trace wieder abzuspielen und die Reproduktionen als Tests zu speichern.
Häufig gestellte Fragen
Sollte ich OpenTelemetry oder ein zweckgebundenes Agenten-Observability-Tool verwenden? Verwenden Sie OpenTelemetry für den Transport und das Trace-Modell, da es bereits die Korrelation handhabt und Ihre Infrastruktur es wahrscheinlich spricht. Agenten-spezifische Tools fügen nützliche Ansichten hinzu; die zugrunde liegenden Daten sollten jedoch portabel sein.
Wie viel kostet das Speichern von Full-Tracing? Weniger, als man erwartet, wenn man es staffelt. Volle Nutzlasten für einige Tage und strukturierte Datensätze ohne Bodies für länger halten das meiste Volumen gering. Prompt-Dumps sind der teure Teil, also hashen und bemessen Sie sie, anstatt sie standardmäßig zu speichern.
Muss ich den Argumentationstext des Modells protokollieren? Normalerweise nicht. Das Tool, das es ausgewählt hat, die Argumente, die es erzeugt hat, und die Optionen, die es hatte, erklären die meisten Entscheidungen. Wo ein Anbieter Argumentationsinhalte offenlegt, speichern Sie diese nur für fehlgeschlagene Läufe und behandeln Sie sie als sensibel.
Wie trace ich über mehrere Agenten hinweg? Behalten Sie eine Trace-ID für die gesamte Aufgabe und geben Sie jedem Agenten einen eigenen Span, wobei die Übergabe als Ereignis aufgezeichnet wird. Unser Beitrag zur Multi-Agenten-Übergabe behandelt, was in diesen Übergabe-Datensatz gehört.
Was, wenn der Agent auf der Maschine eines Kunden läuft? Protokollieren Sie lokal, schwärzen Sie aggressiv und senden Sie nur aggregierte Metriken, es sei denn, der Benutzer stimmt dem zu. Tool-Namen, Ergebnisse und Dauern reichen in der Regel für die Überwachung auf Flottenebene aus, ohne dass Nutzlasten das Gerät verlassen.
Ist ein Anfrage-Body-Hash tatsächlich nützlich? Ja, für die häufigsten Fragen. Er beweist, dass zwei Aufrufe identisch waren, was die meisten Untersuchungen von doppelten Schreibvorgängen löst, ohne die Nutzlast selbst zu speichern. Kombinieren Sie ihn mit den Idempotenzschlüsseln, die das Duplikat hätten verhindern sollen.