Tests & Simulationen

Zwei Test-Harnesses: Integrationstests auf echter Infrastruktur und Agenten-Simulationen mit LLM-as-Judge

Das Testen von Agenten ist eine zentrale Fähigkeit des Frameworks, kein nachträglicher Gedanke. Agent-Lab bringt zwei sich ergänzende Harnesses mit, mit denen Sie sowohl das Framework selbst als auch die darauf aufbauenden Agenten validieren können:

Integrationstests prüfen das System gegen echte Infrastruktur (Postgres, Redis, Keycloak, Embeddings, Headless Chrome), die bei Bedarf mit testcontainers hochgefahren wird – sie decken externe Services, Datenbankoperationen, Vektorsuche und API-Endpoints ab.
Agenten-Simulationen bewerten das Agentenverhalten End-to-End gegen echte LLMs, benotet von einem LLM-as-Judge und im Zeitverlauf in Langfuse und LangWatch nachverfolgt.

Die Hauptkonfiguration für Integrationstests befindet sich in tests/conftest.py; passen Sie sie an Ihre Umgebung an.

Hinweis: Integrationstests und Simulationen führen echte Aufrufe externer Services durch und können Kosten verursachen. Führen Sie sie in einer kontrollierten Umgebung aus und überwachen Sie die Nutzung.

Integrationstests

Erfordert Docker (oder eine andere Container-Runtime) – die Suite stellt echte Container über testcontainers bereit.

make test_unit         # fast lane: boots the app with no infrastructure
make test_integration  # the full real-infrastructure suite
make test              # both, with coverage (gate: 90%)

Die erste Ausführung kann mehrere Minuten dauern – Docker-Images und Embedding-Modelle werden einmalig heruntergeladen. Die Testabdeckung von agent_lab/ wird in der CI (SonarCloud) erzwungen.

Die per Scaffolding erzeugten Projekte spiegeln dies wider: tests/ enthält Smoke-Tests ohne Container sowie eine optionale testcontainers-Suite.

Agenten-Simulationen

End-to-End-Simulationen von Agenten befinden sich in tests/simulation/ und rufen echte LLM-Anbieter auf. Sie sind mit agent_test markiert und standardmäßig abgewählt; führen Sie sie so aus:

make test_simulations
# or a single track:
make scenario_simulation
make langwatch_simulation
make langfuse_simulation

Drei sich ergänzende Tracks teilen sich die Bootstrap-Helfer für Agenten, den Judge und die Datensatzdefinitionen unter tests/simulation/datasets/:

tests/simulation/scenario/ – Konversationssimulationen mit dem Framework langwatch-scenario: Ein Benutzersimulator steuert den Agenten, während ein Judge-Agent die Interaktion bewertet.
tests/simulation/langfuse/ – datensatzgetriebene Experimente mit Langfuse-Datensätzen. Jeder Lauf synchronisiert die Datensatzdefinitionen, ruft den Agenten pro Eintrag auf, bewertet die Ausgabe mit einem clientseitigen LLM-as-Judge und speichert Lauf und Bewertungen in Langfuse, um sie im Zeitverlauf vergleichen zu können. Wird automatisch übersprungen, wenn LANGFUSE_BASE_URL (oder das veraltete LANGFUSE_HOST), LANGFUSE_PUBLIC_KEY und LANGFUSE_SECRET_KEY nicht gesetzt sind.
tests/simulation/langwatch/ – dieselben Datensatzexperimente, gespiegelt nach LangWatch über langwatch.experiment, wobei die Judge-Bewertung pro Eintrag protokolliert wird. Die Definitionen werden idempotent in einen einzigen konsolidierten Datensatz simulations synchronisiert (eine Spalte dataset kennzeichnet die Quelldefinition, da der kostenlose LangWatch-Plan höchstens 3 Datensätze pro Projekt erlaubt). Wird automatisch übersprungen, wenn LANGWATCH_ENDPOINT und LANGWATCH_API_KEY nicht gesetzt sind.

Die in den Tracks abgedeckten Referenzagenten: Coordinator-Planner-Supervisor, React-RAG, Vision/Dokument, Browser-Automatisierung, Voice Memos und Adaptive RAG.

LLM-Konfiguration für Judge und Agenten

Der Judge (und der Benutzersimulator für Szenarien) verwenden litellm-Modell-IDs gegen einen beliebigen OpenAI-API-kompatiblen Endpoint:

Umgebungsvariable	Standard	Zweck
`SIMULATION_JUDGE_MODEL`	`openai/gpt-5-nano`	litellm-Modell-ID, die vom LLM-as-Judge verwendet wird
`SIMULATION_JUDGE_API_BASE`	Standard des Anbieters	benutzerdefinierter OpenAI-kompatibler Endpoint für das Judge-Modell
`SIMULATION_JUDGE_API_KEY`	Standard des Anbieters	API-Schlüssel für den benutzerdefinierten Endpoint

Die zu testenden Agenten laufen auf einem Standard-LLM, das von einem beliebigen OpenAI-kompatiblen Endpoint bereitgestellt wird (z. B. einem Inferenzserver im LAN) und pro Test von tests/simulation/common/llm_factory.py eingerichtet wird. Die Ausnahme ist der Voice-Memos-Agent, der bei OpenAI bleibt (er benötigt Audio-Chat-Eingaben). Embeddings verwenden weiterhin den Fallback EMBEDDINGS_ENDPOINT (den Ollama-Testcontainer, der bge-m3 bereitstellt), passend zum pgvector-Dump. Der Endpoint muss Tool Calling / Structured Output für die Supervisor-basierten Suites (Browser-Automatisierung, Supervisor) unterstützen:

Umgebungsvariable	Standard	Zweck
`SIMULATION_LLM_MODEL`	keiner (erforderlich)	Modell-Tag, mit dem die Simulationen ausgeführt werden (z. B. `qwen3:30b`)
`SIMULATION_LLM_API_BASE`	keiner (erforderlich)	OpenAI-kompatibler Endpoint, der das Modell bereitstellt
`SIMULATION_LLM_API_KEY`	`dummy-key`	API-Schlüssel, falls der Endpoint einen erfordert

Die Evaluierungsplattformen einrichten

make test_simulations (und die Targets der einzelnen Tracks) führen zunächst den Schritt sync_simulation_evals aus, der die Datensatzdefinitionen auf jede konfigurierte Plattform spiegelt. Um zusätzlich das serverseitige Evaluierungs-Setup von Langfuse bereitzustellen (eine LLM-Verbindung für das Judge-Modell, einen Evaluator simulation_llm_as_judge und eine Evaluierungsregel pro Simulationsdatensatz – sichtbar im Bereich „Evaluations“ von Langfuse), führen Sie Folgendes aus:

uv run python tests/setup_simulation_evals.py

Das Skript ist idempotent und kann gefahrlos erneut ausgeführt werden.