Referencia de configuración

Cada clave de configuración y variable de entorno, y cómo se elige la fuente activa

Cómo se carga la configuración

La configuración es un diccionario simple que carga un ConfigSource (consulta agent_lab/core/config.py) y que se vincula al contenedor de DI. create_app() selecciona una fuente mediante default_config_source(), exactamente en este orden; gana la primera coincidencia:

#	Condición (variable de entorno definida)	Fuente activa
1	`VAULT_K8S_ROLE`	`KubernetesVaultConfigSource`: Vault mediante el token proyectado de la ServiceAccount del pod
2	`DOCKER`	`YamlConfigSource("config-docker.yml")`
3	`TESTING`	`YamlConfigSource("config-test.yml")`
4	`DEVELOPING`	`YamlConfigSource("config-dev.yml")`
5	(ninguna de las anteriores)	`VaultConfigSource`: lee `VAULT_URL` / `VAULT_TOKEN`

Puedes anular la selección para cada aplicación:

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

Claves de configuración

El diccionario que debe devolver la fuente activa. Los valores predeterminados que se muestran provienen de config-dev.yml (desarrollo); la aplicación de referencia incluye config-dev.yml, config-test.yml y config-docker.yml exactamente con esta estructura.

Clave	Propósito	Valor de ejemplo
`api_base_url`	URL base pública de esta API (se usa para los enlaces en las respuestas)	`http://localhost:8000`
`cdp_url`	Endpoint de Chrome headless (CDP) para agentes web (`WebAgentBase`)	`http://localhost:9222`
`auth.enabled`	Monta el middleware de autenticación y las rutas `/auth` cuando es `true`	`false`
`auth.url`	URL base de Keycloak	`https://auth.example.com`
`auth.realm`	Nombre del realm de Keycloak	`agent-lab`
`auth.client_id`	ID de cliente OIDC	`agent-lab-api`
`auth.client_secret`	Secreto de cliente OIDC	`…`
`broker.url`	URL de Redis para actualizaciones de estado mediante pub/sub en operaciones largas	`redis://localhost:6379/0`
`db.url`	PostgreSQL: datos relacionales	`postgresql://postgres:postgres@localhost:5432/agent_lab`
`db.vectors`	PostgreSQL: base de datos de embeddings con pgvector	`postgresql://postgres:postgres@localhost:5432/agent_lab_vectors`
`db.checkpoints`	PostgreSQL: base de datos de checkpoints de LangGraph (memoria del agente)	`postgresql://postgres:postgres@localhost:5432/agent_lab_checkpoints`
`vault.url`	Dirección de Vault (también se vuelve a escribir para que los servicios puedan leer secretos)	`http://localhost:8200`
`vault.token`	Token de Vault	`dev-only-token`
`static.enabled`	Sirve una compilación de SPA (`false` cuando no existe una compilación del frontend)	`false`
`static.directory`	Directorio que contiene la compilación de la SPA	`static/frontend/browser`
`static.index_file`	Archivo de respaldo de la SPA	`index.html`
`static.mount_path`	Punto de montaje de la SPA	`/`

static es un caso especial: las fuentes YAML lo configuran de forma explícita, mientras que la fuente de Vault lo deriva de una convención en el código: se habilita cuando existe una compilación de SPA en STATIC_DIR.

Contenido del secreto de Vault

VaultConfigSource lee un único secreto KV-v2 (motor secret, ruta app_secrets de forma predeterminada) y lo asigna a las claves anteriores:

Clave del secreto	Se asigna a
`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`

Cómo aprovisionar ese contenido (Docker Compose de desarrollo, Kubernetes, Terraform) se explica en Secretos con Vault y en la Guía de implementación.

Variables de entorno

Selección de la fuente de configuración

Variable	Valor predeterminado	Propósito
`DEVELOPING`	(sin definir)	Selecciona `config-dev.yml` (depuración en el IDE)
`TESTING`	(sin definir)	Selecciona `config-test.yml` (suite de pruebas)
`DOCKER`	(sin definir)	Selecciona `config-docker.yml` (Compose)
`VAULT_URL`	(sin definir)	Dirección de Vault para la fuente predeterminada
`VAULT_TOKEN`	(sin definir)	Token de Vault para la fuente predeterminada
`VAULT_ENGINE_PATH`	`secret`	Punto de montaje de KV-v2
`VAULT_SECRET_PATH`	`app_secrets`	Ruta del secreto
`VAULT_K8S_ROLE`	(sin definir)	Rol de autenticación de Kubernetes en Vault; habilita la fuente de K8s y tiene prioridad
`STATIC_DIR`	`static/frontend/browser`	Dónde se busca la compilación de la SPA

Observabilidad

Variable	Valor predeterminado	Propósito
`OTEL_EXPORTER_OTLP_ENDPOINT`	(sin definir: rastreo desactivado)	URL base del collector OTLP/HTTP; trazas → `/v1/traces`, métricas → `/v1/metrics`, logs → `/v1/logs`
`SERVICE_NAME`	`Agent-Lab`	Nombre del recurso de OTel
`SERVICE_VERSION`	`snapshot`	Versión del recurso de OTel
`LANGFUSE_HOST`	(sin definir)	URL base de Langfuse; junto con las dos claves siguientes, habilita el backend de Langfuse
`LANGFUSE_PUBLIC_KEY`	(sin definir)	Clave `pk-lf-…` de Langfuse
`LANGFUSE_SECRET_KEY`	(sin definir)	Clave `sk-lf-…` de Langfuse
`LANGWATCH_ENDPOINT`	(sin definir)	Endpoint de LangWatch; junto con la clave siguiente, habilita el backend de LangWatch
`LANGWATCH_API_KEY`	(sin definir)	Clave de API de LangWatch

Si falta alguna variable de Langfuse, el backend de Langfuse se deshabilita sin aviso y la aplicación igual se inicia (lo mismo ocurre con LangWatch). Detalles y punto de extensión: Observabilidad.

Autenticación e integraciones

Variable	Valor predeterminado	Propósito
`AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` / `AZURE_TENANT_ID`	(sin definir)	Credenciales de Microsoft Entra ID para `/auth/exchange`
`EMBEDDINGS_ENDPOINT`	(sin definir)	Servicio de embeddings que usan los agentes de recuperación
`OPENAI_API_KEY`	(sin definir)	OpenAI (entrada de audio de notas de voz; juez predeterminado de las simulaciones)

Simulaciones (solo para la suite de pruebas)

Variable	Valor predeterminado	Propósito
`SIMULATION_LLM_MODEL`	(obligatoria)	Etiqueta del modelo que ejecuta los agentes bajo prueba (p. ej., `qwen3:30b`)
`SIMULATION_LLM_API_BASE`	(obligatoria)	Endpoint compatible con OpenAI que sirve ese modelo
`SIMULATION_LLM_API_KEY`	`dummy-key`	Clave de API del endpoint, si se requiere
`SIMULATION_JUDGE_MODEL`	`openai/gpt-5-nano`	ID de modelo de litellm que usa el LLM como juez
`SIMULATION_JUDGE_API_BASE`	valor predeterminado del proveedor	Endpoint personalizado compatible con OpenAI para el juez
`SIMULATION_JUDGE_API_KEY`	valor predeterminado del proveedor	Clave de API para el endpoint personalizado del juez

Consulta Pruebas y simulaciones para saber cómo se usan.

Fuentes de configuración personalizadas

Implementa la ABC ConfigSource y pásala a create_app(config_source=...); es útil para AWS Secrets Manager, implementaciones que solo usan variables de entorno o para envolver otra fuente:

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

Las fuentes incluidas (YamlConfigSource, VaultConfigSource, KubernetesVaultConfigSource) y default_config_source() se exportan desde el paquete de nivel superior agent_lab.