agentcompass launch

使用 YAML 或 JSON 编排文件，通过一个全局调度器协调多个显式评测请求。

agentcompass launch <orchestration.yaml> [OPTIONS]

编排中的每个请求仍然选择一个 Benchmark、Harness、Model 和 Environment，结构与 agentcompass run 创建的评测请求一致。只有一个请求时使用 run；需要比较多个 Model、评测多个 Benchmark 或混合不同 Harness、Environment 时使用 launch。

AgentCompass 不会自动推导组合矩阵。每个请求都需要显式命名和声明，从而保证参数、结果、失败和复用来源可审计。

​

定义编排

以下编排定义两个评测请求，它们共享一个包含 16 个实际 attempt 执行槽位的全局资源池。公共 model 设置只需在 defaults 中定义一次，两个请求则分别设置自己的 k 和汇总策略：

# terminal-evaluations.yaml

# 所有请求合计最多同时执行的实际 attempt 数，包括 retry。
task_concurrency: 16

# 每个请求继承的值；请求可以覆盖其中的字段。
defaults:
  model:
    id: ${MODEL_NAME}
    base_url: ${MODEL_BASE_URL}
    api_key: ${MODEL_API_KEY}
    api_protocol: openai-chat
    params:
      temperature: 1
      top_p: 0.95

requests:
  # 用户定义的请求名称，用于结果目录、编排进度和结果展示。
  - name: tb2vrf
    benchmark:
      id: terminal_bench_2_verified
    harness:
      id: terminus2
      max_turns: 300
    environment:
      id: docker
    execution:
      attempts:
        k: 3
        strategy: avg

  - name: tb21
    benchmark:
      id: terminal_bench_2_1
    harness:
      id: terminus2
      max_turns: 300
    environment:
      id: daytona
    execution:
      attempts:
        k: 5
        strategy: pass

解析文件前，导出其中引用的全部环境变量：

export MODEL_NAME=""
export MODEL_BASE_URL=""
export MODEL_API_KEY=""

环境变量引用必须占据整个字段，例如 ${MODEL_API_KEY}。AgentCompass 会拒绝局部字符串插值，防止未解析或意外拼接的密钥静默进入请求。

​

字段说明

字段	含义
task_concurrency	所有请求共享的实际 attempt 执行并发上限，retry 也使用同一并发池；不会分别应用到每个请求。
defaults	所有请求继承的值；每个请求只需覆盖不同字段。
defaults.model.id	实际发送给端点并记录在结果元数据中的 model ID。
base_url / api_key / api_protocol	公共 model 端点的连接设置。环境变量引用可以避免把凭据写入 YAML。
model.params	通过所选 Harness/协议转发的 model 推理参数，例如 temperature 和 top_p。
requests	需要调度的评测请求；声明顺序决定调度优先级。
requests[].name	唯一的用户自定义请求名称，用于结果目录、进度和请求级结果展示；Benchmark 由 benchmark.id 选择。
requests[].execution.attempts.k	当前请求中每个任务的 attempt 数量，必须是正整数，默认为 1。
requests[].execution.attempts.strategy	当前请求的汇总策略，可选 avg 或 pass，默认为 avg；标量主指标只支持 avg。
benchmark.id	真实注册的 Benchmark ID，例如 terminal_bench_2_1。
harness.id	真实注册的 Harness ID，例如 terminus2。
harness.max_turns	Harness 专属参数。组件字段与 id 同级，不需要 params 包装层。
environment.id	真实注册的 Environment provider ID，例如 daytona 或 docker。

因此，即使 Benchmark 或 Environment 配置改变，请求的 name 仍可以保持稳定。使用agentcompass list benchmark、agentcompass list harness 和 agentcompass list env 查看合法组件 ID。

​

映射规则

部分	结构	含义
model	id、端点字段和可选 params	生成和 provider 请求选项放在 model.params 下。
benchmark、harness、environment	id 与组件字段位于同一层	id 选择组件，其余字段都成为组件参数；不要添加 params 包装层。
execution	部分执行映射	控制请求的多次 attempt、分析、重试、Recipe 和 Environment 保留；全局任务并发数仍由编排管理。
请求级 runtime	reuse、reuse_run_id 和 checkpoint_resume	选择历史运行，并控制是否从 agent 运行后的 checkpoint 继续待执行的 fresh 评测。
output	run_name 和 run_id	组织新请求的结果目录。

可选 version 默认为最新受支持的编排格式。请求名称不能为空且必须唯一。AgentCompass 会把名称规范化为单个安全目录名；如果不同名称解析到同一输出命名空间，即使运行 ID 不同也会被拒绝。

每个请求的结果目录为：

<results_dir>/[<output.run_name>/]<requests[].name>/<run_id>/

以上述编排为例，使用 --run-id baseline 时，会在默认结果根目录下创建：

results/tb2vrf/baseline/
results/tb21/baseline/

output.run_name 添加可选的分组前缀。不同请求名称会隔离输出，包括使用相同 Model 和 Benchmark、不同 Harness 的请求。显式运行 ID 在各自请求命名空间中必须尚未使用。

​

为每个请求设置 k 和策略

launch 不使用统一的 --k 或 --attempt-strategy 覆盖所有 Benchmark。如上例所示，将 attempts 写在 requests[].execution 下，即可为每个请求独立选择 k 和 strategy；完整取值与执行行为见 agentcompass run 的“设置多次尝试”。

每个请求都会从公共配置和 defaults.execution 重新开始解析，再用自己的 execution 覆盖继承字段。请求之间不会继承或覆盖对方的 execution；即使后一个请求在前一个运行期间启动，也不会改变前一个已解析的 k 和 strategy。它们只共享顶层 task_concurrency 定义的执行槽位。

如果所有请求都使用相同设置，可以将 attempts 放在 defaults.execution 中，仍然允许单个请求覆盖。对同时包含标量和二元主指标的编排，建议在每个请求中明确写出 strategy，避免标量 Benchmark 继承不适用的 pass。指标类型、策略限制与结果含义见指标与聚合。

​

运行前验证

启动评测前，先解析完整编排：

agentcompass launch terminal-evaluations.yaml --dry-run

--dry-run 会加载配置层、展开环境变量引用、解析组件默认值、验证每个请求并输出脱敏后的编排；它不会加载 Benchmark 任务或创建结果目录。请检查输出中的组件 ID、任务筛选条件、Environment、Model API 端点地址、并发和复用设置。

确认后启动同一编排：

agentcompass launch terminal-evaluations.yaml

如需临时调整，可以通过 CLI 参数覆盖编排文件中的共享运行控制：

agentcompass launch terminal-evaluations.yaml \
  --task-concurrency 8 \
  --provider-limit docker=8 \
  --progress plain

完整参数见 agentcompass launch --help。常用的编排级参数如下：

参数	作用
--task-concurrency <n>	设置所有请求共享的实际 attempt 执行并发上限，包括 retry。
--timeout-seconds <n>	设置整个编排的挂钟时间上限；默认 360000 秒（100 小时）。如需取消该上限，请显式设置为 0。
--provider-limit <provider>=<n>	限制一个 provider 上同时运行的尝试数量；可为多个 provider 重复传入。
--env-open-qps <provider>=<qps>	限制 Environment 启动速率；可为多个 provider 重复传入。
--progress auto|plain|none	选择多请求终端渲染器。
--auto-install-dependencies	允许在 host 上自动安装缺失的可信可选依赖，默认关闭。
--reuse	默认允许每个请求复用其输出命名空间中的最新运行。
--run-id <id>	为每个新请求输出设置同一个显式运行 ID；不同请求命名空间可以使用相同 ID。
--dry-run	只解析、验证、脱敏并输出，不执行评测。

​

调度与失败隔离

所有请求共享一个执行工作池。声明顺序决定准入优先级：较早请求的任务优先进入执行；当早期请求的待启动任务已全部准入后，后续请求会使用空闲槽位。这个顺序是确定的，但不会强制前一项完整评测结束后才启动下一项。

在定义编排中的 task_concurrency: 16 示例中：

1. AgentCompass 首先使用 tb21 的任务填满可用槽位。
2. 随着 tb21 的任务完成，它尚未启动的任务继续优先获得槽位。
3. 当 tb21 的全部任务都已准入后，空闲槽位会立即启动 tb2vrf 的任务，即使最后几个 tb21 任务仍在运行。
4. 如果 tb21 少于 16 个任务，未使用的槽位会立即开始 tb2vrf 的任务。

这是允许重叠的有序准入，而不是请求之间的严格屏障。请求顺序控制哪些待启动任务优先获得容量，task_concurrency 控制整个编排中同时执行的实际 attempt 总数，包括 retry 和同一任务的多次 attempt。

每个请求都有独立的运行目录、进度文件、日志、摘要和终端结果。请求级失败会记录为 failed，但不会阻止后续请求运行。所有请求完成时编排返回 completed；只有部分请求失败时返回 partial_failure；共享操作被停止时则返回超时或取消状态。

三种进度模式的终端行为及其与进度文件的关系，见日志与进度。

提高全局并发前，请先参考运行控制中的容量建议。

​

复用已有运行

--reuse 会为编排中的每个请求默认启用最新运行复用：

agentcompass launch terminal-evaluations.yaml --reuse

单个请求可以设置 runtime.reuse: false 退出复用。若要选择精确来源，在该请求或 defaults 中设置 runtime.reuse_run_id；output.run_id 命名新结果，不是复用来源。

复用只会在当前请求的结果命名空间中查找，包括可选的 output.run_name 前缀。规范化后名称不同的请求可以独立复用各自的最新运行，即使 Model 和 Benchmark 相同。选中的来源仍需使用相同的 Benchmark ID 和 attempt 计划，但允许修改评测设置；修改请求名称会改变复用的查找位置。

已有结果目录保留原位。自动复用只搜索新的请求目录层级，不会发现旧 Benchmark/Model 层级中的运行。规范化后的请求命名空间冲突，以及显式输出目录已存在，都会在任务执行前被拒绝。

复用结果的匹配方式和使用限制见继续中断的运行。

​

相关页面

• 运行控制
• agentcompass run
• Python SDK
• 结果