Référence de configuration

Chaque clé de configuration et variable d'environnement, et la manière dont la source active est choisie

Chargement de la configuration

La configuration est un simple dictionnaire chargé par une ConfigSource (voir agent_lab/core/config.py) et lié au conteneur DI. create_app() sélectionne une source via default_config_source(), exactement dans cet ordre — la première correspondance l'emporte :

#	Condition (variable d'environnement définie)	Source active
1	`VAULT_K8S_ROLE`	`KubernetesVaultConfigSource` — Vault via le jeton ServiceAccount projeté du pod
2	`DOCKER`	`YamlConfigSource("config-docker.yml")`
3	`TESTING`	`YamlConfigSource("config-test.yml")`
4	`DEVELOPING`	`YamlConfigSource("config-dev.yml")`
5	(aucune des précédentes)	`VaultConfigSource` — lit `VAULT_URL` / `VAULT_TOKEN`

Vous pouvez remplacer cette sélection pour chaque application :

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

Clés de configuration

Le dictionnaire que la source active doit renvoyer. Les valeurs par défaut indiquées proviennent de config-dev.yml (développement) ; l'application de référence fournit config-dev.yml, config-test.yml et config-docker.yml avec exactement cette structure.

Clé	Rôle	Exemple de valeur
`api_base_url`	URL de base publique de cette API (utilisée pour les liens dans les réponses)	`http://localhost:8000`
`cdp_url`	Point de terminaison Chrome headless (CDP) pour les agents web (`WebAgentBase`)	`http://localhost:9222`
`auth.enabled`	Monte le middleware d'authentification et les routes `/auth` lorsque la valeur est `true`	`false`
`auth.url`	URL de base de Keycloak	`https://auth.example.com`
`auth.realm`	Nom du realm Keycloak	`agent-lab`
`auth.client_id`	Identifiant du client OIDC	`agent-lab-api`
`auth.client_secret`	Secret du client OIDC	`…`
`broker.url`	URL Redis pour les mises à jour d'état pub/sub des opérations longues	`redis://localhost:6379/0`
`db.url`	PostgreSQL — données relationnelles	`postgresql://postgres:postgres@localhost:5432/agent_lab`
`db.vectors`	PostgreSQL — base de données des embeddings pgvector	`postgresql://postgres:postgres@localhost:5432/agent_lab_vectors`
`db.checkpoints`	PostgreSQL — base de données des checkpoints LangGraph (mémoire des agents)	`postgresql://postgres:postgres@localhost:5432/agent_lab_checkpoints`
`vault.url`	Adresse de Vault (également réécrite pour que les services puissent lire les secrets)	`http://localhost:8200`
`vault.token`	Jeton Vault	`dev-only-token`
`static.enabled`	Sert un build de SPA (`false` lorsqu'aucun build frontend n'existe)	`false`
`static.directory`	Répertoire contenant le build de la SPA	`static/frontend/browser`
`static.index_file`	Fichier de repli de la SPA	`index.html`
`static.mount_path`	Point de montage de la SPA	`/`

static est un cas particulier : les sources YAML la configurent explicitement, tandis que la source Vault la déduit d'une convention de code — elle est activée lorsqu'un build de SPA existe sous STATIC_DIR.

Charge utile du secret Vault

VaultConfigSource lit un unique secret KV-v2 (moteur secret, chemin app_secrets par défaut) et le fait correspondre aux clés ci-dessus :

Clé du secret	Correspond à
`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`

La manière de provisionner cette charge utile (Docker Compose de développement, Kubernetes, Terraform) est décrite dans Secrets avec Vault et dans le guide de déploiement.

Variables d'environnement

Sélection de la source de configuration

Variable	Valeur par défaut	Rôle
`DEVELOPING`	(non définie)	Sélectionne `config-dev.yml` (débogage dans l'IDE)
`TESTING`	(non définie)	Sélectionne `config-test.yml` (suite de tests)
`DOCKER`	(non définie)	Sélectionne `config-docker.yml` (Compose)
`VAULT_URL`	(non définie)	Adresse de Vault pour la source par défaut
`VAULT_TOKEN`	(non définie)	Jeton Vault pour la source par défaut
`VAULT_ENGINE_PATH`	`secret`	Point de montage KV-v2
`VAULT_SECRET_PATH`	`app_secrets`	Chemin du secret
`VAULT_K8S_ROLE`	(non définie)	Rôle d'authentification Kubernetes de Vault ; active la source K8s et est prioritaire
`STATIC_DIR`	`static/frontend/browser`	Emplacement où le build de la SPA est recherché

Observabilité

Variable	Valeur par défaut	Rôle
`OTEL_EXPORTER_OTLP_ENDPOINT`	(non définie — traçage désactivé)	URL de base du collecteur OTLP/HTTP ; traces → `/v1/traces`, métriques → `/v1/metrics`, logs → `/v1/logs`
`SERVICE_NAME`	`Agent-Lab`	Nom de la ressource OTel
`SERVICE_VERSION`	`snapshot`	Version de la ressource OTel
`LANGFUSE_HOST`	(non définie)	URL de base de Langfuse ; avec les deux clés ci-dessous, active le backend Langfuse
`LANGFUSE_PUBLIC_KEY`	(non définie)	Clé Langfuse `pk-lf-…`
`LANGFUSE_SECRET_KEY`	(non définie)	Clé Langfuse `sk-lf-…`
`LANGWATCH_ENDPOINT`	(non définie)	Point de terminaison LangWatch ; avec la clé ci-dessous, active le backend LangWatch
`LANGWATCH_API_KEY`	(non définie)	Clé d'API LangWatch

Si l'une des variables Langfuse est absente, le backend Langfuse est désactivé silencieusement et l'application démarre quand même (il en va de même pour LangWatch). Détails et point d'extension : Observabilité.

Authentification et intégrations

Variable	Valeur par défaut	Rôle
`AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` / `AZURE_TENANT_ID`	(non définies)	Identifiants Microsoft Entra ID pour `/auth/exchange`
`EMBEDDINGS_ENDPOINT`	(non définie)	Service d'embeddings utilisé par les agents de récupération
`OPENAI_API_KEY`	(non définie)	OpenAI (entrée audio des mémos vocaux ; juge de simulation par défaut)

Simulations (suite de tests uniquement)

Variable	Valeur par défaut	Rôle
`SIMULATION_LLM_MODEL`	(obligatoire)	Tag du modèle qui exécute les agents testés (par exemple `qwen3:30b`)
`SIMULATION_LLM_API_BASE`	(obligatoire)	Point de terminaison compatible OpenAI qui sert ce modèle
`SIMULATION_LLM_API_KEY`	`dummy-key`	Clé d'API du point de terminaison, si nécessaire
`SIMULATION_JUDGE_MODEL`	`openai/gpt-5-nano`	Identifiant de modèle litellm utilisé par le LLM-as-judge
`SIMULATION_JUDGE_API_BASE`	valeur par défaut du fournisseur	Point de terminaison personnalisé compatible OpenAI pour le juge
`SIMULATION_JUDGE_API_KEY`	valeur par défaut du fournisseur	Clé d'API du point de terminaison personnalisé du juge

Voir Tests et simulations pour savoir comment elles sont utilisées.

Sources de configuration personnalisées

Implémentez la classe abstraite ConfigSource et passez-la à create_app(config_source=...) — utile pour AWS Secrets Manager, les déploiements reposant uniquement sur l'environnement, ou pour encapsuler une autre source :

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

Les sources fournies (YamlConfigSource, VaultConfigSource, KubernetesVaultConfigSource) et default_config_source() sont toutes exportées par le package de premier niveau agent_lab.