From 4f92e5056c0a05986766b4a9abfde76e85c49924 Mon Sep 17 00:00:00 2001 From: Benjamin Admin Date: Mon, 4 May 2026 22:26:56 +0200 Subject: [PATCH] docs: Complete agent architecture reference for reuse in other agents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Full documentation of the ZeroClaw compliance agent architecture: - System overview diagram (Frontend → Backend → LLM → Playwright) - Detailed request flow for Website-Scan mode (7 steps) - All 5 components: Frontend, Backend, Consent-Tester, Ollama, Soul Files - 20 banner checks across 3 files - LLM call patterns (/api/generate + /api/chat + think-mode stripping) - Blueprint for creating new agents (5 steps: Soul, Route, Page, Proxy, Docker) - Timeouts, environment variables, file reference with LOC counts Designed as reusable blueprint for Sales, HR, Finance, or other agents. Co-Authored-By: Claude Opus 4.6 (1M context) --- zeroclaw/docs/agent-architecture.md | 367 ++++++++++++++++++++++++++++ 1 file changed, 367 insertions(+) create mode 100644 zeroclaw/docs/agent-architecture.md diff --git a/zeroclaw/docs/agent-architecture.md b/zeroclaw/docs/agent-architecture.md new file mode 100644 index 0000000..7d4f9fb --- /dev/null +++ b/zeroclaw/docs/agent-architecture.md @@ -0,0 +1,367 @@ +# ZeroClaw Agent-Architektur — Referenzdokumentation + +Dieses Dokument beschreibt die vollstaendige Architektur des Compliance-Agenten, +damit sie als Blaupause fuer weitere Agenten (z.B. Sales, HR, Finance) genutzt werden kann. + +--- + +## 1. Ueberblick + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ FRONTEND (Next.js) │ +│ admin-compliance/app/sdk/agent/page.tsx │ +│ 5 Tabs: Quick | Scan | Cookie-Test | Vergleich | Login-Test │ +│ │ +│ Proxy-Routes: /api/sdk/v1/agent/* │ +│ → leiten an Backend weiter (vermeidet SSL-Cert-Probleme) │ +└──────────────────────┬──────────────────────────────────────────┘ + │ POST /api/sdk/v1/agent/{mode} + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ BACKEND (Python/FastAPI) │ +│ backend-compliance:8002 │ +│ │ +│ Orchestriert den gesamten Flow: │ +│ 1. Ruft Playwright-Service fuer Website-Crawling │ +│ 2. Erkennt Services via Regex (82+ Patterns) │ +│ 3. Ruft LLM fuer Klassifikation/Korrekturen │ +│ 4. Prueft Pflichtfelder (Art. 13, §355, §305ff) │ +│ 5. Sendet E-Mail-Report │ +│ │ +│ Routes: │ +│ - agent_analyze_routes.py (Schnellanalyse) │ +│ - agent_scan_routes.py (Website-Scan + DSI Discovery) │ +│ - agent_compare_routes.py (Multi-Website-Vergleich) │ +│ - agent_notification_routes.py (E-Mail) │ +│ - agent_history_routes.py (Scan-Verlauf + PDF) │ +└──────────┬──────────────────────┬───────────────────────────────┘ + │ │ + ▼ ▼ +┌─────────────────────┐ ┌──────────────────────────────────────┐ +│ OLLAMA (LLM) │ │ CONSENT-TESTER (Playwright) │ +│ Mac Mini lokal │ │ consent-tester:8094 │ +│ │ │ │ +│ Qwen 3.5:35b-a3b │ │ Headless Chromium Browser: │ +│ Port: 11434 │ │ - /scan (3-Phasen Cookie-Test) │ +│ │ │ - /website-scan (JS-Rendering) │ +│ Endpunkte: │ │ - /dsi-discovery (Dokumentensuche) │ +│ /api/chat │ │ - /authenticated-scan (Login-Test) │ +│ /api/generate │ │ │ +│ /api/embeddings │ │ 20 Banner-Checks (rechtlich) │ +└─────────────────────┘ └──────────────────────────────────────┘ +``` + +--- + +## 2. Request-Flow (am Beispiel Website-Scan) + +``` +User klickt "Scan starten" im Frontend + │ + ▼ +POST /api/sdk/v1/agent/scan { url, mode, recipient } + │ + ├── Next.js API Route (Proxy) + │ admin-compliance/app/api/sdk/v1/agent/scan/route.ts + │ → Leitet an backend-compliance:8002 weiter + │ → Timeout: 5 Minuten + │ + ▼ +Backend: agent_scan_routes.py :: scan_website_endpoint() + │ + ├── Schritt 1: Playwright Website-Scan + │ POST http://consent-tester:8094/website-scan + │ → Chromium oeffnet URL, rendert JavaScript + │ → Klickt Navigations-Menues, entdeckt Unterseiten + │ → Gibt HTML aller Seiten zurueck (max 50 Seiten, 3 Min Timeout) + │ + ├── Schritt 1b: DSI Document Discovery + │ POST http://consent-tester:8094/dsi-discovery + │ → Findet alle rechtlichen Dokumente (DSI, AGB, Widerruf, Cookie) + │ → Oeffnet Accordions, Tabs, Sidebars + │ → Folgt Cross-Domain-Links (z.B. help.instagram.com) + │ → Extrahiert Text aus jedem Dokument + │ → Backend prueft Vollstaendigkeit (Art. 13 Checkliste) + │ + ├── Schritt 2: Service-Erkennung (deterministisch, kein LLM) + │ service_registry.py: 82+ Regex-Patterns gegen HTML + │ → Google Analytics, Facebook Pixel, Stripe, Hotjar, etc. + │ → Jeder Service hat: Kategorie, Anbieter, Land, Rechtsgrundlage + │ + ├── Schritt 3: DSE-Extraktion (LLM) + │ POST http://ollama:11434/api/generate + │ Prompt: "Extrahiere alle erwahnten Dienste aus dieser DSE..." + │ → Qwen 3.5 liest den DSE-Text und gibt JSON zurueck + │ → Fallback: Regex-Suche wenn LLM fehlschlaegt + │ + ├── Schritt 4: SOLL/IST-Vergleich + │ SOLL = Services aus DSE (was dokumentiert ist) + │ IST = Services auf Website (was tatsaechlich laeuft) + │ → "undocumented": auf Website, nicht in DSE (Verstoss!) + │ → "documented": beides OK + │ → "outdated": in DSE, nicht mehr auf Website + │ + ├── Schritt 5: Pflichtfeld-Pruefung + │ mandatory_content_checker.py: 9 Art. 13 DSGVO Felder + │ legal_basis_validator.py: Rechtsgrundlage korrekt? + │ dsi_document_checker.py: Jedes gefundene Dokument pruefen + │ + ├── Schritt 6: Korrekturen generieren (LLM, nur bei Findings) + │ POST http://ollama:11434/api/generate + │ Prompt: "Erstelle DSE-Textbaustein fuer Google Analytics..." + │ → Qwen 3.5 generiert einbaufertigen Text + │ + ├── Schritt 7: E-Mail senden + │ smtp_sender.py → Mailpit (SMTP :1025) + │ HTML-Report mit allen Findings + Korrekturen + │ + └── Response zurueck an Frontend + ScanResponse { pages_scanned, services[], findings[], + discovered_documents[], summary } +``` + +--- + +## 3. Komponenten im Detail + +### 3.1 Frontend (Next.js) + +**Seite:** `admin-compliance/app/sdk/agent/page.tsx` +**Hooks:** `admin-compliance/app/sdk/agent/_hooks/` +**Komponenten:** `admin-compliance/app/sdk/agent/_components/` + +| Komponente | Aufgabe | +|---|---| +| ScanResult.tsx | Service-Tabelle, Findings, PDF-Download | +| ConsentTestResult.tsx | 3-Phasen-Anzeige + Banner-Checks | +| CompareResult.tsx | Side-by-Side Vergleich | +| AuthTestResult.tsx | 5 Login-Checks | +| TextReference.tsx | Originaltext + Korrekturvorschlag | +| FollowUpQuestions.tsx | Ja/Nein Fragen | + +**Proxy-Pattern:** Jeder API-Call geht ueber eine Next.js API Route +(`app/api/sdk/v1/agent/*/route.ts`) die serverseitig an das Backend weiterleitet. +Das vermeidet CORS- und SSL-Probleme. + +### 3.2 Backend (Python/FastAPI) + +**Service:** `backend-compliance:8002` +**Prefix:** `/api/compliance/agent/` + +| Route-Datei | Endpunkt | Aufgabe | +|---|---|---| +| agent_analyze_routes.py | POST /analyze | Schnellanalyse (1 URL) | +| agent_scan_routes.py | POST /scan | Deep Scan + DSI Discovery | +| agent_compare_routes.py | POST /compare | Multi-URL Vergleich | +| agent_notification_routes.py | POST /notify | E-Mail senden | +| agent_history_routes.py | GET/POST /scans | Scan-Verlauf | +| agent_recurring_routes.py | */monitored-urls | Wiederkehrende Scans | + +**Wichtiges Design-Prinzip:** Das Backend orchestriert, macht aber keine +Browser-Operationen. Alles was einen Browser braucht → consent-tester. + +### 3.3 Consent-Tester (Playwright/FastAPI) + +**Service:** `consent-tester:8094` +**Dockerfile:** Chromium als appuser installiert (Permission-Fix) + +| Endpunkt | Aufgabe | Dateien | +|---|---|---| +| POST /scan | 3-Phasen Cookie-Test | consent_scanner.py, banner_text_checker.py, banner_advanced_checks.py | +| POST /website-scan | JS-gerendertes Crawling | playwright_scanner.py | +| POST /dsi-discovery | Dokumenten-Suche | dsi_discovery.py | +| POST /authenticated-scan | Login + Rechte-Check | authenticated_scanner.py | +| GET /health | Healthcheck | main.py | + +**20 Banner-Checks** in 3 Dateien: +- banner_text_checker.py (Checks 1-11) +- banner_advanced_checks.py (Checks 12-20) + +### 3.4 LLM (Ollama) + +**Modell:** Qwen 3.5:35b-a3b (23.9 GB, lokal auf Mac Mini) +**Port:** 11434 (erreichbar als `host.docker.internal:11434`) + +**Zwei Aufruf-Patterns:** + +```python +# Pattern 1: /api/generate (einfache Completion) +resp = await client.post(f"{OLLAMA_URL}/api/generate", json={ + "model": "qwen3.5:35b-a3b", + "prompt": "Erstelle einen DSE-Textbaustein...", + "stream": False, +}) +text = resp.json()["response"] + +# Pattern 2: /api/chat (Chat mit System-Prompt) +resp = await client.post(f"{OLLAMA_URL}/api/chat", json={ + "model": "qwen3.5:35b-a3b", + "messages": [ + {"role": "system", "content": "Du bist ein DSGVO-Experte..."}, + {"role": "user", "content": prompt}, + ], + "stream": False, + "format": "json", # Erzwingt JSON-Ausgabe +}) +text = resp.json()["message"]["content"] +``` + +**Think-Mode beachten:** Qwen 3.5 gibt `...` Tags aus. +Diese muessen aus der Antwort entfernt werden: +```python +raw = re.sub(r".*?", "", raw, flags=re.DOTALL).strip() +``` + +### 3.5 Soul Files (Agent-Persoenlichkeiten) + +**Pfad:** `admin-compliance/agent-core/soul/` + +| Datei | Agent | Aufgabe | +|---|---|---| +| compliance-advisor.soul.md | Compliance Advisor | Rechtsfragen beantworten (RAG) | +| drafting-agent.soul.md | Drafting Agent | DSGVO-Dokumente generieren | + +**Aufbau einer Soul-Datei:** +1. Identitaet (Wer bin ich?) +2. Kompetenzbereich (Was kann ich?) +3. RAG-Nutzung (Welche Quellen?) +4. Kommunikationsstil (Wie antworte ich?) +5. Einschraenkungen (Was darf ich nicht?) +6. Produktwissen (Features des Tools) +7. FAQ (Haeufige Fragen + Antworten) +8. Eskalation (Wann verweise ich weiter?) + +--- + +## 4. Blaupause: Neuen Agenten erstellen + +### Schritt 1: Soul-Datei erstellen + +```markdown +# Mein Agent + +## Identitaet +Du bist der [Name]-Agent. Du hilfst bei [Aufgabe]. + +## Kompetenzbereich +- [Thema 1] +- [Thema 2] + +## Kommunikationsstil +- Sachlich, verstaendlich +- Quellenangaben + +## Einschraenkungen +- Keine [X]-Beratung +``` + +### Schritt 2: Backend-Route erstellen + +```python +# backend-compliance/compliance/api/mein_agent_routes.py +from fastapi import APIRouter +router = APIRouter(prefix="/compliance/mein-agent", tags=["mein-agent"]) + +@router.post("/analyze") +async def analyze(req: AnalyzeRequest): + # 1. Daten holen (Playwright, API, DB) + # 2. LLM aufrufen (Ollama) + # 3. Ergebnis aufbereiten + # 4. E-Mail senden + return result +``` + +### Schritt 3: Frontend-Page erstellen + +``` +admin-compliance/app/sdk/mein-agent/ +├── page.tsx # Hauptseite mit Tabs +├── _hooks/ # State + API-Calls +└── _components/ # Ergebnis-Anzeige +``` + +### Schritt 4: Next.js Proxy-Route + +```typescript +// admin-compliance/app/api/sdk/v1/mein-agent/[[...path]]/route.ts +const BACKEND_URL = 'http://backend-compliance:8002' + +export async function POST(req, { params }) { + const path = (await params).path?.join('/') || '' + const resp = await fetch(`${BACKEND_URL}/api/compliance/mein-agent/${path}`, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: await req.text(), + }) + return NextResponse.json(await resp.json()) +} +``` + +### Schritt 5: In docker-compose.yml registrieren + +Der Agent laeuft als Teil des Backend-Services (kein eigener Container noetig, +es sei denn er braucht Playwright — dann eigenen Service wie consent-tester). + +--- + +## 5. Timeouts + +| Komponente | Timeout | Grund | +|---|---|---| +| Frontend → Backend Proxy | 300s (5 Min) | Scan kann lange dauern | +| Backend → Playwright | 180s (3 Min) | Browser-Rendering + Crawling | +| Backend → Ollama LLM | 180s (3 Min) | Grosse Modelle sind langsam | +| Playwright → Website | 20s pro Seite | Einzelne Seite laden | +| Exhaustive Crawl | 180-300s | Safety-Limit fuer rekursives Crawling | + +--- + +## 6. Environment-Variablen + +| Variable | Default | Beschreibung | +|---|---|---| +| OLLAMA_URL | http://host.docker.internal:11434 | Ollama LLM Endpunkt | +| OLLAMA_MODEL | qwen3.5:35b-a3b | Standard-Modell | +| BACKEND_URL | http://backend-compliance:8002 | Backend API | +| CONSENT_SERVICE_URL | http://consent-tester:8094 | Playwright-Service | +| RAG_SERVICE_URL | http://rag-service:8097 | RAG/Embedding Service | +| QDRANT_URL | https://qdrant-dev.breakpilot.ai | Vektor-Datenbank | +| SMTP_HOST | mailpit | E-Mail Server | +| SMTP_PORT | 1025 | SMTP Port | + +--- + +## 7. Dateien (Referenz) + +### Backend +| Datei | LOC | Aufgabe | +|---|---|---| +| agent_scan_routes.py | 448 | Scan-Orchestrierung | +| agent_scan_helpers.py | 109 | Summary + Korrekturen | +| agent_analyze_routes.py | 309 | Schnellanalyse | +| agent_compare_routes.py | 94 | Multi-Vergleich | +| agent_notification_routes.py | 111 | E-Mail | +| service_registry.py | 508 | 82+ Service-Patterns | +| dsi_document_checker.py | 229 | Dokument-Checklisten | +| mandatory_content_checker.py | 274 | Art. 13 Pflichtfelder | +| legal_basis_validator.py | 155 | Rechtsgrundlagen | + +### Consent-Tester +| Datei | LOC | Aufgabe | +|---|---|---| +| main.py | 321 | FastAPI + Endpunkte | +| consent_scanner.py | 213 | 3-Phasen-Test | +| banner_text_checker.py | 407 | Banner-Checks 1-11 | +| banner_advanced_checks.py | 396 | Banner-Checks 12-20 | +| dsi_discovery.py | 488 | Dokumenten-Suche | +| playwright_scanner.py | 266 | Website-Crawling | +| authenticated_scanner.py | 230 | Login-Tests | + +### Frontend +| Datei | LOC | Aufgabe | +|---|---|---| +| agent/page.tsx | 207 | 5-Tab Agent UI | +| ScanResult.tsx | 241 | Scan-Ergebnis | +| ConsentTestResult.tsx | 207 | Cookie-Test-Ergebnis | +| TextReference.tsx | 108 | Korrekturvorschlaege |