agentcompass run

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

agentcompass run [OPTIONS] BENCHMARK HARNESS MODEL

运行最小评测

下面通过 --benchmark-params 中的 sample_ids，按稳定任务 ID 选择一个 Benchmark 任务，用于快速验证组件和端点配置：

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。

参数参考

本节说明 agentcompass run 的参数用法，并列出完整签名、默认值和作用对象；并发、超时、重试、输出与调试参数的使用建议见运行控制。“内置默认值”指用户级、项目级或显式配置文件覆盖前使用的值。“按需”参数仅在所选组件或端点需要时必填。

组件选择与参数

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

配置与 Recipe

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

执行控制

参数	是否必需	内置默认值	控制内容
`--execution-params <json>`	可选	YAML execution 默认值	深度合并公共执行字段，包括收尾宽限、产物准备超时与产物限制；专用 CLI 选项优先。
`--task-concurrency <int>`	可选	`32`	限制实际并发执行的 attempt 数，包括 retry。
`--max-retries <int>`	可选	`0`	在当前逻辑 attempt 内，对匹配的任务或评分失败最多 retry 指定次数。
`--retry-pattern-list <json>`	可选	`null`	匹配 ERROR 的 message/code；null 或 [] 只重试 FATAL，WARNING 不触发重试。
`--keep-environment`	可选	关闭	跳过 Environment 清理，以保留任务和验证器 sandbox 供调试。

设置多次尝试

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

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

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 的处理见指标与聚合。

使用 launch 时，每个请求可以单独设置 k 和策略，详见为每个请求设置 k 和策略。

输出与复用

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

进程级设置

参数	是否必需	内置默认值	控制内容
`--results-dir <path>`	可选	`results`	设置运行输出的根目录。
`--data-dir <path>`	可选	`data`	设置下载数据集、缓存和已准备 Benchmark 数据的根目录。
`--timeout-seconds <int>`	可选	`360000`	设置组件预检完成后评测执行阶段的整体超时时间（秒）；显式设置为 `0` 可取消这一整体时限。组件专属的命令和验证器超时仍独立生效。
`--env-open-qps <provider=qps>`	可选	本地：`0`；远程：`10`	限制每个 provider 创建 Environment 的速率。可为多个 provider 重复指定；`0` 表示不限制。
`--provider-limit <provider=count>`	可选	每个内置 provider 为 `128`	设置进程级 provider 实际 attempt 执行上限，包括 retry。可按 provider 重复指定；`0` 表示禁用限制。
`--progress <mode>`	可选	`auto`	选择终端进度输出：`auto`、`plain` 或 `none`。
`--log-level <level>`	可选	`INFO`	设置控制台日志级别：`DEBUG`、`INFO`、`WARNING`、`ERROR` 或 `CRITICAL`。
`--file-log-level <level>`	可选	`DEBUG`	独立设置运行日志文件的级别。
`--auto-install-dependencies`	可选	关闭	允许 AgentCompass 在当前 Python 环境中安装缺失的可信组件可选依赖。

分析

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

组件专属 JSON 参数

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

参数	归属	字段查询位置
`--model-params`	Harness、API 协议和端点	model 参数结构和端点 provider 的请求结构
`--benchmark-params`	所选 Benchmark	Benchmark 参数结构和 `agentcompass config docs benchmark <id>`
`--harness-params`	所选 Harness	Harness 参数结构和 `agentcompass config docs harness <id>`
`--env-params`	所选 Environment	Environment 参数结构和 `agentcompass config docs env <id>`

sample_ids 属于 --benchmark-params；多次尝试使用上述执行参数。provider 的 CPU、内存、镜像和网络设置属于 --env-params。评测各部分的概念分工见配置评测。

使用 AgentCompass

模块

其他功能

运行最小评测

参数参考

组件选择与参数

配置与 Recipe

执行控制

设置多次尝试

输出与复用

进程级设置

分析

组件专属 JSON 参数

​运行最小评测

​参数参考

​组件选择与参数

​配置与 Recipe

​执行控制

​设置多次尝试

​输出与复用

​进程级设置

​分析

​组件专属 JSON 参数

运行最小评测

参数参考

组件选择与参数

配置与 Recipe

执行控制

设置多次尝试

输出与复用

进程级设置

分析

组件专属 JSON 参数