구성 레퍼런스 · Agent-Lab

모든 구성 키와 환경 변수, 그리고 활성 소스가 선택되는 방식

구성 로드 방식

구성은 ConfigSource(agent_lab/core/config.py 참고)가 로드하는 일반 딕셔너리이며, DI 컨테이너에 바인딩됩니다. create_app()은 default_config_source()를 통해 아래 순서대로 소스를 선택하며, 처음 일치하는 항목이 적용됩니다.

#	조건(설정된 환경 변수)	활성 소스
1	`VAULT_K8S_ROLE`	`KubernetesVaultConfigSource` — 파드의 프로젝션된 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`	웹 에이전트(`WebAgentBase`)용 Headless Chrome(CDP) 엔드포인트	`http://localhost:9222`
`auth.enabled`	`true`이면 인증 미들웨어와 `/auth` 라우트를 마운트	`false`
`auth.url`	Keycloak 기본 URL	`https://auth.example.com`
`auth.realm`	Keycloak 렐름 이름	`agent-lab`
`auth.client_id`	OIDC 클라이언트 ID	`agent-lab-api`
`auth.client_secret`	OIDC 클라이언트 시크릿	`…`
`broker.url`	장시간 작업의 상태 업데이트용 Pub/Sub에 사용하는 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 컬렉터 기본 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 ABC를 구현하고 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 패키지에서 export됩니다.