agentcompass launch

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

agentcompass launch <orchestration.yaml> [OPTIONS]

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

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

​

定义编排

以下编排定义两个评测请求，它们共享一个包含 16 个 Benchmark 任务槽位的全局资源池。公共 model 设置只需在 defaults 中定义一次：

# terminal-evaluations.yaml

# 所有请求合计最多同时运行的 Benchmark 任务数。
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: tb21
    benchmark:
      id: terminal_bench_2_1
    harness:
      id: terminus2
      max_turns: 300
    environment:
      id: daytona

  - name: tb2vrf
    benchmark:
      id: terminal_bench_2_verified
    harness:
      id: terminus2
      max_turns: 300
    environment:
      id: docker

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

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

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

​

字段说明

字段	含义
task_concurrency	所有请求共享的全局 Benchmark 任务并发上限，不会分别应用到每个请求。
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	真实注册的 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	部分执行映射	控制请求的分析、重试、Recipe 和 Environment 保留；全局任务并发数仍由编排管理。
请求级 runtime	reuse 和 reuse_run_id	选择该请求是否可以复用历史运行。
output	run_name 和 run_id	组织新请求的结果目录。

可选 version 默认为最新受支持的编排格式。请求名称不能为空且必须唯一。

​

运行前验证

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

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>	设置所有请求共享的 Benchmark 任务并发上限。
--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。
--dry-run	只解析、验证、脱敏并输出，不执行评测。

​

调度与失败隔离

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

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

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

这是允许重叠的有序准入，而不是请求之间的严格屏障。请求顺序控制哪些待启动任务优先获得容量，task_concurrency 控制整个编排中同时运行的 Benchmark 任务总数。

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

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

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

​

复用已有运行

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

agentcompass launch terminal-evaluations.yaml --reuse

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

多个请求可以有意使用相同 Benchmark 和 model。AgentCompass 会发出警告，因为它们的结果层级发生重叠。对于这些请求，隐式复用“最新匹配运行”存在歧义，因此会被拒绝；请为每个重复的 Benchmark/model 请求指定明确的 runtime.reuse_run_id。显式输出目录冲突也会在任务执行前被拒绝。

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

​

相关页面

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