21a844cb8a
A previous `git pull --rebase origin main` dropped 177 local commits,
losing 3400+ files across admin-v2, backend, studio-v2, website,
klausur-service, and many other services. The partial restore attempt
(660295e2) only recovered some files.
This commit restores all missing files from pre-rebase ref 98933f5e
while preserving post-rebase additions (night-scheduler, night-mode UI,
NightModeWidget dashboard integration).
Restored features include:
- AI Module Sidebar (FAB), OCR Labeling, OCR Compare
- GPU Dashboard, RAG Pipeline, Magic Help
- Klausur-Korrektur (8 files), Abitur-Archiv (5+ files)
- Companion, Zeugnisse-Crawler, Screen Flow
- Full backend, studio-v2, website, klausur-service
- All compliance SDKs, agent-core, voice-service
- CI/CD configs, documentation, scripts
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
287 lines
6.6 KiB
Markdown
287 lines
6.6 KiB
Markdown
# 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
|
|
|
|
```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/`
|