breakpilot-core/docs-src/architecture/multi-agent.md

Multi-Agent Architektur - Entwicklerdokumentation

Status: Implementiert Modul: /agent-core/

---

1. Übersicht

Die Multi-Agent-Architektur erweitert Breakpilot um ein verteiltes Agent-System basierend auf Mission Control Konzepten.

Kernkomponenten

Komponente	Pfad	Beschreibung
Session Management	/agent-core/sessions/	Lifecycle & Recovery
Shared Brain	/agent-core/brain/	Langzeit-Gedächtnis
Orchestrator	/agent-core/orchestrator/	Koordination
SOUL Files	/agent-core/soul/	Agent-Persönlichkeiten

---

2. Agent-Typen

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

---

3. Wichtige Dateien

Session Management

agent-core/sessions/
├── session_manager.py   # AgentSession, SessionManager, SessionState
├── heartbeat.py         # HeartbeatMonitor, HeartbeatClient
└── checkpoint.py        # CheckpointManager

Shared Brain

agent-core/brain/
├── memory_store.py      # MemoryStore, Memory (mit TTL)
├── context_manager.py   # ConversationContext, ContextManager
└── knowledge_graph.py   # KnowledgeGraph, Entity, Relationship

Orchestrator

agent-core/orchestrator/
├── message_bus.py       # MessageBus, AgentMessage, MessagePriority
├── supervisor.py        # AgentSupervisor, AgentInfo, AgentStatus
└── task_router.py       # TaskRouter, RoutingRule, RoutingResult

---

4. Datenbank-Schema

Die Migration befindet sich in: /backend/migrations/add_agent_core_tables.sql

Tabellen

1. agent_sessions - Session-Daten mit Checkpoints
2. agent_memory - Langzeit-Gedächtnis mit TTL
3. agent_messages - Audit-Trail für Inter-Agent Kommunikation

Helper-Funktionen

-- Abgelaufene Memories bereinigen
SELECT cleanup_expired_agent_memory();

-- Inaktive Sessions bereinigen
SELECT cleanup_stale_agent_sessions(48); -- 48 Stunden

---

5. Integration Voice-Service

Der EnhancedTaskOrchestrator erweitert den bestehenden TaskOrchestrator:

# voice-service/services/enhanced_task_orchestrator.py

from agent_core.sessions import SessionManager
from agent_core.orchestrator import MessageBus

class EnhancedTaskOrchestrator(TaskOrchestrator):
    # Nutzt Session-Checkpoints für Recovery
    # Routet komplexe Tasks an spezialisierte Agents
    # Führt Quality-Checks via BQAS durch

Wichtig: Der Enhanced Orchestrator ist abwärtskompatibel und kann parallel zum Original verwendet werden.

---

6. Integration BQAS

Der QualityJudgeAgent integriert BQAS mit dem Multi-Agent-System:

# voice-service/bqas/quality_judge_agent.py

from bqas.judge import LLMJudge
from agent_core.orchestrator import MessageBus

class QualityJudgeAgent:
    # Wertet Responses in Echtzeit aus
    # Nutzt Memory für konsistente Bewertungen
    # Empfängt Evaluierungs-Requests via Message Bus

---

7. Code-Beispiele

Session erstellen

from agent_core.sessions import SessionManager

manager = SessionManager(redis_client=redis, db_pool=pool)
session = await manager.create_session(
    agent_type="tutor-agent",
    user_id="user-123"
)

Memory speichern

from agent_core.brain import MemoryStore

store = MemoryStore(redis_client=redis, db_pool=pool)
await store.remember(
    key="student:123:progress",
    value={"level": 5, "score": 85},
    agent_id="tutor-agent",
    ttl_days=30
)

Nachricht senden

from agent_core.orchestrator import MessageBus, AgentMessage

bus = MessageBus(redis_client=redis)
await bus.publish(AgentMessage(
    sender="orchestrator",
    receiver="grader-agent",
    message_type="grade_request",
    payload={"exam_id": "exam-1"}
))

---

8. Tests ausführen

# Alle Agent-Core Tests
cd agent-core && pytest -v

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

# Einzelne Module
pytest tests/test_session_manager.py -v
pytest tests/test_message_bus.py -v

---

9. Deployment-Schritte

1. Migration ausführen

psql -h localhost -U breakpilot -d breakpilot \
  -f backend/migrations/add_agent_core_tables.sql

2. Voice-Service aktualisieren

# Sync zu Server
rsync -avz --exclude 'node_modules' --exclude '.git' \
  /path/to/breakpilot-pwa/ server:/path/to/breakpilot-pwa/

# Container neu bauen
docker compose build --no-cache voice-service

# Starten
docker compose up -d voice-service

3. Verifizieren

# Session-Tabelle prüfen
psql -c "SELECT COUNT(*) FROM agent_sessions;"

# Memory-Tabelle prüfen
psql -c "SELECT COUNT(*) FROM agent_memory;"

---

10. Monitoring

Metriken

Metrik	Beschreibung
agent_session_count	Anzahl aktiver Sessions
agent_heartbeat_delay_ms	Zeit seit letztem Heartbeat
agent_message_latency_ms	Nachrichtenlatenz
agent_memory_count	Gespeicherte Memories
agent_routing_success_rate	Erfolgreiche Routings

Health-Check-Endpunkte

GET /api/v1/agents/health       # Supervisor Status
GET /api/v1/agents/sessions     # Aktive Sessions
GET /api/v1/agents/memory/stats # Memory-Statistiken

---

11. Troubleshooting

Problem: Session nicht gefunden

1. Prüfen ob Valkey läuft: redis-cli ping
2. Session-Timeout prüfen (default 24h)
3. Heartbeat-Status checken

Problem: Message Bus Timeout

1. Redis Pub/Sub Status prüfen
2. Ziel-Agent registriert?
3. Timeout erhöhen (default 30s)

Problem: Memory nicht gefunden

1. Namespace korrekt?
2. TTL abgelaufen?
3. Cleanup-Job gelaufen?

---

12. Erweiterungen

Neuen Agent hinzufügen

1. SOUL-Datei erstellen in /agent-core/soul/
2. Routing-Regel in task_router.py hinzufügen
3. Handler beim Supervisor registrieren
4. Tests schreiben

Neuen Memory-Typ hinzufügen

1. Key-Schema definieren (z.B. student:*:progress)
2. TTL festlegen
3. Access-Pattern dokumentieren

---

13. Referenzen

• Agent-Core README: /agent-core/README.md
• Migration: /backend/migrations/add_agent_core_tables.sql
• Voice-Service Integration: /voice-service/services/enhanced_task_orchestrator.py
• BQAS Integration: /voice-service/bqas/quality_judge_agent.py
• Tests: /agent-core/tests/