Verteilte Traces für Agenten: Werkzeugaufrufe über Systemgrenzen verfolgen

Verteiltes Tracing verbindet einzelne Aufrufe zu einer nachvollziehbaren Kette, auch wenn eine Aufgabe mehrere Prozesse, Dienste oder Sicherheitsgrenzen durchquert. Für KI-Agenten lohnt sich das besonders. Ein scheinbar einfacher Auftrag kann intern mehrere Werkzeuge, APIs und Entscheidungsschritte auslösen. Die Grundlage für die Weitergabe des Trace-Kontexts beschreibt der Editor’s Draft der Spezifikation Trace Context des Webstandardgremiums W3C.

Eine Aufgabe als logische Operation

Die W3C-Spezifikation beschreibt einen verteilten Trace als Menge von Ereignissen, die zu einer einzigen logischen Operation gehören und dabei Prozess-, Netzwerk- und Sicherheitsgrenzen überschreiten können. Ihr Beispiel ist ein Klick auf einer Website, der mehrere nachgelagerte Dienste anstößt.

Bei einem Agenten ist diese Operation die Nutzeraufgabe, etwa: „Fasse mir die offenen Tickets zusammen.“ Werkzeugaufrufe und die dadurch ausgelösten Dienste bilden die nachgelagerte Kette. Sicherheitsgrenzen kommen ins Spiel, sobald ein Werkzeug ein fremdes System anspricht oder Daten an einen externen Dienst überträgt.

Spans machen die Kette lesbar

Ein Trace lässt sich in einzelne Arbeitsschritte, sogenannte Spans, gliedern. Ein solcher Schritt erhält eine Trace-ID für die gesamte Kette, eine eigene Span-ID, Zeitangaben und bei untergeordneten Schritten einen Verweis auf den vorherigen Zusammenhang. Der oberste Schritt eröffnet die Kette.

Für Agentensysteme ist es ein guter Ausgangspunkt, Werkzeugaufrufe und wichtige interne Schritte getrennt abzubilden. Ein ausgehender API-Aufruf, die Verarbeitung beim angesprochenen Dienst und eine lokale Auswertung sollten als unterschiedliche Schritte sichtbar sein. Diese Aufteilung ist keine universelle Vorgabe, sondern eine Modellierungsentscheidung: Sie muss zur tatsächlichen Architektur und zur späteren Fehlersuche passen.

Die Lücke ist der Befund

Angenommen, erwartet wird diese Kette: Nutzeraufgabe, Adressprüfung, Lagerabfrage, Bewertung. Im Fehlerfall sind aber nur die Nutzeraufgabe und die Adressprüfung sichtbar.

Dann beginnt die Diagnose an der Lücke. Wurde für die Lagerabfrage kein Schritt erfasst, ging der Trace-Kontext beim Übergang verloren, oder startete der Aufruf gar nicht? Der Trace beantwortet das nicht von selbst. Er zeigt aber, an welcher Verbindung Logs, Fehlermeldungen und Werkzeugergebnisse geprüft werden müssen.

Ich halte das für den stärksten Grund, Agenten überhaupt zu tracen. Eine hübsche Baumansicht erfolgreicher Läufe hilft im Alltag wenig, eine sichtbare Bruchstelle dagegen sehr. Entscheidend ist deshalb zuerst, ob der Trace-Kontext jeden Werkzeugaufruf und jeden externen Dienst tatsächlich erreicht. Weitere Attribute kommen danach.

Opaque Values nicht uminterpretieren

Zur Weitergabe des Kontexts gehört auch der im W3C-Glossar beschriebene opaque value. Nur der Teilnehmer, der ihn erzeugt hat, kennt seine Bedeutung. Alle anderen behandeln ihn als bloße Bytefolge.

Das ist Absicht. So verbindet der Trace-Kontext Schritte über Dienst- und Anbietergrenzen hinweg, ohne interne Datenformate offenzulegen.

Beispiel: Bestellung vorbereiten

Ein einfaches, ausgedachtes Szenario macht die Modellierung greifbar: Ein Agent soll eine Lieferadresse prüfen und eine Bestellung vorbereiten.

[Start] Aufgabe: Bestellung vorbereiten
 ├─ [Schritt] Werkzeug ruft Adressdienst auf
 │   └─ [Schritt] Adressdienst verarbeitet Anfrage
 ├─ [Schritt] Werkzeug fragt Lagerbestand ab
 │   └─ [Schritt] Lagerdienst verarbeitet Anfrage
 └─ [Schritt] Agent bewertet das Ergebnis

Die Zuordnung bleibt eine Modellierungsentscheidung. Bei asynchroner Verarbeitung oder Nachrichtenwarteschlangen können zusammengehörige Schritte zeitlich weit auseinanderliegen. Wie Wiederholungen und Idempotenz zusammenspielen, erklärt der Beitrag zu Agenten-Retries und Idempotenz.

Nur erfassen, was die Diagnose braucht

Trace-Daten sind kein neutrales Nebenprodukt. Die W3C-Spezifikation widmet Datenschutz und Sicherheit eigene Abschnitte.

In einen erfassten Schritt gehören deshalb nur Felder, die für Betrieb und Fehlersuche nötig sind. Zugangsdaten, vollständige Nutzereingaben oder vertrauliche Werkzeugparameter sollten nicht gespeichert werden, nur weil die Instrumentierung es technisch erlaubt. Zum Umgang mit Zugangsdaten in Parametern passt der Beitrag über Bearer-Tokens in Agentenaufrufen.

Fazit: Erst die Kette, dann die Details

Ein Startpunkt pro Nutzeraufgabe und ein eigener erfasster Schritt für jeden relevanten Werkzeugaufruf sind eine brauchbare Modellierung, keine universelle Vorgabe. Die Mindestregel ist schlichter: Der Trace muss die tatsächlichen Systemgrenzen abbilden und bei einer Lücke zeigen, wo die Diagnose beginnt. Sensible Inhalte bleiben draußen. Jedes weitere Attribut muss eine konkrete Betriebsfrage beantworten, sonst ist es Ballast.