wiki/concepts/AI-Agent-Architecture-Review.md

Review: AI Agent Architecture & Unified Workspace

Konzept-Review | Version 2.0 | März 2026 Bezugsdokument: AI-Agent-Architecture-Konzept.md v2.0

---

1. Gesamturteil

Version 2.0 des Konzepts hat die Mehrheit der kritischen Punkte aus dem ersten Review adressiert. Die grössten Lücken (Fehlerbehandlung, Kosten-Budget, RBAC-Klarstellung, ServiceCenter-Integration, Background Workflows, Observability) sind nun beschrieben. Das Konzept ist von einer Richtungsvorgabe zu einem tragfähigen Architektur-Dokument gereift.

Dimension	v1.3	v2.0	Kommentar
Tauglichkeit	Gut	Gut	Unverändert stark
Durchdachtheit	Teilweise	Gut	Fehlerbehandlung, Kosten-Kontrolle, Observability ergänzt
Logische Korrektheit	Mehrheitlich	Korrekt	Zahlen korrigiert, Datenmodell-Duplikat aufgelöst
Strukturelle Nachvollziehbarkeit	Gut	Gut	ServiceCenter-Registry explizit, RBAC-Design-Entscheidung dokumentiert
Wartbarkeit	Unklar	Teilweise	Observability ergänzt, Test-Strategie fehlt weiterhin
Praktikabilität	Riskant	Machbar	Background Workflows nun DB-basiert, Budget-Cap vorhanden

---

2. Adressierte Punkte aus dem ersten Review

2.1 Vollständig adressiert

Punkt	Wo in v2.0	Bewertung
Faktische Zahlen (7 Methods, 36 Actions, 22 dynamicMode)	Abschnitt 10.3	Korrekt
FileContentIndex Doppeldefinition	Abschnitt 5.4 verweist auf 4.4 als kanonisch	Gelöst
ServiceCenter-Registry (module, class, dependencies, objectKey)	Abschnitt 3.1, expliziter Registry-Eintrag	Sauber, Dependencies ["ai", "chat", "extraction", "billing", "streaming"] korrekt
RBAC Design-Entscheidung	Abschnitt 3.5, Tabelle mit darunterliegender Absicherung pro Tool	Korrekt: keine Tool-Level-RBAC, Daten-/Service-Ebene reicht
Knowledge Store Shared Layer RBAC	Abschnitt 3.5: isShared=True erfordert Access-Level ALL, neue Tabellen brauchen TABLE_NAMESPACE	Klar definiert
maxCostCHF Budget-Cap	Abschnitt 3.1 (AgentConfig), 3.2 (Loop-Prüfung)	Korrekt integriert, nutzt getWorkflowCost()
Entity Cache Opt-in	Abschnitt 3.1 (entityCacheEnabled: bool = False), 4.8 (Opt-in + Regex/NER-Alternative)	Sauber gelöst
Progressive Summarization Kosten	Abschnitt 4.7: günstigeres Modell, fliesst ins Budget ein, eigener Typ in BillingTransaction	Transparent
Fehlerbehandlung	Abschnitt 3.4: Tabelle mit 7 Fehlertypen + Strategien	Vollständig
Input-Validierung	Abschnitt 3.4: Path-Traversal, SQL-Injection, Container-Limits	Konkret
Parallele Tool-Ausführung	Abschnitt 3.2 (_executeToolCalls), 3.3, 3.6 (readOnly-Flag)	Korrekt: readOnly parallel, write sequential
ZIP-Bomb-Schutz	Abschnitt 5.4: MAX_TOTAL_EXTRACTED_SIZE=500MB, MAX_FILE_COUNT=10000, Symlink-Blockierung	Konkrete Limits definiert
Background Workflows	Abschnitt 11: DB-basierte Queue (BackgroundJob), Worker-Prozess, Retry, Billing-Cap, User-Benachrichtigung	Von "schwächster Teil" zu solide aufgewertet
Observability	Neuer Abschnitt 12: AgentTrace, AgentRoundLog, ToolCallLog, Kosten-Transparenz, Monitoring-Metriken	Umfassend
AiCallRequest Abwärtskompatibilität	Abschnitt 3.3: "bestehende prompt/context/contentParts bleiben"	Explizit erwähnt
Graceful Degradation bei maxRounds	Abschnitt 3.2: Status maxRoundsReached + _summarizeProgress()	Sauber implementiert

2.2 Teilweise adressiert

Punkt	Status	Was fehlt
Background Workflow Concurrency	maxConcurrency als Feld auf BackgroundJob definiert (Abschnitt 11.1)	Worker-Code erzwingt das Limit nicht -- die Queue-Logik braucht einen Semaphore oder Worker-Pool-Begrenzung
Kosten-Transparenz im UI	Billing-Posten sind definiert (Abschnitt 12.2), Monitoring-Metriken beschrieben (12.3)	Kein UI-Mockup für die Kosten-Anzeige im Workspace. Kein Kosten-Voranschlag vor Agent-Start

2.3 Noch offen

Punkt	Priorität	Kommentar
Test-Strategie	Mittel	Kein Wort zu Unit-Tests, Integration-Tests oder Evaluation-Frameworks. Agent-Systeme sind nicht-deterministisch -- wie wird Qualität sichergestellt? Empfehlung: deterministische Tool-Mock-Tests, Prompt-Regression-Suite, End-to-End-Tests mit fixierten LLM-Responses
LangGraph-Migration	Niedrig	Chatbot mit LangGraph-Graph (planner → conditional routing → agent_sql_plan / agent_tavily / agent_answer) und custom DatabaseCheckpointer. Konzept sagt "Abgelöst" (Abschnitt 14), aber: Migration bestehender Conversations? Wie bildet der neue Agent den Graph-Router ab? LangGraph-Features (interrupt/resume, state snapshots) -- Ersatz?
Zeitplanung	Mittel	9 Phasen weiterhin ohne Aufwandschätzung oder Meilensteine
End-to-End-Sequenzdiagramm	Niedrig	User → SSE → Agent → Tool → Billing → Response als Mermaid Sequence Diagram wäre wertvoll für Implementierer
Rollback-Kriterien	Niedrig	Was passiert, wenn eine Phase scheitert?
Embedding-Re-Indexierung	Niedrig	Strategie bei Modellwechsel (alle Chunks neu embedden) nicht beschrieben

---

3. Neue Inhalte in v2.0 -- Qualitätsprüfung

3.1 AgentConfig (Abschnitt 3.1) -- Gut

class AgentConfig(BaseModel):
    maxRounds: int = 25
    maxCostCHF: Optional[float] = None
    entityCacheEnabled: bool = False
    toolSet: str = "core"
    operationType: str = "AGENT"

Sinnvolle Defaults. maxCostCHF = None bedeutet kein Limit als Default -- das ist riskant für unbeaufsichtigte Workflows. Empfehlung: Default-Budget pro FeatureInstance konfigurierbar machen, damit Admins ein Sicherheitsnetz haben.

3.2 Fehlerbehandlung (Abschnitt 3.4) -- Gut

Die Fehler-Taxonomie mit 7 Typen und klaren Strategien ist solide. Besonders gut:

• Tool-Fehler → Agent entscheidet (nicht blindes Retry)
• Knowledge Store nicht verfügbar → degraded mode (kein Hard-Fail)
• Externe APIs → Exponential Backoff (max 3)

Ein Punkt fehlt: Poison Messages. Wenn ein bestimmter Prompt den Agent reliabel in eine Endlosschleife treibt (z.B. Tool A schlägt fehl → Agent ruft Tool A erneut auf → Endlosschleife), wird das nur durch maxRounds abgefangen. Ein spezifischer Schutz (z.B. max 3 identische Tool-Calls hintereinander → Abbruch) wäre robuster.

3.3 RBAC-Abschnitt (3.5) -- Korrekt

Die Tabelle mit der darunterliegenden Absicherung pro Tool-Kategorie ist präzise und deckt sich mit der tatsächlichen Codebasis. Die Design-Entscheidung "keine Tool-Level-RBAC" ist korrekt begründet und architektonisch konsistent.

Kleiner Hinweis: Die Formulierung "Promote in Shared Layer (isShared=True) erfordert Access-Level ALL" ist sinnvoll. Es sollte dokumentiert werden, auf welchem ObjectKey dieses Access-Level geprüft wird (vermutlich data.knowledge.FileContentIndex oder ähnlich).

3.4 Background Workflows (Abschnitt 11) -- Deutlich verbessert

Von asyncio.create_task() zu DB-basierter Queue mit BackgroundJob-Model, Worker-Prozess, Retry und Billing-Cap. Das ist ein grosser Sprung.

Offene Punkte:

• Worker-Lifecycle: Wer startet den Worker? Ist er Teil des FastAPI-Lifespan (wie der bestehende eventManager)? Oder ein separater Prozess?
• Concurrency: maxConcurrency auf dem Job-Model, aber der Worker pollt sequentiell (dequeueNext → process → next). Mehrere Worker-Tasks parallel zu starten fehlt.
• Dead-Letter-Queue: Nach maxRetries wird der Job als failed markiert und der User benachrichtigt. Aber gibt es eine Möglichkeit, fehlgeschlagene Jobs zu inspizieren und manuell erneut zu starten?

3.5 Observability (Abschnitt 12) -- Gut

AgentTrace → AgentRoundLog → ToolCallLog ist eine saubere Hierarchie. Die Kosten-Transparenz-Tabelle (Abschnitt 12.2) mit eigenen description-Typen pro Billing-Posten ist praktisch.

Die Monitoring-Metriken (12.3) decken die wichtigsten Dimensionen ab. Was fehlt: Alerting. Bei welchen Schwellwerten wird ein Admin benachrichtigt? (z.B. >50% Abbrüche wegen Budget, Knowledge-Store-Fehlerrate >5%, etc.)

---

4. Verbleibende Empfehlungen

Bereich	Empfehlung	Priorität
Test-Strategie	Neuer Abschnitt: deterministische Tool-Tests (Mock-LLM), Prompt-Regression, E2E-Tests	Mittel
Default-Budget	maxCostCHF Default pro FeatureInstance konfigurierbar (Admin-Sicherheitsnetz)	Mittel
Poison-Message-Schutz	Max N identische Tool-Calls hintereinander → Abbruch	Niedrig
Background Worker Lifecycle	Klären: Teil von FastAPI-Lifespan oder separater Prozess? Concurrency-Enforcement	Mittel
LangGraph-Migrationsplan	Detailkonzept für Phase 8: History-Migration, Router-Abbildung	Niedrig
Zeitplanung	Aufwandschätzung pro Phase, Meilensteine	Mittel
Shared-Layer ObjectKey	Dokumentieren, auf welchem DATA-ObjectKey der ALL-Check für isShared=True läuft	Niedrig

---

5. Fazit

Version 2.0 ist ein umsetzungsreifes Architektur-Dokument. Die kritischen Lücken der Vorgängerversion sind geschlossen:

Thema	v1.3	v2.0
Fehlerbehandlung	Fehlte komplett	7 Fehlertypen mit Strategien
Kosten-Kontrolle	Kein Budget-Cap	maxCostCHF, Entity-Cache Opt-in, Summary-Kosten transparent
RBAC	Nicht erwähnt	Explizite Design-Entscheidung: keine Tool-RBAC, Daten-/Service-Ebene reicht
ServiceCenter	Nicht beschrieben	Vollständiger Registry-Eintrag mit Dependencies
Background Workflows	asyncio.create_task()	DB-basierte Queue, Retry, Billing-Cap
Observability	Nicht erwähnt	AgentTrace, RoundLog, ToolCallLog, Monitoring-Metriken
Parallele Tools	Blinde asyncio.gather()	readOnly-Flag, sequential default
ZIP-Sicherheit	maxDepth=5 ohne Limits	500MB, 10000 Files, Symlink-Block
Zahlen	8/39/25 (falsch)	7/36/22 (korrekt)
FileContentIndex	Doppelt definiert	Kanonisch in 4.4, Referenz in 5.4

Die einzige relevante offene Lücke ist die fehlende Test-Strategie. Für ein AI-Agent-System, das nicht-deterministisch arbeitet, ist das ein wichtiger Aspekt, der vor Phase 1 geklärt werden sollte -- mindestens als Grundsatz-Entscheidung (wie werden Agent-Workflows getestet?).

Die Phasen 1-6 sind umsetzbar. Phase 7 (Unified UI) bleibt ein eigenständiges Grossprojekt. Phase 8 (LangGraph-Migration) braucht ein Detail-Konzept. Phase 9 ist nun solide fundiert.