'use client' import { useState } from 'react' import Link from 'next/link' import { ArrowLeft, Cpu, Brain, MessageSquare, Database, Activity, Shield, ChevronDown, ChevronRight, GitBranch, Layers, Server, FileText, AlertTriangle, CheckCircle, Zap, RefreshCw } from 'lucide-react' interface Section { id: string title: string icon: React.ReactNode content: React.ReactNode } export default function ArchitecturePage() { const [expandedSections, setExpandedSections] = useState(['overview', 'agents', 'soul-files']) const toggleSection = (id: string) => { setExpandedSections(prev => prev.includes(id) ? prev.filter(s => s !== id) : [...prev, id] ) } const sections: Section[] = [ { id: 'overview', title: 'System-Uebersicht', icon: , content: (

Das Breakpilot Multi-Agent-System basiert auf dem Mission Control Konzept. Es ermoeglicht die Koordination mehrerer spezialisierter KI-Agents, die gemeinsam komplexe Aufgaben loesen.

{/* Architecture Diagram */}
{`
┌─────────────────────────────────────────────────────────────────┐
│                     Breakpilot Services                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │Voice Service│  │Klausur Svc  │  │  Admin-v2 / AlertAgent  │  │
│  └──────┬──────┘  └──────┬──────┘  └───────────┬─────────────┘  │
│         │                │                      │                │
│         └────────────────┼──────────────────────┘                │
│                          │                                       │
│  ┌───────────────────────▼───────────────────────────────────┐  │
│  │                    Agent Core                              │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌───────────────────┐  │  │
│  │  │   Sessions  │  │Shared Brain │  │   Orchestrator    │  │  │
│  │  │ - Manager   │  │ - Memory    │  │ - Message Bus     │  │  │
│  │  │ - Heartbeat │  │ - Context   │  │ - Supervisor      │  │  │
│  │  │ - Checkpoint│  │ - Knowledge │  │ - Task Router     │  │  │
│  │  └─────────────┘  └─────────────┘  └───────────────────┘  │  │
│  └───────────────────────────────────────────────────────────┘  │
│                          │                                       │
│  ┌───────────────────────▼───────────────────────────────────┐  │
│  │                   Infrastructure                           │  │
│  │     Valkey (Redis)          PostgreSQL          Qdrant     │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
            `}
Session Management

Verwaltet Agent-Lifecycles mit State Machine, Checkpoints und automatischer Recovery.

Shared Brain

Gemeinsames Gedaechtnis fuer alle Agents mit TTL, Context-Verwaltung und Knowledge Graph.

Orchestrator

Message Bus, Supervisor und Task Router fuer die Agent-Koordination.

) }, { id: 'agents', title: 'Agent-Typen', icon: , content: (

Jeder Agent hat eine spezialisierte Rolle im System. Die Agents kommunizieren ueber den Message Bus und nutzen das Shared Brain fuer konsistente Entscheidungen.

{/* TutorAgent */}

TutorAgent

Lernbegleitung und Fragen beantworten

Geduldig Ermutigend Sokratisch
SOUL: tutor-agent.soul.md | Routing: learning_*, help_*, question_*
{/* GraderAgent */}

GraderAgent

Klausur-Korrektur und Bewertung

Objektiv Fair Konstruktiv
SOUL: grader-agent.soul.md | Routing: grade_*, evaluate_*, correct_*
{/* QualityJudge */}

QualityJudge

BQAS Qualitaetspruefung

Kritisch Praezise Schnell
SOUL: quality-judge.soul.md | Routing: quality_*, review_*, validate_*
{/* AlertAgent */}

AlertAgent

Monitoring und Benachrichtigungen

Wachsam Proaktiv Priorisierend
SOUL: alert-agent.soul.md | Routing: alert_*, monitor_*, notify_*
{/* Orchestrator */}

Orchestrator

Task-Koordination und Routing

Koordinierend Effizient Zuverlaessig
SOUL: orchestrator.soul.md | Routing: Fallback fuer alle unbekannten Intents
) }, { id: 'soul-files', title: 'SOUL-Files (Persoenlichkeiten)', icon: , content: (

SOUL-Dateien (Semantic Outline for Unified Learning) definieren die Persoenlichkeit und Verhaltensregeln jedes Agents. Sie bestimmen, wie ein Agent kommuniziert, entscheidet und eskaliert.

# Beispiel: tutor-agent.soul.md
{`
# TutorAgent SOUL

## Identitaet
Du bist ein geduldiger, ermutigender Lernbegleiter fuer Schueler.
Dein Ziel ist es, Verstaendnis zu foerdern, nicht Antworten vorzugeben.

## Kommunikationsstil
- Verwende einfache, klare Sprache
- Stelle Rueckfragen, um Verstaendnis zu pruefen
- Gib Hinweise statt direkter Loesungen
- Feiere kleine Erfolge

## Fachgebiete
- Mathematik (Grundschule bis Abitur)
- Naturwissenschaften (Physik, Chemie, Biologie)
- Sprachen (Deutsch, Englisch)

## Einschraenkungen
- Gib NIEMALS vollstaendige Loesungen fuer Hausaufgaben
- Verweise bei komplexen Themen auf Lehrkraefte
- Erkenne Frustration und biete Pausen an

## Eskalation
- Bei wiederholtem Unverstaendnis: Schlage alternatives Erklaerformat vor
- Bei emotionaler Belastung: Empfehle Gespraech mit Vertrauensperson
- Bei technischen Problemen: Eskaliere an Support
            `}

SOUL-Struktur

Identitaet

Wer ist der Agent? Welche Rolle nimmt er ein?

Kommunikationsstil

Wie kommuniziert der Agent mit Benutzern?

Fachgebiete

In welchen Bereichen ist der Agent kompetent?

Einschraenkungen

Was darf der Agent NICHT tun?

Eskalation

Wann und wie eskaliert der Agent an andere Agents oder Menschen?

) }, { id: 'message-bus', title: 'Message Bus & Kommunikation', icon: , content: (

Der Message Bus ermoeglicht die asynchrone Kommunikation zwischen Agents via Redis Pub/Sub. Er unterstuetzt Prioritaeten, Request-Response-Pattern und Broadcast-Nachrichten.

# Nachrichtenfluss
{`
┌──────────────┐                    ┌──────────────┐
│   Sender     │                    │   Receiver   │
│   (Agent)    │                    │   (Agent)    │
└──────┬───────┘                    └──────▲───────┘
       │                                   │
       │ publish(AgentMessage)             │ handle(message)
       │                                   │
       ▼                                   │
┌────────────────────────────────────────────────────────┐
│                     Message Bus                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │ Priority Q  │  │   Routing   │  │   Logging   │    │
│  │ HIGH/NORMAL │  │   Rules     │  │   Audit     │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
│                                                         │
│                 Redis Pub/Sub                          │
└────────────────────────────────────────────────────────┘
            `}

Nachrichtentypen

Typ Prioritaet Beschreibung
task_request NORMAL Neue Aufgabe an Agent senden
task_response NORMAL Antwort auf task_request
escalation HIGH Eskalation an anderen Agent
alert CRITICAL Kritische Benachrichtigung
heartbeat LOW Liveness-Signal
) }, { id: 'shared-brain', title: 'Shared Brain (Gedaechtnis)', icon: , content: (

Das Shared Brain speichert Wissen und Kontext, auf den alle Agents zugreifen koennen. Es besteht aus drei Komponenten: Memory Store, Context Manager und Knowledge Graph.

Memory Store

Langzeit-Gedaechtnis fuer Fakten, Entscheidungen und Lernfortschritte.

  • - TTL-basierte Expiration (30 Tage default)
  • - Access-Tracking (Haeufigkeit)
  • - Pattern-basierte Suche
  • - Hybrid: Redis + PostgreSQL

Context Manager

Verwaltet Konversationskontext mit automatischer Komprimierung.

  • - Max 50 Messages pro Context
  • - Automatische Zusammenfassung
  • - System-Messages bleiben erhalten
  • - Entity-Extraktion

Knowledge Graph

Graph-basierte Darstellung von Entitaeten und ihren Beziehungen.

  • - Entitaeten: Student, Lehrer, Fach
  • - Beziehungen: lernt, unterrichtet
  • - BFS-basierte Pfadsuche
  • - Verwandte Entitaeten finden
# Memory Store Beispiel
{`
# Speichern
await store.remember(
    key="student:123:progress",
    value={"level": 5, "score": 85, "topic": "algebra"},
    agent_id="tutor-agent",
    ttl_days=30
)

# Abrufen
progress = await store.recall("student:123:progress")
# → {"level": 5, "score": 85, "topic": "algebra"}

# Suchen
all_progress = await store.search("student:123:*")
# → [Memory(...), Memory(...), ...]
            `}
) }, { id: 'task-routing', title: 'Task Routing', icon: , content: (

Der Task Router entscheidet, welcher Agent eine Anfrage bearbeitet. Er verwendet Intent-basierte Regeln mit Prioritaeten und Fallback-Ketten.

Intent-Pattern Ziel-Agent Prioritaet Fallback
learning_* TutorAgent 10 Orchestrator
help_*, question_* TutorAgent 8 Orchestrator
grade_*, evaluate_* GraderAgent 10 Orchestrator
quality_*, review_* QualityJudge 10 GraderAgent
alert_*, monitor_* AlertAgent 10 Orchestrator
* (alle anderen) Orchestrator 0 -

Routing-Strategien

  • ROUND_ROBIN - Gleichmaessige Verteilung
  • LEAST_LOADED - Agent mit wenigsten Tasks
  • PRIORITY - Hoechste Prioritaet zuerst
  • RANDOM - Zufaellige Auswahl

Fallback-Verhalten

  • 1. Versuche Ziel-Agent zu erreichen
  • 2. Bei Timeout: Fallback-Agent nutzen
  • 3. Bei Fehler: Orchestrator uebernimmt
  • 4. Bei kritischen Fehlern: Alert an Admin
) }, { id: 'session-lifecycle', title: 'Session Lifecycle', icon: , content: (

Sessions verwalten den Zustand von Agent-Interaktionen. Jede Session hat einen definierten Lebenszyklus mit Checkpoints fuer Recovery.

# Session State Machine
{`
                    ┌─────────────────────────────────────┐
                    │                                     │
                    ▼                                     │
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  ACTIVE  │───▶│  PAUSED  │───▶│ COMPLETED│    │  FAILED  │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
     │               │                               ▲
     │               │                               │
     └───────────────┴───────────────────────────────┘
                          (bei Fehler)

States:
- ACTIVE: Session laeuft, Agent verarbeitet Tasks
- PAUSED: Session pausiert, wartet auf Eingabe
- COMPLETED: Session erfolgreich beendet
- FAILED: Session mit Fehler beendet
            `}

Heartbeat Monitoring

30s
Timeout
5s
Check Interval
3
Max Missed Beats

Nach 3 verpassten Heartbeats wird der Agent als ausgefallen markiert und die Restart-Policy greift (max. 3 Versuche).

) }, { id: 'database', title: 'Datenbank-Schema', icon: , content: (

Das Agent-System nutzt PostgreSQL fuer persistente Daten und Valkey (Redis) fuer Caching und Pub/Sub.

{/* agent_sessions */}

agent_sessions

Speichert Session-Daten mit Checkpoints

{`
CREATE TABLE agent_sessions (
    id UUID PRIMARY KEY,
    agent_type VARCHAR(50) NOT NULL,
    user_id UUID REFERENCES users(id),
    state VARCHAR(20) NOT NULL DEFAULT 'active',
    context JSONB DEFAULT '{}',
    checkpoints JSONB DEFAULT '[]',
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    last_heartbeat TIMESTAMPTZ DEFAULT NOW()
);
                `}
{/* agent_memory */}

agent_memory

Langzeit-Gedaechtnis mit TTL

{`
CREATE TABLE agent_memory (
    id UUID PRIMARY KEY,
    namespace VARCHAR(100) NOT NULL,
    key VARCHAR(500) NOT NULL,
    value JSONB NOT NULL,
    agent_id VARCHAR(50) NOT NULL,
    access_count INTEGER DEFAULT 0,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    expires_at TIMESTAMPTZ,
    UNIQUE(namespace, key)
);
                `}
{/* agent_messages */}

agent_messages

Audit-Trail fuer Inter-Agent Kommunikation

{`
CREATE TABLE agent_messages (
    id UUID PRIMARY KEY,
    sender VARCHAR(50) NOT NULL,
    receiver VARCHAR(50) NOT NULL,
    message_type VARCHAR(50) NOT NULL,
    payload JSONB NOT NULL,
    priority INTEGER DEFAULT 1,
    correlation_id UUID,
    created_at TIMESTAMPTZ DEFAULT NOW()
);
                `}
) } ] return (
{/* Header */}
Zurueck zur Agent-Verwaltung

Multi-Agent Architektur

Technische Dokumentation des Breakpilot Multi-Agent-Systems

{/* Table of Contents */}

Inhaltsverzeichnis

{sections.map(section => ( ))}
{/* Sections */}
{sections.map(section => (
{expandedSections.includes(section.id) && (
{section.content}
)}
))}
{/* Footer Links */}

Weiterführende Ressourcen

Agent-Uebersicht Aktive Sessions Statistiken
) }