> ## Documentation Index
> Fetch the complete documentation index at: https://opencompass-docs-preview-pr-335-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# agentcompass launch

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

```bash theme={"system"}
agentcompass launch <orchestration.yaml> [OPTIONS]
```

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

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

## 定义编排

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

```yaml theme={"system"}
# 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
```

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

```bash theme={"system"}
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`](/zh/user_guide/using_agentcompass/cli/run#设置多次尝试) | 当前请求中每个任务的 attempt 数量，必须是正整数，默认为 `1`。 |
| [`requests[].execution.attempts.strategy`](/zh/user_guide/using_agentcompass/cli/run#设置多次尝试) | 当前请求的汇总策略，可选 `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 不同也会被拒绝。

每个请求的结果目录为：

```text theme={"system"}
<results_dir>/[<output.run_name>/]<requests[].name>/<run_id>/
```

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

```text theme={"system"}
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` 的“设置多次尝试”](/zh/user_guide/using_agentcompass/cli/run#设置多次尝试)。

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

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

## 运行前验证

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

```bash theme={"system"}
agentcompass launch terminal-evaluations.yaml --dry-run
```

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

确认后启动同一编排：

```bash theme={"system"}
agentcompass launch terminal-evaluations.yaml
```

如需临时调整，可以通过 CLI 参数覆盖编排文件中的[共享运行控制](/zh/user_guide/using_agentcompass/run_controls)：

```bash theme={"system"}
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`；共享操作被停止时则返回超时或取消状态。

三种进度模式的终端行为及其与进度文件的关系，见[日志与进度](/zh/user_guide/using_agentcompass/run_controls#日志与进度)。

提高全局并发前，请先参考[运行控制](/zh/user_guide/using_agentcompass/run_controls#安全扩展并发)中的容量建议。

## 复用已有运行

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

```bash theme={"system"}
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 层级中的运行。规范化后的请求命名空间冲突，以及显式输出目录已存在，都会在任务执行前被拒绝。

复用结果的匹配方式和使用限制见[继续中断的运行](/zh/user_guide/using_agentcompass/run_controls#继续中断的运行)。

## 相关页面

* [运行控制](/zh/user_guide/using_agentcompass/run_controls)
* [`agentcompass run`](/zh/user_guide/using_agentcompass/cli/run)
* [Python SDK](/zh/user_guide/using_agentcompass/python_api#多评测请求)
* [结果](/zh/user_guide/other_features/results/overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.