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

The `researchharness` harness runs [ResearchHarness](https://github.com/InternScience/ResearchHarness) as a research agent inside a prepared environment. It runs [ResearchClawBench](/en/user_guide/modules/benchmarks/researchclawbench) and other long-form research benchmarks such as [SGI Deep Research](/en/user_guide/modules/benchmarks/sgi_deep_research).

## How it works

* **Prepare ResearchHarness.** According to `install_strategy`, the harness uses an existing package or runs `install_command`. The installed package must be ResearchHarness 0.0.49 or later.
* **Run the research loop.** AgentCompass injects a runner into the task environment, passes the prepared prompt and workspace, and launches the ResearchHarness agent. `max_rounds` limits agent rounds, while `timeout` limits the maximum runtime of one task.
* **Configure retrieval services.** Serper powers web and scholar search, Jina fetches web content, and MinerU parses PDF documents. Their credentials are supplied by dedicated harness parameters or same-named environment variables.
* **Collect results.** The harness converts ResearchHarness events into the standard trajectory, final answer, execution status, and requested output files in `RunResult`.

## Parameters

Pass harness configuration with `--harness-params '{...}'`, or place it under `harness.params` in the YAML supplied to `--config`; command-line values take precedence.

### Parameter reference

<div style={{overflowX:'auto'}}>
  <table style={{minWidth:'960px', width:'100%', tableLayout:'fixed', overflowWrap:'anywhere'}}>
    <thead>
      <tr><th style={{width:'20%', whiteSpace:'nowrap'}}>Parameter</th><th style={{width:'11%', whiteSpace:'nowrap'}}>Type</th><th style={{width:'24%', whiteSpace:'nowrap'}}>Default</th><th style={{width:'19%'}}>Choices / values</th><th style={{width:'26%'}}>Description</th></tr>
    </thead>

    <tbody>
      <tr><td style={{whiteSpace:'nowrap'}}><code>install\_strategy</code></td><td style={{whiteSpace:'nowrap'}}>string</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>How to prepare the ResearchHarness package.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>install\_command</code></td><td style={{whiteSpace:'nowrap'}}>string</td><td><code style={{whiteSpace:'normal', overflowWrap:'anywhere'}}>python3 -m pip install researchharness</code></td><td>shell command</td><td>Command used when the selected strategy installs the package.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>install\_timeout</code></td><td style={{whiteSpace:'nowrap'}}>int / null</td><td style={{whiteSpace:'nowrap'}}><code>900</code></td><td>integer ≥ 1 / <code>null</code></td><td>Install-command timeout in seconds.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>timeout</code></td><td style={{whiteSpace:'nowrap'}}>int</td><td style={{whiteSpace:'nowrap'}}><code>10800</code></td><td>integer ≥ 1</td><td>Maximum runtime of one task in seconds.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>max\_rounds</code></td><td style={{whiteSpace:'nowrap'}}>int</td><td style={{whiteSpace:'nowrap'}}><code>500</code></td><td>integer ≥ 1</td><td>Maximum agent rounds for one task.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>llm\_request\_timeout\_seconds</code></td><td style={{whiteSpace:'nowrap'}}>int</td><td style={{whiteSpace:'nowrap'}}><code>1200</code></td><td>integer ≥ 1</td><td>Timeout for one model request in seconds.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>webfetch\_tool\_timeout\_seconds</code></td><td style={{whiteSpace:'nowrap'}}>int</td><td style={{whiteSpace:'nowrap'}}><code>300</code></td><td>integer ≥ 1</td><td>Timeout for one WebFetch call in seconds.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>readpdf\_tool\_timeout\_seconds</code></td><td style={{whiteSpace:'nowrap'}}>int</td><td style={{whiteSpace:'nowrap'}}><code>300</code></td><td>integer ≥ 1</td><td>Timeout for one ReadPDF call in seconds.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>max\_output\_tokens</code></td><td style={{whiteSpace:'nowrap'}}>int</td><td style={{whiteSpace:'nowrap'}}><code>16384</code></td><td>integer ≥ 1</td><td>Maximum output tokens for one model request.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>max\_input\_tokens</code></td><td style={{whiteSpace:'nowrap'}}>int</td><td style={{whiteSpace:'nowrap'}}><code>131072</code></td><td>integer ≥ 1</td><td>Maximum input tokens for one model request.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>compact\_trigger\_tokens</code></td><td style={{whiteSpace:'nowrap'}}>string</td><td style={{whiteSpace:'nowrap'}}><code>96k</code></td><td>positive integer or <code>k</code> suffix</td><td>Token threshold that triggers context compaction.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>serper\_api\_key</code></td><td style={{whiteSpace:'nowrap'}}>string</td><td><code>{"${SERPER_API_KEY}"}</code></td><td>API key or environment reference</td><td>Credential used by web and scholar search.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>jina\_api\_key</code></td><td style={{whiteSpace:'nowrap'}}>string</td><td><code>{"${JINA_API_KEY}"}</code></td><td>API key or environment reference</td><td>Credential used to fetch web content.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>mineru\_token</code></td><td style={{whiteSpace:'nowrap'}}>string</td><td><code>{"${MINERU_TOKEN}"}</code></td><td>token or environment reference</td><td>Credential used to parse PDF documents.</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>extra\_tools</code></td><td style={{whiteSpace:'nowrap'}}>list</td><td style={{whiteSpace:'nowrap'}}><code>\[]</code></td><td>tool-name list</td><td>Additional ResearchHarness tools, for example <code>str\_replace\_editor</code>.</td></tr>
    </tbody>
  </table>
</div>

### Retrieval and parsing API keys

`serper_api_key`, `jina_api_key`, and `mineru_token` default to `${SERPER_API_KEY}`, `${JINA_API_KEY}`, and `${MINERU_TOKEN}`. Set those variables in the process that starts AgentCompass, or pass explicit values through `--harness-params`. Dedicated parameters take precedence over generic environment overrides.

## Run examples

<Tabs>
  <Tab title="Default configuration">
    Set `SERPER_API_KEY`, `JINA_API_KEY`, and `MINERU_TOKEN` in the shell, then run ResearchClawBench with the ResearchHarness defaults.

    ```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="Custom parameters">
    Set explicit research limits and pass the external-service credentials through harness parameters.

    ```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>

## Output

For each task, ResearchHarness returns a `RunResult` containing the execution status, final answer, normalized trajectory, requested output files, and raw ResearchHarness events and logs. The selected benchmark writes aggregate metrics and per-task details under `results/<benchmark>/<model>/<run>/`; see [Results](/en/user_guide/results).