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

# 依赖管理

AgentCompass 会按需检查当前评测所需的可选 Python 依赖。这里的 host 是运行当前 `agentcompass` 进程的机器；通用依赖管理器只检查和修改该进程使用的 Python 解释器。

任务 [Environment](/zh/user_guide/modules/environments/overview) 中的软件包由镜像、快照、[Recipe](/zh/user_guide/other_features/recipes) 或 Harness 准备。Docker 守护进程、GPU 和 provider 凭证等系统前置条件也不属于 Python 依赖管理。

<table style={{width:'100%', tableLayout:'fixed'}}>
  <thead>
    <tr><th style={{width:'26%'}}>依赖或前置条件</th><th style={{width:'46%', paddingLeft:'10px', paddingRight:'10px'}}>准备方式</th><th style={{width:'28%', paddingLeft:'10px', paddingRight:'10px'}}>通用自动安装</th></tr>
  </thead>

  <tbody>
    <tr><td>AgentCompass 解释器中的 Python 软件包</td><td style={{paddingLeft:'10px', paddingRight:'10px'}}>安装 <code>agentcompass\[\<extra>]</code> 可选依赖组</td><td style={{paddingLeft:'10px', paddingRight:'10px'}}>仅适用于下表标注支持的路径</td></tr>
    <tr><td>Harness 运行器或任务 Environment 中的软件包</td><td style={{paddingLeft:'10px', paddingRight:'10px'}}>镜像、快照、Recipe 或组件专属安装流程</td><td style={{paddingLeft:'10px', paddingRight:'10px'}}>不适用</td></tr>
    <tr><td>Docker、GPU、系统工具和 provider 前置条件</td><td style={{paddingLeft:'10px', paddingRight:'10px'}}>操作系统或 provider 配置</td><td style={{paddingLeft:'10px', paddingRight:'10px'}}>不适用</td></tr>
  </tbody>
</table>

基础安装步骤见[安装 AgentCompass](/zh/get_started/installation#安装-agentcompass)。本页只说明按组件选择的可选依赖。

## 可选依赖

表中列出可通过 `agentcompass[<extra>]` 安装的 Python 可选依赖组；`<extra>` 即表中的名称。

<div style={{overflowX:'auto'}}>
  <table style={{minWidth:'900px', width:'100%', tableLayout:'fixed'}}>
    <thead>
      <tr><th style={{width:'20%', whiteSpace:'nowrap'}}>可选依赖</th><th style={{width:'34%'}}>用途</th><th style={{width:'46%'}}>通用自动安装</th></tr>
    </thead>

    <tbody>
      <tr><td><code>swebench</code></td><td>为 <a href="/zh/user_guide/modules/benchmarks/swebench_verified"><code>swebench\_verified</code></a> 和 <a href="/zh/user_guide/modules/benchmarks/swebench_multilingual"><code>swebench\_multilingual</code></a> 生成测试脚本并解析评分结果</td><td>支持</td></tr>
      <tr><td><code>scicode</code></td><td>运行 <a href="/zh/user_guide/modules/benchmarks/scicode">SciCode</a> 的 host 侧评测器</td><td>支持</td></tr>
      <tr><td><code>gdpval</code></td><td>为 <a href="/zh/user_guide/modules/benchmarks/gdpval_ac"><code>gdpval\_ac</code></a> 下载参考文件并提供 XLSX 报告工具</td><td>支持</td></tr>
      <tr><td><code>wildclawbench</code></td><td>在 host 上解密 <a href="/zh/user_guide/modules/benchmarks/wildclawbench">WildClawBench</a> 标准答案</td><td>支持</td></tr>
      <tr><td><code>mini-swe-agent</code></td><td>以 <code>launch\_mode=local</code> 运行 <a href="/zh/user_guide/modules/harnesses/mini_swe_agent"><code>mini\_swe\_agent</code></a></td><td>仅本地模式的 <code>install\_strategy=install\_if\_missing</code> 支持</td></tr>
      <tr><td><code>frontier-engineering</code></td><td>为 <a href="/zh/user_guide/modules/harnesses/openevolve#execution-environment">OpenEvolve Harness</a> 提供 <code>openevolve</code></td><td>不支持；通过镜像或手动安装准备</td></tr>
      <tr><td><code>taubench</code></td><td>通过 <code>host\_process</code> 运行 <a href="/zh/user_guide/modules/benchmarks/taubench">TauBench</a></td><td>不支持；通过镜像或手动安装准备</td></tr>
    </tbody>
  </table>
</div>

[`swebench_pro`](/zh/user_guide/modules/benchmarks/swebench_pro) 使用自己的评测脚本，不需要在 host 安装官方 `swebench` Python 包。

`scicode` extra 不包含测试问题 `80` 额外需要的 `matplotlib`；完整准备要求见 [SciCode 的数据与依赖](/zh/user_guide/modules/benchmarks/scicode#数据与依赖)。

### 手动安装

在仓库源码目录中手动安装一个或多个 extra：

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

若使用已安装的发布版本：

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

## 自动安装

自动安装默认关闭。未启用时，通用检查发现依赖缺失会抛出 [`OptionalDependencyError`](/zh/user_guide/other_features/troubleshooting#常见失败)，并打印适用于当前解释器的 `uv` 和 `pip` 安装命令。启用后，AgentCompass 会在相应检查发生时尝试安装 extra，并在安装后重新检查声明的导入模块；自动安装优先使用 `uv`，找不到时改用当前解释器的 `python -m pip`。

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

| 接口                    | 设置方式                                                                                                                                 |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `agentcompass run`    | 使用 `--auto-install-dependencies` 启用；使用 `--no-auto-install-dependencies` 显式关闭。                                                        |
| `agentcompass launch` | 使用同名选项作为整个编排的共享运行设置。                                                                                                                 |
| 配置文件或编排文件             | 设置 `runtime.auto_install_dependencies: true`。                                                                                        |
| Python SDK            | 向 `run_evaluation()` 或 `launch()` 传入 `auto_install_dependencies=True`，详见 [Python SDK](/zh/user_guide/using_agentcompass/python_api)。 |
| 环境变量（仅单评测请求）          | 设置 `AGENTCOMPASS_AUTO_INSTALL_DEPENDENCIES=true`；也接受 `1`、`yes` 和 `on`，以及对应的 false 值。`launch` 不读取该环境变量。                               |

单评测请求的优先级为：显式 CLI 或 SDK 值 > 环境变量 > 配置文件 > 默认值。多评测编排的优先级为：显式 CLI 或 SDK 值 > 编排文件中的 `runtime` > 配置文件 > 默认值。

只应为可信组件启用自动安装，因为该操作会修改当前 Python 环境。该功能只适用于表中标注支持的路径；`mini_swe_agent` 远程模式、OpenEvolve 和 TauBench 不会触发通用自动安装。本地 `mini_swe_agent` 也只会在软件包缺失时自动安装，已安装版本不符仍会报错。通用检查只确认当前解释器能否发现声明的模块，不校验版本或审计完整的传递依赖图；实际安装时，传递依赖仍由 `uv` 或 `pip` 解析。

## 检查时机

AgentCompass 只执行当前评测路径声明的依赖检查，不会扫描全部 extra。依赖已经满足时，检查会静默通过。

| 检查类型                | 时机                  | 检查位置                           |
| ------------------- | ------------------- | ------------------------------ |
| Benchmark 依赖预检      | 任务加载前               | 运行 AgentCompass 的当前 Python 解释器 |
| Harness 本地依赖检查      | Harness 会话启动前       | 运行 AgentCompass 的当前 Python 解释器 |
| Environment 内组件依赖检查 | Harness 会话启动或任务准备阶段 | 所选 Environment 中实际执行组件的 Python |

## 特殊场景与依赖冲突

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

未显式指定其他镜像时，`taubench_docker` Recipe 会使用预装 TauBench 依赖的镜像，此时运行 AgentCompass 的 Python 解释器无需安装 `taubench` extra。使用 `host_process` 时，TauBench 会在每个任务运行前通过所选 Environment 的 `python3` 检查 `tau2==1.0.1`，因此以下两步必须安装到同一个解释器。

在仓库源码目录中运行：

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

使用已安装的发布版本时，将 `-e ".[taubench]"` 替换为 `"agentcompass[taubench]"`。单独以 `--no-deps` 安装固定的 `tau2` 来源，可避免其传递依赖改写 AgentCompass 共享的 LiteLLM 或 Tenacity 版本。

`banking_knowledge` 的 `terminal_use`、`terminal_use_write`、`alltools` 和 `alltools-qwen` 检索方式还需要所选 Environment 中的系统工具；默认 Docker 镜像已经提供。其他 Environment 的准备方法见 [TauBench 的 `banking_knowledge` 检索配置](/zh/user_guide/modules/benchmarks/taubench#banking_knowledge-检索配置)。

## 相关页面

* [安装 AgentCompass](/zh/get_started/installation)
* [Environment](/zh/user_guide/modules/environments/overview)
* [常见失败](/zh/user_guide/other_features/troubleshooting#常见失败)