Agent Observability: Logging und Tracing für KI-Agenten aufbauen

Ein Agent, der in Produktion läuft, ist eine Blackbox mit Handlungsfreiheit. Er plant, ruft Werkzeuge auf, bewertet Zwischenergebnisse und entscheidet über den nächsten Schritt. Zehn solcher Schritte später steht ein Ergebnis, und wenn es falsch ist, beginnt die eigentliche Arbeit: herauszufinden, wo genau der Lauf gekippt ist. Ohne Agent Observability ist diese Frage nicht zu beantworten. Man sieht die Eingabe, man sieht die Ausgabe, und dazwischen liegt Nebel.

Das Problem ist strukturell anders als bei klassischen Anwendungen. Ein Fehler in einer Web-Applikation hat einen Stacktrace, eine Zeile, einen Commit. Ein Fehler in einem Agentenlauf hat oft keinen technischen Fehler im engeren Sinn: Alle Aufrufe waren erfolgreich, alle Antworten wohlgeformt, nur die Kette der Entscheidungen führte in die falsche Richtung. Wer das nachvollziehen will, braucht mehr als das Standard-Logging der Infrastruktur. Er braucht eine lückenlose Aufzeichnung dessen, was der Agent gesehen, entschieden und getan hat.

Was geloggt gehört

Die Grundregel lautet: Jede Interaktion mit dem Modell und jeder Werkzeugaufruf werden vollständig festgehalten. Konkret bedeutet das pro Schritt:

• Prompts und Antworten in voller Länge, inklusive System-Prompt-Version und aller Kontextdokumente, die dem Modell vorlagen.
• Tool-Calls mit Name, Parametern, Rückgabewert und Dauer. Auch fehlgeschlagene Aufrufe, gerade die.
• Token-Verbrauch pro Aufruf, getrennt nach Eingabe und Ausgabe. Ohne diese Zahl lässt sich weder Kostenentwicklung noch Kontextwachstum beurteilen.
• Kosten, direkt aus dem Token-Verbrauch abgeleitet und pro Lauf aggregiert. Ein Agent, der sich in einer Schleife verfängt, fällt über die Kosten oft früher auf als über die Qualität.
• Metadaten: Modellversion, Temperatur, Latenz, Nutzer- oder Mandanten-Kennung, Feature-Flag-Stände.

Wichtig ist die Vollständigkeit der Prompts. Die Versuchung ist groß, nur die Nutzereingabe zu loggen und den Rest wegzulassen, weil er sich ja aus dem Code ergibt. In der Praxis ergibt er sich eben nicht: Der zusammengebaute Kontext hängt von Retrieval-Ergebnissen, Verlaufskürzungen und dynamischen Anweisungen ab. Was das Modell wirklich gesehen hat, weiß man nur, wenn man es aufgezeichnet hat.

Traces: den Lauf als Baum strukturieren

Einzelne Log-Zeilen genügen nicht, wenn ein Lauf aus vielen Schritten besteht. Das passende Werkzeug ist der Trace, wie man ihn aus verteilten Systemen kennt: eine eindeutige Kennung pro Agentenlauf, unter der alle Einzelschritte als sogenannte Spans hängen. Jeder Modellaufruf ist ein Span, jeder Tool-Call ist ein Span, und verschachtelte Abläufe wie ein Sub-Agent oder eine Retrieval-Pipeline bilden Unterbäume.

Diese Struktur zahlt sich doppelt aus. Erstens lässt sich ein einzelner Lauf als Ganzes lesen: Welche Schritte gab es, in welcher Reihenfolge, wie lange dauerte jeder, wo entstand der meiste Token-Verbrauch. Zweitens lassen sich Läufe vergleichen: Wenn eine Aufgabenklasse plötzlich doppelt so viele Schritte braucht wie vor dem letzten Prompt-Update, sieht man das in den Trace-Längen sofort, lange bevor es jemand am Ergebnis bemerkt.

Praktisch bewährt hat sich, die Trace-Kennung durch alle Ebenen zu reichen, auch an externe Aufrufe. Dann führt der Weg von einer Nutzerbeschwerde über die Anfrage-ID direkt zum vollständigen Lauf, ohne Suchen und Raten.

Metriken und Alerts, die sich lohnen

Traces beantworten die Frage nach dem Einzelfall. Für den Überblick braucht es aggregierte Metriken. Bewährt haben sich wenige, dafür aussagekräftige Größen:

• Erfolgsquote pro Aufgabentyp, soweit sich Erfolg automatisch feststellen lässt, etwa über Format-Checks oder nachgelagerte Validierung.
• Schrittanzahl und Laufdauer pro Lauf, als Verteilung betrachtet. Ausreißer nach oben deuten auf Schleifen oder festgefahrene Läufe.
• Kosten pro Lauf und pro Feature, täglich aggregiert.
• Fehlerraten der Tool-Calls, getrennt nach Werkzeug. Ein Werkzeug, das schleichend unzuverlässiger wird, zieht die Agentenqualität mit nach unten.
• Abbruch- und Eskalationsquote: wie oft der Agent aufgibt oder an einen Menschen übergibt.

Alerts sollten auf Veränderungen reagieren, nicht auf absolute Schwellen allein. Ein Anstieg der mittleren Schrittanzahl, ein Sprung bei den Kosten pro Lauf oder eine wachsende Tool-Fehlerrate sind die Signale, die auf ein Problem hinweisen, bevor es die Nutzer erreichen.

Datenschutz beim Logging von Nutzereingaben

Vollständiges Logging kollidiert schnell mit dem Datenschutz, denn Prompts enthalten, was Nutzer eingeben, und das können personenbezogene oder vertrauliche Daten sein. Wer hier nachlässig ist, baut sich ein Schattenarchiv sensibler Informationen mit unklarer Rechtsgrundlage.

Drei Grundsätze helfen, ohne die Observability zu opfern. Erstens: Zugriff trennen. Vollständige Traces mit Rohdaten sieht nur ein kleiner Kreis, aggregierte Metriken sieht das ganze Team. Zweitens: Aufbewahrung begrenzen. Rohe Prompts und Antworten brauchen selten mehr als einige Wochen Vorhaltezeit, Metriken dürfen länger leben. Drittens: wo möglich pseudonymisieren oder maskieren, etwa indem erkennbare Identifikatoren vor dem Persistieren ersetzt werden. Die konkrete Ausgestaltung gehört mit der eigenen Datenschutzverantwortung abgestimmt, denn sie hängt vom Anwendungsfall und den verarbeiteten Datenkategorien ab. Entscheidend ist, dass die Frage vor dem Go-live beantwortet wird und nicht nach dem ersten Auskunftsersuchen.

Fehleranalyse anhand konkreter Traces

Der eigentliche Ertrag der ganzen Infrastruktur zeigt sich in der Fehleranalyse. Ein typischer Ablauf: Eine Nutzerin meldet ein falsches Ergebnis. Über die Anfrage-ID findet man den Trace und liest den Lauf Schritt für Schritt. Schritt drei zeigt, dass das Retrieval ein veraltetes Dokument geliefert hat. Schritt fünf zeigt, dass das Modell den Widerspruch zwischen zwei Quellen bemerkt, aber falsch aufgelöst hat. Damit ist aus einer diffusen Beschwerde ein konkreter Befund geworden: kein Modellproblem, sondern ein Datenproblem plus eine Lücke in den Anweisungen zur Quellengewichtung.

Diese Art der Analyse verändert die Arbeitsweise des Teams. Statt über Vermutungen zu diskutieren, liest man Läufe. Wiederkehrende Fehlermuster werden zu Prüffällen für die Evals, auffällige Traces zu Material für Prompt-Verbesserungen. Observability ist damit nicht nur ein Betriebsthema, sondern die Rohstoffquelle für jede gezielte Verbesserung des Agenten.

Fazit

Agent Observability ist kein Zubehör, sondern die Voraussetzung dafür, einen autonomen Agenten überhaupt verantwortbar zu betreiben. Der Aufbau folgt einer klaren Reihenfolge: vollständiges Logging von Prompts, Tool-Calls, Tokens und Kosten, darauf Traces, die jeden Lauf als lesbaren Baum abbilden, darauf wenige aggregierte Metriken mit Alerts auf Veränderung, und das Ganze mit klaren Regeln für Zugriff und Aufbewahrung. Wer das etabliert hat, beantwortet die Frage, was der Agent da eigentlich getan hat, in Minuten statt in Tagen. Und genau daran entscheidet sich, ob ein Agentensystem ein beherrschbares Werkzeug ist oder ein Risiko mit guter Laune.