# AgentEval

**Repository Path**: gcpaas/AgentEval

## Basic Information

- **Project Name**: AgentEval
- **Description**: 面向 AI 应用开发者、测试工程师与平台运维者的 Agent 自动化评测平台。它通过标准化连接器快速接入各类 Agent，按统一任务集执行任务，适用于版本迭代中的回归测试、模型选型以及不同模型在同一任务集上的横向对比。平台从正确性、安全性、LLM 过程质量三个维度自动打分，减少人工评估成本，提升结果可复现性，并输出 HTML、Markdown、JSON 三种格式报告。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GCAgenteval

## 介绍

GCAgenteval 是面向 AI 应用开发者、测试工程师与平台运维者的 Agent 自动化评测平台。它通过标准化连接器快速接入各类 Agent，按统一任务集执行任务，适用于版本迭代中的回归测试、模型选型以及不同模型在同一任务集上的横向对比。平台从正确性、安全性、LLM 过程质量三个维度自动打分，减少人工评估成本，提升结果可复现性，并输出 HTML、Markdown、JSON 三种格式报告。

## 评分说明

平台对被测 Agent 的每一道题从三个维度独立打分，每个维度的分值均为 **0–1（即 0%–100%）**，1.0 为满分：

- **正确性（outcome / Oracle）**：确定性校验 Agent 在工作区中产出的文件、命令结果、Git 状态、YAML/JSON/CSV 等内容是否正确。零成本、可复现，是每道题的核心达标项。
- **安全性（security / 安全门）**：以确定性规则（轨迹正则 + workspace 路径正则）校验是否存在越权、注入、泄露等风险。命中“门控级”规则时直接判该题不通过。
- **LLM 过程质量（process / Trajectory）**：对 Agent 的推理轨迹（tool 调用、思考、输出）做语义评判，衡量过程是否符合工程规范。需配置 judge 模型才会评分。

### 综合分（单题总分）怎么算

单题的**综合分 = 已评分各维度分数的乘积（Π）**，而非加权平均。规则如下：

- 每个维度分数取 0–1，综合分同样落在 0–1 之间，**单题综合分满分 = 1.0（100%）**。
- **乘法“一票否决”**：只要任一已评分维度为 0，综合分即为 0。例如正确性为 0 时，即便过程分、安全分都是满分，综合分仍为 0。
- **未评分的维度不参与乘法**，既不当作 0、也不当作满分，而是在报告中单独披露（避免“看起来像满分”）。若三维度全部未评分，综合分记为 0。

### 结论分档（Verdict）

除分数外，每道题还有通过结论：

- 运行出错 / 超时 → 直接**不通过（FAIL）**；
- 安全门控命中 → 直接**不通过（FAIL）**；
- 结果（正确性）维度判 0 → **不通过**；
- 其余 → 按正确性维度结论给出**通过 / 部分通过**。

## 使用说明

日常评测推荐用 **Web 控制台**；需要脚本化/CI 时用 **命令行**。

### 方式 A：Web 控制台（推荐）

```bash
# 1. 编译（打出可执行 jar，含 Web 控制台静态页）
mvn -q clean package -DskipTests

# 2. 启动本地评测服务（监听地址由 config/server.yaml 的 host 决定，默认 127.0.0.1:8787；无鉴权）
java -jar gca-cli/target/gcagenteval.jar serve --port 8787
```

浏览器打开 <http://127.0.0.1:8787>，控制台提供：

- **提交评测**：选择被测对象（agent）、过程分 judge 模型，输入题号，点提交即开始跑。
- **运行记录**：实时查看每题状态、综合分、各维度得分与耗时。
- **题库**：页面底部列出全部任务（题号 — 名称 — 简介 — 轮数），方便确认本次评测覆盖哪些题。
- **报告**：评测完成后可查看 HTML 报告；报告文件同时落在 `results/<agent>/` 下（`report.html` / `report.md` / `report.json`）。

### 方式 B：命令行

```bash
# 跑指定被测对象（agent 在 config/agent.yaml 定义）
java -jar gca-cli/target/gcagenteval.jar run --agent demo-local --repeat 1 --concurrency 1

# 不重跑，从既有结果重建报告
java -jar gca-cli/target/gcagenteval.jar report --results results/demo-local

# 其他辅助命令
java -jar gca-cli/target/gcagenteval.jar list     # 列出题库任务与可用 agent / 连接器
java -jar gca-cli/target/gcagenteval.jar doctor   # 环境与配置自检（密钥、端口、依赖可用性等）
```

> 想改默认行为：服务与 agent 的配置在 `config/server.yaml`、`config/agent.yaml`，其中的 `${VAR:-默认}` 在运行时用环境变量展开。

#### 配置密钥（如用到远程/API 类 agent 或 judge 模型）

所有密钥一律走环境变量，不要写进文件。常用变量：

```bash
# 自定义 HTTP/SSE 被测服务：在 config/agent.yaml 对应 agent 的 base_url 中配置（可用 ${VAR} 注入环境变量）

# OpenAI 兼容的被测 agent（openai_compatible agent）
export GCAGENTEVAL_BASE_URL="https://api.deepseek.com"
export GCAGENTEVAL_API_KEY="sk-..."
export GCAGENTEVAL_MODEL="deepseek-chat"

# 过程分 使用的 judge 模型
export GCAGENTEVAL_JUDGE_BASE_URL="http://<host>:<port>"
export GCAGENTEVAL_JUDGE_API_KEY="sk-..."
export GCAGENTEVAL_JUDGE_MODEL="your-judge-model"
```

`config/agent.yaml`、`config/server.yaml` 中的 `${VAR:-默认}` 会在运行时用环境变量展开（变量缺失则回退默认值）。

### 配置文件（config/）

评测平台共有三份配置，分工如下：

- **`config/app.yaml`**（项目级；文件缺失则使用默认值）：决定工程名与各类目录，以及"去哪里读取 agent 配置"。字段与默认值：

  | 字段 | 说明 | 默认 |
  |---|---|---|
  | `project_name` | 报告/控制台显示的项目名 | `GCAgenteval` |
  | `tasks_dir` | 题库根目录 | `tasks` |
  | `work_dir` | 运行时沙箱与轨迹产物目录 | `work` |
  | `results_dir` | 评测结果与报告输出根目录 | `results` |
  | `agent_config` | agent 配置文件路径 | `config/agent.yaml` |

  所有 CLI 命令（`run`/`report`/`list`/`doctor`）与 `serve` 启动时都会先读它；文件不存在时自动回退上表默认值。
- **`config/server.yaml`**（仅 `serve` 使用）：控制服务监听 `host` / `port`、过程分 judge 模型、并发默认值。其中 `host` 默认 `127.0.0.1`，且 `tasks_dir` 可在此覆盖 `app.yaml` 的取值。它不含 agent 定义。
- **`config/agent.yaml`**（由 `app.yaml` 的 `agent_config` 指向，默认即它）：被测 agent 定义与每个 agent 的过程分 judge，详见下文"接入新 Agent"。

### 接入新 Agent（扩展 agent）

在 `config/agent.yaml` 下新增一个 agent 条目，选择连接器并填写参数即可，任务定义完全不变：

- 本地命令行 Agent：用 `connector: local_process`，在 `params.command` / `args` 中用占位符引用 agent 脚本与 `{workspace}`。
- OpenAI 兼容 API：用 `connector: openai_compatible`，填 `base_url` / `api_key_env` / `system_prompt`。
- 自定义 HTTP/SSE 服务：用 `connector: generic_http`，按事件路径配置流式字段（SSE 的 `TEXT_MESSAGE_CONTENT` / `REASONING_MESSAGE_CONTENT` / `TOOL_CALL_*` 等）。
- 新协议：实现 `io.gcagenteval.core.spi.AgentConnector` 并在 `META-INF/services` 声明，即被 `ConnectorRegistry` 自动识别。

#### 示例：新增一个本地进程型 Agent

以「零代码接入任意命令行 Agent」的 `local_process` 为例，在 `config/agent.yaml` 的 `agents:` 下加一段即可：

```yaml
agents:
  my-cli-agent:                       # 自定义 agent 名，run / serve 时通过 --agent 引用
    connector: local_process
    agent_id: my-cli-agent
    model_id: my-model               # 仅作为报告里的标签，不实际控制模型
    timeout_sec: 180
    params:
      command: "python"
      args:
        # 进程 cwd 是沙箱目录，因此 agent 脚本必须用绝对路径引用
        - "{project_root}/examples/demo-agent/demo_agent.py"
        - "--workspace"
        - "{workspace}"              # 任务工作区，agent 必须把产物写到这里
        - "--task-dir"
        - "{task_dir}"               # 任务素材目录（fixtures 等）
        - "--round"
        - "{round}"                  # 当前轮次（多轮任务用）
        - "--trace"
        - "{sandbox}/trace-round{round}.jsonl"   # 轨迹输出，连接器据此读取步骤
      # 每题每轮一份轨迹文件，避免多轮之间互相污染
      trace_file: "{sandbox}/trace-round{round}.jsonl"
```

接入要点：

- **脚本用绝对路径**：进程的工作目录是沙箱目录，相对路径会从沙箱解析，所以 agent 脚本（如 `{project_root}/examples/demo-agent/demo_agent.py`）要用绝对路径引用。
- **必须写轨迹**：agent 需向 `--trace` 指定的文件写入标准轨迹（每步含 `kind`：`PROMPT` / `REASONING` / `TOOL_CALL` / `TOOL_RESULT` / `OUTPUT`），否则评测读不到过程，过程分（Trajectory）无法评分。
- **任务定义不动**：`tasks/` 下无需任何改动，换 `--agent my-cli-agent` 即可对比不同 Agent。

### 新增 / 扩展评测能力

- 新增 Oracle 校验基元：实现 `OracleVerifier` 并在 `VerifierRegistry` 注册，即可在任意任务的 `ground_truth.json` 中以 `type` 引用。
- 新增评测器：实现 `Evaluator`（`dimension()` 返回三维度之一），通过 `CompositeEvaluator.register(...)` 挂载。

---

## 软件架构

GCAgenteval 是一个基于 Maven 的多模块 Java 17 工程，整体遵循「**接入（Connector）→ 运行（Runner）→ 三路评测（Evaluator）→ 报告（Reporter）**」的分层流水线。核心抽象通过 SPI 接口解耦，扩展只需实现接口并在 `META-INF/services` 中声明。

```
gcagenteval (parent pom)
├── gca-core          # 核心模型与 SPI 契约：模型(Dimension/EvaluationResult/...)、AgentConnector/Evaluator/OracleVerifier/LlmClient/TaskHook
├── gca-connectors    # 连接器实现：local_process / openai_compatible / mcp / generic_http
├── gca-runner        # 运行引擎：任务加载、占位符渲染、沙箱、Hook、多轮执行、结果落盘
├── gca-evaluators    # 三路评测实现：Oracle 声明式引擎 + 校验基元 / Security / Trajectory
├── gca-report        # 报告：HTML / Markdown / JSON 生成 + 失败聚类
├── gca-cli           # 命令行入口：run / serve / list / doctor / report（Picocli，产出可执行 jar）
└── gca-server        # 本地评测服务（ApiServer + RunService + JudgeConfigStore + Web 控制台）
```

---

## 目录结构速览

| 路径 | 说明 |
|---|---|
| `tasks/` | 任务定义（`task.yaml` + `prompt.txt` + `ground_truth.json` + `fixtures/`） |
| `config/` | `app.yaml`（项目路径，可省略）、`server.yaml`（serve 监听与 judge）、`agent.yaml`（被测对象） |
| `examples/` | 示例 agent 脚本（如 `demo-agent`） |
| `gca-cli/target/gcagenteval.jar` | 编译产物，命令行 / 服务入口 |
| `results/<agent>/` | 评测结果与报告输出目录 |
| `work/<agent>/` | 运行时沙箱与 Agent 轨迹产物 |