Beobachtbarkeit von KI-Agenten: Was der Agent getan hat und wie Sie es belegen

Was Beobachtbarkeit eines KI-Agenten ist

Beobachtbarkeit von KI-Agenten heißt, anhand von Artefakten und nicht aus Erinnerung oder den Worten des Agenten drei Fragen beantworten zu können: Was hat er getan, warum genau so, und womit ist belegt, dass das Ergebnis stimmt? Wenn der Agent nach zwanzig Minuten Arbeit sagt »fertig, aber zwei Tests schlagen fehl, vielleicht wegen des Timings«, und auf die Frage, welche Pfade betroffen sind, nur antwortet »zeigen Sie mir den Code«, fehlt die Beobachtbarkeit. Der Agent ist nicht dumm, ihm fehlt nur, was er vorlegen könnte.

Das Problem ist systemisch. Ein und derselbe Agent kann in einer Woche zehnmal ehrlich »fertig« sagen, und jedes Mal kann das etwas anderes bedeuten: Mal sind alle Tests gelaufen, mal nur einer, mal gar keiner. Je länger ein Projekt lebt, desto teurer wird jede neue Sitzung, denn sie beginnt mit Ausgraben.

Zwei Schichten: Laufzeit und Prozess

Beobachtbarkeit verwechselt man mit Logs, aber Logs sind nur die halbe Sache.

Nur die Laufzeit: Man sieht, was gescheitert ist, aber nicht, was erreicht werden sollte. Nur der Prozess: Man weiß, was gewollt war, sieht aber nicht, warum es nicht geklappt hat. Man braucht beide.

Warum der Agent das nicht von selbst tut

Die Anweisung »protokolliere gründlicher« hilft nicht, aus drei Gründen.

• Er weiß nicht, was er nicht weiß. Der Agent protokolliert kein Signal, dessen Bedeutung er nicht erkennt.
• Das Format schwankt. In einer Sitzung schreibt er ausführlich, in der nächsten in einer einzigen Zeile. Vergleichen und Kennzahlen bilden lässt sich so nicht.
• Der Prozess lässt sich nicht aus Logs schließen. Die Antwort auf »warum so« steht in Dokumenten, die vor der Arbeit entstanden sind, nicht in der Ausgabe von Befehlen.

Deshalb baut man Beobachtbarkeit in das Harness ein — die Umgebung des Agenten: Vorlagen, Hooks, Skripte, ein verpflichtendes Berichtsformat.

Was protokolliert werden sollte: das Minimum

Ein gutes Journal ist keine Stenografie von allem, sondern eine Auswahl von Fakten, mit denen sich der Ablauf rekonstruieren und Statistik bilden lässt.

• Kennungen: Sitzungs-ID, ID der Aufgabe oder des Features, Modell des Agenten.
• Aktionen mit Nebenwirkungen: welche Befehle gestartet und welche Dateien geändert wurden. Das Lesen von Dateien braucht meist nicht protokolliert zu werden.
• Ergebnisse der Prüfungen: welcher Prüfbefehl, Rückgabecode, wie viele Tests bestanden und fehlgeschlagen sind.
• Wiederholungen: wie viele Versuche ein Schritt brauchte und worin sie sich unterschieden.
• Verbrauch: Token und Zeit, sofern das Werkzeug sie liefert.
• Ergebnis: Aufgabe angenommen, abgelehnt oder abgebrochen, und warum.

Was man nicht schreibt: Geheimnisse, Zugriffstoken, personenbezogene Daten aus der Ausgabe von Befehlen. Das Journal kann in den allgemeinen Zugriff oder erneut in den Kontext des Modells gelangen.

Aktionsjournal über Hooks in Claude Code

In Claude Code führt man das Journal am besten über Hooks — Befehle, die das Werkzeug selbst startet und nicht das Modell. Sie laufen deshalb immer. Der Hook erhält als Eingabe ein JSON mit der Beschreibung des Ereignisses, darunter Sitzungs-ID, Name des Werkzeugs und seine Parameter. Ein Beispiel für die Einrichtung in .claude/settings.json, die nach jedem Aufruf von Bash, Edit oder Write eine Zeile ins Journal schreibt:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — eine JSON-Zeile pro Aktion
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

Das Format JSONL (ein JSON-Datensatz pro Zeile) lässt sich bequem mit jq filtern und in jedes Analysesystem laden. Zusätzlich speichert Claude Code die vollständige Historie der Sitzungen lokal im Verzeichnis ~/.claude/projects/. Dort können Sie die Überlegungen und die vollständige Ausgabe nachlesen, für Statistiken ist aber das eigene, kompakte Journal praktischer.

Tracing: ein Trace pro Sitzung, ein Span pro Aufgabe

Wenn viele Agenten arbeiten oder nach Zeitplan laufen, reichen Textjournale nicht mehr: Man braucht Aggregate. Hier helfen die gewöhnlichen Werkzeuge des verteilten Tracings und der Standard OpenTelemetry.

• Trace — eine Sitzung des Agenten.
• Span — eine Aufgabe innerhalb der Sitzung.
• Verschachtelte Spans — Verifikationsschritte: Build, Tests, End-to-End-Tests.

Mindestens an jedem Span sollten Attribute stehen: ID des Features und der Sitzung, Modell, Ergebnis der Prüfung, Token, Anzahl der Wiederholungen. Solche Daten lassen sich in Jaeger, Grafana Tempo oder Honeycomb auswerten und beantworten Fragen, die man in einer einzelnen Sitzung nicht sieht: Welcher Aufgabentyp braucht am häufigsten Wiederholungen, wo verbraucht der Agent die meisten Token, nach welcher Änderung am Harness ist der Anteil angenommener Aufgaben gesunken. Claude Code bietet einen eingebauten Export von Metriken und Ereignissen über OpenTelemetry, der über Umgebungsvariablen aktiviert wird; Einzelheiten stehen in der Dokumentation des Werkzeugs.

Commits als Journal

Das billigste und verlässlichste Journal haben Sie ohnehin: git. Man muss es nur lesbar machen.

1. Ein Commit — eine Aufgabe. Dann entspricht git log der Liste des Erledigten, und das Zurücknehmen einer Aufgabe ist ein einziges git revert.
2. In der Nachricht steht, was und wie geprüft wurde. Nicht »fix«, sondern was geändert wurde, warum, und mit welchem Befehl es geprüft wurde.
3. Commit erst nach grüner Prüfung. Dann ist jeder Punkt der Historie ein funktionierender Stand, und git bisect findet den Schuldigen.

fix(payments): Rundung des Rabatts auf ganze Cent

Der Rabatt wurde als float berechnet, bei einer Summe von 999.99 ging ein Cent verloren.
Die Berechnung auf int in Cent umgestellt.
Geprüft: make test (142 passed), make e2e checkout — ok.
Außerhalb des Umfangs: Rundung in Berichten, in BACKLOG.md festgehalten.

Der Bericht des Agenten: Belege statt Eindrücke

Die abschließende Nachricht des Agenten ist ebenfalls ein Artefakt der Beobachtbarkeit, wenn sie eine feste Form hat. Legen Sie eine Vorlage in AGENTS.md oder CLAUDE.md fest:

## Bericht am Ende der Aufgabe
- Was erledigt wurde: Liste der Änderungen (Datei — Kern)
- Wie geprüft: genaue Befehle und deren Ergebnis
- Was NICHT geprüft wurde und warum
- Abweichungen von der Vereinbarung über die Aufgabe
- Offene Fragen an den Menschen

Die wichtigste Regel: Jede Aussage verweist auf einen Beleg — eine Datei und Zeile, die Ausgabe eines Tests, einen Eintrag im Journal. »Sieht normal aus« und »ich denke, passt« zählen nicht als Bericht. Der Punkt »was nicht geprüft wurde« ist besonders wertvoll, denn er zeigt ehrlich die Grenzen der Sicherheit.

Vereinbarung vor dem Code und Matrix danach

Die Prozessschicht beginnt vor der Arbeit. Eine kurze Vereinbarung über die Aufgabe (Sprint Contract) legt Umfang, Abnahmekriterien, den Abschnitt »außerhalb des Umfangs« und offene Fragen fest, die der Mensch entscheidet. Der Abschnitt »außerhalb des Umfangs« verhindert etwa die Hälfte aller Streitigkeiten über das Ergebnis.

Nach der Arbeit wird das Ergebnis nach einer Bewertungsmatrix beurteilt und nicht nach dem Eindruck. Sonst kommen zwei erfahrene Reviewer zu unterschiedlichen Urteilen, und die Bewertung wird zur Lotterie.

Jede Dimension wird mit A, B, C oder D bewertet, und eine Bewertung ohne Verweis gilt nicht. Eine einfache Entscheidungsregel: Eine D oder zwei C führen zur Ablehnung mit einer Liste dessen, was zu korrigieren ist. Dieselbe Matrix kann auch ein eigener prüfender Agent anwenden.

Wie Sie nachvollziehen, was der Agent in einer Sitzung getan hat

Gibt es keinen Bericht oder misstrauen Sie ihm, gehen Sie die Artefakte in dieser Reihenfolge durch.

1. Zustand des Arbeitsbaums: git status — was nicht committet ist, ob Müll-Dateien liegen.
2. Historie: git log --stat seit Beginn der Sitzung — welche Commits und Dateien.
3. Umfang der Änderungen: git diff --stat main...HEAD, danach der vollständige Diff der wichtigen Dateien.
4. Aktionsjournal: welche Befehle gestartet wurden und was die Prüfungen zurückgaben.
5. Erneute Prüfung: starten Sie Build und Tests selbst. Vertrauen Sie der Ausgabe eines Befehls, nicht der Nacherzählung.

# welche Befehle der Agent in der letzten Sitzung gestartet hat
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# welche Dateien am häufigsten geändert wurden
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

Typische Fehler

• Alles protokollieren. Gigabytes an Stenografie liest niemand. Protokollieren Sie Aktionen mit Nebenwirkungen und die Ergebnisse der Prüfungen.
• Freies Format. Wenn der Agent das Format des Journals selbst bestimmt, gibt es keine Aggregate. Das Format legt das Harness fest.
• Dem Bericht ohne Befehlsausgabe glauben. »Tests grün« ohne Ausgabe ist eine Meinung.
• Blinde Wiederholungen. Ohne Ursache des Fehlers ändert der Agent zufällige Stellen. Verlangen Sie zuerst die Diagnose mit einem Verweis auf das Log und erst danach die Korrektur.
• »Räumen wir später auf.« Debug-Dateien und nicht committete Änderungen verwirren die nächste Sitzung: Sie kann das Vorübergehende nicht vom Absichtlichen unterscheiden.

Fazit

Die Beobachtbarkeit von KI-Agenten baut sich aus zwei Schichten auf: Laufzeit (Aktionsjournal über Hooks, Traces, Commits mit der Beschreibung der Prüfungen) und Prozess (Vereinbarung über die Aufgabe vor dem Code, Bewertungsmatrix und Bericht mit Belegen). Dann bedeutet »fertig« in jeder Sitzung dasselbe, und die Prüfung der Arbeit des Agenten dauert Minuten. Dieses Thema behandeln wir im Kurs zum Harness Engineering praktisch, an einem durchgehenden Projekt eines Zahlungs-Backends.