> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ResearchHarness

`researchharness` Harness 在准备好的 Environment 中运行 [ResearchHarness](https://github.com/InternScience/ResearchHarness) 研究 agent。它用于运行 [ResearchClawBench](/zh/user_guide/modules/benchmarks/researchclawbench)，也可运行 [SGI Deep Research](/zh/user_guide/modules/benchmarks/sgi_deep_research) 等长文本研究 Benchmark。

## 工作原理

* **准备 ResearchHarness。** Harness 根据 `install_strategy` 使用环境中已有的包，或执行 `install_command` 完成安装。已安装版本必须为 ResearchHarness 0.0.49 或更高版本。
* **运行研究循环。** AgentCompass 向任务环境注入运行器，传入准备好的提示词和工作区，并启动 ResearchHarness agent。`max_rounds` 限制 agent 轮数，`timeout` 限制单个任务的最大运行时长。
* **配置检索服务。** Serper 用于网页和学术搜索，Jina 用于读取网页内容，MinerU 用于解析 PDF。凭据可通过专用 Harness 参数或同名环境变量提供。
* **回收结果。** Harness 将 ResearchHarness 事件规整为标准轨迹、最终答案、执行状态和任务要求的输出文件，并返回 `RunResult`。

## 参数

通过 `--harness-params '{...}'` 传入 Harness 配置，也可写入 `--config` 的 `harness.params`；同名项以命令行为准。

### 参数总览

<div style={{overflowX:'auto'}}>
  <table style={{minWidth:'960px', width:'100%', tableLayout:'fixed', overflowWrap:'anywhere'}}>
    <thead>
      <tr><th style={{width:'20%', whiteSpace:'nowrap'}}>参数</th><th style={{width:'11%', whiteSpace:'nowrap'}}>类型</th><th style={{width:'24%', whiteSpace:'nowrap'}}>默认值</th><th style={{width:'19%'}}>可选值 / 取值</th><th style={{width:'26%'}}>说明</th></tr>
    </thead>

    <tbody>
      <tr><td style={{whiteSpace:'nowrap'}}><code>install\_strategy</code></td><td style={{whiteSpace:'nowrap'}}>字符串</td><td style={{whiteSpace:'nowrap'}}><code>install\_if\_missing</code></td><td><code>preinstalled</code> / <code>install\_if\_missing</code> / <code>install\_always</code></td><td>准备 ResearchHarness 包的方式。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>install\_command</code></td><td style={{whiteSpace:'nowrap'}}>字符串</td><td><code style={{whiteSpace:'normal', overflowWrap:'anywhere'}}>python3 -m pip install researchharness</code></td><td>命令</td><td>所选策略需要安装包时执行的命令。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>install\_timeout</code></td><td style={{whiteSpace:'nowrap'}}>整数 / 空值</td><td style={{whiteSpace:'nowrap'}}><code>900</code></td><td>整数 ≥ 1 / <code>null</code></td><td>安装命令的超时时间，单位为秒。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>timeout</code></td><td style={{whiteSpace:'nowrap'}}>整数</td><td style={{whiteSpace:'nowrap'}}><code>10800</code></td><td>整数 ≥ 1</td><td>单个任务的最大运行时长，单位为秒。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>max\_rounds</code></td><td style={{whiteSpace:'nowrap'}}>整数</td><td style={{whiteSpace:'nowrap'}}><code>500</code></td><td>整数 ≥ 1</td><td>单个任务的最大 agent 轮数。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>llm\_request\_timeout\_seconds</code></td><td style={{whiteSpace:'nowrap'}}>整数</td><td style={{whiteSpace:'nowrap'}}><code>1200</code></td><td>整数 ≥ 1</td><td>单次 model 请求的超时时间，单位为秒。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>webfetch\_tool\_timeout\_seconds</code></td><td style={{whiteSpace:'nowrap'}}>整数</td><td style={{whiteSpace:'nowrap'}}><code>300</code></td><td>整数 ≥ 1</td><td>单次 WebFetch 工具调用的超时时间，单位为秒。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>readpdf\_tool\_timeout\_seconds</code></td><td style={{whiteSpace:'nowrap'}}>整数</td><td style={{whiteSpace:'nowrap'}}><code>300</code></td><td>整数 ≥ 1</td><td>单次 ReadPDF 工具调用的超时时间，单位为秒。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>max\_output\_tokens</code></td><td style={{whiteSpace:'nowrap'}}>整数</td><td style={{whiteSpace:'nowrap'}}><code>16384</code></td><td>整数 ≥ 1</td><td>单次 model 请求的最大输出词元数。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>max\_input\_tokens</code></td><td style={{whiteSpace:'nowrap'}}>整数</td><td style={{whiteSpace:'nowrap'}}><code>131072</code></td><td>整数 ≥ 1</td><td>单次 model 请求的最大输入词元数。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>compact\_trigger\_tokens</code></td><td style={{whiteSpace:'nowrap'}}>字符串</td><td style={{whiteSpace:'nowrap'}}><code>96k</code></td><td>正整数或 <code>k</code> 后缀</td><td>触发上下文压缩的词元阈值。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>serper\_api\_key</code></td><td style={{whiteSpace:'nowrap'}}>字符串</td><td><code>{"${SERPER_API_KEY}"}</code></td><td>API 密钥或环境变量引用</td><td>网页与学术搜索使用的凭据。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>jina\_api\_key</code></td><td style={{whiteSpace:'nowrap'}}>字符串</td><td><code>{"${JINA_API_KEY}"}</code></td><td>API 密钥或环境变量引用</td><td>读取网页内容使用的凭据。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>mineru\_token</code></td><td style={{whiteSpace:'nowrap'}}>字符串</td><td><code>{"${MINERU_TOKEN}"}</code></td><td>令牌或环境变量引用</td><td>解析 PDF 文档使用的凭据。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>extra\_tools</code></td><td style={{whiteSpace:'nowrap'}}>列表</td><td style={{whiteSpace:'nowrap'}}><code>\[]</code></td><td>工具名列表</td><td>追加 ResearchHarness 工具，例如 <code>str\_replace\_editor</code>。</td></tr>
    </tbody>
  </table>
</div>

### 检索与解析 API 密钥

`serper_api_key`、`jina_api_key` 和 `mineru_token` 默认引用 `${SERPER_API_KEY}`、`${JINA_API_KEY}` 和 `${MINERU_TOKEN}`。可在启动 AgentCompass 的进程中设置这些环境变量，也可通过 `--harness-params` 显式传值。专用参数的优先级高于通用环境变量覆盖。

## 运行示例

<Tabs>
  <Tab title="默认配置">
    在终端中设置 `SERPER_API_KEY`、`JINA_API_KEY` 和 `MINERU_TOKEN`，然后使用 ResearchHarness 默认配置运行 ResearchClawBench。

    ```bash theme={"system"}
    agentcompass run \
      researchclawbench \
      researchharness \
      "$MODEL_NAME" \
      --env host_process \
      --benchmark-params '{
        "judge_model": {"id": "your-judge-model", "base_url": "https://your-judge-endpoint/v1", "api_key": "sk-…", "api_protocol": "openai-chat"}
      }' \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY"
    ```
  </Tab>

  <Tab title="自定义参数">
    显式设置研究过程上限，并通过 Harness 参数传入外部服务凭据。

    ```bash theme={"system"}
    agentcompass run \
      researchclawbench \
      researchharness \
      "$MODEL_NAME" \
      --env host_process \
      --benchmark-params '{
        "judge_model": {"id": "your-judge-model", "base_url": "https://your-judge-endpoint/v1", "api_key": "sk-…", "api_protocol": "openai-chat"}
      }' \
      --harness-params '{
        "max_rounds": 600,
        "timeout": 14400,
        "llm_request_timeout_seconds": 1800,
        "serper_api_key": "${SERPER_API_KEY}",
        "jina_api_key": "${JINA_API_KEY}",
        "mineru_token": "${MINERU_TOKEN}"
      }' \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY"
    ```
  </Tab>
</Tabs>

## 输出

ResearchHarness 为每个任务返回 `RunResult`，其中包含执行状态、最终答案、标准轨迹、任务要求的输出文件，以及原始 ResearchHarness 事件与日志。所选 Benchmark 会将聚合指标和单任务详情写入 `results/<benchmark>/<model>/<run>/`，详见[结果](/zh/user_guide/other_features/results)。