测试与模拟 · Agent-Lab

两套测试工具：基于真实基础设施的集成测试，以及 LLM-as-judge 智能体模拟

测试智能体是本框架的一等能力，而不是事后补充。Agent-Lab 提供两套互补的测试工具，既可用于验证框架本身，也可用于验证你在框架之上构建的智能体：

集成测试针对按需通过 testcontainers 启动的真实基础设施（Postgres、Redis、Keycloak、嵌入服务、无头 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 数据集中（由 dataset 列标识来源定义，因为 LangWatch 免费版每个项目最多只允许 3 个数据集）。若未设置 LANGWATCH_ENDPOINT 和 LANGWATCH_API_KEY，则会自动跳过。

各测试轨道覆盖的参考智能体包括：coordinator-planner-supervisor、react RAG、视觉/文档、浏览器自动化、语音备忘录以及自适应 RAG 智能体。

评审与智能体的 LLM 配置

评审（以及 scenario 用户模拟器）使用 litellm 模型 ID，可对接任何兼容 OpenAI API 的端点：

环境变量	默认值	用途
`SIMULATION_JUDGE_MODEL`	`openai/gpt-5-nano`	LLM-as-judge 使用的 litellm 模型 ID
`SIMULATION_JUDGE_API_BASE`	提供商默认值	评审模型使用的自定义 OpenAI 兼容端点
`SIMULATION_JUDGE_API_KEY`	提供商默认值	自定义端点的 API 密钥

被测智能体运行在由任意 OpenAI 兼容端点（例如局域网内的推理服务器）提供的默认 LLM 上，并由 tests/simulation/common/llm_factory.py 为每个测试单独创建。唯一的例外是语音备忘录智能体，它仍使用 OpenAI（因为需要音频对话输入）。嵌入仍使用 EMBEDDINGS_ENDPOINT 回退方案（由测试用的 Ollama 容器提供 bge-m3 服务），与 pgvector 转储数据保持一致。对于基于 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

该脚本是幂等的，可以安全地重复运行。