agent-architecture-audit

Agent Architecture Audit (Agenten-Architektur-Audit)

Ein Diagnose-Workflow für Agentensysteme, die Fehler hinter Wrapper-Ebenen, veraltetem Speicher, Wiederholungsschleifen oder Transport-/Rendering-Mutationen verstecken.

Wann aktivieren

VERPFLICHTEND für:

• Veröffentlichung einer agenten- oder LLM-gestützten Anwendung in der Produktion
• Auslieferung von Funktionen mit Tool-Aufrufen, Speicherung oder mehrstufigen Workflows
• Agentenverhalten verschlechtert sich nach dem Hinzufügen von Wrapper-Ebenen
• Benutzer berichten "der Agent wird schlechter" oder "Tools sind unzuverlässig"
• Gleiches Modell funktioniert in der Spielwiese, aber nicht innerhalb Ihres Wrappers
• Debugging des Agentenverhaltens länger als 15 Minuten ohne Ursachenfindung

Besonders wichtig bei:

• Sie haben neue Prompt-Ebenen, Tool-Definitionen oder Speichersysteme hinzugefügt
• Unterschiedliche Agenten in Ihrem System verhalten sich inkonsistent
• Das Modell funktionierte gestern einwandfrei, halluziniert heute aber
• Sie vermuten versteckte Reparatur-/Wiederholungsschleifen, die Antworten stillschweigend verändern

Nicht verwenden für:

• Allgemeines Code-Debugging – verwenden Sie agent-introspection-debugging
• Code-Review – verwenden Sie sprachspezifische Reviewer-Agenten
• Sicherheitsscans – verwenden Sie security-review oder security-review/scan
• Leistungsbenchmarking von Agenten – verwenden Sie agent-eval
• Schreiben neuer Funktionen – verwenden Sie den entsprechenden Workflow-Skill

Der 12-Schichten-Stack

Jedes Agentensystem durchläuft diese Schichten. Jede davon kann die Antwort verfälschen:

#	Schicht	Was schief geht
1	Systemaufforderung	Widersprüchliche Anweisungen, Anweisungsaufblähung
2	Sitzungshistorie	Veraltete Kontexteinspritzung aus vorherigen Durchgängen
3	Langzeitspeicher	Verschmutzung über Sitzungen hinweg, alte Themen in neuen Gesprächen
4	Destillation	Komprimierte Artefakte tauchen als Pseudo-Fakten wieder auf
5	Aktiver Abruf	Redundante Zusammenfassungsebenen 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	Tool-Output falsch gelesen oder ignoriert
9	Antwortformung	Formatkorruption in der endgültigen Antwort
10	Plattform-Rendering	Transport-Ebenen-Mutation (UI, API, CLI verändert gültige Antworten)
11	Versteckte Reparaturschleifen	Stille Fallback-/Wiederholungsagenten 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 Basis-Modell liefert korrekte Antworten, aber die Wrapper-Ebenen machen es schlechter.

Symptome:

• Modell funktioniert in der Spielwiese oder bei direktem API-Aufruf einwandfrei, bricht in Ihrem Agenten ab
• Neue Prompt-Ebene hinzugefügt, vorhandenes Verhalten verschlechtert
• Agent klingt selbstbewusst, ist aber selbstbewusst falsch
• "Es funktionierte vor dem letzten Update"

2. Speicherverschmutzung

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 neue)
• Artefakte derselben Sitzung tauchen als Pseudo-Fakten wieder auf
• Speicher wächst unbegrenzt und verschlechtert die Antwortqualität im Laufe der Zeit

3. Fehlerhafte Werkzeugdisziplin

Tools werden im Prompt deklariert, aber nicht im Code durchgesetzt. Das Modell überspringt sie oder halluziniert deren 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 verändert sie während der Auslieferung.

Symptome:

• Logs zeigen korrekte Antwort, Benutzer sieht kaputte Ausgabe
• Markdown-Rendering, JSON-Parsing oder Streaming-Fragmente verfälschen gültige Antworten
• Stiller Fallback-Agent ersetzt die Antwort vor der Auslieferung
• Ausgabe unterscheidet sich zwischen Terminal und UI

5. Versteckte Agentenebenen

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

Symptome:

• Ausgabe ändert sich zwischen interner Generierung und Benutzerauslieferung
• "Auto-Korrektur"-Schleifen führen einen zweiten LLM-Durchlauf aus, von dem der Benutzer nichts weiß
• Mehrere Agenten ändern dieselbe Ausgabe ohne Koordination
• Antworten werden durch unsichtbare Ebenen "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 begann es?
• Zu prüfende Schichten – welche der 12 Schichten sind relevant?

Phase 2: Beweiserhebung

Sammeln Sie Beweise aus dem Codebestand:

• Quellcode – Agenten-Loop, Tool-Router, Speicherverwaltung, Prompt-Assembly
• Logs – historische Sitzungsprotokolle, Tool-Aufruf-Aufzeichnungen
• Konfiguration – Prompt-Vorlagen, Tool-Schemata, Anbietereinstellungen
• Speicherdateien – SOPs, Wissensdatenbanken, Sitzungsarchive

Verwenden Sie rg, um nach Anti-Patterns zu suchen:

# Tool-Anforderungen, die nur im Prompt-Text ausgedrückt werden (nicht im Code)
rg "must.*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

Für jeden Befund dokumentieren:

• Symptom – was der Benutzer sieht
• Mechanismus – wie der Wrapper es verursacht
• Ursprungsschicht – welche der 12 Schichten
• Grundursache – die tiefste Ursache
• Beweis – file:line oder log:row Referenz
• Vertrauensgrad – 0,0 bis 1,0

Phase 4: Korrekturstrategie

Standard-Reihenfolge der Korrekturen (Code zuerst, nicht Prompt zuerst):

1. Code-gestützte Tool-Anforderungen – im Code durchsetzen, nicht nur im Prompt-Text
2. Versteckte Reparatur-Agenten entfernen oder eingrenzen – Fallback explizit mit Verträgen machen
3. Kontext-Duplikation reduzieren – gleiche Information über Prompt + Historie + Speicher + Destillation
4. Speicheraufnahme verschärfen – Benutzerkorrekturen > Agentenaussagen
5. Destillationsauslöser verschärfen – nicht komprimieren, was nicht komprimiert werden sollte
6. Rendering-Mutation reduzieren – durchreichen, nicht transformieren
7. Auf getypte JSON-Envelopes umstellen – strukturierter interner Fluss, nicht freiform Prosa

Schweregrad-Modell

Stufe	Bedeutung	Aktion
critical	Agent kann selbstbewusst falsches Betriebsverhalten erzeugen	Vor nächster Version beheben
high	Agent beeinträchtigt häufig Korrektheit oder Stabilität	In diesem Sprint beheben
medium	Korrektheit überlebt meist, aber Ausgabe ist fragil oder verschwenderisch	Für nächsten Zyklus planen
low	Meist kosmetische oder Wartbarkeitsprobleme	Backlog

Ausgabeformat

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

1. Nach Schweregrad geordnete Befunde (kritischste zuerst)
2. Architekturdiagnose (welche Schicht hat was verfälscht und warum)
3. Geordneter Korrekturplan (Code zuerst, nicht Prompt zuerst)

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

Schnell-Diagnose-Fragen

Wenn Sie ein Agentensystem auditieren, beantworten Sie diese:

#	Frage	Wenn Ja →
1	Kann das Modell ein erforderliches Tool überspringen und trotzdem antworten?	Tool nicht durch Code abgesichert
2	Taucht alter Gesprächsinhalt in neuen Durchgängen auf?	Speicherverschmutzung
3	Ist dieselbe Information in Systemaufforderung UND Speicher UND Historie?	Kontext-Duplikation
4	Führt die Plattform einen zweiten LLM-Durchlauf vor der Auslieferung durch?	Versteckte Reparaturschleife
5	Unterscheidet sich die Ausgabe zwischen interner Generierung und Benutzerauslieferung?	Rendering-Korruption
6	Sind "muss Tool X verwenden"-Regeln nur im Prompt-Text?	Fehlerhafte Werkzeugdisziplin
7	Kann der eigene Monolog des Agenten zu persistentem Speicher werden?	Speichervergiftung

Anti-Patterns vermeiden

• Vermeiden Sie es, das Modell zu beschuldigen, bevor Sie Wrapper-Ebenen-Regressionen widerlegt haben.
• Vermeiden Sie es, den Speicher zu beschuldigen, ohne den Kontaminationspfad aufzuzeigen.
• Lassen Sie nicht zu, dass ein sauberer aktueller Zustand einen schmutzigen historischen Vorfall auslöscht.
• Behandeln Sie Markdown-Prosa nicht als vertrauenswürdiges internes Protokoll.
• Akzeptieren Sie kein "muss Tool verwenden" im Prompt-Text, wenn der Code es nie durchsetzt.
• Halten Sie Befunde direkt, belegbasiert und nach Schweregrad geordnet.

Berichtsschema

Audits sollten strukturierte Berichte nach diesem Format erzeugen:

{
  "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": ["file:line"],
      "confidence": 0.0,
      "recommended_fix": "string"
    }
  ],
  "ordered_fix_plan": [
    { "order": 1, "goal": "string", "why_now": "string", "expected_effect": "string" }
  ]
}

Verwandte Skills

• agent-introspection-debugging – Debuggen von Laufzeitfehlern in 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 – Erstellung von Agenten-Harness von Grund auf