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

# 快速开始

通过仓库自带的交互式示例，完成 [SWE-bench Verified](/zh/user_guide/modules/benchmarks/swebench_verified) Benchmark 的一次真实任务评测并查看结果。

本页使用固定的单个样本 `astropy__astropy-12907` 演示完整流程：配置 Model 和 Environment、检查生成的命令、运行代码仓库修复任务，以及查看评测结果。首次使用 AgentCompass 时，建议先完成本页示例，再配置完整 Benchmark。

## 准备运行

先完成[安装](/zh/get_started/installation)，然后在已激活的 Python 虚拟环境中确认 AgentCompass CLI 可用：

```bash theme={"system"}
agentcompass --version
```

运行示例前，还需要准备：

* 支持 OpenAI Chat Completions 协议的 Model 端点。
* Docker，或 [Daytona](https://www.daytona.io/docs/) / [Modal](https://modal.com/docs) 远程 sandbox 凭证；可用选项与配置见安装页的 [Environment](/zh/get_started/installation#environment) 章节。
* 首次下载数据集、任务镜像和可选依赖所需的网络访问；后续运行会复用已下载的文件。

## 运行示例

在 AgentCompass 代码仓库根目录运行交互式脚本：

```bash theme={"system"}
python examples/run_swebench_verified.py
```

脚本会按以下顺序引导你完成配置：

1. 输入 `MODEL_BASE_URL`、`MODEL_API_KEY` 和 `MODEL_NAME`；如果这些环境变量已经设置，脚本会复用现有值。
2. 选择 Docker、Daytona 或 Modal 作为 Environment，并补充远程 provider 所需的凭证。
3. 检查 Model API 密钥已脱敏的完整命令和参数说明表。
4. 确认无误后启动评测。

脚本只将输入值传给本次运行的子进程，不会写入终端配置文件。

<Tabs>
  <Tab title="Docker">
    Docker 是默认选项，适合能够拉取并运行 SWE-bench 任务镜像的 Linux 或 WSL 2 设备。运行脚本前，先确认 Docker 守护进程可用：

    ```bash theme={"system"}
    docker version
    ```
  </Tab>

  <Tab title="Daytona">
    选择 Daytona 后，脚本会复用环境变量中的 `DAYTONA_API_KEY`，或通过隐藏输入读取密钥。`DAYTONA_API_URL` 和 `DAYTONA_TARGET` 可按需填写：

    ```bash theme={"system"}
    export DAYTONA_API_KEY="..."
    ```
  </Tab>

  <Tab title="Modal">
    选择 Modal 后，脚本可以使用 `~/.modal.toml`，也可以复用或读取服务令牌：

    ```bash theme={"system"}
    export MODAL_TOKEN_ID="..."
    export MODAL_TOKEN_SECRET="..."
    ```
  </Tab>
</Tabs>

## 了解本次运行

本示例使用 `mini_swe_agent` 在 `swebench_verified` 上运行一个固定任务，并将任务并发数设为 `1`，便于确认 Model 和 Environment 配置是否正确。

启动任务前，脚本会暂停并显示：

* 可直接复制的命令预览，其中 Model API 密钥会替换为星号。
* 参数说明表，列出每个关键参数的实际取值及其作用。

本次运行使用以下配置：

| 参数                           | 示例值                                         | 作用                                |
| ---------------------------- | ------------------------------------------- | --------------------------------- |
| `model`                      | `$MODEL_NAME`                               | 指定待测 Model，并用于组织结果目录。             |
| `benchmark`                  | `swebench_verified`                         | 加载 SWE-bench Verified 任务并评测生成的补丁。 |
| `harness`                    | `mini_swe_agent`                            | 在准备好的代码仓库中运行编程 agent。             |
| `--env`                      | `docker`、`daytona` 或 `modal`                | 指定任务命令和评测器的执行位置。                  |
| `--model-*`                  | 端点、密钥、`openai-chat`、温度 `0`                  | 配置 Model 连接、API 协议和采样参数。          |
| `--benchmark-params`         | `{"sample_ids":["astropy__astropy-12907"]}` | 只选择一个固定任务。                        |
| `--env-params`               | provider 专用 JSON                            | 按需传入远程 Environment 配置。            |
| `--task-concurrency`         | `1`                                         | 每次只运行一个 Benchmark 任务。             |
| `--results-dir` 与 `--run-id` | 自动生成的本地路径                                   | 为本次运行单独保存任务详情、汇总、日志和分析结果。         |
| `--enable-analysis`          | 启用                                          | 在评测完成后分析任务轨迹。                     |
| `--progress` 与 `--log-level` | `auto`、`ERROR`                              | 显示必要的运行进度，并减少非关键日志。               |

只有在你确认后，脚本才会启动任务。选择 Docker 时，生成命令的核心部分等价于以下 CLI 写法；结果目录和运行 ID 由脚本自动补充：

```bash theme={"system"}
agentcompass run \
  swebench_verified \
  mini_swe_agent \
  "$MODEL_NAME" \
  --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 \
  --model-params '{"temperature":0}' \
  --task-concurrency 1 \
  --enable-analysis \
  --progress auto \
  --log-level ERROR
```

确认运行后，AgentCompass 会依次完成：

```text theme={"system"}
加载指定的 Benchmark 任务
  → 通过 Recipe 确定任务镜像和工作区
  → 打开所选 Environment
  → 使用 Mini-SWE-agent 修改并测试代码仓库
  → 执行 SWE-bench 评测器
  → 保存任务详情、汇总、日志和分析结果
```

## 调整运行方式

如果只想检查最终命令和参数，不启动任务，请添加 `--dry-run`：

```bash theme={"system"}
python examples/run_swebench_verified.py --dry-run
```

如果需要运行评测，但不希望结束后打开本地结果查看器，请添加 `--no-visualization`：

```bash theme={"system"}
python examples/run_swebench_verified.py --no-visualization
```

## 查看结果

评测完成后，脚本会输出任务是否解决、轨迹步数、工具调用次数、耗时、分析器发现项和结果目录。每次运行使用独立的运行 ID，目录结构如下：

```text theme={"system"}
results/
└── swebench_verified/
    └── <model>/
        └── <run-id>/
            ├── details/
            ├── logs/
            ├── summary.md
            └── analysis_summary.md
```

`details/` 保存单任务结果，`logs/` 保存运行日志，`summary.md` 汇总评测结果，`analysis_summary.md` 汇总轨迹分析。

如果本机已安装 Node.js 和 npm，脚本会在评测结束后询问是否打开本地结果查看器。首次打开时可能需要安装前端依赖；关闭查看器时，在终端按 Enter 即可。

## 下一步

<CardGroup cols={2}>
  <Card title="运行完整评测" icon="wand-sparkles" href="/zh/get_started/complete_evaluation">
    选择 Model、Benchmark、Harness 和 Environment，并生成完整运行命令。
  </Card>

  <Card title="学习 CLI" icon="square-terminal" href="/zh/user_guide/using_agentcompass/cli/overview">
    了解 `run`、`launch`、结果汇总、分析和配置命令。
  </Card>

  <Card title="选择 Environment" icon="cloud" href="/zh/user_guide/modules/environments/overview">
    比较 Docker、Daytona、Modal 的适用场景和配置方式。
  </Card>

  <Card title="检查结果产物" icon="chart-no-axes-combined" href="/zh/user_guide/other_features/results">
    了解结果目录、单任务详情、汇总文件和复用规则。
  </Card>
</CardGroup>