如何在Agents‘ Last Exam中配置实验YAML：并发、auto-resume、timeout等关键参数详解-平芜编程栈

【免费下载链接】agents-last-exam

Agents' Last Exam

项目地址：https://gitcode.com/gh_mirrors/ag/agents-last-exam

Agents' Last Exam（ALE）是一个用于在真实沙箱中评测 AI Agent 的开源基准框架，而实验 YAML（experiment YAML）是启动一次批量评测的唯一入口：用一个文件把 Agent 预设、沙箱环境与任务清单"接线"起来，并通过concurrency、auto_resume、wall_time_s等运行级参数控制整批任务的行为。本文带你从 3 个必填字段写到并发与断点续跑，完整讲清实验 YAML 的每一个关键参数。

1️⃣ 先认识实验YAML：一个文件搞定批量评测

一次实验 =Agent × 环境 × 任务的组合矩阵。实验 YAML 的设计刻意"很薄"：

它只负责接线——Agent 配置放在configs/agents/，环境配置放在configs/environments/，实验文件只按路径引用它们；
运行级参数（并发、超时、续跑、清理策略）则直接写在实验 YAML 的顶层。

仓库自带的最小示例就是 example_exp.yaml，复制修改后即可运行：

name: my_experiment secret_file: secret/.env # KEY=value 形式的密钥文件 agents: - configs/agents/claude_code.yaml # 多写几行 = 运行 agent 矩阵 environment: configs/environments/environment_gcloud.yaml tasks: selected_tasks/hello_both.txt # 任务清单 # ---- 运行级参数（全部可选，此处为默认值）---- output: root: .logs/ale # 宿主机运行日志目录 concurrency: 1 # 同时进行的 unit 数 wall_time_s: 7200 # 每个 unit 的墙上时钟上限（秒） auto_resume: true # 跳过已完成/超时，自动重试失败项 max_attempts: 3 # 失败 unit 的总尝试次数（1..3） cleanup_mode: delete # delete | stop | keep

2️⃣ 三个必填字段：name、agents、tasks + environment

字段	是否必填	说明
`name`	✅	实验名，同时也是输出目录名（`.logs/ale/<name>/`）
`agents`	✅	Agent 预设 YAML 路径列表，位于`configs/agents/`；列多个即跑agent 矩阵（每个 agent × 每个任务）。单 agent 也可用`agent:`简写
`environment`	✅	环境 YAML 路径，每个实验只能有一个，定义 provider、镜像与路由
`tasks`	✅	任务清单：`.txt`每行一个任务路径（`#`开头为注释）；`.yaml`则支持`{path, variants}`条目

几个实用细节：

Agent 预设决定用哪个 harness、哪个模型。例如 configs/agents/claude_code.yaml 中harness: claude_code+model:一行即可切换模型；同名 harness 想同时跑多个配置变体时，在预设里显式写id:区分输出目录。
环境 YAML按"快照（snapshot）"路由 provider：一个环境可以混用后端，比如 Linux 任务走 Docker、Windows/GPU 任务走云 VM。参考 configs/environments/environment_gcloud.yaml 与 configs/environments/docker.yaml。
任务清单仓库内置多档：冒烟用的 selected_tasks/hello_both.txt（Linux + Windows 各一个 hello），完整公开集 selected_tasks/unlicensed.txt。
所有相对路径都相对于主 YAML 所在目录解析；配置里可用${env:VAR}引用环境变量（变量未设置会直接报错，见 ale_run/orchestration/config_loader.py）。

3️⃣ 并发与超时：concurrency 和 wall_time_s 怎么设

concurrency（默认 1）：同时"在飞"的 unit 数。每个 unit 从获取沙箱、跑 Agent 到评测结束都独占一个槽位，所以它实际上就是同时存活的沙箱数上限。官方建议按min(云厂商配额, LLM 限频 ÷ agent 数)来取值；使用 static provider（共用一台机器）时必须保持 1（见 ale_run/orchestration/experiment_spec.py）。

wall_time_s：实验级的墙上时钟预算（秒），会覆盖每个任务卡片自带的vm.timeout。比如设18000就是统一 5 小时预算；超时的 unit 会被标记为status=timeout并被停止。不设置时按各任务卡片自己的值（或框架默认）。

典型批量配置（摘自 docs/quickstart.md）：

tasks: selected_tasks/unlicensed.txt concurrency: 8 auto_resume: true max_attempts: 3 cleanup_mode: delete

4️⃣ 断点续跑：auto_resume 与 max_attempts 详解

这是长批次最关键的一对参数：

auto_resume（默认true）：启动时扫描输出根目录下历史run.json（布局为<output.root>/<agent>/<model>/<task>/v<i>/<时间戳>/），跳过状态为completed或timeout的 unit，并对新失败的 unit 自动重新入队（实现见 ale_run/cli.py）；
max_attempts（默认 3，范围 1..3）：单个失败 unit 在本次调用中的总尝试次数上限（含首次运行）。每次尝试都会保留独立的时间戳运行目录，互不覆盖；
想一次性干净重跑（不扫描历史、不重试）：命令行加--disable-resume，或在 YAML 里持久写auto_resume: false。

# 一次性重跑所有 unit，不续跑、不重试 uv run python -m ale_run run my_experiment.yaml --disable-resume

💡 大批次跑挂了、机器重启了？不用管——直接重新执行同一条run命令，auto_resume会自动跳过已完成的 unit，只补跑失败的。

5️⃣ 另外两个参数：cleanup_mode 与 prompt_suffix

cleanup_mode（默认delete）：unit 结束后沙箱的处置方式——delete销毁（省配额）、stop停止但保留磁盘以便事后检查产物、keep保持运行（调试用）；
prompt_suffix（默认空）：以独立段落形式追加到每个任务提示词末尾（会一并记录进 trajectory）。适合统一声明"全程自主、不可交互、无法完成时写 infeasible.md"之类的要求，多行文本用 YAML 的|块标量即可。

6️⃣ 别搞混：output_path 在环境YAML里

output.root（实验 YAML）只控制宿主机运行记录目录；而沙箱内产物的去向由环境 YAML的output_path决定，三态取值：

取值	行为	适用场景
`null`	不回收产物，只留评分	只要分数、省空间
`local`	直接拉到运行目录`output/`	本地开发、小规模
`gs://`/`s3://`/`oss://`	从沙箱直传云存储桶	大规模批次的集中存储

同理，任务数据来源task_data_source（如baked_in_sandbox、local:<dir>）也写在环境 YAML 里（见 configs/environments/docker.yaml）。

7️⃣ 标准启动流程：先 dry-run，再过滤，最后全量

# 1. 安装依赖 uv sync --all-packages # 2. 干跑：解析并打印整个 agent × task × variant 矩阵，不创建任何沙箱 uv run python -m ale_run run example_exp.yaml --dry-run # 3. 只跑矩阵中的一部分（调试常用） uv run python -m ale_run run my_experiment.yaml \ --agent claude_code \ --task demo/hello # 4. 确认无误后正式运行 uv run python -m ale_run run my_experiment.yaml

干跑会输出实验名、环境路由、输出根目录、并发数及全部 unit 清单，是开跑前验证配置正确性的最快方法。更完整的运行与产物收集说明见 docs/ale-docs-site/pages/run.html。