# Multi-Agent Architektur - Entwicklerdokumentation

**Status:** Implementiert
**Letzte Aktualisierung:** 2025-01-15
**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

```sql
-- 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`:

```python
# 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:

```python
# 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

```python
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

```python
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

```python
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

```bash
# 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

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

### 2. Voice-Service aktualisieren

```bash
# 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

```bash
# 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/`

---

## 14. Änderungshistorie

| Datum | Version | Änderung |
|-------|---------|----------|
| 2025-01-15 | 1.0.0 | Initial Release |