KI Agent Tool Call Tracing: Was bei jeder Anfrage loggen

Agenten-Observability: Tool-Aufrufe so tracen, dass sie debugbar bleiben

Ein Benutzer meldet, dass der Agent gestern Nachmittag „etwas Seltsames getan hat“. Sie öffnen die Protokolle und finden Folgendes:

Apidog heute ausprobieren

INFO  agent run started
INFO  calling tool: updateOrder
INFO  tool returned 200
INFO  agent run completed

Der Agent hat updateOrder aufgerufen. Sie wissen jedoch nicht:

• mit welchen Argumenten,
• für welche Bestellung,
• warum er dieses Tool gewählt hat,
• oder welche Antwort zurückkam.

Nach jeder aufgezeichneten Metrik war der Lauf erfolgreich. Keine einzige Entscheidung lässt sich rekonstruieren.

Agentensysteme versagen oft auf eine Weise, die erst im Nachhinein verständlich wird. Deshalb ist das Protokoll selbst ein Teil des Produkts. Dieser Leitfaden zeigt, welche Daten jeder Tool-Aufruf enthalten sollte, wie Modellentscheidungen mit HTTP-Anfragen korreliert werden, was vor dem Speichern geschwärzt werden muss und wie aus Traces reproduzierbare Tests entstehen.

Die API-Observability auf Service-Ebene behandelt die darunterliegende Infrastruktur. Hier geht es um die Agenten-Ebene.

Sobald ein Trace vorhanden ist, hilft Apidog: Spielen Sie den fehlerhaften Aufruf gegen denselben Endpunkt ab und beobachten Sie das Ergebnis.

Drei Schichten, ein Trace

Ein Agent erzeugt Ereignisse auf drei Ebenen:

1. Argumentationsschicht: Was war im Kontext? Welche Tools standen zur Verfügung? Welches Tool wurde mit welchen Argumenten ausgewählt?
2. Tool-Schicht: Der Executor validiert Argumente, wendet Richtlinien an, ordnet den Aufruf einer HTTP-Anfrage zu und verarbeitet das Ergebnis.
3. HTTP-Schicht: Methode, URL, Header, Body, Status und Latenz der Übertragung.

Das Debugging überschreitet fast immer diese Grenzen. Eine falsche Kunden-ID ist zunächst ein Argumentationsproblem, wird aber erst in der HTTP-Anfrage sichtbar. Ein 200-Status mit leerem Body ist ein HTTP-Problem, das einige Schritte später als seltsame Modellentscheidung erscheint.

Verbinden Sie deshalb alle Ebenen mit gemeinsamen IDs:

• eine Trace-ID pro Agentenlauf,
• eine Span-ID pro Tool-Aufruf,
• beide IDs auf jedem Datensatz jeder Schicht.

OpenTelemetry-Traces modellieren dieses Muster bereits. Die GenAI-Semantikkonventionen helfen bei portablen Attributnamen.

Was jeder Tool-Aufruf enthalten sollte

Ein brauchbarer Datensatz sieht beispielsweise so aus:

{
  "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 liefern dabei besonders viel diagnostischen Wert:

tool_args

Protokollieren Sie die vom Modell erzeugten Argumente vor der Normalisierung durch den Executor. Sendet der Agent die falsche ID, ist sie hier sichtbar.

tools_available

Dieses Feld erklärt die Auswahlentscheidung. Wenn ein Tool ungewöhnlich erscheint, sehen Sie sofort, welche Alternativen das Modell hatte.

retry_count

Damit unterscheiden Sie eine langsame API von einem Aufruf, der zweimal fehlschlug und erst beim dritten Versuch erfolgreich war. Ohne dieses Feld sehen drei Versuche wie ein einziger Aufruf aus.

outcome

Verwenden Sie einen expliziten Enum statt einer Ableitung aus dem HTTP-Status:

success
failed
timed_out
blocked_by_policy
rejected_by_human

blocked_by_policy und rejected_by_human sind keine technischen Fehler. Es handelt sich um funktionierende Schutzmaßnahmen. Vermischen Sie sie mit Fehlern, verfälschen Sie Ihre Fehlerrate.

policy

Der Policy-Block ist Ihr Audit-Trail. Wenn jemand fragt, ob eine destruktive Aktion genehmigt wurde, sollten approval_required, approved_by und der Entscheidungszeitpunkt die Antwort liefern. Das passt zur Durchsetzung aus dem Beitrag über KI-Agenten-Schutzmaßnahmen.

Protokollieren Sie die Entscheidung, nicht nur die Aktion

Die schwierigsten Agentenfehler sind Entscheidungsfehler. Zeichnen Sie deshalb zusätzlich Folgendes auf:

• Tool-Definitionen oder Toolset-Hash: Ändert sich die Auswahlgenauigkeit, kann eine bearbeitete Beschreibung die Ursache sein. Der Hash zeigt sofort, ob sich das Toolset zwischen einem guten und einem schlechten Lauf geändert hat. Der Beitrag zu Tool-Schema-Design erklärt, warum dieser Text das Verhalten stark beeinflusst.
• Modell und Einstellungen: Modell-ID, Temperatur und Prompt-Version gehören in den Laufdatensatz.
• Prompt-Größe: Speichern Sie entweder den vollständigen Prompt oder mindestens Token-Anzahl und Hash. Ein doppelt so großer Prompt weist oft auf unerwartet angehängten Kontext hin.
• Rohes Tool-Ergebnis: Speichern Sie die vollständige Antwort vor dem Kürzen. Sonst können Sie nicht unterscheiden, ob Daten von der API fehlten oder vom Executor entfernt wurden. Siehe Tool-Antworten aus dem Kontextfenster entfernen.

Schwärzen Sie vor dem Speichern

Agenten-Traces sind besonders sensibel: Sie enthalten sowohl Anfragen als auch Entscheidungsgrundlagen. Prompts sammeln außerdem leicht personenbezogene Daten.

1. Niemals Zugangsdaten speichern

Entfernen Sie:

• Authorization-Header,
• API-Schlüssel,
• Cookies,
• signierte URLs.

Speichern Sie stattdessen eine Schlüssel-ID oder einen anderen nicht geheimen Bezeichner. So bleibt nachvollziehbar, welcher Agent gehandelt hat. Der Beitrag über API-Schlüssel mit geringsten Rechten für Agenten beschreibt dieses Prinzip.

2. An der Grenze schwärzen

Filtern Sie nicht erst beim Lesen. Zu diesem Zeitpunkt kann das Geheimnis bereits auf die Festplatte geschrieben, repliziert oder gesichert worden sein. Schwärzen Sie in der Logging-Middleware, bevor der Datensatz den Prozess verlässt.

3. Nicht speicherbare Bodies hashen

Ein Request-Body-Hash beweist, dass zwei Aufrufe identisch waren, ohne die Nutzlast selbst zu speichern. Das reicht für viele Untersuchungen zu doppelten Schreibvorgängen.

4. Aufbewahrung nach Sensibilität staffeln

Ein praktikables Modell:

• vollständige Traces: eine Woche,
• geschwärzte Zusammenfassungen: ein Jahr.

Die meisten Debugging-Vorgänge finden innerhalb weniger Tage statt. Audit-Fragen kommen dagegen oft erst Monate später.

Traces in Tests umwandeln

Der größte Nutzen guter Traces ist nicht nur schnelleres Debugging, sondern realistische Testabdeckung.

Fehlgeschlagene Läufe als Regressionstests

Nehmen Sie die Tool-Aufrufe aus einem fehlerhaften Trace und spielen Sie sie gegen Ihre API ab. Nach der Korrektur speichern Sie die Wiedergabe als Regressionstest.

In Apidog können Sie die fehlerhafte Anfrage als gespeicherten Fall neu erstellen, das korrigierte Verhalten bestätigen und sie anschließend in CI ausführen.

Mocks aus echten Traces ableiten

Die am häufigsten verwendeten Endpunkte und die tatsächlich auftretenden Fehlerstatus stammen direkt aus den Traces. Verwenden Sie diese Daten, um Mocks zu bauen, statt Szenarien zu erraten. Eine Anleitung finden Sie unter Agenten gegen Mocks statt gegen Produktion ausführen.

Drift wöchentlich messen

Überwachen Sie mindestens:

• Verteilung der Tool-Auswahl,
• Wiederholungsrate pro Endpunkt,
• Aufrufe pro abgeschlossener Aufgabe,
• Anteil der durch Richtlinien blockierten Läufe.

Eine Verschiebung ist ein Frühwarnsignal. API-Vertragstests fangen häufig die vorgelagerte API-Änderung ab, die diese Drift verursacht.

Drei Untersuchungen, die ein Trace ermöglichen muss

„Der Agent hat den falschen Kunden belastet.“

Sie benötigen:

• die vom Modell erzeugten Argumente,
• die aufgelöste URL,
• den vorherigen Tool-Schritt,
• das Ergebnis dieses Schritts.

Oft liefert ein vorheriger Aufruf mehrere Treffer und das Modell wählt den ersten. Der Trace muss die Mehrdeutigkeit und die anschließende Auswahl zeigen. Ohne tool_args bleibt nur ein 200-Status und ein unzufriedener Kunde.

„Am Dienstag hat es 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.

Eine dieser Änderungen benennt die Ursache oft direkt. Deshalb gehört Konfiguration in den Laufdatensatz, nicht nur eine Ereignisliste.

„Hat das jemand genehmigt?“

Schreiben Sie den Policy-Block zum Zeitpunkt der Entscheidung:

• War eine Genehmigung erforderlich?
• Wer hat genehmigt?
• Wann wurde genehmigt?
• Wurde ein Dry-Run ausgeführt?

So wird ein angespanntes Gespräch zu einer einfachen Nachschlageaktion.

Keine dieser Fragen wird durch „Das Tool gab 200 zurück“ beantwortet. Die entscheidenden Felder sind billig zu speichern, nachträglich aber nicht zuverlässig rekonstruierbar.

Sampling: Was niemals verworfen werden sollte

Full-Fidelity-Tracing für jeden Lauf kann bei hohem Volumen teuer werden. Sampeln Sie deshalb nach Signal, nicht nach Volumen. Das SRE-Buchkapitel zum Monitoring beschreibt dieses Prinzip ausführlich.

Behalten Sie immer:

• fehlgeschlagene Läufe,
• Läufe mit Policy-Block,
• Läufe mit Schreibvorgängen.

Erfolgreiche schreibgeschützte Läufe können Sie sampeln. Behalten Sie aber genug davon, um Baselines zu berechnen.

Auch wenn Sie Payloads verwerfen, sollte der Laufdatensatz bestehen bleiben. Ein kleiner Skelett-Trace mit Tool-Namen, Ergebnissen und Dauern unterstützt weiterhin die wichtigsten Metriken. Bodies und Prompts sind die teuersten Bestandteile und können zuerst entfallen.

Vorsicht beim Tail-Sampling

Entscheiden Sie erst nach Abschluss des Laufs, ob Sie ihn behalten. Ein Lauf kann bis Schritt drei unauffällig sein und in Schritt neun scheitern. Er muss dann vollständig verfügbar sein. Puffern Sie ihn, statt frühe Spans unwiderruflich zu verwerfen.

Wo der Trace leben sollte

Wenn der Agent als eigener Dienst Ihre APIs aufruft, ist ein zentraler Trace-Speicher sinnvoll. Bei Agenten, die auf Entwicklermaschinen laufen, liegt der Trace dagegen schnell im Terminal, auf dem der Lauf gestartet wurde.

Sharkly verfolgt einen anderen Ansatz: Der Ausführungs-Trace wird an die zugewiesene Aufgabe angehängt. Laufverlauf, Ausführungsprotokoll und Ergebnis liegen neben Ziel, Status und dem Kommentar-Thread, in dem ein Mensch die Arbeit prüft.

Der praktische Unterschied ist der Abruf: „Warum hat der Agent das getan?“ wird durch Öffnen der Aufgabe beantwortet, statt durch die Suche nach Maschine, Sitzung und Scrollback.

Das ersetzt weder Tracing noch die Laufzeitumgebung. Claude Code und Codex erledigen weiterhin die Arbeit. Es ändert nur den Speicherort des Datensatzes, wenn der Agent kein von Ihnen bereitgestellter Dienst ist.

Vier Kennzahlen für das Dashboard

Aufrufe pro abgeschlossener Aufgabe

Das klarste Effizienzmaß. Steigt der Wert, exploriert der Agent meist stärker, weil eine Beschreibung schlechter wurde oder ein Endpunkt fehlschlägt.

Wiederholungsrate pro Endpunkt

Damit erkennen Sie die unzuverlässigsten Abhängigkeiten und Verschlechterungen. Der Leitfaden zur Fehlerbehebung von Agenten beschreibt, wie Sie die betroffenen Endpunkte priorisieren.

Durch Richtlinien blockierte Rate

Diese Rate sollte niedrig und stabil bleiben. Ein Anstieg bedeutet entweder, dass der Agent unerlaubte Aktionen versucht, oder dass eine Richtlinie zu streng geworden ist.

Zeit bis zum ersten Tool-Aufruf

Ein langsamer Start deutet häufig auf einen aufgeblähten Prompt hin. Die Prompt-Größe wächst oft schleichend, ohne dass jemand bewusst eine Änderung vornimmt.

Checkliste

• [ ] Eine Trace-ID pro Lauf und eine Span-ID pro Tool-Aufruf auf allen drei Ebenen.
• [ ] Modellargumente vor der Normalisierung protokolliert.
• [ ] Verfügbare Tools bei jedem Aufruf aufgezeichnet.
• [ ] `outcomegebnisse zusätzlich zur gekürzten Modellantwort gespeichert.
• [ ] Zugangsdaten in der Middleware entfernt.
• [ ] Nicht speicherbare Bodies gehasht.
• [ ] Aufbewahrung nach Sensibilität gestaffelt.
• [ ] Fehlerhafte Traces in wiederholbare Testfälle umwandelbar.

Das Ziel ist einfach: Wenn jemand fragt, warum der Agent eine Aktion ausgeführt hat, sollten die Aufzeichnungen eine Antwort liefern – keine Vermutung. Apidog herunterladen, um Aufrufe aus einem Trace abzuspielen und Reproduktionen als Tests zu speichern.

Häufig gestellte Fragen

OpenTelemetry oder ein zweckgebundenes Agenten-Observability-Tool?

Verwenden Sie OpenTelemetry für Transport und Trace-Modell. Agenten-spezifische Tools können zusätzliche Ansichten liefern, aber die zugrunde liegenden Daten sollten portabel bleiben.

Wie viel kostet Full-Tracing?

Weniger als erwartet, wenn Sie die Aufbewahrung staffeln: vollständige Nutzlasten für einige Tage und strukturierte Datensätze ohne Bodies für längere Zeit. Prompt-Dumps sind oft der teuerste Teil. Hashen und messen Sie sie, statt sie standardmäßig vollständig zu speichern.

Muss ich den Argumentationstext des Modells protokollieren?

Normalerweise nicht. Ausgewähltes Tool, erzeugte Argumente und verfügbare Optionen erklären die meisten Entscheidungen. Wenn ein Anbieter Argumentationsinhalte offenlegt, speichern Sie sie nur für fehlgeschlagene Läufe und behandeln Sie sie als besonders sensibel.

Wie trace ich über mehrere Agenten hinweg?

Verwenden Sie eine Trace-ID für die gesamte Aufgabe und einen eigenen Span pro Agent. Zeichnen Sie die Übergabe als Ereignis auf. Der Leitfaden zur Multi-Agenten-Übergabe beschreibt die erforderlichen Übergabedaten.

Was gilt für Agenten auf Kundenmaschinen?

Protokollieren Sie lokal, schwärzen Sie aggressiv und senden Sie ohne Zustimmung nur aggregierte Metriken. Tool-Namen, Ergebnisse und Dauern reichen meist für Flottenüberwachung aus, ohne Payloads vom Gerät zu übertragen.

Ist ein Request-Body-Hash wirklich nützlich?

Ja. Er beweist, dass zwei Aufrufe identisch waren, und löst damit viele Untersuchungen zu doppelten Schreibvorgängen, ohne die Nutzlast zu speichern. Kombinieren Sie ihn mit Idempotenzschlüsseln, die Duplikate eigentlich verhindern sollten.