Agent-Architektur-Audit

Was macht Agent-Architektur-Audit?

Ein diagnostischer Workflow für Agentensysteme, die Fehler hinter Wrapper-Schichten, veralteten Speicher, Wiederholungs-Schleifen oder Transport-/Rendering-Mutationen verbergen.

Wann aktivieren

VERPFLICHTEND für:

• Veröffentlichung einer beliebigen Agenten- oder LLM-gestützten Anwendung in der Produktion
• Auslieferung von Features mit Tool-Aufrufen, Speicher oder mehrstufigen Workflows
• Agentenverhalten verschlechtert sich nach Hinzufügen von Wrapper-Schichten
• Benutzer berichten "der Agent wird schlechter" oder "Tools sind unzuverlässig"
• Gleiches Modell funktioniert in der Playground-Umgebung, bricht aber innerhalb Ihres Wrappers
• Debugging von Agentenverhalten für mehr als 15 Minuten ohne Auffinden der Grundursache

Besonders kritisch wenn:

• Sie neue Prompt-Schichten, Tool-Definitionen oder Speichersysteme hinzugefügt haben
• Verschiedene Agenten in Ihrem System sich inkonsistent verhalten
• Das Modell gestern noch gut funktionierte, aber heute halluziniert
• Sie versteckte Reparatur-/Wiederholungs-Schleifen vermuten, die Antworten stillschweigend verändern

Nicht verwenden für:

• Allgemeines Code-Debugging — verwenden Sie agent-introspection-debugging
• Code-Review — verwenden Sie sprachspezifische Reviewer-Agenten
• Sicherheitsüberprüfung — verwenden Sie security-review oder security-review/scan
• Leistungsbenchmarking von Agenten — verwenden Sie agent-eval
• Schreiben neuer Features — verwenden Sie den entsprechenden Workflow-Skill

Der 12-Schichten-Stack

Jedes Agentensystem hat diese Schichten. Jede von ihnen kann die Antwort korrumpieren:

#	Schicht	Was schiefgeht
1	System-Prompt	Widersprüchliche Anweisungen, Anweisungsaufblähung
2	Sitzungshistorie	Veraltete Kontextinjektion aus vorherigen Runden
3	Langzeitspeicher	Verschmutzung über Sitzungen hinweg, alte Themen in neuen Gesprächen
4	Destillation	Komprimierte Artefakte gelangen als Pseudo-Fakten wieder ein
5	Aktiver Abruf	Redundante Wiederzusammenfassungs-Schichten verschwenden Kontext
6	Tool-Auswahl	Falsches Tool-Routing, Modell überspringt erforderliche Tools
7	Tool-Ausführung	Halluzinierte Ausführung — behauptet aufzurufen, tut es aber nicht
8	Tool-Interpretation	Fehlinterpretierte oder ignorierte Tool-Ausgabe
9	Antwortformung	Format-Korruption in der endgültigen Antwort
10	Plattform-Rendering	Transportebenen-Mutation (UI, API, CLI mutiert gültige Antworten)
11	Versteckte Reparatur-Schleifen	Stille Fallback-/Wiederholungs-Agenten führen einen zweiten LLM-Durchlauf aus
12	Persistenz	Abgelaufener Zustand oder zwischengespeicherte Artefakte werden als Live-Beweise wiederverwendet

Häufige Fehlermuster

1. Wrapper-Regression

Das Basismodell produziert korrekte Antworten, aber die Wrapper-Schichten machen es schlechter.

Symptome:

• Modell funktioniert gut in der Playground-Umgebung oder bei direktem API-Aufruf, bricht in Ihrem Agenten
• Neue Prompt-Schicht hinzugefügt, vorhandenes Verhalten verschlechtert
• Agent klingt selbstbewusst, ist aber selbstbewusst falsch
• "Es hat vor dem letzten Update funktioniert"

2. Speicherkontamination

Alte Themen gelangen durch Historie, Speicherabruf oder Destillation in neue Gespräche.

Symptome:

• Agent bringt nicht zusammenhängende vergangene Themen zur Sprache
• Benutzerkorrekturen bleiben nicht haften (alter Speicher überschreibt neuen)
• Artefakte derselben Sitzung gelangen als Pseudo-Fakten wieder ein
• Speicher wächst unbegrenzt und verschlechtert die Antwortqualität mit der Zeit

3. Tool-Disziplin-Fehler

Tools werden im Prompt deklariert, aber nicht im Code erzwungen. Das Modell überspringt sie oder halluziniert die Ausführung.

Symptome:

• "Muss Tool X verwenden" im Prompt, aber Modell antwortet, ohne es aufzurufen
• Tool-Ergebnisse sehen korrekt aus, wurden aber nie tatsächlich ausgeführt
• Verschiedene Tools streiten sich um dieselbe Verantwortung
• Modell verwendet Tool, wenn es nicht sollte, oder überspringt es, wenn es muss

4. Rendering-/Transport-Korruption

Die interne Antwort des Agenten ist korrekt, aber die Plattformebene mutiert sie während der Zustellung.

Symptome:

• Logs zeigen korrekte Antwort, Benutzer sieht kaputte Ausgabe
• Markdown-Rendering, JSON-Parsing oder Streaming-Fragmente korrumpieren gültige Antworten
• Versteckter Fallback-Agent ersetzt stillschweigend die Antwort vor der Zustellung
• Ausgabe unterscheidet sich zwischen Terminal und UI

5. Versteckte Agenten-Schichten

Stille Reparatur-, Wiederholungs-, Zusammenfassungs- oder Abruf-Agenten laufen ohne explizite Verträge.

Symptome:

• Ausgabe ändert sich zwischen interner Generierung und Benutzerzustellung
• "Auto-Fix"-Schleifen führen einen zweiten LLM-Durchlauf aus, von dem der Benutzer nichts weiß
• Mehrere Agenten modifizieren dieselbe Ausgabe ohne Koordination
• Antworten werden durch unsichtbare Schichten "geglättet" oder "korrigiert"

Audit-Workflow

Phase 1: Umfang

Definieren Sie, was Sie auditieren:

• Zielsystem — welche Agentenanwendung?
• Einstiegspunkte — wie interagieren Benutzer damit?
• Modell-Stack — welche(s) LLM(s) und Anbieter?
• Symptome — was meldet der Benutzer?
• Zeitfenster — wann hat es begonnen?
• Zu prüfende Schichten — welche der 12 Schichten sind relevant?

Phase 2: Beweissammlung

Sammeln Sie Beweise aus der Codebasis:

• Quellcode — Agenten-Schleife, Tool-Router, Speicheraufnahme, Prompt-Zusammenstellung
• Logs — historische Sitzungsabläufe, Tool-Aufrufprotokolle
• Konfiguration — Prompt-Vorlagen, Tool-Schemata, Anbietereinstellungen
• Speicherdateien — SOPs, Wissensdatenbanken, Sitzungsarchive

Verwenden Sie rg, um Anti-Patterns zu suchen:

# Tool-Anforderungen nur im Prompt-Text ausgedrückt (nicht im Code)
rg "muss.*tool|必须.*工具|required.*call" --type md

# Tool-Ausführung ohne Validierung
rg "tool_call|toolCall|tool_use" --type py --type ts

# Versteckte LLM-Aufrufe außerhalb der Haupt-Agenten-Schleife
rg "completion|chat\.create|messages\.create|llm\.invoke"

# Speicheraufnahme ohne Priorität für Benutzerkorrekturen
rg "memory.*admit|long.*term.*update|persist.*memory" --type py --type ts

# Fallback-Schleifen, die zusätzliche LLM-Aufrufe ausführen
rg "fallback|retry.*llm|repair.*prompt|re-?prompt" --type py --type ts

# Stille Ausgabe-Mutation
rg "mutate|rewrite.*response|transform.*output|shap" --type py --type ts

Phase 3: Fehlerzuordnung

Dokumentieren Sie für jeden Befund:

• Symptom — was der Benutzer sieht
• Mechanismus — wie der Wrapper es verursacht
• Quellschicht — welche der 12 Schichten
• Grundursache — die tiefste Ursache
• Beweis — datei:zeile oder log:zeile Referenz
• Konfidenz — 0.0 bis 1.0

Phase 4: Fix-Strategie

Standard-Fix-Reihenfolge (code-first, nicht prompt-first):

1. Code-Gate für Tool-Anforderungen — im Code erzwingen, nicht nur im Prompt-Text
2. Versteckte Reparatur-Agenten entfernen oder eingrenzen — Fallback explizit mit Verträgen machen
3. Kontext-Duplizierung reduzieren — gleiche Informationen durch Prompt + Historie + Speicher + Destillation
4. Speicheraufnahme straffen — Benutzerkorrekturen > Agentenbehauptungen
5. Destillationsauslöser straffen — nicht komprimieren, was nicht komprimiert werden sollte
6. Rendering-Mutation reduzieren — durchreichen, nicht transformieren
7. Auf typisierte JSON-Envelopes umstellen — strukturierter interner Fluss, nicht freiform Prosa

Schweregradmodell

Stufe	Bedeutung	Aktion
critical	Agent kann selbstbewusst falsches Betriebsverhalten erzeugen	Vor dem nächsten Release beheben
high	Agent verschlechtert häufig Korrektheit oder Stabilität	In diesem Sprint beheben
medium	Korrektheit überlebt meistens, aber Ausgabe ist fragil oder verschwenderisch	Für nächsten Zyklus planen
low	Meist kosmetische oder wartungsbezogene Probleme	Backlog

Ausgabeformat

Präsentieren Sie dem Benutzer die Ergebnisse in dieser Reihenfolge:

1. Nach Schweregrad sortierte Ergebnisse (kritischste zuerst)
2. Architektur-Diagnose (welche Schicht hat was korrumpiert und warum)
3. Geordneter Fix-Plan (code-first, nicht prompt-first)

Beginnen Sie nicht mit Komplimenten oder Zusammenfassungen. Wenn das System kaputt ist, sagen Sie es direkt.

Schnelle Diagnosefragen

Beim Auditieren eines Agentensystems beantworten Sie diese:

#	Frage	Falls Ja →
1	Kann das Modell ein erforderliches Tool überspringen und trotzdem antworten?	Tool nicht code-gated
2	Taucht alter Gesprächsinhalt in neuen Runden auf?	Speicherkontamination
3	Sind dieselben Informationen im System-Prompt UND im Speicher UND in der Historie?	Kontext-Duplizierung
4	Führt die Plattform einen zweiten LLM-Durchlauf vor der Zustellung durch?	Versteckte Reparatur-Schleife
5	Unterscheidet sich die Ausgabe zwischen interner Generierung und Benutzerzustellung?	Rendering-Korruption
6	Sind "muss Tool X verwenden"-Regeln nur im Prompt-Text?	Tool-Disziplin-Fehler
7	Kann der eigene Monolog des Agenten zu persistentem Speicher werden?	Speichervergiftung

Anti-Patterns vermeiden

• Vermeiden Sie es, dem Modell die Schuld zu geben, bevor Sie Wrapper-Schichten-Regressionen widerlegt haben.
• Vermeiden Sie es, dem Speicher die Schuld zu geben, ohne den Kontaminationspfad zu zeigen.
• Lassen Sie einen sauberen aktuellen Zustand keinen schmutzigen historischen Vorfall auslöschen.
• Behandeln Sie Markdown-Prosa nicht als vertrauenswürdiges internes Protokoll.
• Akzeptieren Sie kein "muss Tool verwenden" im Prompt-Text, wenn der Code es nie erzwingt.
• Halten Sie Ergebnisse direkt, belegbar und nach Schweregrad sortiert.

Berichtsschema

Audits sollten strukturierte Berichte in dieser Form erstellen:

{
  "schema_version": "ecc.agent-architecture-audit.report.v1",
  "executive_verdict": {
    "overall_health": "high_risk",
    "primary_failure_mode": "string",
    "most_urgent_fix": "string"
  },
  "scope": {
    "target_name": "string",
    "model_stack": ["string"],
    "layers_to_audit": ["string"]
  },
  "findings": [
    {
      "severity": "critical|high|medium|low",
      "title": "string",
      "mechanism": "string",
      "source_layer": "string",
      "root_cause": "string",
      "evidence_refs": ["datei:zeile"],
      "confidence": 0.0,
      "recommended_fix": "string"
    }
  ],
  "ordered_fix_plan": [
    { "order": 1, "goal": "string", "why_now": "string", "expected_effect": "string" }
  ]
}

Verwandte Fähigkeiten

• agent-introspection-debugging — Debuggen von Laufzeitfehlern von Agenten (Schleifen, Timeouts, Zustandsfehler)
• agent-eval — Benchmarking der Agentenleistung im direkten Vergleich
• security-review — Sicherheitsaudit für Code und Konfiguration
• autonomous-agent-harness — Einrichtung autonomer Agentenoperationen
• agent-harness-construction — Aufbau von Agenten-Harnesses von Grund auf