breakpilot-compliance/zeroclaw/docs/agent-architecture.md

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:

# 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 <think>...</think> Tags aus. Diese muessen aus der Antwort entfernt werden:

raw = re.sub(r"<think>.*?</think>", "", 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

# 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

# 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

// 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