Konfigurationsreferenz

Alle Konfigurationsschlüssel und Umgebungsvariablen – und wie die aktive Quelle ausgewählt wird

Wie die Konfiguration geladen wird

Die Konfiguration ist ein einfaches Dictionary, das von einer ConfigSource geladen wird (siehe agent_lab/core/config.py) und an den DI-Container gebunden ist. create_app() wählt eine Quelle über default_config_source() aus, und zwar genau in dieser Reihenfolge – der erste Treffer gewinnt:

#	Bedingung (gesetzte Umgebungsvariable)	Aktive Quelle
1	`VAULT_K8S_ROLE`	`KubernetesVaultConfigSource` – Vault über das projizierte ServiceAccount-Token des Pods
2	`DOCKER`	`YamlConfigSource("config-docker.yml")`
3	`TESTING`	`YamlConfigSource("config-test.yml")`
4	`DEVELOPING`	`YamlConfigSource("config-dev.yml")`
5	(keine der obigen)	`VaultConfigSource` – liest `VAULT_URL` / `VAULT_TOKEN`

Sie können die Auswahl pro Anwendung überschreiben:

app = create_app(config_source=YamlConfigSource("config.yml"))  # explicit

Konfigurationsschlüssel

Das Dictionary, das die aktive Quelle zurückgeben muss. Die angezeigten Standardwerte stammen aus config-dev.yml (Entwicklung); die Referenzanwendung liefert config-dev.yml, config-test.yml und config-docker.yml mit genau dieser Struktur aus.

Schlüssel	Zweck	Beispielwert
`api_base_url`	Öffentliche Basis-URL dieser API (wird für Links in Responses verwendet)	`http://localhost:8000`
`cdp_url`	Headless-Chrome-Endpoint (CDP) für Web-Agenten (`WebAgentBase`)	`http://localhost:9222`
`auth.enabled`	Bindet bei `true` die Auth-Middleware und die `/auth`-Routen ein	`false`
`auth.url`	Basis-URL von Keycloak	`https://auth.example.com`
`auth.realm`	Name des Keycloak-Realms	`agent-lab`
`auth.client_id`	OIDC-Client-ID	`agent-lab-api`
`auth.client_secret`	OIDC-Client-Secret	`…`
`broker.url`	Redis-URL für Pub/Sub-Statusupdates bei langen Operationen	`redis://localhost:6379/0`
`db.url`	PostgreSQL – relationale Daten	`postgresql://postgres:postgres@localhost:5432/agent_lab`
`db.vectors`	PostgreSQL – pgvector-Embeddings-Datenbank	`postgresql://postgres:postgres@localhost:5432/agent_lab_vectors`
`db.checkpoints`	PostgreSQL – Datenbank für LangGraph-Checkpoints (Gedächtnis der Agenten)	`postgresql://postgres:postgres@localhost:5432/agent_lab_checkpoints`
`vault.url`	Vault-Adresse (wird auch zurückgeschrieben, damit Services Secrets lesen können)	`http://localhost:8200`
`vault.token`	Vault-Token	`dev-only-token`
`static.enabled`	Einen SPA-Build ausliefern (`false`, wenn kein Frontend-Build vorhanden ist)	`false`
`static.directory`	Verzeichnis mit dem SPA-Build	`static/frontend/browser`
`static.index_file`	Fallback-Datei der SPA	`index.html`
`static.mount_path`	Mount-Punkt der SPA	`/`

static ist ein Sonderfall: Die YAML-Quellen konfigurieren den Schlüssel explizit, während die Vault-Quelle ihn aus einer Code-Konvention ableitet – aktiviert, wenn unter STATIC_DIR ein SPA-Build vorhanden ist.

Vault-Secret-Payload

VaultConfigSource liest ein einzelnes KV-v2-Secret (standardmäßig Engine secret, Pfad app_secrets) und bildet es auf die obigen Schlüssel ab:

Secret-Schlüssel	Wird abgebildet auf
`api_base_url`	`api_base_url`
`cdp_url`	`cdp_url`
`auth_enabled` → `auth.enabled`	`auth.enabled`
`auth_url` → `auth.url`	`auth.url`
`auth_realm` → `auth.realm`	`auth.realm`
`auth_client_id` → `auth.client_id`	`auth.client_id`
`auth_client_secret` → `auth.client_id`	`auth.client_secret`
`broker_url`	`broker.url`
`db_url`	`db.url`
`db_vectors`	`db.vectors`
`db_checkpoints`	`db.checkpoints`

Wie diese Payload bereitgestellt wird (Docker Compose für die Entwicklung, Kubernetes, Terraform), wird in Secrets mit Vault und im Deployment-Guide beschrieben.

Umgebungsvariablen

Auswahl der Konfigurationsquelle

Variable	Standard	Zweck
`DEVELOPING`	(nicht gesetzt)	Wählt `config-dev.yml` (Debugging in der IDE)
`TESTING`	(nicht gesetzt)	Wählt `config-test.yml` (Test-Suite)
`DOCKER`	(nicht gesetzt)	Wählt `config-docker.yml` (Compose)
`VAULT_URL`	(nicht gesetzt)	Vault-Adresse für die Standardquelle
`VAULT_TOKEN`	(nicht gesetzt)	Vault-Token für die Standardquelle
`VAULT_ENGINE_PATH`	`secret`	Mount-Punkt der KV-v2-Engine
`VAULT_SECRET_PATH`	`app_secrets`	Secret-Pfad
`VAULT_K8S_ROLE`	(nicht gesetzt)	Rolle für die Kubernetes-Authentifizierung bei Vault; aktiviert die K8s-Quelle und hat Vorrang
`STATIC_DIR`	`static/frontend/browser`	Wo nach dem SPA-Build gesucht wird

Observability

Variable	Standard	Zweck
`OTEL_EXPORTER_OTLP_ENDPOINT`	(nicht gesetzt – Tracing aus)	Basis-URL des OTLP/HTTP-Collectors; Traces → `/v1/traces`, Metriken → `/v1/metrics`, Logs → `/v1/logs`
`SERVICE_NAME`	`Agent-Lab`	Name der OTel-Ressource
`SERVICE_VERSION`	`snapshot`	Version der OTel-Ressource
`LANGFUSE_HOST`	(nicht gesetzt)	Basis-URL von Langfuse; aktiviert zusammen mit den beiden folgenden Schlüsseln das Langfuse-Backend
`LANGFUSE_PUBLIC_KEY`	(nicht gesetzt)	Langfuse-Schlüssel `pk-lf-…`
`LANGFUSE_SECRET_KEY`	(nicht gesetzt)	Langfuse-Schlüssel `sk-lf-…`
`LANGWATCH_ENDPOINT`	(nicht gesetzt)	LangWatch-Endpoint; aktiviert zusammen mit dem folgenden Schlüssel das LangWatch-Backend
`LANGWATCH_API_KEY`	(nicht gesetzt)	LangWatch-API-Schlüssel

Fehlt eine der Langfuse-Variablen, wird das Langfuse-Backend stillschweigend deaktiviert und die Anwendung startet trotzdem (dasselbe gilt für LangWatch). Details und der Erweiterungspunkt: Observability.

Authentifizierung und Integrationen

Variable	Standard	Zweck
`AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` / `AZURE_TENANT_ID`	(nicht gesetzt)	Microsoft-Entra-ID-Zugangsdaten für `/auth/exchange`
`EMBEDDINGS_ENDPOINT`	(nicht gesetzt)	Embeddings-Service, der von Retrieval-Agenten verwendet wird
`OPENAI_API_KEY`	(nicht gesetzt)	OpenAI (Audioeingabe für Voice Memos; Standard für den Simulations-Judge)

Simulationen (nur Test-Suite)

Variable	Standard	Zweck
`SIMULATION_LLM_MODEL`	(erforderlich)	Modell-Tag, mit dem die zu testenden Agenten ausgeführt werden (z. B. `qwen3:30b`)
`SIMULATION_LLM_API_BASE`	(erforderlich)	OpenAI-kompatibler Endpoint, der dieses Modell bereitstellt
`SIMULATION_LLM_API_KEY`	`dummy-key`	API-Schlüssel für den Endpoint, falls erforderlich
`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 den Judge
`SIMULATION_JUDGE_API_KEY`	Standard des Anbieters	API-Schlüssel für den benutzerdefinierten Judge-Endpoint

Wie diese verwendet werden, erfahren Sie unter Tests & Simulationen.

Benutzerdefinierte Konfigurationsquellen

Implementieren Sie die ABC ConfigSource und übergeben Sie sie an create_app(config_source=...) – nützlich für AWS Secrets Manager, Deployments, die ausschließlich Umgebungsvariablen nutzen, oder zum Wrappen einer anderen Quelle:

from agent_lab import ConfigSource, create_app


class MyConfigSource(ConfigSource):
    def load(self) -> dict:
        return {
            "api_base_url": "https://api.example.com",
            "db": {"url": "postgresql://…", "vectors": "…", "checkpoints": "…"},
            "auth": {"enabled": True, "url": "…", "realm": "…", "client_id": "…", "client_secret": "…"},
            "broker": {"url": "redis://…"},
            # … remaining keys as in the table above
        }


app = create_app(config_source=MyConfigSource())

Die mitgelieferten Quellen (YamlConfigSource, VaultConfigSource, KubernetesVaultConfigSource) und default_config_source() werden alle vom Top-Level-Paket agent_lab exportiert.