Diese Seite erklärt das System auf zwei Ebenen: erst das Was und Warum
in fünf Minuten — dann das Wie im Detail, mit lauffähigen Befehlen,
API-Referenz und Policy-Anatomie. Alles darin läuft genau so auf der Referenz-Instanz.
Sie wollen den Überblick ohne Technik?
Dafür gibt es den Rundgang auf der Produktseite.
Ihr KI-Agent führt riskante Aktionen nicht einfach aus. Er legt sie vor: ein einziger API-Call an das Policy-Gate, bevor das Tool läuft. Das Gate entscheidet in Millisekunden, mappt die Entscheidung auf Regulatorik-Kontrollen und schreibt sie fälschungssicher in die Audit-Kette. Kein Proxy, kein Sidecar, keine neue Infrastruktur — der Agent ruft das Gate aktiv auf (opt-in).
transfer_funds ausführenDie Posture-Ansicht: Wer läuft, wer wurde gestoppt, ist die Kette intakt? Kill-Switch per Klick — jede Statusänderung wird selbst auditiert.
Alle Spans (LLM-Calls, Tool-Calls, Gate-Verdikte) landen über OpenTelemetry in einer gemeinsamen, self-hosteten Datenbasis (Langfuse).
Ein Endpunkt liefert das Prüfer-Bundle: gefilterte Nachweise plus das Verdikt über die gesamte Kette — Integrität ist Teil des Exports.
Der mitgelieferte Demo-Agent — ein Zahlungs-Assistent im Financial-Services-Szenario — spielt den kompletten Kontrollzyklus durch. Jede Szene entspricht einer Harness-Dimension:
lookup_account und check_balance liegen in der Tool-Allowlist des
Agenten → allow. Das Gate kostet den Normalbetrieb nichts.
transfer_funds über 84.500 € ist als irreversibel klassifiziert →
pause (Human-Gate): menschliche Freigabe erforderlich, bevor etwas passiert.
Dieselbe Entscheidung trifft EU AI Act art-14 (Menschliche Aufsicht) und MaRisk at-4.3.2 (Prozessintegrierte Kontrollen) — beide Control-Hits stehen in der Gate-Antwort und in der Kette.
Der Betreiber pausiert den Agenten — per Dashboard-Klick oder API. Die Statusänderung wird selbst als Audit-Eintrag festgehalten.
Selbst das harmlose check_balance wird jetzt geblockt → block.
Ausführungssteuerung wirkt vor jeder weiteren Aktion.
Der Agent wird wieder aktiviert. Die Kette hält jeden Schritt: Verdikte, Eingriffe, Statuswechsel — verifizierbar über einen einzigen Endpunkt.
Die Posture-Seite unter /dashboard ist servergerendert und
zeigt den Live-Zustand der Instanz — kein Mockup, kein Frontend-Framework. Vier Blicke genügen:
Die Seite ist entlang der fünf Kontrolldimensionen gegliedert; das Band oben zeigt je Dimension den Live-Status: Agenten-Zähler, Verdikte und Eingriffe, Ketten-Urteil (Kette intakt ✓ plus Head-Hash), deny-by-default-Treffer. Verdikt-Donut und Rahmenwerk-Balken machen die Verteilungen sichtbar — jede Zahl stammt aus der Audit-Kette.
Jede Zeile: ID, Name, Risikoklasse, Status, erlaubte Tools. Daneben die Knöpfe Pause, Kill, Aktivieren — ein Klick, ein auditierter Statuswechsel, sofort wirksam am Gate.
Die jüngsten Verdikte mit Badge (allow pause · Human-Gate block), Begründung im Klartext und den getroffenen Controls. Badges tragen immer Text — nie Farbe allein.
Für die Tiefenanalyse: Die OTel-Spans jedes Gate-Verdikts liegen im self-hosteten Trace-Store (eigene Subdomain). Vom Verdict zur vollständigen Trace-Historie in einem Sprung.
/actions/*) authentifiziert Agenten per API-Key.
Die öffentliche Startseite bleibt frei. Zugang zur Referenz-Instanz gibt es
auf Anfrage.Ab hier wird es technisch: eigene Instanz starten, Agenten anbinden, Regulatorik erweitern. Alle Befehle sind wörtlich lauffähig — Python 3.12+ und Docker genügen.
Stufe 1 braucht keinerlei Infrastruktur: Gate, Risk-Engine, Audit-Kette und Dashboard laufen komplett in einem Python-Prozess. Die Stufen 2–3 fügen den vollen Observability-Stack hinzu.
# Stufe 1 — Control-Plane ohne Infrastruktur (empfohlen zum Kennenlernen) uv venv --python 3.12 && uv pip install -e ".[dev]" .venv/bin/python -m pytest # 29 Tests grün, keine Services nötig make dev # API + Dashboard auf http://localhost:8080 # Stufe 2 — voller Stack: Langfuse v3, ClickHouse, MinIO, OTel-Collector, n8n cp deploy/.env.example deploy/.env # Secrets setzen — niemals committen make up # 9 Services, healthchecked; ~6–9 GB RAM # Stufe 3 — das Demo-Drehbuch (Szenen 1–6 von oben) python examples/demo_agent.py --otlp http://localhost:4318 # Optional: ein voller Arbeitstag (69 Entscheidungen, 6 Agenten) → gefülltes Dashboard python examples/demo_day.py
Danach: http://localhost:8080/dashboard zeigt die Verdikte,
http://localhost:8080/evidence/verify das Ketten-Urteil. Referenz-Deployment
mit Härtung, TLS und Backup: deploy/RUNBOOK.md im Repository.
Ihr Agent ruft vor jedem riskanten Tool-Call das Gate auf und respektiert das Verdikt. Das ist der ganze Vertrag:
# Aktion vorlegen (mit API-Key, falls die Instanz einen verlangt) curl -X POST https://ihre-instanz.example.com/actions/authorize \ -H "Content-Type: application/json" \ -H "X-API-Key: $AGO_API_KEY" \ -d '{ "agent_id": "AG-014", "tool_name": "transfer_funds", "context": { "amount": "84500", "recipient": "DE89…" } }'
# Antwort — Verdikt, Begründung, Regulatorik und Ketten-Position in einem { "decision": "pause", "reason": "'transfer_funds' ist irreversibel — menschliche Freigabe erforderlich", "controls": [ { "framework": "EU AI Act", "control_id": "art-14", "severity": "high" }, { "framework": "MaRisk (angelehnt)", "control_id": "at-4.3.2", "severity": "high" } ], "event_id": "9f2c…", "audit_seq": 5, "audit_head": "1a6fcbc9…" }
① Agent-Status ≠ aktiv → block (Kill-Switch wirkt zuerst) · ② Tool nicht in der Allowlist → block (deny by default) · ③ Aktion irreversibel → pause (Human-Gate) · ④ sonst → allow. Jede Entscheidung durchläuft Risk-Engine und Audit-Kette — auch die erlaubten.
Das Gate verlangt X-API-Key, sobald AGO_API_KEY gesetzt ist —
lokal ohne Konfiguration bleibt es offen. Menschliche Endpunkte (Dashboard, Inventar)
schützt der Reverse-Proxy; der Demo-Agent nimmt dafür AGO_BASIC_AUTH=user:pass
entgegen.
Mit --otlp sendet der Demo-Agent je Verdikt einen Span mit
governance.*-Attributen an den Collector. Eigene Agenten instrumentieren
Sie einmal nach OTel-GenAI-Konvention — der Datenvertrag ist der einzige Vertrag.
Langfuse v3 verarbeitet Spans asynchron: Nach dem Senden dauert es ~40–45 Sekunden, bis Events über die Public API und UI sichtbar sind. Das ist Architektur, kein Fehler.
Alle Endpunkte der Control-Plane. „Proxy-Auth" = Zugangsschutz des
Reverse-Proxy (Betriebsentscheidung); lokal per make dev ist alles offen.
Interaktive Spezifikation: /docs (OpenAPI).
| Endpunkt | Zweck | Auth |
|---|---|---|
POST /actions/authorize | Das Gate. Aktion vorlegen → Verdikt + Controls + Ketten-Position | X-API-Key |
GET /inventory/agents | Agenten-Inventar mit Risikoklasse und Tool-Scope | Proxy-Auth |
POST /inventory/agents/{id}/status | Kill-Switch: active ·
paused · killed — selbst auditiert | Proxy-Auth |
POST /inventory/agents/{id}/enforcement | Lernphase ein/aus
(observe · enforce): Einführung ohne Betriebsstörung —
Human-Gate und Kill-Switch bleiben auch in der Lernphase scharf | Proxy-Auth |
GET /inventory/agents/{id}/allowlist-proposal | Allowlist-Vorschlag aus dem beobachteten Ist-Verhalten der Kette — die Übernahme bleibt eine menschliche, versionierte Entscheidung | Proxy-Auth |
POST /risk/evaluate | Beliebiges Governance-Event gegen alle aktiven Policy-Packs prüfen | Proxy-Auth |
GET /monitoring/summary | Kennzahlen aus dem Audit-Trail: Entscheidungen, Eingriffe, Agenten-Status | Proxy-Auth |
GET /reporting/posture | Control-Hits je Rahmenwerk + Evidence-Status | Proxy-Auth |
GET /evidence/verify | Ketten-Urteil: Einträge, chain_intact,
Head-Hash | Proxy-Auth |
GET /evidence/export | Prüfer-Bundle (filterbar nach Agent/Bereich) — immer inkl. Voll-Ketten-Verdikt | Proxy-Auth |
GET /evidence/view | Prüfer-Ansicht: die Hash-Kette menschenlesbar — Integritäts-Banner, sichtbare prev→hash-Verkettung, Filter | Proxy-Auth |
GET /dashboard | Posture-Seite; Kill-Switch-Formulare posten auf
/dashboard/agents/{id}/status | Proxy-Auth |
GET /health · GET /docs | Liveness · OpenAPI-Spezifikation | Proxy-Auth |
Policy-Packs sind versionierte YAML-Dateien in Git. Ein Control besteht aus Identität, Schwere und einem Trigger, der auf die OTel-Attribute des Events matcht:
# policy_packs/eu_ai_act/pack.yaml — Auszug framework: "EU AI Act" version: "0.2.0" controls: - id: art-14 title: "Menschliche Aufsicht" severity: high trigger: # Teilmengen-Match auf Event-Attribute governance.event.type: guardrail_verdict governance.guardrail.decision: pause
Autor, Diff, Review, Deploy-Zeitpunkt — die Änderungsgeschichte der Kontrollen ist selbst ein Nachweis. Die Plattform zieht versionierte Packs beim Deploy.
Auch irreversible Aktionen und
Tool-Allowlists je Risikoklasse sind Daten (policy_packs/harness/rules.yaml) —
Verhalten ändern heißt Daten ändern.
Die FS-Packs (MaRisk/DORA) sind angelehnte Demo-Mappings, keine Rechtsberatung — die Härtung erfolgt bewusst mit dem Regulatorik-Partner.
Jeder Audit-Eintrag trägt den SHA-256-Hash seines Vorgängers. Daraus folgen
drei Eigenschaften, die im Prüffall zählen — und für die Prüfung vor Ort zeigt die
Prüfer-Ansicht (GET /evidence/view) die Kette
menschenlesbar: Integritäts-Banner, Eintrag für Eintrag, mit sichtbarer
prev→hash-Verkettung.
GET /evidence/verify läuft die komplette Kette ab und antwortet mit
Eintragszahl, chain_intact und Head-Hash — dieselbe Prüfung, die das
Dashboard in der vierten Kachel zeigt.
Beim Laden einer persistierten Kette wird verifiziert. Wurde ein Eintrag verändert, verweigert die Control-Plane den Start — lieber down als auf manipulierter Evidence arbeiten.
GET /evidence/export?agent_id=AG-014 liefert das Prüfer-Bundle. Das
Voll-Ketten-Verdikt ist immer enthalten — ein Ausschnitt allein kann Integrität
nicht beweisen, und das Bundle sagt ehrlich, wogegen es verifiziert wurde.
Konfiguration läuft über Umgebungsvariablen (Präfix AGO_ für die
Control-Plane); die Vorlage deploy/.env.example dokumentiert den vollen Stack.
Die wichtigsten:
| Variable | Wirkung |
|---|---|
AGO_API_KEY | Schaltet den API-Key-Zwang auf /actions/*
scharf — Agenten müssen X-API-Key mitsenden |
AGO_AUDIT_LOG_FILE | Persistiert die Audit-Kette als JSONL; beim Start wird verifiziert und der Agenten-Status aus der Kette wiederhergestellt |
AGO_ACTIVE_FRAMEWORKS | Welche Policy-Packs aktiv sind (Default inkl. EU AI Act, ISO 42001, FS-Packs) |
AGO_LANGFUSE_HOST + Keys | Anbindung des Lese-Adapters an den Trace-Store (Langfuse Public API) |
BIND | Bind-Adresse der Compose-Ports — Default
127.0.0.1, damit Docker die Host-Firewall nicht umgeht |
MEM_* | Speicher-Limits je Service — Profile für 8-GB- und 16-GB-Maschinen in der Vorlage |
Provisionierung, Härtung (Firewall, fail2ban, SSH), TLS, Backup mit
Restore-Probe und die Kunden-Rollout-Checkliste stehen im Betriebshandbuch
deploy/RUNBOOK.md.
In 20 Minuten führen wir das Drehbuch live auf der Referenz-Instanz vor — Gate, Kill-Switch, Evidence-Export. Danach besprechen wir, wie Ihre Agenten unter den Harness kommen.