Riferimento della configurazione

Ogni chiave di configurazione e variabile d'ambiente, e come viene scelta la sorgente attiva

Come viene caricata la configurazione

La configurazione è un semplice dizionario caricato da una ConfigSource (vedi agent_lab/core/config.py) e collegato al container DI. create_app() seleziona una sorgente tramite default_config_source(), esattamente in quest'ordine: vince la prima corrispondenza:

#	Condizione (variabile d'ambiente impostata)	Sorgente attiva
1	`VAULT_K8S_ROLE`	`KubernetesVaultConfigSource` — Vault tramite il token ServiceAccount proiettato del pod
2	`DOCKER`	`YamlConfigSource("config-docker.yml")`
3	`TESTING`	`YamlConfigSource("config-test.yml")`
4	`DEVELOPING`	`YamlConfigSource("config-dev.yml")`
5	(nessuna delle precedenti)	`VaultConfigSource` — legge `VAULT_URL` / `VAULT_TOKEN`

Puoi sovrascrivere la selezione per singola app:

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

Chiavi di configurazione

Il dizionario che la sorgente attiva deve restituire. I valori predefiniti indicati provengono da config-dev.yml (sviluppo); l'app di riferimento include config-dev.yml, config-test.yml e config-docker.yml con esattamente questa struttura.

Chiave	Scopo	Valore di esempio
`api_base_url`	URL base pubblico di questa API (usato per i link nelle risposte)	`http://localhost:8000`
`cdp_url`	Endpoint di Chrome headless (CDP) per gli agenti web (`WebAgentBase`)	`http://localhost:9222`
`auth.enabled`	Monta il middleware di autenticazione e le route `/auth` quando è `true`	`false`
`auth.url`	URL base di Keycloak	`https://auth.example.com`
`auth.realm`	Nome del realm di Keycloak	`agent-lab`
`auth.client_id`	Client id OIDC	`agent-lab-api`
`auth.client_secret`	Client secret OIDC	`…`
`broker.url`	URL di Redis per gli aggiornamenti di stato pub/sub sulle operazioni lunghe	`redis://localhost:6379/0`
`db.url`	PostgreSQL — dati relazionali	`postgresql://postgres:postgres@localhost:5432/agent_lab`
`db.vectors`	PostgreSQL — database degli embedding pgvector	`postgresql://postgres:postgres@localhost:5432/agent_lab_vectors`
`db.checkpoints`	PostgreSQL — database dei checkpoint LangGraph (memoria degli agenti)	`postgresql://postgres:postgres@localhost:5432/agent_lab_checkpoints`
`vault.url`	Indirizzo di Vault (viene anche riscritto, così i servizi possono leggere i segreti)	`http://localhost:8200`
`vault.token`	Token di Vault	`dev-only-token`
`static.enabled`	Serve una build SPA (`false` quando non esiste una build del frontend)	`false`
`static.directory`	Directory che contiene la build SPA	`static/frontend/browser`
`static.index_file`	File di fallback della SPA	`index.html`
`static.mount_path`	Punto di montaggio della SPA	`/`

static è un caso speciale: le sorgenti YAML lo configurano in modo esplicito, mentre la sorgente Vault lo deriva da una convenzione nel codice: è abilitato quando esiste una build SPA in STATIC_DIR.

Payload del segreto in Vault

VaultConfigSource legge un singolo segreto KV-v2 (engine secret, path app_secrets per impostazione predefinita) e lo mappa sulle chiavi indicate sopra:

Chiave del segreto	Mappata su
`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`

Come effettuare il provisioning di questo payload (Docker Compose di sviluppo, Kubernetes, Terraform) è spiegato in Segreti con Vault e nella guida al deployment.

Variabili d'ambiente

Selezione della sorgente di configurazione

Variabile	Predefinito	Scopo
`DEVELOPING`	(non impostata)	Seleziona `config-dev.yml` (debug nell'IDE)
`TESTING`	(non impostata)	Seleziona `config-test.yml` (suite di test)
`DOCKER`	(non impostata)	Seleziona `config-docker.yml` (Compose)
`VAULT_URL`	(non impostata)	Indirizzo di Vault per la sorgente predefinita
`VAULT_TOKEN`	(non impostata)	Token di Vault per la sorgente predefinita
`VAULT_ENGINE_PATH`	`secret`	Punto di montaggio KV-v2
`VAULT_SECRET_PATH`	`app_secrets`	Path del segreto
`VAULT_K8S_ROLE`	(non impostata)	Ruolo di autenticazione Kubernetes di Vault; abilita la sorgente K8s e ha la precedenza
`STATIC_DIR`	`static/frontend/browser`	Dove viene cercata la build SPA

Osservabilità

Variabile	Predefinito	Scopo
`OTEL_EXPORTER_OTLP_ENDPOINT`	(non impostata — tracing disattivato)	URL base del collector OTLP/HTTP; trace → `/v1/traces`, metriche → `/v1/metrics`, log → `/v1/logs`
`SERVICE_NAME`	`Agent-Lab`	Nome della risorsa OTel
`SERVICE_VERSION`	`snapshot`	Versione della risorsa OTel
`LANGFUSE_HOST`	(non impostata)	URL base di Langfuse; insieme alle due chiavi seguenti, abilita il backend Langfuse
`LANGFUSE_PUBLIC_KEY`	(non impostata)	Chiave `pk-lf-…` di Langfuse
`LANGFUSE_SECRET_KEY`	(non impostata)	Chiave `sk-lf-…` di Langfuse
`LANGWATCH_ENDPOINT`	(non impostata)	Endpoint di LangWatch; insieme alla chiave seguente, abilita il backend LangWatch
`LANGWATCH_API_KEY`	(non impostata)	API key di LangWatch

Se manca una qualsiasi variabile di Langfuse, il backend Langfuse viene disabilitato silenziosamente e l'app si avvia comunque (lo stesso vale per LangWatch). Dettagli e punto di estensione: Osservabilità.

Autenticazione e integrazioni

Variabile	Predefinito	Scopo
`AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` / `AZURE_TENANT_ID`	(non impostata)	Credenziali Microsoft Entra ID per `/auth/exchange`
`EMBEDDINGS_ENDPOINT`	(non impostata)	Servizio di embedding usato dagli agenti di retrieval
`OPENAI_API_KEY`	(non impostata)	OpenAI (input audio dei memo vocali; giudice predefinito delle simulazioni)

Simulazioni (solo suite di test)

Variabile	Predefinito	Scopo
`SIMULATION_LLM_MODEL`	(obbligatoria)	Tag del modello che esegue gli agenti sotto test (ad es. `qwen3:30b`)
`SIMULATION_LLM_API_BASE`	(obbligatoria)	Endpoint compatibile con OpenAI che serve quel modello
`SIMULATION_LLM_API_KEY`	`dummy-key`	API key per l'endpoint, se richiesta
`SIMULATION_JUDGE_MODEL`	`openai/gpt-5-nano`	Id del modello litellm usato dall'LLM-as-judge
`SIMULATION_JUDGE_API_BASE`	predefinito del provider	Endpoint personalizzato compatibile con OpenAI per il giudice
`SIMULATION_JUDGE_API_KEY`	predefinito del provider	API key per l'endpoint personalizzato del giudice

Consulta Test e simulazioni per scoprire come vengono utilizzate.

Sorgenti di configurazione personalizzate

Implementa la ABC ConfigSource e passala a create_app(config_source=...): è utile per AWS Secrets Manager, per deployment basati solo su variabili d'ambiente o per incapsulare un'altra sorgente:

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

Le sorgenti incluse (YamlConfigSource, VaultConfigSource, KubernetesVaultConfigSource) e default_config_source() sono tutte esportate dal package di primo livello agent_lab.