unified ai service concept
This commit is contained in:
ValueOn AG
parent
ef006acb1c
commit
1c9b62aef9
2 changed files with 1610 additions and 0 deletions
1464
concepts/AI-Agent-Architecture-Konzept.md
Normal file
1464
concepts/AI-Agent-Architecture-Konzept.md
Normal file
File diff suppressed because it is too large
Load diff
146
concepts/AI-Agent-Architecture-Review.md
Normal file
146
concepts/AI-Agent-Architecture-Review.md
Normal file
|
|
@ -0,0 +1,146 @@
|
|||
# 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
|
||||
|
||||
```python
|
||||
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.
|
||||
Loading…
Reference in a new issue