테스트 및 시뮬레이션

두 가지 테스트 하네스: 실제 인프라 기반 통합 테스트와 LLM-as-judge 에이전트 시뮬레이션

에이전트 테스트는 나중에 덧붙인 기능이 아니라 프레임워크의 핵심 기능입니다. Agent-Lab은 프레임워크 자체를 검증하는 데에도, 그 위에 구축한 에이전트를 검증하는 데에도 사용할 수 있는 상호 보완적인 두 가지 하네스를 제공합니다.

통합 테스트는 testcontainers로 필요할 때 띄우는 실제 인프라(Postgres, Redis, Keycloak, 임베딩, Headless Chrome)를 대상으로 시스템을 검증하며, 외부 서비스, 데이터베이스 작업, 벡터 검색, API 엔드포인트를 다룹니다.
에이전트 시뮬레이션은 실제 LLM을 대상으로 에이전트 동작을 엔드 투 엔드로 평가하며, LLM-as-judge가 점수를 매기고 Langfuse와 LangWatch에서 시간에 따른 변화를 추적합니다.

통합 테스트의 주요 구성은 tests/conftest.py에 있습니다. 사용 환경에 맞게 수정하세요.

참고: 통합 테스트와 시뮬레이션은 외부 서비스를 실제로 호출하므로 비용이 발생할 수 있습니다. 통제된 환경에서 실행하고 사용량을 모니터링하세요.

통합 테스트

Docker(또는 다른 컨테이너 런타임)가 필요합니다. 테스트 스위트는 testcontainers를 통해 실제 컨테이너를 프로비저닝합니다.

make test_unit         # fast lane: boots the app with no infrastructure
make test_integration  # the full real-infrastructure suite
make test              # both, with coverage (gate: 90%)

처음 실행할 때는 Docker 이미지와 임베딩 모델을 한 번 다운로드하므로 몇 분 정도 걸릴 수 있습니다. agent_lab/의 커버리지는 CI(SonarCloud)에서 강제됩니다.

스캐폴딩된 프로젝트도 같은 구조를 따릅니다. tests/에는 컨테이너가 필요 없는 스모크 테스트와 선택적인 testcontainers 스위트가 들어 있습니다.

에이전트 시뮬레이션

엔드 투 엔드 에이전트 시뮬레이션은 tests/simulation/에 있으며 실제 LLM 공급자를 호출합니다. 이 테스트에는 agent_test 마커가 지정되어 있어 기본적으로 제외됩니다. 다음과 같이 실행하세요.

make test_simulations
# or a single track:
make scenario_simulation
make langwatch_simulation
make langfuse_simulation

상호 보완적인 세 가지 트랙이 에이전트 부트스트랩 헬퍼, 심사 모델, 그리고 tests/simulation/datasets/ 아래의 데이터셋 정의를 공유합니다.

tests/simulation/scenario/ — langwatch-scenario 프레임워크를 사용한 대화형 시뮬레이션입니다. 사용자 시뮬레이터가 에이전트를 구동하고, 심사 에이전트가 상호작용에 점수를 매깁니다.
tests/simulation/langfuse/ — Langfuse 데이터셋을 사용한 데이터셋 기반 실험입니다. 각 실행은 데이터셋 정의를 동기화하고, 항목마다 에이전트를 호출하고, 클라이언트 측 LLM-as-judge로 출력에 점수를 매긴 뒤, 실행과 점수를 Langfuse에 기록해 시간에 따라 비교할 수 있게 합니다. LANGFUSE_BASE_URL(또는 지원 중단된 LANGFUSE_HOST), LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY가 설정되지 않으면 자동으로 건너뜁니다.
tests/simulation/langwatch/ — 동일한 데이터셋 실험을 langwatch.experiment를 통해 LangWatch에 미러링하며, 항목별 심사 점수를 기록합니다. 정의는 하나로 통합된 simulations 데이터셋에 멱등적으로 동기화됩니다(LangWatch 무료 플랜은 프로젝트당 최대 3개의 데이터셋만 허용하므로, dataset 열로 원본 정의를 구분합니다). LANGWATCH_ENDPOINT와 LANGWATCH_API_KEY가 설정되지 않으면 자동으로 건너뜁니다.

각 트랙에서 다루는 레퍼런스 에이전트는 coordinator-planner-supervisor, ReAct RAG, 비전/문서, 브라우저 자동화, 음성 메모, 적응형 RAG 에이전트입니다.

심사 모델 및 에이전트 LLM 구성

심사 모델(및 시나리오 사용자 시뮬레이터)은 OpenAI API 호환 엔드포인트에 대해 litellm 모델 ID를 사용합니다.

환경 변수	기본값	용도
`SIMULATION_JUDGE_MODEL`	`openai/gpt-5-nano`	LLM-as-judge가 사용하는 litellm 모델 ID
`SIMULATION_JUDGE_API_BASE`	공급자 기본값	심사 모델용 사용자 정의 OpenAI 호환 엔드포인트
`SIMULATION_JUDGE_API_KEY`	공급자 기본값	사용자 정의 엔드포인트의 API 키

테스트 대상 에이전트는 OpenAI 호환 엔드포인트(예: LAN 추론 서버)가 제공하는 기본 LLM에서 실행되며, tests/simulation/common/llm_factory.py가 테스트마다 이를 프로비저닝합니다. 예외는 음성 메모 에이전트로, 오디오 채팅 입력이 필요하기 때문에 OpenAI를 계속 사용합니다. 임베딩은 pgvector 덤프와 일치하도록 EMBEDDINGS_ENDPOINT 폴백(bge-m3를 제공하는 테스트용 Ollama 컨테이너)을 계속 사용합니다. supervisor 기반 스위트(브라우저 자동화, supervisor)를 위해서는 엔드포인트가 도구 호출/구조화된 출력을 지원해야 합니다.

환경 변수	기본값	용도
`SIMULATION_LLM_MODEL`	없음(필수)	시뮬레이션을 실행하는 모델 태그(예: `qwen3:30b`)
`SIMULATION_LLM_API_BASE`	없음(필수)	모델을 제공하는 OpenAI 호환 엔드포인트
`SIMULATION_LLM_API_KEY`	`dummy-key`	엔드포인트에 필요한 경우 API 키

평가 플랫폼 설정

make test_simulations(및 트랙별 타깃)는 먼저 sync_simulation_evals 단계를 실행해 데이터셋 정의를 구성된 모든 플랫폼에 미러링합니다. Langfuse 서버 측 평가 설정(심사 모델용 LLM 연결, simulation_llm_as_judge 평가자, 시뮬레이션 데이터셋별 평가 규칙 하나씩 — Langfuse의 Evaluations 섹션에서 확인 가능)까지 프로비저닝하려면 다음을 실행하세요.

uv run python tests/setup_simulation_evals.py

이 스크립트는 멱등적이므로 여러 번 실행해도 안전합니다.