breakpilot-pwa/agent-core/README.md

Breakpilot Agent Core

Multi-Agent Architecture Infrastructure für Breakpilot.

Übersicht

Das agent-core Modul stellt die gemeinsame Infrastruktur für Breakpilots Multi-Agent-System bereit:

• Session Management: Agent-Sessions mit Checkpoints und Recovery
• Shared Brain: Langzeit-Gedächtnis und Kontext-Verwaltung
• Orchestration: Message Bus, Supervisor und Task-Routing

Architektur

┌─────────────────────────────────────────────────────────────────┐
│                     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     │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Verzeichnisstruktur

agent-core/
├── __init__.py              # Modul-Exports
├── README.md                # Diese Datei
├── requirements.txt         # Python-Abhängigkeiten
├── pytest.ini               # Test-Konfiguration
│
├── soul/                    # Agent SOUL Files (Persönlichkeiten)
│   ├── tutor-agent.soul.md
│   ├── grader-agent.soul.md
│   ├── quality-judge.soul.md
│   ├── alert-agent.soul.md
│   └── orchestrator.soul.md
│
├── brain/                   # Shared Brain Implementation
│   ├── __init__.py
│   ├── memory_store.py      # Langzeit-Gedächtnis
│   ├── context_manager.py   # Konversations-Kontext
│   └── knowledge_graph.py   # Entity-Beziehungen
│
├── sessions/                # Session Management
│   ├── __init__.py
│   ├── session_manager.py   # Session-Lifecycle
│   ├── heartbeat.py         # Liveness-Monitoring
│   └── checkpoint.py        # Recovery-Checkpoints
│
├── orchestrator/            # Multi-Agent Orchestration
│   ├── __init__.py
│   ├── message_bus.py       # Inter-Agent Kommunikation
│   ├── supervisor.py        # Agent-Überwachung
│   └── task_router.py       # Intent-basiertes Routing
│
└── tests/                   # Unit Tests
    ├── conftest.py
    ├── test_session_manager.py
    ├── test_heartbeat.py
    ├── test_message_bus.py
    ├── test_memory_store.py
    └── test_task_router.py

Komponenten

1. Session Management

Verwaltet Agent-Sessions mit State-Machine und Recovery-Fähigkeiten.

from agent_core.sessions import SessionManager, AgentSession

# Session Manager erstellen
manager = SessionManager(
    redis_client=redis,
    db_pool=pg_pool,
    namespace="breakpilot"
)

# Session erstellen
session = await manager.create_session(
    agent_type="tutor-agent",
    user_id="user-123",
    context={"subject": "math"}
)

# Checkpoint setzen
session.checkpoint("task_started", {"task_id": "abc"})

# Session beenden
session.complete({"result": "success"})

Session States:

• ACTIVE - Session läuft
• PAUSED - Session pausiert
• COMPLETED - Session erfolgreich beendet
• FAILED - Session fehlgeschlagen

2. Heartbeat Monitoring

Überwacht Agent-Liveness und triggert Recovery bei Timeout.

from agent_core.sessions import HeartbeatMonitor, HeartbeatClient

# Monitor starten
monitor = HeartbeatMonitor(
    timeout_seconds=30,
    check_interval_seconds=5,
    max_missed_beats=3
)
await monitor.start_monitoring()

# Agent registrieren
monitor.register("agent-1", "tutor-agent")

# Heartbeat senden
async with HeartbeatClient("agent-1", monitor) as client:
    # Agent-Arbeit...
    pass

3. Memory Store

Langzeit-Gedächtnis für Agents mit TTL und Access-Tracking.

from agent_core.brain import MemoryStore

store = MemoryStore(redis_client=redis, db_pool=pg_pool)

# Erinnerung speichern
await store.remember(
    key="evaluation:math:student-1",
    value={"score": 85, "feedback": "Gut gemacht!"},
    agent_id="grader-agent",
    ttl_days=30
)

# Erinnerung abrufen
result = await store.recall("evaluation:math:student-1")

# Nach Pattern suchen
similar = await store.search("evaluation:math:*")

4. Context Manager

Verwaltet Konversationskontext mit automatischer Komprimierung.

from agent_core.brain import ContextManager, MessageRole

ctx_manager = ContextManager(redis_client=redis)

# Kontext erstellen
context = ctx_manager.create_context(
    session_id="session-123",
    system_prompt="Du bist ein hilfreicher Tutor...",
    max_messages=50
)

# Nachrichten hinzufügen
context.add_message(MessageRole.USER, "Was ist Photosynthese?")
context.add_message(MessageRole.ASSISTANT, "Photosynthese ist...")

# Für LLM API formatieren
messages = context.get_messages_for_llm()

5. Message Bus

Inter-Agent Kommunikation via Redis Pub/Sub.

from agent_core.orchestrator import MessageBus, AgentMessage, MessagePriority

bus = MessageBus(redis_client=redis)
await bus.start()

# Handler registrieren
async def handle_message(msg):
    return {"status": "processed"}

await bus.subscribe("grader-agent", handle_message)

# Nachricht senden
await bus.publish(AgentMessage(
    sender="orchestrator",
    receiver="grader-agent",
    message_type="grade_request",
    payload={"exam_id": "exam-1"},
    priority=MessagePriority.HIGH
))

# Request-Response Pattern
response = await bus.request(message, timeout=30.0)

6. Agent Supervisor

Überwacht und koordiniert alle Agents.

from agent_core.orchestrator import AgentSupervisor, RestartPolicy

supervisor = AgentSupervisor(message_bus=bus, heartbeat_monitor=monitor)

# Agent registrieren
await supervisor.register_agent(
    agent_id="tutor-1",
    agent_type="tutor-agent",
    restart_policy=RestartPolicy.ON_FAILURE,
    max_restarts=3,
    capacity=10
)

# Agent starten
await supervisor.start_agent("tutor-1")

# Load Balancing
available = supervisor.get_available_agent("tutor-agent")

7. Task Router

Intent-basiertes Routing mit Fallback-Ketten.

from agent_core.orchestrator import TaskRouter, RoutingRule, RoutingStrategy

router = TaskRouter(supervisor=supervisor)

# Eigene Regel hinzufügen
router.add_rule(RoutingRule(
    intent_pattern="learning_*",
    agent_type="tutor-agent",
    priority=10,
    fallback_agent="orchestrator"
))

# Task routen
result = await router.route(
    intent="learning_math",
    context={"grade": 10},
    strategy=RoutingStrategy.LEAST_LOADED
)

if result.success:
    print(f"Routed to {result.agent_id}")

SOUL Files

SOUL-Dateien definieren die Persönlichkeit und Verhaltensregeln jedes Agents.

Agent	SOUL File	Verantwortlichkeit
TutorAgent	tutor-agent.soul.md	Lernbegleitung, Fragen beantworten
GraderAgent	grader-agent.soul.md	Klausur-Korrektur, Bewertung
QualityJudge	quality-judge.soul.md	BQAS Qualitätsprüfung
AlertAgent	alert-agent.soul.md	Monitoring, Benachrichtigungen
Orchestrator	orchestrator.soul.md	Task-Koordination

Datenbank-Schema

agent_sessions

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

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

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()
);

Integration

Mit Voice-Service

from services.enhanced_task_orchestrator import EnhancedTaskOrchestrator

orchestrator = EnhancedTaskOrchestrator(
    redis_client=redis,
    db_pool=pg_pool
)

await orchestrator.start()

# Session für Voice-Interaktion
session = await orchestrator.create_session(
    voice_session_id="voice-123",
    user_id="teacher-1"
)

# Task verarbeiten (nutzt Multi-Agent wenn nötig)
await orchestrator.process_task(task)

Mit BQAS

from bqas.quality_judge_agent import QualityJudgeAgent

judge = QualityJudgeAgent(
    message_bus=bus,
    memory_store=memory
)

await judge.start()

# Direkte Evaluation
result = await judge.evaluate(
    response="Der Satz des Pythagoras...",
    task_type="learning_math",
    context={"user_input": "Was ist Pythagoras?"}
)

if result["verdict"] == "production_ready":
    # Response ist OK
    pass

Tests

# In agent-core Verzeichnis
cd agent-core

# Alle Tests ausführen
pytest -v

# Mit Coverage
pytest --cov=. --cov-report=html

# Einzelnes Test-Modul
pytest tests/test_session_manager.py -v

# Async-Tests
pytest tests/test_message_bus.py -v

Metriken

Das Agent-Core exportiert folgende Metriken:

Metrik	Beschreibung
agent_session_duration_seconds	Dauer von Agent-Sessions
agent_heartbeat_delay_seconds	Zeit seit letztem Heartbeat
agent_message_latency_ms	Latenz der Inter-Agent Kommunikation
agent_memory_access_total	Memory-Zugriffe pro Agent
agent_error_total	Fehler pro Agent-Typ

Nächste Schritte

1. Migration ausführen: psql -f backend/migrations/add_agent_core_tables.sql
2. Voice-Service erweitern: Enhanced Orchestrator aktivieren
3. BQAS integrieren: Quality Judge Agent starten
4. Monitoring aufsetzen: Metriken in Grafana integrieren