超时设置

为整次评测、每次 agent 执行或每次评分设置时间预算。通常先关注下面三个参数；本页的其他设置用于处理特定的收集或超时问题。

想限制什么	设置
一次 run 的全部任务，或一次 launch 的全部请求	--timeout-seconds
每次 attempt 的 agent 执行	run_timeout_seconds
每次 attempt 的 evaluation 执行	evaluation_timeout_seconds

后两个字段放在 execution 下，下面的示例展示各个入口的传入方式。

​

设置执行与评测预算

下面的示例给 agent 3,600 秒、评分 600 秒，并为整次评测设置 7,200 秒的总时限。任务、Model 环境变量和 Docker 配置与快速开始一致。

CLI

agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env docker \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --model-api-protocol openai-chat \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --task-concurrency 1 \
  --timeout-seconds 7200 \
  --execution-params '{
    "run_timeout_seconds": 3600,
    "evaluation_timeout_seconds": 600
  }'

YAML

将下面的配置保存为 timeouts.yaml，然后在运行命令中添加 --config timeouts.yaml，替换 CLI 示例中的两个超时选项。

runtime:
  timeout_seconds: 7200

execution:
  run_timeout_seconds: 3600
  evaluation_timeout_seconds: 600

配置文件保存可复用的设置；Model、Benchmark、Harness 和 Environment 仍由运行命令选择。完整结构见配置文件。

Python SDK

import os

from agentcompass import run_evaluation

result = run_evaluation(
    model=os.environ["MODEL_NAME"],
    benchmark="swebench_verified",
    harness="mini_swe_agent",
    environment="docker",
    model_base_url=os.environ["MODEL_BASE_URL"],
    model_api_key=os.environ["MODEL_API_KEY"],
    model_api_protocol="openai-chat",
    benchmark_params={"sample_ids": ["astropy__astropy-12907"]},
    task_concurrency=1,
    timeout_seconds=7200,
    execution_params={
        "run_timeout_seconds": 3600,
        "evaluation_timeout_seconds": 600,
    },
)

使用 launch 时，通过 --timeout-seconds 设置总时限；公共任务预算放在 defaults.execution 下，单个请求的覆盖值放在 requests[].execution 下。

总时限从组件预检完成后开始，覆盖任务加载、准备、执行、评分、分析和汇总。默认值为 360000 秒（100 小时），显式设置为 0 可取消总时限。到期后，未完成的工作会被取消，并开始资源清理；清理可能在总时限之后继续进行。

任务预算不会延长总时限。估算总时长时，要给调度、全部任务及重试、结果收集和评测留出时间。总时限可能在这些阶段中的任意一个阶段到期。

​

理解默认值

所有时间值的单位都是秒。execution 中的时间设置接受有限正数，0 不能用于禁用任务超时。

字段	默认值	什么时候调整
run_timeout_seconds	null：继承	为每个任务指定统一的 agent 执行预算。
evaluation_timeout_seconds	null：继承	调整每个任务的评分时间。

未填写字段或将其设为 null 时，依次继承 Benchmark 计划预算、task 预算；执行阶段还可回退到 Harness 默认值。所有来源都没有提供预算时，该阶段不设时限。设置 null 不会清除已继承的预算。

每次 attempt 和重试都会重新开始阶段计时。执行和评分独立计时；执行阶段未用完的时间不会累加到评分阶段。

如果任务已经有合适的相对预算，而你想统一延长它们，可以设置倍率。例如，下面的配置将 agent 执行预算加倍，评分预算保持原值：

execution:
  run_timeout_multiplier: 2

字段	默认值	作用
timeout_multiplier	1.0	调整执行和评测预算。
run_timeout_multiplier	null	替换执行阶段的公共倍率。
evaluation_timeout_multiplier	null	替换评测阶段的公共倍率。

最终预算为 基础秒数 × 有效倍率。阶段专属倍率替换公共倍率，两者不会相乘；显式设置的预算也会应用倍率。没有基础预算时，倍率不会产生时限。收集预算和执行补偿不受倍率影响。

​

查看各阶段的超时范围

下图展示包含 Harness 和独立评测 Environment 的一次 attempt。从左向右阅读，列宽不代表实际耗时。部分 Benchmark 会跳过产物传输，或在执行 Environment 中评分。

执行阶段包含 Harness 内部的 agent 准备、模型请求和工具循环。结果收集随后开始，使用独立预算。评测预算从评测 Environment 就绪且产物恢复完成后开始计时。

灰色列不受图中六项阶段设置直接约束。Environment 创建有单独的启动时限；关闭 Harness 和资源清理不计入 run_timeout_seconds。

​

单次请求与命令时限

run_timeout_seconds 和 evaluation_timeout_seconds 限制整个阶段；阶段中的模型请求、工具命令或评委请求还可能有自己的时限。延长阶段预算不会同步延长这些时限。单次操作超时后是否重试、继续执行或终止，由对应组件决定。

下面列出常见设置，链接指向对应组件的参数说明。字段及默认值由所选组件决定，并非所有 Harness 或 Benchmark 都支持这些字段。

参数	CLI JSON 选项	适用组件与作用
timeout	--model-params	mini-SWE-agent 和 OpenHands 的单次模型请求。
command_timeout	--harness-params	mini-SWE-agent 和 OpenHands 的单条工具命令。
llm_request_timeout_seconds	--harness-params	ResearchHarness 的单次模型请求。
judge_timeout_seconds	--benchmark-params	PinchBench 的单次评委请求，独立于整个 evaluation 阶段的预算。

例如，下面的 mini_swe_agent 命令将整个 agent 执行预算设为 3,600 秒，每次模型请求的时限为 120 秒，每条工具命令的时限为 300 秒：

agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env docker \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --model-api-protocol openai-chat \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-params '{"timeout":120}' \
  --harness-params '{"command_timeout":300}' \
  --execution-params '{"run_timeout_seconds":3600}'

SDK 使用对应的 model_params、harness_params 和 benchmark_params。使用 --config 时，Harness 和 Benchmark 字段直接写在 harnesses、benchmarks 下的对应组件 ID 中；Model 参数通过运行命令、编排请求或 SDK 提供。完整写法见配置文件结构。

查询所选 Harness 或 Benchmark 的完整字段和默认值：

agentcompass config docs harness <harness-id>
agentcompass config docs benchmark <benchmark-id>

​

进阶参数

没有对应操作的失败时，可以保留默认值。这些字段都放在 execution 下，通过 CLI 的 --execution-params、YAML 或 SDK 的 execution_params 设置。

字段	默认值	作用范围
run_timer_compensation_seconds	120	runtime 为 Harness 执行增加的宽限，用于内部准备和停止收尾。
runresult_collect_timeout_seconds	60	读取 Harness 输出，将答案、轨迹和诊断信息组装为 RunResult。
artifact_collect_timeout_seconds	null	顺序执行的整组产物准备命令的总时限；null 表示不设整组时限。
artifact_collect[].timeout_seconds	60	每条产物准备命令。
artifact_limits.timeout_seconds	600	每次整批产物下载或恢复。

补偿、结果收集、单条准备命令和传输预算必须是有限正数。准备与传输限制的使用示例见保存与准备产物。

​

给 Harness 留出超时收尾时间

部分 Harness 会在准备 agent 后才启动内部执行计时器。runtime 默认为 Harness 执行额外预留 120 秒，让内部准备和停止收尾有时间完成，避免立即打断内部超时处理。将最终执行预算记为 T 秒，Harness 获得 T 秒，runtime 的外层执行预算为 T + 120 秒。

如果 agent 准备异常缓慢，或日志显示 runtime 超时时 Harness 尚未完成停止收尾，可增大补偿值。例如：

execution:
  run_timeout_seconds: 5400
  run_timer_compensation_seconds: 300

在上述配置中，agent 预算仍为 5,400 秒，runtime 的外层时限为 5,700 秒；内部准备会消耗部分宽限时间。后续结果收集仍有独立的 60 秒预算，不包含在补偿中。

无 Harness 时，执行直接使用最终预算。执行原本无时限时，补偿不会产生新的时限。

​

延长结果收集时间

如果执行已结束，但收集答案、日志或轨迹超过 60 秒，可以增大结果收集预算：

execution:
  runresult_collect_timeout_seconds: 120

执行成功、失败或超时后，都会尝试收集结果。该预算不会延长 agent 执行、产物传输或整次评测的总时限。部分结果可以保留已有证据，但不会清除超时失败，也不保证能得到评分。

​

排查超时

先查看任务的 issues 和 run.log，确认哪一步超时，再调整对应参数。需要检查的文件见排查运行失败。

超时发生在哪里	检查什么
整次评测或编排	总时限 --timeout-seconds。
创建 Environment	Environment 的 setup.build_timeout_seconds 和 provider 配置。
agent 执行	run_timeout_seconds；Harness 尚在内部准备或停止收尾时，检查补偿值。
单条工具命令或单次模型请求	检查单次请求与命令时限，例如所选组件的 timeout 或 command_timeout。
收集答案或轨迹	runresult_collect_timeout_seconds。
准备、下载或恢复文件	产物准备与传输限制。
evaluation 执行	整个阶段检查 evaluation_timeout_seconds；单次评委请求检查 Benchmark 的请求时限，例如 PinchBench 的 judge_timeout_seconds。