Dokumentacja konfiguracji

Każdy klucz konfiguracji i każda zmienna środowiskowa oraz sposób wyboru aktywnego źródła

Jak ładowana jest konfiguracja

Konfiguracja to zwykły słownik ładowany przez ConfigSource (zobacz agent_lab/core/config.py) i wiązany z kontenerem DI. create_app() wybiera źródło za pomocą default_config_source() w dokładnie tej kolejności — wygrywa pierwsze dopasowanie:

#	Warunek (ustawiona zmienna środowiskowa)	Aktywne źródło
1	`VAULT_K8S_ROLE`	`KubernetesVaultConfigSource` — Vault przez projektowany token ServiceAccount poda
2	`DOCKER`	`YamlConfigSource("config-docker.yml")`
3	`TESTING`	`YamlConfigSource("config-test.yml")`
4	`DEVELOPING`	`YamlConfigSource("config-dev.yml")`
5	(żadne z powyższych)	`VaultConfigSource` — odczytuje `VAULT_URL` / `VAULT_TOKEN`

Wybór możesz nadpisać dla każdej aplikacji:

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

Klucze konfiguracji

Słownik, który musi zwrócić aktywne źródło. Pokazane wartości domyślne pochodzą z config-dev.yml (środowisko deweloperskie); aplikacja referencyjna zawiera config-dev.yml, config-test.yml i config-docker.yml o dokładnie takiej strukturze.

Klucz	Przeznaczenie	Przykładowa wartość
`api_base_url`	Publiczny bazowy URL tego API (używany w linkach w odpowiedziach)	`http://localhost:8000`
`cdp_url`	Endpoint Headless Chrome (CDP) dla agentów webowych (`WebAgentBase`)	`http://localhost:9222`
`auth.enabled`	Montuje middleware uwierzytelniania i trasy `/auth`, gdy ma wartość `true`	`false`
`auth.url`	Bazowy URL Keycloak	`https://auth.example.com`
`auth.realm`	Nazwa realmu Keycloak	`agent-lab`
`auth.client_id`	Identyfikator klienta OIDC	`agent-lab-api`
`auth.client_secret`	Sekret klienta OIDC	`…`
`broker.url`	URL Redis dla aktualizacji statusu długich operacji przez pub/sub	`redis://localhost:6379/0`
`db.url`	PostgreSQL — dane relacyjne	`postgresql://postgres:postgres@localhost:5432/agent_lab`
`db.vectors`	PostgreSQL — baza danych embeddingów pgvector	`postgresql://postgres:postgres@localhost:5432/agent_lab_vectors`
`db.checkpoints`	PostgreSQL — baza danych checkpointów LangGraph (pamięć agenta)	`postgresql://postgres:postgres@localhost:5432/agent_lab_checkpoints`
`vault.url`	Adres Vault (zapisywany także z powrotem, aby usługi mogły odczytywać sekrety)	`http://localhost:8200`
`vault.token`	Token Vault	`dev-only-token`
`static.enabled`	Serwuje build SPA (`false`, gdy build frontendu nie istnieje)	`false`
`static.directory`	Katalog zawierający build SPA	`static/frontend/browser`
`static.index_file`	Plik zastępczy (fallback) SPA	`index.html`
`static.mount_path`	Punkt montowania SPA	`/`

static jest wyjątkowy: źródła YAML konfigurują go jawnie, natomiast źródło Vault wyprowadza go z konwencji w kodzie — jest włączony, gdy w STATIC_DIR istnieje build SPA.

Ładunek sekretu w Vault

VaultConfigSource odczytuje pojedynczy sekret KV-v2 (domyślnie silnik secret, ścieżka app_secrets) i mapuje go na powyższe klucze:

Klucz sekretu	Mapowany na
`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`

Sposób przygotowania tego ładunku (deweloperski Docker Compose, Kubernetes, Terraform) opisują strony Sekrety w Vault i Przewodnik wdrażania.

Zmienne środowiskowe

Wybór źródła konfiguracji

Zmienna	Wartość domyślna	Przeznaczenie
`DEVELOPING`	(nieustawiona)	Wybiera `config-dev.yml` (debugowanie w IDE)
`TESTING`	(nieustawiona)	Wybiera `config-test.yml` (zestaw testów)
`DOCKER`	(nieustawiona)	Wybiera `config-docker.yml` (Compose)
`VAULT_URL`	(nieustawiona)	Adres Vault dla źródła domyślnego
`VAULT_TOKEN`	(nieustawiona)	Token Vault dla źródła domyślnego
`VAULT_ENGINE_PATH`	`secret`	Punkt montowania KV-v2
`VAULT_SECRET_PATH`	`app_secrets`	Ścieżka sekretu
`VAULT_K8S_ROLE`	(nieustawiona)	Rola uwierzytelniania Kubernetes w Vault; włącza źródło K8s i ma pierwszeństwo
`STATIC_DIR`	`static/frontend/browser`	Miejsce, w którym szukany jest build SPA

Obserwowalność

Zmienna	Wartość domyślna	Przeznaczenie
`OTEL_EXPORTER_OTLP_ENDPOINT`	(nieustawiona — śledzenie wyłączone)	Bazowy URL kolektora OTLP/HTTP; ślady → `/v1/traces`, metryki → `/v1/metrics`, logi → `/v1/logs`
`SERVICE_NAME`	`Agent-Lab`	Nazwa zasobu OTel
`SERVICE_VERSION`	`snapshot`	Wersja zasobu OTel
`LANGFUSE_HOST`	(nieustawiona)	Bazowy URL Langfuse; razem z dwoma poniższymi kluczami włącza backend Langfuse
`LANGFUSE_PUBLIC_KEY`	(nieustawiona)	Klucz Langfuse `pk-lf-…`
`LANGFUSE_SECRET_KEY`	(nieustawiona)	Klucz Langfuse `sk-lf-…`
`LANGWATCH_ENDPOINT`	(nieustawiona)	Endpoint LangWatch; razem z poniższym kluczem włącza backend LangWatch
`LANGWATCH_API_KEY`	(nieustawiona)	Klucz API LangWatch

Jeśli brakuje którejkolwiek zmiennej Langfuse, backend Langfuse zostaje po cichu wyłączony, a aplikacja i tak się uruchamia (tak samo w przypadku LangWatch). Szczegóły i punkt rozszerzenia: Obserwowalność.

Uwierzytelnianie i integracje

Zmienna	Wartość domyślna	Przeznaczenie
`AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` / `AZURE_TENANT_ID`	(nieustawiona)	Poświadczenia Microsoft Entra ID dla `/auth/exchange`
`EMBEDDINGS_ENDPOINT`	(nieustawiona)	Usługa embeddingów używana przez agentów wyszukujących
`OPENAI_API_KEY`	(nieustawiona)	OpenAI (wejście audio agenta notatek głosowych; domyślny sędzia symulacji)

Symulacje (tylko zestaw testów)

Zmienna	Wartość domyślna	Przeznaczenie
`SIMULATION_LLM_MODEL`	(wymagana)	Tag modelu wykonującego testowanych agentów (np. `qwen3:30b`)
`SIMULATION_LLM_API_BASE`	(wymagana)	Endpoint zgodny z OpenAI, który serwuje ten model
`SIMULATION_LLM_API_KEY`	`dummy-key`	Klucz API endpointu, jeśli jest wymagany
`SIMULATION_JUDGE_MODEL`	`openai/gpt-5-nano`	Identyfikator modelu litellm używanego przez LLM w roli sędziego
`SIMULATION_JUDGE_API_BASE`	domyślna dostawcy	Niestandardowy endpoint zgodny z OpenAI dla sędziego
`SIMULATION_JUDGE_API_KEY`	domyślna dostawcy	Klucz API niestandardowego endpointu sędziego

Sposób korzystania z tych zmiennych opisuje strona Testy i symulacje.

Niestandardowe źródła konfiguracji

Zaimplementuj abstrakcyjną klasę bazową ConfigSource i przekaż ją do create_app(config_source=...) — przydaje się to w przypadku AWS Secrets Manager, wdrożeń opartych wyłącznie na zmiennych środowiskowych lub opakowywania innego źródła:

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())

Dostarczane źródła (YamlConfigSource, VaultConfigSource, KubernetesVaultConfigSource) oraz default_config_source() są eksportowane z pakietu najwyższego poziomu agent_lab.