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

# Dependencies

AgentCompass checks optional Python dependencies only when the active evaluation path needs them. The host is the machine running the current `agentcompass` process; the generic dependency manager inspects and modifies only the Python interpreter used by that process.

Packages inside a task [Environment](/en/user_guide/modules/environments/overview) are prepared by an image, snapshot, [Recipe](/en/user_guide/other_features/recipes), or harness. System prerequisites such as the Docker daemon, GPUs, and provider credentials are also outside Python dependency management.

<table style={{width:'100%', tableLayout:'fixed'}}>
  <thead>
    <tr><th style={{width:'26%'}}>Dependency or prerequisite</th><th style={{width:'46%', paddingLeft:'10px', paddingRight:'10px'}}>How it is prepared</th><th style={{width:'28%', paddingLeft:'10px', paddingRight:'10px'}}>Generic auto-install</th></tr>
  </thead>

  <tbody>
    <tr><td>Python packages in the AgentCompass interpreter</td><td style={{paddingLeft:'10px', paddingRight:'10px'}}>Install an <code>agentcompass\[\<extra>]</code> optional dependency group</td><td style={{paddingLeft:'10px', paddingRight:'10px'}}>Only for paths marked as supported below</td></tr>
    <tr><td>Packages in a harness runner or task Environment</td><td style={{paddingLeft:'10px', paddingRight:'10px'}}>Image, snapshot, Recipe, or component-specific installation</td><td style={{paddingLeft:'10px', paddingRight:'10px'}}>Not applicable</td></tr>
    <tr><td>Docker, GPU, system-tool, and provider prerequisites</td><td style={{paddingLeft:'10px', paddingRight:'10px'}}>Operating-system or provider configuration</td><td style={{paddingLeft:'10px', paddingRight:'10px'}}>Not applicable</td></tr>
  </tbody>
</table>

See [Install AgentCompass](/en/get_started/installation#install-agentcompass) for the base installation. This page covers only component-specific optional dependencies.

## Optional Extras

The table lists optional Python dependency groups installed as `agentcompass[<extra>]`; `<extra>` is the name in the first column.

<div style={{overflowX:'auto'}}>
  <table style={{minWidth:'900px', width:'100%', tableLayout:'fixed'}}>
    <thead>
      <tr><th style={{width:'20%', whiteSpace:'nowrap'}}>Extra</th><th style={{width:'34%'}}>Purpose</th><th style={{width:'46%'}}>Generic auto-install</th></tr>
    </thead>

    <tbody>
      <tr><td><code>swebench</code></td><td>Generate test scripts and parse scores for <a href="/en/user_guide/modules/benchmarks/swebench_verified"><code>swebench\_verified</code></a> and <a href="/en/user_guide/modules/benchmarks/swebench_multilingual"><code>swebench\_multilingual</code></a></td><td>Supported</td></tr>
      <tr><td><code>scicode</code></td><td>Run the host-side evaluator for <a href="/en/user_guide/modules/benchmarks/scicode">SciCode</a></td><td>Supported</td></tr>
      <tr><td><code>gdpval</code></td><td>Download reference files and provide XLSX report utilities for <a href="/en/user_guide/modules/benchmarks/gdpval_ac"><code>gdpval\_ac</code></a></td><td>Supported</td></tr>
      <tr><td><code>wildclawbench</code></td><td>Decrypt <a href="/en/user_guide/modules/benchmarks/wildclawbench">WildClawBench</a> ground truth on the host</td><td>Supported</td></tr>
      <tr><td><code>mini-swe-agent</code></td><td>Run <a href="/en/user_guide/modules/harnesses/mini_swe_agent"><code>mini\_swe\_agent</code></a> with <code>launch\_mode=local</code></td><td>Supported only by local mode with <code>install\_strategy=install\_if\_missing</code></td></tr>
      <tr><td><code>frontier-engineering</code></td><td>Provide <code>openevolve</code> for the <a href="/en/user_guide/modules/harnesses/openevolve#execution-environment">OpenEvolve harness</a></td><td>Not supported; prepare it through an image or manual installation</td></tr>
      <tr><td><code>taubench</code></td><td>Run <a href="/en/user_guide/modules/benchmarks/taubench">TauBench</a> through <code>host\_process</code></td><td>Not supported; prepare it through an image or manual installation</td></tr>
    </tbody>
  </table>
</div>

[`swebench_pro`](/en/user_guide/modules/benchmarks/swebench_pro) uses its own evaluation scripts and does not require the official `swebench` Python package on the host.

The `scicode` extra does not include the additional `matplotlib` dependency needed by test problem `80`; see [SciCode data and dependencies](/en/user_guide/modules/benchmarks/scicode#data-and-dependencies) for the complete setup.

### Manual Installation

To install one or more extras manually from a source checkout:

```bash theme={"system"}
uv pip install -e ".[swebench,mini-swe-agent]"
```

For an installed release:

```bash theme={"system"}
python -m pip install "agentcompass[swebench,mini-swe-agent]"
```

## Automatic Installation

Automatic installation is disabled by default. When it is not enabled, a generic check that finds a missing dependency raises [`OptionalDependencyError`](/en/user_guide/other_features/troubleshooting#common-failures) and prints `uv` and `pip` commands for the current interpreter. When auto-install is enabled, AgentCompass attempts to install the extra when that check runs and then checks the declared imports again. It prefers `uv` and falls back to the current interpreter's `python -m pip` when `uv` is unavailable.

```bash theme={"system"}
agentcompass run <benchmark> <harness> <model> --auto-install-dependencies
```

| Interface                                  | Setting                                                                                                                                                       |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentcompass run`                         | Enable with `--auto-install-dependencies`; explicitly disable with `--no-auto-install-dependencies`.                                                          |
| `agentcompass launch`                      | Use the same option as a shared runtime setting for the entire orchestration.                                                                                 |
| Configuration or orchestration file        | Set `runtime.auto_install_dependencies: true`.                                                                                                                |
| Python SDK                                 | Pass `auto_install_dependencies=True` to `run_evaluation()` or `launch()`; see the [Python SDK](/en/user_guide/using_agentcompass/python_api).                |
| Environment variable (single request only) | Set `AGENTCOMPASS_AUTO_INSTALL_DEPENDENCIES=true`; `1`, `yes`, and `on` are also true, with corresponding false values. `launch` does not read this variable. |

For a single evaluation request, precedence is: explicit CLI or SDK value > environment variable > configuration > default. For a multi-request orchestration, precedence is: explicit CLI or SDK value > orchestration `runtime` > configuration > default.

Enable auto-install only for trusted components because it modifies the current Python environment. It applies only to paths marked as supported in the table; remote `mini_swe_agent`, OpenEvolve, and TauBench do not trigger generic auto-install. Local `mini_swe_agent` also auto-installs only when the package is absent; an installed version mismatch still fails. The generic check confirms only that the current interpreter can discover the declared modules; it does not validate versions or audit the full transitive dependency graph. `uv` or `pip` still resolves transitive dependencies during installation.

## Check Timing

AgentCompass runs only dependency checks declared by the active evaluation path; it does not scan every extra. A satisfied check completes silently.

| Check type                                | Timing                                      | Location                                                       |
| ----------------------------------------- | ------------------------------------------- | -------------------------------------------------------------- |
| Benchmark dependency preflight            | Before task loading                         | Current Python interpreter running AgentCompass                |
| Local harness dependency check            | Before the harness session starts           | Current Python interpreter running AgentCompass                |
| In-Environment component dependency check | Harness session startup or task preparation | Python that executes the component in the selected Environment |

## Special Cases and Dependency Conflicts

### [TauBench](/en/user_guide/modules/benchmarks/taubench)

Unless you explicitly configure another image, the `taubench_docker` Recipe selects one with the TauBench dependencies preinstalled, so the Python interpreter running AgentCompass does not need the `taubench` extra. With `host_process`, TauBench checks `tau2==1.0.1` through `python3` in the selected Environment before each task; install both steps below into that same interpreter.

From a source checkout:

```bash theme={"system"}
TAUBENCH_PYTHON="$(command -v python3)"
uv pip install --python "$TAUBENCH_PYTHON" -e ".[taubench]"
uv pip install --python "$TAUBENCH_PYTHON" --no-deps \
  "tau2 @ git+https://github.com/sierra-research/tau2-bench@v1.0.1"
```

For an installed release, replace `-e ".[taubench]"` with `"agentcompass[taubench]"`. Installing the pinned `tau2` source separately with `--no-deps` prevents its transitive dependencies from changing AgentCompass's shared LiteLLM or Tenacity versions.

The `terminal_use`, `terminal_use_write`, `alltools`, and `alltools-qwen` retrieval methods for `banking_knowledge` also need system tools in the execution Environment; the default Docker image already provides them. See [TauBench `banking_knowledge` retrieval configuration](/en/user_guide/modules/benchmarks/taubench#banking_knowledge-retrieval-configuration) to prepare another Environment.

## Related Pages

* [Install AgentCompass](/en/get_started/installation)
* [Environments](/en/user_guide/modules/environments/overview)
* [Common failures](/en/user_guide/other_features/troubleshooting#common-failures)