Audit-Logs für KI-Agenten: wie man Entscheidungsketten in Production rekonstruiert

Idee in 30 Sekunden

Audit-Logs sind ein zentrales Runtime-Journal der Agent-Entscheidungen: was passiert ist, warum es passiert ist und wer es ausgelöst hat.

Wann das nötig ist:
wenn ein Agent mit Tools, Approval und Limits arbeitet und jeder Incident auf Fakten statt Vermutungen analysiert werden muss.

Problem

Ohne Audit-Logs sieht das Team Symptome, aber nicht die Entscheidungskette. Im Demo fällt das kaum auf. In Production wird jeder Incident zu manuellem "Raten".

Typische Folgen:

• unklar, warum es deny oder stop gab
• unmöglich zu rekonstruieren, welcher Schritt side effects (Zustandsänderungen) erzeugt hat
• schwer dem Kunden zu erklären, wer wann eine Policy geändert oder eine Begrenzung aktiviert hat

Analogie: Das ist wie ein Unfall ohne Kameramitschnitt zu untersuchen. Man sieht das Ergebnis, aber es gibt keine prüfbare Ereignisfolge.

Und jede Minute ohne qualitativ guten Audit Trail verlängert den Incident und erhöht die Recovery-Zeit.

Lösung

Die Lösung ist ein zentraler Audit-Layer in Runtime, der sowohl Policy-Entscheidungen als auch den Ausführungsfakt der Aktion schreibt. Jeder Agent-Schritt loggt ein standardisiertes Event: decision, reason, action, scope, actor, timestamp.

Für Runtime ist ein einheitliches Entscheidungsmodell wichtig:

• allow
• stop
• approval_required

Wichtig ist auch, nicht nur Blockierungen zu loggen, sondern auch erfolgreiche Ausführung. Sonst sieht man im Incident "warum gestoppt wurde", aber nicht "was wirklich ausgeführt wurde".

Audit-Logs ≠ Debug-Logs

Das sind unterschiedliche Aufgaben:

• Audit-Logs sind ein strukturierter und reproduzierbarer Journal von Entscheidungen und Aktionen.
• Debug-Logs sind technische Details für lokale Diagnose.

Eins ohne das andere reicht nicht:

• ohne Audit-Logs gibt es keine rechtlich und operativ belastbare Entscheidungshistorie
• ohne Debug-Logs ist lokales Debugging der Implementierungsdetails schwer

Beispiel:

• audit: decision=stop, reason=rate_limited_tenant, tenant_id=t_42, action=crm.search
• debug: Stack Trace, interne Retry-Versuche, Latenz einzelner Abhängigkeiten

Komponenten der Audit-Kontrolle

Diese Komponenten arbeiten bei jedem Agent-Schritt zusammen.

Beispiel-Alert:

Slack: 🛑 Support-Agent decision=stop, reason=approval_required, tenant=t_42, run_id=run_981.

Wie das in der Architektur aussieht

Audit-Layer sitzt in der Runtime-Loop und erfasst Entscheidungen vor und nach Ausführung der nächsten Agent-Aktion. Jeder Outcome (allow, stop, approval_required) wird in einen zentralen Audit Trail geschrieben. Hier ist der Policy-Layer eine logische Runtime-Schicht, kein separater Service.

Jeder Schritt durchläuft diesen Flow vor Ausführung: Runtime führt eine Aktion nicht direkt aus, bevor Policy eine Entscheidung zurückgibt und das Event im Audit erfasst ist.

Flow kurz zusammengefasst:

• Runtime bildet die nächste Agent-Aktion
• Policy gibt allow, stop oder approval_required zurück
• Runtime loggt pre-event mit decision und reason
• wenn Aktion ausgeführt wurde, loggt Runtime post-event mit result
• beide Event-Typen sind für Alerting und Untersuchung durchsuchbar

Beispiel

Support-Agent bekommt eine Anfrage auf refund.create. Policy gibt approval_required zurück.

Ergebnis:

• Ausführung startet ohne Freigabe nicht
• im Audit steht decision=approval_required, actor, scope, action_key
• nach Freigabe steht ein separates Event decision=allow und das Ausführungsresultat

Audit-Logs verkürzen die Incident-Untersuchung auf Runtime-Schritt-Ebene, statt erst nach manueller Artefaktsammlung.

Im Code sieht das so aus

Die vereinfachte Skizze oben zeigt den Haupt-Flow. Kritisch: Audit-Events müssen strukturiert und schema-konsistent sein, sonst bricht die Incident-Suche.

Beispiel für Audit-Konfiguration:

audit:
  sink: append_only
  retention_days: 180
  redact_fields: ["email", "phone", "card_number"]
  hash_args: true
  sign_events: true

action = planner.next(state)
action_key = make_action_key(action.name, action.args)
decision = policy.evaluate(action, state.user_context)

base_event = {
    "run_id": run_id,
    "step_id": state.step,
    "tenant_id": state.tenant_id,
    "action": action.name,
    "action_key": action_key,
    "timestamp": clock.iso(),
}

audit.log(
    **base_event,
    phase="pre_exec",
    decision=decision.outcome,
    reason=decision.reason,
    args_hash=hash_args(action.args),
)

if decision.outcome == "approval_required":
    # approval resume flow wird als separater Runtime-Schritt geloggt:
    # approval_required -> approval_granted -> allow -> result
    return stop("approval_required")

if decision.outcome == "stop":
    return stop(decision.reason)

result = executor.execute(action)

audit.log(
    **base_event,
    phase="post_exec",
    decision=decision.outcome,
    reason=decision.reason,
    result=result.status,
)

return result

Wie das während der Ausführung aussieht

Szenario 1: policy stop

1. Runtime bildet Aktion crm.search.
2. Policy gibt stop (reason=rate_limited_tenant) zurück.
3. Runtime schreibt pre-event ins Audit.
4. Aktion wird nicht ausgeführt.
5. Team sieht den stop reason sofort in Logs.

Szenario 2: approval_required

1. Runtime bildet refund.create.
2. Policy gibt approval_required zurück.
3. Runtime schreibt pre-event und stoppt Ausführung.
4. Nach menschlicher Entscheidung startet ein separater Schritt.
5. Im Audit ist die ganze Kette sichtbar: approval_required -> allow -> result.

Szenario 3: allow + Ausführung

1. Runtime bildet die nächste Aktion.
2. Policy gibt allow zurück.
3. Runtime führt Aktion aus.
4. Schreibt post-event mit result.
5. Journal enthält Entscheidung und Ausführungsresultat.

Typische Fehler

• nur stop loggen, aber allow nicht loggen
• rohe args ohne redaction/hash speichern
• kein stabiler action_key für Deduplizierung
• audit und debug in einen unstrukturierten Textstrom mischen
• actor für Policy-Änderungen und Operator-Aktionen nicht erfassen
• Audit-Events nachträglich ändern oder löschen können

Ergebnis: Logs sind da, liefern im Incident aber kein prüfbares Bild.

Selbstcheck

Schneller Audit-Logging-Check vor dem Production-Start:

FAQ

Q: Worin unterscheiden sich Audit-Logs und Traces?
A: Trace zeigt den technischen Ausführungspfad, Audit-Log zeigt Policy-Entscheidungen und Aktionen als wer/was/warum. Für Incidents braucht man meist beides.

Q: Kann man für Komfort vollständige args loggen?
A: Besser nicht. In Production ist hash oder redacted-Variante sicherer, damit keine Secrets und PII leaken.

Q: Welcher minimale Feldsatz ist Pflicht?
A: Mindestens: run_id, step_id, decision, reason, action, action_key, scope, timestamp.

Q: Wann Event schreiben: vor oder nach Ausführung?
A: Beide Phasen sind wichtig: pre-event erfasst die Entscheidung, post-event erfasst Fakt und Ergebnis der Ausführung.

Q: Wo sollten Audit-Logs gespeichert werden?
A: In zentralem append-only Storage mit kontrolliertem Zugriff, retention und schneller Suche nach run_id/tenant_id/reason.

Wo Audit-Logs im Gesamtsystem liegen

Audit-Logs sind die Basis-Transparenzschicht in Agent Governance. Zusammen mit RBAC, Limits, Budget Controls, Approval und Kill switch geben sie kontrollierbares und erklärbares Agent-Verhalten in Production.

Verwandte Seiten

Als Nächstes zum Thema:

• Agent Governance Überblick — Gesamtmodell der Agent-Kontrolle in Production.
• Access Control (RBAC) — wie man Zugriffe vor Aktionsausführung begrenzt.
• Human approval — wie man riskante Write-Aktionen steuert.
• Rate limiting für Agenten — wie man Retry-Stürme und Spitzen begrenzt.
• Rollback-Strategien — wie man Traffic sicher auf stable version zurückschaltet.