Entwicklerhandbuch

Zwei Wege der Entwicklung

Agent-Lab ist ein Framework, das Sie als Bibliothek nutzen, und zugleich ein Repository, in dem Sie direkt arbeiten können. Beides wird unterstützt:

• Als Bibliothek (empfohlen für Produkte). Fügen Sie btech-agent-lab zu Ihrem eigenen Projekt hinzu, definieren Sie Agenten durch Erweitern der Basisklassen und stellen Sie die Anwendung mit create_app() zusammen. Sie erweitern das Framework über seine öffentliche API – Vererbung, Decorators und Konfiguration – und bearbeiten niemals Framework-Code. Beginnen Sie mit dem Tutorial oder dem Schnellstart und lesen Sie dann Das Framework erweitern. Um den Boilerplate-Code zu überspringen, erzeugen Sie ein fertiges Nutzerprojekt per Scaffolding mit uvx cookiecutter gh:btech-software/agent-lab --directory cookiecutter (siehe cookiecutter/README.md).
• Im Repository (für Mitwirkende und die Referenzimplementierung). Klonen Sie das Repository, fügen Sie Agenten unter agent_lab/services/agent_types/ hinzu, führen Sie die mitgelieferte Referenzanwendung aus und nutzen Sie die Notebooks und Integrationstests. So werden die integrierten Agenten entwickelt. Siehe Agentische Workflows entwickeln.

Beide Wege verwenden dieselben Bausteine; der Unterschied liegt nur darin, wo Ihr Code liegt. Wählen Sie, was zu Ihrem Projekt passt.

Setup

Installation

Agent-Lab setzt Python 3.12+ voraus und verwendet uv für das Dependency-Management.

Agent-Lab als Bibliothek nutzen – installieren Sie es in Ihr eigenes Projekt:

pip install btech-agent-lab
# or
uv add btech-agent-lab

Im Repository arbeiten – klonen Sie es und synchronisieren Sie die Umgebung:

git clone https://github.com/btech-software/agent-lab.git
cd agent-lab
uv sync                 # runtime dependencies
uv sync --group test    # add the test/simulation dependencies

Stellen Sie sicher, dass Docker oder eine andere Container-Runtime installiert ist und läuft – die Integrationstests verwenden sie (über testcontainers), und die mitgelieferten Docker-Compose-Dateien stellen die Abhängigkeiten der Anwendung bereit.

Die Beispiel-Umgebungsdatei kopieren

cp .env.example .env

Diese Datei enthält API-Schlüssel für KI-Anbieter und die Endpoints, die von den Agenten-Simulationen verwendet werden. Jede Variable ist in der Konfigurationsreferenz dokumentiert.

Referenzimplementierung

Das Repository enthält eine vollständige Referenzanwendung (agent_lab.main), die alle integrierten Agenten registriert – RAG, Browser-Automatisierung, Voice Memos, Vision und Multi-Agenten-Supervisors. Sie ist sowohl ein deploybares Produkt als auch das maßgebliche Beispiel dafür, wie das Framework genutzt wird: Sie ist nichts weiter als ein Aufruf von create_app() über die integrierten Agentenpakete.

# agent_lab/main.py
from agent_lab.app_factory import create_app

app = create_app()  # scans DEFAULT_SCAN_PACKAGES: all built-in capabilities

Nutzen Sie sie als lebendige Referenz beim Entwickeln Ihrer eigenen Anwendung und als schnellsten Weg, um Agent-Lab End-to-End auszuprobieren. Die Bereitstellung ihrer Infrastruktur (die drei PostgreSQL-Datenbanken, Redis, Keycloak, Vault) in Entwicklung oder Produktion wird im Deployment-Guide beschrieben. Der nächste Abschnitt zeigt, wie Sie sie lokal ausführen.

Die Anwendung ausführen

Die Anwendung mit Uvicorn starten

Für Entwicklung und Debugging mit einer IDE führen Sie die Referenzanwendung direkt aus:

uvicorn agent_lab.main:app --reload

Die interaktive OpenAPI-Dokumentation finden Sie unter http://localhost:8000/docs.

Wenn Sie Agent-Lab als Bibliothek nutzen, führen Sie Ihre Anwendung auf dieselbe Weise aus – richten Sie uvicorn auf das Modul aus, das create_app() aufruft:

uvicorn app:app --reload    # where app.py defines `app = create_app(scan_packages=[...])`

Die Anwendung mit Docker Compose starten

Zwei vorkonfigurierte Docker-Compose-Dateien führen die Referenzanwendung zusammen mit einem Observability-Stack aus:

• compose-grafana.yml: die Anwendung plus Grafana, Prometheus, Tempo und Loki.
• compose-opensearch.yml: die Anwendung plus OpenSearch Dashboards.

docker compose -f compose-grafana.yml up --build       # Grafana stack
docker compose -f compose-opensearch.yml up --build    # OpenSearch Dashboards stack

Nach dem Start der Anwendung ist die API unter http://localhost:18000/docs erreichbar. Observability-Dashboards:

• Grafana: http://localhost:3000 (Standard-Zugangsdaten: admin/admin). Siehe das Grafana-Beispiel.
• OpenSearch Dashboards: http://localhost:5601. Siehe das OpenSearch-Beispiel.

Entwicklungspraktiken

Dependency Injection

Die Anwendung verwendet Dependency Injector für Dependency Injection, was Zuständigkeiten sauber trennt und das Testen erleichtert.

Der Container ist in agent_lab/core/container.py definiert. Wenn Sie Agent-Lab als Bibliothek nutzen, leiten Sie von Container ab, um eigene Provider hinzuzufügen, und übergeben Sie die Instanz an create_app(container=...). Wenn Sie im Repository arbeiten, registrieren Sie zusätzliche Framework-Services direkt im Container.

Anwendungskonfiguration

Die Konfiguration wird über eine ConfigSource geladen (siehe agent_lab/core/config.py) und an den DI-Container gebunden. Das Framework bringt drei YAML-Quellen für Entwicklung und Tests mit, die automatisch anhand einer Umgebungsvariable ausgewählt werden:

• config-dev.yml: Entwicklungsumgebung, aktiviert, wenn DEVELOPING gesetzt ist – gedacht für das Debugging in der IDE.
• config-test.yml: Testumgebung, aktiviert, wenn TESTING gesetzt ist – wird vom Setup der Integrationstests verwendet.
• config-docker.yml: Docker-Compose-Umgebung, aktiviert, wenn DOCKER gesetzt ist.

Diese Dateien definieren Einstellungen wie Datenbankverbindungen und Authentifizierung und sind ausschließlich für Entwicklung und Tests gedacht. Verwenden Sie in der Produktion Vault über VaultConfigSource (der Standard, wenn kein Umgebungs-Flag gesetzt ist). Um die Konfiguration aus einem anderen Backend bereitzustellen, implementieren Sie Ihre eigene ConfigSource und übergeben sie an create_app(config_source=...). Alle Konfigurationsschlüssel und Umgebungsvariablen sind in der Konfigurationsreferenz dokumentiert.

Entity-Domänenmodell

Das Datenmodell – die in der gesamten Anwendung verwendeten Entitäten und ihre Beziehungen – finden Sie im Entity-Domänenmodell.

Logging und Observability

Die Anwendung verwendet OpenTelemetry für Logging und Observability; das Setup befindet sich in agent_lab/infrastructure/metrics/tracer.py. Aufrufe von FastAPI, HTTPX, LangChain, SQLAlchemy und OpenAI sind von Haus aus instrumentiert, mit austauschbaren Backends für Langfuse und LangWatch. Details finden Sie im Observability-Guide.

Tests

Das Projekt verwendet pytest mit Schwerpunkt auf Integrationstests (Coverage-Schwelle: 90 %), gestützt auf Testcontainers, sodass die Tests gegen echte Services in Docker-Containern laufen. Eine separate Simulations-Suite bewertet das Agentenverhalten End-to-End mit einem LLM-as-Judge.

make test               # unit + integration with coverage
make test_simulations   # end-to-end agent simulations (calls live LLMs)

Die erste Ausführung kann mehrere Minuten dauern, da Docker-Images und Embedding-Modelle heruntergeladen werden. Das Gesamtbild finden Sie im Test-Guide.

pre-commit initialisieren

Wenn Sie zur Codebasis beitragen oder neue Agenten auf Basis von Agent-Lab entwickeln möchten, installieren Sie die pre-commit-Hooks:

pre-commit install

So wird sichergestellt, dass Ihr Code vor dem Commit den Coding-Standards des Projekts entspricht.

Agentische Workflows entwickeln

Agent-Lab basiert auf LangGraph, das eine leistungsfähige Möglichkeit bietet, agentische Workflows mit LLMs zu entwickeln. Dank der modularen Architektur und der Agent-Basisklassen ist die Entwicklung eines solchen Workflows unkompliziert.

Eine neue Agent-Implementierung definieren

Der Agent ist ein Kernkonzept in Agent-Lab: eine autonome Einheit, die Aufgaben ausführen, Entscheidungen treffen und mit anderen Agenten oder externen Systemen interagieren kann. Ein Agent ist eine konkrete Implementierung einer der Basisklassen:

Eine Klasse, die WorkflowAgentBase erweitert, definiert:

• einen Workflow, der das Verhalten des Agenten abbildet – Aufgaben, Entscheidungsfindung und Interaktionen mit anderen Agenten oder externen Systemen.
• Initialisierungsparameter wie die Prompts (Jinja2-Templates) und weitere Einstellungen, die das Verhalten des Agenten anpassen (Vector-Store-Collections, Temperatur usw.).

Hier ein Beispiel für persistierte Initialisierungsparameter eines Agenten, der Sprachtranskription und -analyse durchführt, nachdem der Agent erstellt und in der Datenbank gespeichert wurde:

Über die REST API lassen sich mehrere Agenten auf Basis derselben Implementierung erstellen und verfeinern.

Den Agenten mit @discoverable_agent registrieren

Dekorieren Sie Ihre AgentBase-Unterklasse mit @discoverable_agent("<agent_type>"). Dieser eine Decorator ist die gesamte Registrierung, die ein Agent benötigt – er macht den Agenten:

• auffindbar für die Agent-Registry (agent_lab/services/agent_types/registry.py),
• auflösbar über den DI-Container, der ihn lazy instanziiert und alle deklarierten extra_deps injiziert,
• gültig in der API, weil das Schema zur Agentenerstellung agent_type dynamisch gegen die Registry validiert.

from agent_lab import AgentBase, AgentUtils, discoverable_agent


@discoverable_agent("my_agent", extra_deps=("my_service",))
class MyAgent(AgentBase):
    def __init__(self, agent_utils: AgentUtils, my_service):
        super().__init__(agent_utils)
        self.my_service = my_service
    ...

Hinweis (Migration): Frühere Versionen erforderten es, jeden Agenten manuell in container.py zu verdrahten, ihn zu registry.py hinzuzufügen und das Pydantic-Schema in agents/schema.py zu erweitern. Diese Schritte sind obsolet – @discoverable_agent übernimmt sie alle. Alle von Ihnen deklarierten extra_deps werden zum Zeitpunkt der Instanziierung anhand ihres Namens aus dem (gegebenenfalls abgeleiteten) Container aufgelöst.

Benötigt ein Agent über AgentUtils hinaus weitere Kollaborateure, stellen Sie diese als Provider im Container bereit (leiten Sie von Container ab, wenn Sie die Bibliothek nutzen) und benennen Sie sie in extra_deps.

Den Agenten auffindbar machen

Das Framework importiert nur Agentenmodule, die ihm bekannt gemacht werden, damit der Decorator ausgeführt wird:

• Im Repository: Legen Sie den Agenten unter agent_lab/services/agent_types/ ab – die Referenzanwendung scannt dieses Paket als Teil von DEFAULT_SCAN_PACKAGES (create_app()).

• Als Bibliothek: Übergeben Sie Ihr Paket an create_app(scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"]) – eine explizite Liste ersetzt die Standardwerte (so schließen Sie auch integrierte Fähigkeiten aus) – oder veröffentlichen Sie es aus einem installierten Paket über die Entry-Point-Gruppe agent_lab.agents, damit Nutzer es automatisch übernehmen:

  # pyproject.toml of the package that ships the agents
  [project.entry-points."agent_lab.agents"]
  my_agents = "my_agents"

Mit der Agent-Implementierung experimentieren

In den Notebooks finden Sie Beispiele dafür, wie Sie einen Agenten interaktiv mit Jupyter testen – unter Verwendung desselben Dependency-Injection-Mechanismus. Dies ist eine bequeme Möglichkeit, Verhalten in einer kontrollierten Umgebung zu prototypisieren und zu validieren – siehe das Forscherhandbuch.

REST-API-Schnittstelle für Agenten

Sobald ein Agent registriert ist, erstellen und verwalten Sie seine Instanzen über die REST API – Sie können mehrere konfigurierte Instanzen derselben Implementierung betreiben, jede mit eigenen Prompts und Einstellungen. Den Endpoint-Katalog und Request-Beispiele finden Sie in der REST-API-Referenz.

Den Agenten testen

• Integrationstests (tests/integration/) validieren den Agenten gegen echte Infrastruktur mit pytest und testcontainers.
• Simulationen (tests/simulation/) bewerten das Verhalten End-to-End mit einem LLM-as-Judge. Siehe den Test-Guide.

MCP-Server

Im MCP-Server-Guide erfahren Sie, wie Sie Ihre Agenten (und zusätzliche Tools) für MCP-Clients wie Claude Desktop bereitstellen – für Agent-Discovery, Dialogverlauf und Agent-zu-Agent-Kommunikation.

Das Framework erweitern

Wenn Sie Agent-Lab als Bibliothek nutzen, gestalten Sie die Anwendung vollständig über create_app() und die öffentliche API, die vom Top-Level-Paket agent_lab exportiert wird – niemals durch Bearbeiten von Framework-Code:

from agent_lab import (
    DEFAULT_SCAN_PACKAGES,
    Container,
    RouterMount,
    YamlConfigSource,
    create_app,
)

class MyContainer(Container):
    my_service = ...  # providers.Factory(MyService, ...)

app = create_app(
    container=MyContainer(),
    scan_packages=[*DEFAULT_SCAN_PACKAGES, "my_agents"],
    config_source=YamlConfigSource("config.yml"),
    extra_routers=[RouterMount(my_router, "/custom", ["custom"])],
    mcp_instructions=["Extra guidance for MCP clients."],
)

Alles oben Genannte wird von agent_lab exportiert (siehe agent_lab/__init__.py); die vollständige Liste der Konfigurationsschlüssel, die diese Stellschrauben verwenden, finden Sie in der Konfigurationsreferenz.

Mitwirken

Unterstützung aus der Community wird sehr geschätzt. Wenn Sie auf Probleme stoßen oder Verbesserungsvorschläge haben, melden Sie diese bitte, indem Sie ein Issue auf unserer Seite GitHub Issues erstellen.

Um zum Projekt beizutragen, gehen Sie wie folgt vor:

1. Forken Sie das Repository.
2. Erstellen Sie einen neuen Branch für Ihr Feature oder Ihren Bugfix.
3. Aktivieren Sie die pre-commit-Hooks mit pre-commit install, nehmen Sie Ihre Änderungen vor und committen Sie sie mit klaren und prägnanten Commit-Messages.
4. Stellen Sie sicher, dass Ihre Änderungen die pre-commit-Hooks und die Coverage-Schwelle von 90 % bestehen (make test).
5. Pushen Sie Ihre Änderungen in Ihr geforktes Repository.
6. Erstellen Sie einen Pull Request (PR) auf den Branch main des ursprünglichen Repositorys.

Wir prüfen Ihren PR und geben Ihnen Feedback. Vielen Dank für Ihre Beiträge und Ihre Unterstützung!

Produktiv-Deployment

Im Deployment-Guide erfahren Sie, wie Sie die Referenzanwendung mit den mitgelieferten Helm-Charts und Terraform-Skripten produktiv deployen.