配置参考 · Agent-Lab

所有配置键和环境变量，以及当前生效的配置源是如何选定的

配置的加载方式

配置是一个普通的字典，由 ConfigSource（参见 agent_lab/core/config.py）加载并绑定到 DI 容器。create_app() 通过 default_config_source() 选择配置源，严格按照以下顺序——第一个匹配项生效：

#	条件（已设置的环境变量）	生效的配置源
1	`VAULT_K8S_ROLE`	`KubernetesVaultConfigSource`——通过 Pod 的投射 ServiceAccount 令牌访问 Vault
2	`DOCKER`	`YamlConfigSource("config-docker.yml")`
3	`TESTING`	`YamlConfigSource("config-test.yml")`
4	`DEVELOPING`	`YamlConfigSource("config-dev.yml")`
5	（以上均未设置）	`VaultConfigSource`——读取 `VAULT_URL` / `VAULT_TOKEN`

你可以针对单个应用覆盖这一选择：

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

配置键

这是当前生效的配置源必须返回的字典。表中的默认值取自 config-dev.yml（开发环境）；参考应用附带的 config-dev.yml、config-test.yml 和 config-docker.yml 都采用完全相同的结构。

键	用途	示例值
`api_base_url`	本 API 的公开基础 URL（用于响应中的链接）	`http://localhost:8000`
`cdp_url`	供 Web 智能体（`WebAgentBase`）使用的无头 Chrome（CDP）端点	`http://localhost:9222`
`auth.enabled`	为 `true` 时挂载认证中间件和 `/auth` 路由	`false`
`auth.url`	Keycloak 基础 URL	`https://auth.example.com`
`auth.realm`	Keycloak realm 名称	`agent-lab`
`auth.client_id`	OIDC 客户端 ID	`agent-lab-api`
`auth.client_secret`	OIDC 客户端密钥	`…`
`broker.url`	用于长时间操作状态更新发布/订阅的 Redis URL	`redis://localhost:6379/0`
`db.url`	PostgreSQL——关系型数据	`postgresql://postgres:postgres@localhost:5432/agent_lab`
`db.vectors`	PostgreSQL——pgvector 嵌入数据库	`postgresql://postgres:postgres@localhost:5432/agent_lab_vectors`
`db.checkpoints`	PostgreSQL——LangGraph 检查点（智能体记忆）数据库	`postgresql://postgres:postgres@localhost:5432/agent_lab_checkpoints`
`vault.url`	Vault 地址（也会被回写，以便各服务读取密钥）	`http://localhost:8200`
`vault.token`	Vault 令牌	`dev-only-token`
`static.enabled`	提供 SPA 构建产物（没有前端构建产物时为 `false`）	`false`
`static.directory`	包含 SPA 构建产物的目录	`static/frontend/browser`
`static.index_file`	SPA 回退文件	`index.html`
`static.mount_path`	SPA 的挂载点	`/`

static 比较特殊：YAML 配置源会显式配置它，而 Vault 配置源则依据代码约定推导它——当 STATIC_DIR 下存在 SPA 构建产物时即启用。

Vault 密钥载荷

VaultConfigSource 读取单个 KV-v2 密钥（默认引擎为 secret，路径为 app_secrets），并将其映射到上述配置键：

密钥中的键	映射到
`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`

如何预置该载荷（开发用 Docker Compose、Kubernetes、Terraform），请参阅使用 Vault 管理密钥和部署指南。

环境变量

配置源选择

变量	默认值	用途
`DEVELOPING`	（未设置）	选用 `config-dev.yml`（IDE 调试）
`TESTING`	（未设置）	选用 `config-test.yml`（测试套件）
`DOCKER`	（未设置）	选用 `config-docker.yml`（Compose）
`VAULT_URL`	（未设置）	默认配置源使用的 Vault 地址
`VAULT_TOKEN`	（未设置）	默认配置源使用的 Vault 令牌
`VAULT_ENGINE_PATH`	`secret`	KV-v2 挂载点
`VAULT_SECRET_PATH`	`app_secrets`	密钥路径
`VAULT_K8S_ROLE`	（未设置）	Vault Kubernetes 认证角色；启用 K8s 配置源并具有最高优先级
`STATIC_DIR`	`static/frontend/browser`	查找 SPA 构建产物的位置

可观测性

变量	默认值	用途
`OTEL_EXPORTER_OTLP_ENDPOINT`	（未设置——追踪关闭）	OTLP/HTTP Collector 基础 URL；追踪 → `/v1/traces`，指标 → `/v1/metrics`，日志 → `/v1/logs`
`SERVICE_NAME`	`Agent-Lab`	OTel 资源名称
`SERVICE_VERSION`	`snapshot`	OTel 资源版本
`LANGFUSE_HOST`	（未设置）	Langfuse 基础 URL；与下面两个密钥一起设置时启用 Langfuse 后端
`LANGFUSE_PUBLIC_KEY`	（未设置）	Langfuse `pk-lf-…` 密钥
`LANGFUSE_SECRET_KEY`	（未设置）	Langfuse `sk-lf-…` 密钥
`LANGWATCH_ENDPOINT`	（未设置）	LangWatch 端点；与下面的密钥一起设置时启用 LangWatch 后端
`LANGWATCH_API_KEY`	（未设置）	LangWatch API 密钥

只要缺少任一 Langfuse 变量，Langfuse 后端就会被静默禁用，应用仍可正常启动（LangWatch 同理）。详细信息及扩展点请参阅可观测性。

认证与集成

变量	默认值	用途
`AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET` / `AZURE_TENANT_ID`	（未设置）	供 `/auth/exchange` 使用的 Microsoft Entra ID 凭据
`EMBEDDINGS_ENDPOINT`	（未设置）	检索类智能体使用的嵌入服务
`OPENAI_API_KEY`	（未设置）	OpenAI（语音备忘录的音频输入；模拟评审的默认模型）

模拟（仅限测试套件）

变量	默认值	用途
`SIMULATION_LLM_MODEL`	（必填）	运行被测智能体的模型标签（例如 `qwen3:30b`）
`SIMULATION_LLM_API_BASE`	（必填）	提供该模型服务的 OpenAI 兼容端点
`SIMULATION_LLM_API_KEY`	`dummy-key`	该端点的 API 密钥（如需要）
`SIMULATION_JUDGE_MODEL`	`openai/gpt-5-nano`	LLM-as-judge 使用的 litellm 模型 ID
`SIMULATION_JUDGE_API_BASE`	提供商默认值	评审模型使用的自定义 OpenAI 兼容端点
`SIMULATION_JUDGE_API_KEY`	提供商默认值	自定义评审端点的 API 密钥

这些变量的使用方式请参阅测试与模拟。

自定义配置源

实现 ConfigSource 抽象基类并将其传给 create_app(config_source=...)——适用于 AWS Secrets Manager、仅依赖环境变量的部署，或对其他配置源进行包装等场景：

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

内置的配置源（YamlConfigSource、VaultConfigSource、KubernetesVaultConfigSource）以及 default_config_source() 都从顶层 agent_lab 包中导出。