> ## 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 run

`agentcompass run` 使用所选 Benchmark、Harness、Model 和 Environment 创建并执行一个评测请求。`BENCHMARK HARNESS MODEL` 是顺序固定的位置参数，Environment 通过 `--env` 选择。

```bash theme={"system"}
agentcompass run [OPTIONS] BENCHMARK HARNESS MODEL
```

## 运行最小评测

下面通过 `--benchmark-params` 中的 [`sample_ids`](/zh/user_guide/modules/benchmarks/overview#共享-benchmark-字段)，按稳定任务 ID 选择一个 Benchmark 任务，用于快速验证组件和端点配置：

```bash theme={"system"}
export MODEL_NAME=""
export MODEL_BASE_URL=""
export MODEL_API_KEY=""

agentcompass run \
  swebench_verified \
  mini_swe_agent \
  "$MODEL_NAME" \
  --env docker \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
```

一条 `run` 命令对应一个评测请求。需要协调多个显式评测请求时，请使用 [`agentcompass launch`](/zh/user_guide/using_agentcompass/cli/launch)。

## 参数参考

通过本节查找参数和默认值。示例与使用建议见[运行控制](/zh/user_guide/using_agentcompass/run_controls)、[超时设置](/zh/user_guide/using_agentcompass/timeouts)和[保存与准备产物](/zh/user_guide/using_agentcompass/artifacts)。“内置默认值”指配置文件覆盖前使用的值。“按需”参数仅在所选组件或端点需要时必填。

### 组件选择与参数

| 参数 | 是否必需 | 内置默认值 | 控制内容 |
| - | - | - | - |
| [`BENCHMARK`](/zh/user_guide/modules/benchmarks/overview#查找-benchmark) | 必需 | 无 | 已注册的 Benchmark ID，决定数据集加载、任务准备、验证和指标。 |
| [`HARNESS`](/zh/user_guide/modules/harnesses/overview#查找-harness) | 必需 | 无 | 已注册的 Harness ID，决定每个任务使用的 agent 循环或框架。 |
| [`MODEL`](/zh/user_guide/modules/models/overview#配置-modelspec) | 必需 | 无 | 主 model ID，也是结果路径中的 model 名。在命令行中建议使用 `"$MODEL_NAME"`。 |
| [`--benchmark-params <json>`](/zh/user_guide/modules/benchmarks/overview#配置-benchmark-参数) | 按需 | 所选 Benchmark 的默认值 | 覆盖所选 Benchmark 配置中定义的通用字段和专属字段。 |
| [`--harness-params <json>`](/zh/user_guide/modules/harnesses/overview#配置-harness-参数) | 按需 | 所选 Harness 的默认值 | 覆盖所选 Harness 定义的完整参数结构。 |
| [`--model-base-url <url>`](/zh/user_guide/modules/models/overview#配置-modelspec) | 按需 | `""` | 接收推理请求的 Model API 基础地址。 |
| [`--model-api-key <key>`](/zh/user_guide/modules/models/overview#配置-modelspec) | 按需 | `""` | 访问 Model API 时使用的鉴权凭证。 |
| [`--model-api-protocol <protocol>`](/zh/user_guide/modules/models/overview#model-api-协议列表) | 可选 | 未指定 | 设置 Model API 协议；具体取值和选择规则见链接页面。 |
| [`--model-params <json>`](/zh/user_guide/modules/models/overview#配置-params-字段) | 可选 | `{}` | 传递所选 Harness、API 协议、端点和 model 部署支持的字段。 |
| [`--env <id>`](/zh/user_guide/modules/environments/overview#选择-environment-provider) | 可选 | `host_process` | 选择任务命令的执行位置，常用选项包括 `docker`、`daytona` 和 `modal`。 |
| [`--env-params <json>`](/zh/user_guide/modules/environments/configuration/overview) | 按需 | 所选 Environment 和 Recipe 的默认值 | 覆盖 Environment 公共 schema 中的 setup、资源、网络策略和任务环境变量。 |

### 配置与 Recipe

| 参数 | 是否必需 | 内置默认值 | 控制内容 |
| - | - | - | - |
| [`--config <path>`](/zh/user_guide/using_agentcompass/cli/config) | 可选 | 无 | 加载额外的 YAML 或 JSON 覆盖文件。可重复指定，并按命令顺序分层覆盖。 |
| [`--recipe <id>`](/zh/user_guide/other_features/recipes#recipe-如何工作) | 可选 | 所有兼容的内置 Recipe | 将自动 Recipe 匹配限制到指定 ID；可重复指定多个。 |
| [`--recipe-dir <path>`](/zh/user_guide/other_features/recipes#可信外部-recipe) | 可选 | `[]` | 加载可信的外部 Recipe 软件包目录；可重复指定多个目录。 |

### 执行控制

| 参数 | 是否必需 | 内置默认值 | 控制内容 |
| - | - | - | - |
| [`--execution-params <json>`](/zh/user_guide/using_agentcompass/timeouts#设置执行与评测预算) | 可选 | YAML execution 默认值 | 覆盖公共执行设置，例如单任务超时与产物保存；专用 CLI 选项优先。 |
| [`--task-concurrency <int>`](/zh/user_guide/using_agentcompass/run_controls#安全扩展并发) | 可选 | `32` | 限制实际并发执行的 attempt 数，包括 retry。 |
| [`--max-retries <int>`](/zh/user_guide/using_agentcompass/run_controls#只重试瞬时失败) | 可选 | `0` | 在当前逻辑 attempt 内，对匹配的任务或评分失败最多 retry 指定次数。 |
| [`--retry-pattern-list <json>`](/zh/user_guide/using_agentcompass/run_controls#只重试瞬时失败) | 可选 | `null` | 匹配 ERROR 的 message/code；null 或 \[] 只重试 FATAL，WARNING 不触发重试。 |
| [`--keep-environment`](/zh/user_guide/using_agentcompass/run_controls#保留-environment-以便调试) | 可选 | 关闭 | 跳过 Environment 清理，以保留任务和验证器 sandbox 供调试。 |

### 设置多次尝试

| 参数 | 是否必需 | 内置默认值 | 控制内容 |
| - | - | - | - |
| `--k <int>` | 可选 | `1` | 设置每个任务最多执行多少次独立 attempt。 |
| `--attempt-strategy <strategy>` | 可选 | `avg` | 选择多次尝试的执行与汇总策略。 |

例如，下面的参数会为每个任务计划 3 次独立 attempt，并采用 `avg` 策略汇总：

```bash theme={"system"}
agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --k 3 \
  --attempt-strategy avg
```

未指定这两个参数时使用 `k=1` 和 `avg`：每个任务只执行一次，指标按 `native@1` 输出。`k>1` 时，各 attempt 是独立的执行单元，并共同受 `--task-concurrency` 限制；两种策略的差异如下：

| `strategy` | 适用的 Benchmark 主指标 | 执行与结果 |
| - | - | - |
| `avg` | 标量 `score` 或二元 `correct` | 计划执行全部 `k` 次 attempt 并计算 `avg@k`；二元指标还会同时产生 `pass@k`。 |
| `pass` | 仅二元 `correct` | 首次成功后提前停止，否则最多执行 `k` 次；只产生主指标的 `pass@k`。 |

需要注意：

* 标量主指标使用 `pass` 会在任务开始前报错。
* `k` 表示逻辑 attempt 数量，不包含 attempt 内部由 `--max-retries` 产生的 retry。
* `avg@k`、`pass@k` 的精确定义以及缺失 attempt 的处理见[指标与聚合](/zh/user_guide/other_features/results/metrics_aggregation)。

使用 `launch` 时，每个请求可以单独设置 `k` 和策略，详见[为每个请求设置 k 和策略](/zh/user_guide/using_agentcompass/cli/launch#为每个请求设置-k-和策略)。

### 输出与复用

| 参数 | 是否必需 | 内置默认值 | 控制内容 |
| - | - | - | - |
| [`--run-name <name>`](/zh/user_guide/using_agentcompass/run_controls#命名新运行) | 可选 | `""` | 在 `results_dir` 和 Model/Benchmark/Harness 组合目录之间添加可选命名空间。 |
| [`--run-id <id>`](/zh/user_guide/using_agentcompass/run_controls#命名新运行) | 可选 | 当前时间戳 | 设置最终运行目录名，不再生成 `YYYYMMDD_HHMMSS`。 |
| [`--reuse [run-id]`](/zh/user_guide/using_agentcompass/run_controls#继续中断的运行) | 可选 | 关闭 | 从同一 Model/Benchmark/Harness 输出命名空间的最新运行或指定运行 ID 中，复用兼容且不含错误的完整详情，或尚无完整详情的中断任务的 checkpoint。 |
| `--no-checkpoint-resume` | 开关 | 关闭 | 不使用 agent 运行后的 checkpoint 继续待执行的 fresh 评测。完整结果与终态 attempt 调度记录仍按原规则复用。 |

### 进程级设置

| 参数 | 是否必需 | 内置默认值 | 控制内容 |
| - | - | - | - |
| [`--results-dir <path>`](/zh/user_guide/using_agentcompass/run_controls#命名新运行) | 可选 | `results` | 设置运行输出的根目录。 |
| [`--data-dir <path>`](/zh/user_guide/other_features/results/overview#数据缓存与输出目录) | 可选 | `data` | 设置下载数据集、缓存和已准备 Benchmark 数据的根目录。 |
| [`--timeout-seconds <int>`](/zh/user_guide/using_agentcompass/timeouts) | 可选 | `360000` | 限制组件预检完成后的整次评测时长，单位为秒；显式设置为 `0` 可取消总时限。单任务和组件超时仍独立生效。 |
| [`--env-open-qps <provider=qps>`](/zh/user_guide/using_agentcompass/run_controls#安全扩展并发) | 可选 | 本地：`0`；远程：`10` | 限制每个 provider 创建 Environment 的速率。可为多个 provider 重复指定；`0` 表示不限制。 |
| [`--provider-limit <provider=count>`](/zh/user_guide/using_agentcompass/run_controls#安全扩展并发) | 可选 | 每个内置 provider 为 `128` | 设置进程级 provider 实际 attempt 执行上限，包括 retry。可按 provider 重复指定；`0` 表示禁用限制。 |
| [`--progress <mode>`](/zh/user_guide/using_agentcompass/run_controls#日志与进度) | 可选 | `auto` | 选择终端进度输出：`auto`、`plain` 或 `none`。 |
| [`--log-level <level>`](/zh/user_guide/using_agentcompass/run_controls#日志与进度) | 可选 | `INFO` | 设置控制台日志级别：`DEBUG`、`INFO`、`WARNING`、`ERROR` 或 `CRITICAL`。 |
| [`--file-log-level <level>`](/zh/user_guide/using_agentcompass/run_controls#日志与进度) | 可选 | `DEBUG` | 独立设置运行日志文件的级别。 |
| [`--auto-install-dependencies`](/zh/user_guide/using_agentcompass/dependencies#自动安装) | 可选 | 关闭 | 允许 AgentCompass 在当前 Python 环境中安装缺失的可信组件可选依赖。 |

### 分析

| 参数 | 是否必需 | 内置默认值 | 控制内容 |
| - | - | - | - |
| [`--enable-analysis`](/zh/user_guide/using_agentcompass/cli/analysis#随评测运行) | 可选 | 开启 | 启用已注册的评测后分析器；使用 `--no-enable-analysis` 跳过。 |
| [`--analysis-params <json>`](/zh/user_guide/using_agentcompass/cli/analysis#随评测运行) | 可选 | 内置分析器默认值 | 选择分析器，并覆盖其并发、model、渲染或专属设置。 |

### 组件专属 JSON 参数

四个 JSON 参数并不共享同一个结构。可用字段和默认值取决于所选组件：

| 参数 | 归属 | 字段查询位置 |
| - | - | - |
| `--model-params` | Harness、API 协议和端点 | [model 参数结构](/zh/user_guide/modules/models/overview#配置-params-字段) 和端点 provider 的请求结构 |
| `--benchmark-params` | 所选 Benchmark | [Benchmark 参数结构](/zh/user_guide/modules/benchmarks/overview#配置-benchmark-参数) 和 `agentcompass config docs benchmark <id>` |
| `--harness-params` | 所选 Harness | [Harness 参数结构](/zh/user_guide/modules/harnesses/overview#配置-harness-参数) 和 `agentcompass config docs harness <id>` |
| `--env-params` | 所选 Environment | [Environment 参数结构](/zh/user_guide/modules/environments/configuration/overview) 和 `agentcompass config docs env <id>` |

[`sample_ids`](/zh/user_guide/modules/benchmarks/overview#共享-benchmark-字段) 属于 `--benchmark-params`；多次尝试使用上述执行参数。provider 的 CPU、内存、镜像和网络设置属于 `--env-params`。评测各部分的概念分工见[配置评测](/zh/user_guide/using_agentcompass/overview#选择四个组件)。


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