Forscherhandbuch

Für wen dieser Guide gedacht ist

Für KI-Forschende und Entwickler, die Experimente in Agent-Lab erkunden, reproduzieren und erweitern möchten. Wenn Sie Python schreiben, Jupyter verwenden und in Experimenten, Agenten und Pipelines denken, werden Sie sich hier sofort zurechtfinden. Vertrautheit mit LLMs, RAG und Container-Grundlagen ist hilfreich, aber nicht erforderlich.

Agent-Lab bietet wiederverwendbare Komponenten (Agententypen, Tools, Integrationen) sowie eine Sammlung von Jupyter-Notebooks mit Schritt-für-Schritt-Beispielen, damit Sie schnell produktiv werden.

Schnellstart – die Beispiele ausführen

Voraussetzungen: Python 3.12+, eine funktionierende Jupyter-Umgebung (JupyterLab oder Notebook) und optional ein lokales Docker für End-to-End-Integrationen. Arbeiten in einem Klon des Repositorys:

uv sync --group notebooks   # runtime + notebook dependencies in one virtualenv
jupyter lab                 # from the repository root

Öffnen Sie notebooks/, beginnen Sie mit 01_… und arbeiten Sie sich durch die Notebooks, die Sie interessieren.

Hinweise:

• Die Notebooks sind größtenteils in sich abgeschlossen; jeder Header nennt die erforderlichen Umgebungsvariablen und externen Services (API-Schlüssel, Endpoints).
• Die erforderlichen Schlüssel stehen in .env – kopieren Sie .env.example und füllen Sie die Datei aus (siehe die Konfigurationsreferenz).
• Um aus Ihrem eigenen Projekt statt aus dem Repository mit Agent-Lab zu experimentieren, führen Sie pip install btech-agent-lab aus und stellen die Anwendung mit create_app() zusammen – siehe Das Framework erweitern im Entwicklerhandbuch.

Projektstruktur – ein kurzer Rundgang

• notebooks/ – interaktive Beispiele für Agententypen, Evaluierung und Integrationen. Beginnen Sie hier.
• agent_lab/ – das Framework-Paket:
  • app_factory.py – der Composition Root: create_app().
  • core/ – Konfigurationsquellen, DI-Container, Auflösung von extra_deps.
  • domain/ – Modelle, Repository-Interfaces, Exceptions (das Entity-Domänenmodell).
  • services/ – Geschäftslogik und die Implementierungen in agent_types/.
  • interface/ – api/ (HTTP-Router) und mcp/ (der MCP-Server).
  • infrastructure/ – Adapter für Datenbank, Authentifizierung, Metriken/Tracing.
• tests/ – die Suites unit/, integration/, template/ und simulation/ (siehe Tests & Simulationen).
• doc/ – die Dokumentation, die Sie gerade lesen.

Wenn Sie diese Schichten verstehen, wissen Sie, wo welches Verhalten liegt: Beispiele in notebooks, zentrale Verträge in core/ und domain/ und Adapter in infrastructure/.

Notebooks – der primäre Lernpfad

Typische Reihenfolge:

Jedes Notebook enthält: eine kurze Beschreibung des Ziels des Experiments, die erforderlichen Umgebungsvariablen und Secrets, Hilfsfunktionen sowie ausgegebene/visuelle Ergebnisse, um Entscheidungen und Metriken der Agenten zu untersuchen.

Profi-Tipp: Führen Sie die Notebooks der Reihe nach aus, um schrittweise zu lernen. Verwenden Sie beim Iterieren kleinere Datensätze und Stichproben, damit die Läufe schnell bleiben.

Kernkonzepte

• Agent – eine registrierte Implementierung unter agent_lab/services/agent_types/ (@discoverable_agent). Die Registry löst sie lazy über den DI-Container auf und injiziert die deklarierten extra_deps.
• Tools – einzelne Fähigkeiten, die ein Agent aufrufen kann (Suche, Browsing, TTS/ASR), implementiert als Adapter in agent_lab/infrastructure/ oder agent_lab/interface/.
• Container – das DI-Kompositionsobjekt (agent_lab/core/container.py); leiten Sie davon ab, um Provider für Ihre Experimente hinzuzufügen.
• Repositories – Datenzugriffs-Interfaces in agent_lab/domain/repositories/.
• ConfigSource – die Herkunft der Konfiguration; verwenden Sie in Experimenten die YAML-Quellen und in der Produktion Vault.

Wenn Sie Verhalten ändern möchten, entscheiden Sie, ob die Änderung experimentell (nur im Notebook), architektonisch (core/domain/services) oder auf Integrationsebene (Adapter in infrastructure) ist. Bevorzugen Sie kleine, testbare Änderungen – und fügen Sie ein Notebook hinzu oder aktualisieren Sie eines, um das neue Verhalten zu zeigen.

Experimente durchführen und Ergebnisse erfassen

Notebooks geben Zwischenschritte aus; für robustere Experimente:

• Verwenden Sie deterministische Seeds, wo Zufälligkeit eine Rolle spielt.

• Erfassen Sie die für Ihre Fragestellung relevanten Metriken – Latenz, Token-Verbrauch, Anzahl der Tool-Aufrufe, Judge-Bewertungen. Die Observability-Schicht exportiert alles als OpenTelemetry (siehe Observability); das Simulations-Harness protokolliert Judge-Bewertungen in Langfuse/LangWatch (siehe Tests & Simulationen).

• Für wiederholbare Läufe exportieren Sie Notebook-Zellen in Skripte und führen diese in der CI oder auf Compute-Knoten aus:

  jupyter nbconvert --to script notebooks/02_test_agent_type-adaptive_rag.ipynb

• Das docker/app/Dockerfile baut ein Runtime-Image mit fixierten Versionen für eine reproduzierbare Ausführung.

Prototyping neuer Verhaltensweisen

1. Einen neuen Agententyp hinzufügen: Erstellen Sie die Klasse unter agent_lab/services/agent_types/, dekorieren Sie sie mit @discoverable_agent("your_type") und fügen Sie ein Notebook hinzu, das sie über den DI-Container einbindet und mit einem kleinen Szenario ausführt. Die vollständige Anleitung finden Sie unter Agentische Workflows entwickeln.
2. Einen Embeddings-Anbieter austauschen: Implementieren Sie einen kompatiblen Adapter unter agent_lab/infrastructure/ und validieren Sie ihn mit Notebook 01.
3. Einen Retrieval-Speicher oder eine Vektordatenbank hinzufügen: Implementieren Sie Repository-Methoden in agent_lab/domain/repositories/ und einen Adapter in agent_lab/infrastructure/database/; befüllen Sie ihn mit einem kleinen Loader-Notebook und demonstrieren Sie das Retrieval in einem Abfrage-Notebook.

Design-Tipp: Halten Sie Adapter-Interfaces schlank und testen Sie sie isoliert mit kleinen Unit-Tests.

Tests und Evaluierung

make test_unit           # unit tests — no infrastructure needed
make test                # unit + integration with coverage
make test_simulations    # LLM-as-judge agent simulations (live LLMs)

Wenn Sie Kernverhalten ändern, fügen Sie einen Unit-Test und ein kurzes Notebook hinzu, das die Änderung demonstriert – diese Kombination macht Forschung hier reproduzierbar. Das vollständige Harness, die Judge-Konfiguration und die Evaluierungsplattformen werden unter Tests & Simulationen beschrieben.

Checkliste für Reproduzierbarkeit

• Fixieren Sie Ihre Umgebung (uv + pyproject.toml / uv.lock).
• Dokumentieren Sie Seeds und Konfigurationsdateien (config-dev.yml, config-test.yml).
• Speichern Sie den Notebook-Checkpoint und alle Ausgabeartefakte (CSV/JSON) zusammen mit Ihrem Experiment.
• Notieren Sie die Tracing-Endpoints, an die Sie exportiert haben – Traces sind Ihr Experimentprotokoll.