# ClawdDotNet — Orchestrator-Erweiterungskonzept 2026 *Stand: 31. August 2026* > **Konzept- und Entwurfsdokument.** Entstanden aus dem Marktvergleich (LangGraph, CrewAI, AutoGen, Letta, OpenHands, OpenClaw, Grokbot) und der anschließenden Detailabstimmung. > > Dieses Dokument beschreibt die neuen Kollaborations-, Daten-, Sicherheits- und Resilienz-Konzepte, um ClawdDotNet als universellen, betriebssicheren Orchestrator für spezialisierte Agententeams (Finanzanalyse, Software-Engineering, SEO/Marketing, Research) zu erweitern. --- ## 1. Übersicht der Kernsäulen ``` Architektur-Übersicht ┌─────────────────────────────────┬─────────────────────────────────┬─────────────────────────────────┐ │ 1. WORKFLOW & KOLLABORATION │ 2. DATEN & GEDÄCHTNIS │ 3. SICHERHEIT & DEFENSE │ │ • Hybride State-Graphs (YAML) │ • Schematisierte Instanz-DB │ • 5-Stufen Schutz vor Amoklauf │ │ • Debatten & Judge-Agent │ • Task-Memory-Flush │ • Quarantäne & Circuit Breaker │ │ • Ephemere Worker vs. Assistent │ • Scratchpad-Lifecycle │ • 1-Klick Rollback via RunId │ ├─────────────────────────────────┼─────────────────────────────────┼─────────────────────────────────┤ │ 4. HITL & EILMELDUNGEN │ 5. PROMPTS & TEMPLATES │ 6. RESILIENZ & BENCHMARK │ │ • ask_supervisor -> ask_human │ • Instanz-Setup für Personalmgr.│ • Multi-LLM Fallback-Kaskade │ │ • Mid-Execution Eilmeldungen │ • Dynamische Prompt-Templates │ • Evals as Code / Modell-Vergl. │ │ • Interaktive Messenger-Buttons │ • ext_clitools/ Build-Struktur │ • Kosten- & Latenz-Benchmarking │ └─────────────────────────────────┴─────────────────────────────────┴─────────────────────────────────┘ ``` --- ## 2. Säule 1: Workflow-Topologien & Kollaborationsmuster ### 2.1 Hybride State-Graphs & Deterministische Pipelines - **Ziel:** Kombination von deterministischer Prozesskonformität (für Pflicht- und Prüfschritte) mit agentischer Autonomie (für Recherche und Synthese). - **Struktur:** Workflows werden deklarativ in YAML-Dateien im Agenten- oder Instanz-Ordner definiert. - **Berechtigungsregel:** Ein Agent kann Workflow-Definitionen nicht eigenständig manipulieren. Änderungen erfolgen ausschließlich durch den Menschen oder über einen expliziten Workflow-Manager-Task. - **Ablauf:** ```mermaid flowchart LR A[Task Start] --> B[Node 1: Deterministic Data Fetch] B --> C[Node 2: Agent Analyse & Draft] C --> D{Node 3: Deterministic Rule Check} D -- Fail --> C D -- Pass --> E[Node 4: Staging Approval] E --> F[Done: Deliverable Commit] ``` ### 2.2 Multi-Agenten-Debatten mit „Judge Agent“ - **Ziel:** Iterative Qualitätsverbesserung durch Arbeiter-Kritiker-Zyklen (*Arbeiter* entwirft $\leftrightarrow$ *Kritiker* prüft) ohne Gefahr von Deadlocks oder Endlosschleifen. - **Steuerung im Taskboard:** - Arbeiter markiert Task als `in_review`. - Kritiker prüft gegen definierte Abnahmekriterien (`acceptance`). Bei Mängeln: Revisions-Task mit Feedback (Runde $1/N$). - **Abbruch-Bedingung:** Maximal 3 Iterationsrunden oder Erreichen des Ziel-Scores. - **Judge-Agent:** Bei verbleibendem Dissens nach Runde 3 greift automatisch der Supervisor/Judge-Agent ein und fällt die finale Entscheidung oder eskaliert gezielt an den Menschen. ### 2.3 Ephemere Subagenten vs. Feste Team-Assistenten - **Aufgabenteilung:** - **Personalmanager-Agent:** Erstellt vollwertige, persistente Team-Agenten mit eigenem Workspace und Langzeitgedächtnis für dauerhafte Rollen. - **Ephemere Subagenten (Worker):** Kurzlebige, zustandslose Worker für massiv-parallele Tool-Jobs (z. B. 20 Webseiten parallel crawlen). - **Budget-Hard-Cap:** Vor dem Start eines Subagenten muss ein Teilbudget aus dem Haupttask reserviert werden (CAS im `BudgetGuard`). Bei Überschreitung des Instanz-Budgets wird der Aufruf sofort abgelehnt. - **Vererbung von `RootRunId`:** Jeder Subagent erbt `RootRunId` und `ParentRunId` (#207), wodurch Gesamtkosten und Fehlerhistorie im Audit-Log lückenlos zusammengeführt werden. --- ## 3. Säule 2: Datenhaltung, Gedächtnis-Hygiene & Task-Lifecycle ### 3.1 Schematisierte Instanz-Datenbank („DocumentDB / CollectionStore“) - **Konzept:** JSON-Dokumenten-Store mit strikter Schema-Validierung, basierend auf dem bewährten `SqliteStorage` (WAL-Modus, keine Dateisperren-Konflikte). - **Ablage:** `SharedWorkspace/data/collections/` (oder als SQLite-Tabelle `InstanceCollections`). - **Schema-Bindung:** Ein Lead-Agent definiert einmalig `schema.json`. Alle `insert`/`update`-Aufrufe werden vor der Ausführung gegen das Schema validiert. - **Revisionssicherheit & Gleichzeitigkeit:** - Jedes Dokument führt `_id`, `_version`, `_created_by`, `_updated_at`, `_run_id` und `_is_deleted`. - Gleichzeitige Updates nutzen Optimistic Locking (CAS auf `_version`). - **Reines Append-Only:** Kein physisches `DELETE` — nur logische Soft-Deletes. ### 3.2 Task-spezifischer Memory-Flush (Kontext-Reset) - **Problem:** Ein Agent darf nach einer Nvidia-Analyse nicht mit Nvidia-Zahlen im Kopf an die Volkswagen-Analyse gehen. - **3-Stufen-Gedächtnisfluss:** 1. **Working Memory (Scratchpad):** Während des Tasks liegt das Rohwissen im Task-Scratchpad (`scratch/t-.md`). 2. **Memory-Commit bei Task-Abschluss:** Beim Übergang auf `done` filtert der Agent generalisierbare Kernfakten heraus und schreibt sie mit passendem `Subject` und `Key` ins Langzeitgedächtnis. 3. **Kontext-Reset:** Beim Wechsel auf einen neuen Task startet der Agent mit leerem Prompt-Kontext. Das automatische Memory-Recall lädt ausschließlich Fakten zum neuen Thema. ### 3.3 Scratchpad-Lifecycle & Archivierung - **Aktiv:** Während `in_progress` unter `SharedWorkspace/scratch/t-.md`. - **Archivierung:** Bei `done` oder `canceled` verschiebt der Taskboard-Scanner das Scratchpad atomar nach `SharedWorkspace/scratch/archive/`. - **Retention:** Ein wöchentlicher Wartungs-Job bereinigt archivierte Scratches älter als $X$ Tage (Standard: 30 Tage). --- ## 4. Säule 3: Sicherheit, Containment & Disaster Recovery ### 4.1 5-Stufen-Schutz gegen amoklaufende Agenten 1. **Prevent (Keine Zerstörungsgewalt):** - Reines Append-Only & Soft-Deletes in Datenbanken und Collections. - Kein Hard-Delete im Dateisystem: `FileRW`-Papierkorb (#195) und `protectedPaths` für Systemordner. - Unveränderliche Identitäten: `Identity.md` und `Soul.md` sind schreibgeschützt (#205). 2. **Contain (Blast Radius):** - Strikt getrennte Workspaces (`personal` vs. `shared`). - Rate-Limits für Task-Erstellung (z. B. max. 10 Tasks / Stunde je Agent). 3. **Detect (Anomalie-Erkennung & Circuit Breaker):** - Häufen sich Fehler oder Massenänderungen (> 5 Fehlversuche / 3 Minuten), stoppt der Engine-Circuit-Breaker den Agenten automatisch. 4. **Isolate (Quarantäne & Not-Aus):** - Der Agent wird in den Status `Quarantined` versetzt; laufende Hintergrund-Tasks werden auf `blocked` gesetzt. - Quarantäne kann durch den Supervisor-Agenten oder per Messenger-Befehl (`/quarantine @agent`) ausgelöst werden. 5. **Recover (1-Klick-Rollback / Time-Travel):** - Jede Aktion trägt die gestempelte `RunId` im Audit-Log. - Mit einem Befehl (`clawddotnet rollback --agent "@agent" --since "12:00"`) werden alle Datei- und Collection-Änderungen des Zeitraums atomar zurückgedreht. ### 4.2 Schutz vor lateraler Team-Infektion - **Untrusted Content Framing (#193):** Alle externen Tool-Ergebnisse, Scratches und Dokumente fremder Agenten werden im Prompt in ``-Tags gekapselt. Der Kern-Prompt verbietet die Befehlsausführung aus diesen Datenquellen strikt. --- ## 5. Säule 4: Human-in-the-Loop & Live-Intervention ### 5.1 Mehrstufige Eskalation: `ask_supervisor` $\rightarrow$ `ask_human` - **Stufe 1 (`ask_supervisor`):** Bei Mehrdeutigkeiten oder Blockaden wendet sich der Agent zuerst an den leitenden Team-Agenten. Kann dieser die Frage anhand von Projektregeln oder Kontext beantworten, läuft der Task ohne Menschen-Wartezeit weiter. - **Stufe 2 (`ask_human`):** Kann der Supervisor nicht entscheiden, wird die Frage als interaktive Nachricht (Telegram Inline-Buttons, Rocket.Chat) mit konkreten Auswahlschaltflächen an den Menschen gesendet. ### 5.2 Mid-Execution Priority Injects (Eilmeldungen & Zwischenrufe) - **Mechanismus:** Vor jedem OpenRouter-Inferenz-Schritt prüft die `AgentEngine` eine instanzinterne Prioritäts-Queue. - **Eilmeldungen:** Erkennt ein Monitor-Agent eine dringende Meldung (z. B. Veröffentlichung von Quartalszahlen), injiziert die Engine vor dem nächsten Denk-Schritt eine Systemnachricht: `[SYSTEM / EILMELDUNG von @market-watcher]: Neue Quartalszahlen NVDA soeben gemeldet: ...` - Der arbeitende Analyst bindet die neue Information unmittelbar ein, ohne dass der Task abgebrochen werden muss. --- ## 6. Säule 5: Vorlagen, Build-Struktur & Modell-Resilienz ### 6.1 Instanz-Erstellungsleitfaden & Dynamische Prompt-Templates - **Leitfaden für KI-Personalmanager:** Umfassender Prompt- und Best-Practice-Katalog für den Supervisor zur fehlerfreien Zusammenstellung neuer Agententeams. - **Dynamische Prompt-Templates (Scriban/Liquid):** Variablen wie `{{team_roster}}` oder `{{current_date}}` in `Identity.md` und `Soul.md` sorgen dafür, dass neue Agenten im Team sofort von allen Kollegen erkannt werden. ### 6.2 Externe CLI-Tools Verzeichnisstruktur (`ext_clitools/`) - Strukturierte und versionierte Ablage externer Binaries im Build: ``` clawddotnet/ └── ext_clitools/ ├── ffmpeg/ ├── yt-dlp/ └── typst/ ``` ### 6.3 Multi-LLM Fallback & Modell-Benchmarking („Evals as Code“) - **Fallback-Kaskade:** Konfiguration eines Ausweichmodells pro Agent (z. B. Primär: `anthropic/claude-3.7-sonnet`, Fallback: `google/gemini-2.5-pro`). Bei 5xx-Fehlern oder anhaltendem 429-Rate-Limit schaltet die Engine unterbrechungsfrei um. - **Evals-Test-Runner:** Automatisierter Benchmark, der definierte Testaufgaben gegen unterschiedliche Modelle laufen lässt, um Qualität, Latenz und Tokenkosten quantitativ zu vergleichen.