docs: update MkDocs for 3-project architecture (core/lehrer/compliance)
- Rewrite system-architecture.md with new 3-project diagram - Update index.md with Core services table and nginx routing - Replace service docs that moved to lehrer/compliance with redirects (klausur-service, voice-service, agent-core, ki-daten-pipeline -> lehrer) (ai-compliance-sdk -> compliance) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Benjamin Boenisch
@@ -1,420 +1,10 @@
|
||||
# Breakpilot Agent Core
|
||||
|
||||
Multi-Agent Architecture Infrastructure fuer Breakpilot.
|
||||
|
||||
## Uebersicht
|
||||
|
||||
Das `agent-core` Modul stellt die gemeinsame Infrastruktur fuer Breakpilots Multi-Agent-System bereit:
|
||||
|
||||
- **Session Management**: Agent-Sessions mit Checkpoints und Recovery
|
||||
- **Shared Brain**: Langzeit-Gedaechtnis 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-Abhaengigkeiten
|
||||
├── pytest.ini # Test-Konfiguration
|
||||
│
|
||||
├── soul/ # Agent SOUL Files (Persoenlichkeiten)
|
||||
│ ├── 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-Gedaechtnis
|
||||
│ ├── 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-Ueberwachung
|
||||
│ └── 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-Faehigkeiten.
|
||||
|
||||
```python
|
||||
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 laeuft
|
||||
- `PAUSED` - Session pausiert
|
||||
- `COMPLETED` - Session erfolgreich beendet
|
||||
- `FAILED` - Session fehlgeschlagen
|
||||
|
||||
### 2. Heartbeat Monitoring
|
||||
|
||||
Ueberwacht Agent-Liveness und triggert Recovery bei Timeout.
|
||||
|
||||
```python
|
||||
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-Gedaechtnis fuer Agents mit TTL und Access-Tracking.
|
||||
|
||||
```python
|
||||
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.
|
||||
|
||||
```python
|
||||
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 hinzufuegen
|
||||
context.add_message(MessageRole.USER, "Was ist Photosynthese?")
|
||||
context.add_message(MessageRole.ASSISTANT, "Photosynthese ist...")
|
||||
|
||||
# Fuer LLM API formatieren
|
||||
messages = context.get_messages_for_llm()
|
||||
```
|
||||
|
||||
### 5. Message Bus
|
||||
|
||||
Inter-Agent Kommunikation via Redis Pub/Sub.
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
Ueberwacht und koordiniert alle Agents.
|
||||
|
||||
```python
|
||||
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.
|
||||
|
||||
```python
|
||||
from agent_core.orchestrator import TaskRouter, RoutingRule, RoutingStrategy
|
||||
|
||||
router = TaskRouter(supervisor=supervisor)
|
||||
|
||||
# Eigene Regel hinzufuegen
|
||||
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 Persoenlichkeit 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 Qualitaetspruefung |
|
||||
| AlertAgent | alert-agent.soul.md | Monitoring, Benachrichtigungen |
|
||||
| Orchestrator | orchestrator.soul.md | Task-Koordination |
|
||||
|
||||
## Datenbank-Schema
|
||||
|
||||
### agent_sessions
|
||||
|
||||
```sql
|
||||
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
|
||||
|
||||
```sql
|
||||
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
|
||||
|
||||
```sql
|
||||
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
|
||||
|
||||
```python
|
||||
from services.enhanced_task_orchestrator import EnhancedTaskOrchestrator
|
||||
|
||||
orchestrator = EnhancedTaskOrchestrator(
|
||||
redis_client=redis,
|
||||
db_pool=pg_pool
|
||||
)
|
||||
|
||||
await orchestrator.start()
|
||||
|
||||
# Session fuer Voice-Interaktion
|
||||
session = await orchestrator.create_session(
|
||||
voice_session_id="voice-123",
|
||||
user_id="teacher-1"
|
||||
)
|
||||
|
||||
# Task verarbeiten (nutzt Multi-Agent wenn noetig)
|
||||
await orchestrator.process_task(task)
|
||||
```
|
||||
|
||||
### Mit BQAS
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```bash
|
||||
# In agent-core Verzeichnis
|
||||
cd agent-core
|
||||
|
||||
# Alle Tests ausfuehren
|
||||
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 |
|
||||
|
||||
## Naechste Schritte
|
||||
|
||||
1. **Migration ausfuehren**: `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
|
||||
# Agent Core
|
||||
|
||||
!!! info "Verschoben nach breakpilot-lehrer"
|
||||
Agent Core gehoert zum **breakpilot-lehrer** Projekt (Team A).
|
||||
|
||||
Die aktuelle Dokumentation befindet sich in der [Lehrer MkDocs-Instanz](http://macmini:8010/services/agent-core/).
|
||||
|
||||
**Container:** `bp-lehrer-agent-core`
|
||||
**Profil:** `dev`
|
||||
**Repo:** `breakpilot-lehrer/agent-core/`
|
||||
|
||||
Reference in New Issue
Block a user