安装 - AgentCompass Documentation

AgentCompass 面向源码 checkout 开发和运行。请从项目根目录以 editable mode 安装；模型 endpoint 放在 Setup 页面配置。

系统要求

Python 3.10 或更新版本（推荐 3.12+）。
git，用于克隆和更新源码 checkout。
wget 和 unzip，用于自动下载或准备数据集。
可选的环境依赖或凭据，例如 Docker、Modal、Daytona 或 HBox。

克隆仓库

git clone https://github.com/open-compass/AgentCompass.git
cd AgentCompass

安装 Python 依赖

任选一种方式即可。将 <compatible_python_version> 替换成 AgentCompass 支持的 Python 版本，例如 3.12 或 3.13。

pip + venv
uv
conda

python -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .

uv venv --python <compatible_python_version>
source .venv/bin/activate

uv pip install -r requirements.txt
uv pip install -e .

conda create -n <env_name> python=<compatible_python_version>
conda activate <env_name>

python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .

运行 SWE-bench Verified 快速开始前，请在同一个环境中安装 benchmark 和 harness 可选依赖：

uv pip install -r requirements/swe.txt
uv pip install -r requirements/mini-swe-agent.txt

Docker 快速开始还要求 Docker 已安装并正在运行：

docker version

验证 CLI

如果已经激活环境：

agentcompass --version

agentcompass --help

agentcompass list benchmark

如果使用 uv，也可以不手动激活 .venv：

uv run agentcompass --version

uv run agentcompass --help

uv run agentcompass list benchmark

从源码更新

使用 rebase 拉取最新代码，让本地提交保持在线性历史顶部。如果 worktree 有未提交改动，请先 commit 或 stash；如果 requirements 或 package metadata 有变化，再重新安装 editable 依赖。

pip + venv
uv
conda

git pull --rebase
source .venv/bin/activate

python -m pip install -r requirements.txt
python -m pip install -e .

git pull --rebase

uv pip install -r requirements.txt
uv pip install -e .

git pull --rebase
conda activate <env_name>

python -m pip install -r requirements.txt
python -m pip install -e .

数据缓存与输出目录

AgentCompass 默认使用可预测的本地目录：

路径	用途
`data/`	下载或准备后的 benchmark 数据集；已有数据会作为本地数据缓存被复用。
`results/`	评测输出，路径形如 `results/<benchmark>/<model>/<timestamp>/`。
run directory 内的 `logs/`	单次 evaluation 的运行日志。

需要时可以覆盖目录：

agentcompass run <benchmark> <harness> <model> --data-dir <data_dir> --results-dir <results_dir>

常见问题

现象	检查项
`agentcompass: command not found`	激活环境，重新运行 `python -m pip install -e .`，或使用 `uv run agentcompass ...`。
Python 版本不匹配	运行 `python --version`，并用 Python `>=3.10` 重新创建环境。
数据集准备失败	检查 `wget`、`unzip`、网络连接，以及 `data/` 或 `--data-dir` 的写权限。
远程环境启动失败	检查 Docker、Modal、Daytona 或 HBox 的凭据和环境配置。
运行时模型 provider 报错	在 Setup 页面配置 model endpoint、API key、protocol 和 provider 命名。

不做 editable install

如果没有安装 console script，可以从源码路径运行：

PYTHONPATH=src python -m agentcompass.cli run \
  swebench_verified \
  mini_swe_agent \
  glm-5.2 \
  --env docker \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --model-api-protocol openai-chat

快速开始

核心模块

执行环境

实战指南

安装

系统要求

克隆仓库

安装 Python 依赖

验证 CLI

从源码更新

数据缓存与输出目录

常见问题

不做 editable install

​系统要求

​克隆仓库

​安装 Python 依赖

​验证 CLI

​从源码更新

​数据缓存与输出目录

​常见问题

​不做 editable install

系统要求

克隆仓库

安装 Python 依赖

验证 CLI

从源码更新

数据缓存与输出目录

常见问题

不做 editable install