AgentEvalTool/docs/api-reference/web-api-v1.0.md

# AgentEvalTool Web API 参考

**版本**: v1.0  
**日期**: 2026-07-09  
**状态**: 已发布  
**作者**: AgentEval Team

---

## 一、概述

AgentEvalTool 提供 RESTful Web API 用于管理评测对象、场景、执行评测和查看报告。

**基础 URL**: `http://localhost:8000`  
**API 前缀**: `/api`  
**内容类型**: `application/json`

## 二、健康检查

### 2.1 健康检查

```http
GET /api/health
```

**响应**：
```json
{
  "status": "ok"
}
```

## 三、评测对象 API

### 3.1 列出所有评测对象

```http
GET /api/targets
```

**响应**：
```json
[
  {
    "id": "aa4cd4e4-1c84-41d0-b3d7-06ee7dd94971",
    "name": "社区医院AI客服",
    "description": "...",
    "platform": "ai_digital_employee",
    "channel_type": "tutu-api",
    "status": "active",
    "created_at": "2026-07-09T10:21:39",
    "updated_at": "2026-07-09T10:21:39"
  }
]
```

### 3.2 创建评测对象

```http
POST /api/targets
Content-Type: application/json

{
  "name": "社区医院AI客服",
  "description": "...",
  "platform": "ai_digital_employee",
  "channel_type": "tutu-api",
  "channel_config": {
    "base_url": "https://api.example.com",
    "token": "jwt-token",
    "tenant": "tenant-id",
    "chat_channel_id": "channel-id",
    "chat_contact_id": "contact-id"
  }
}
```

**响应**：创建的评测对象 JSON

### 3.3 获取评测对象详情

```http
GET /api/targets/{id}
```

### 3.4 更新评测对象

```http
PUT /api/targets/{id}
Content-Type: application/json

{
  "name": "更新后的名称",
  "channel_config": { ... }
}
```

### 3.5 删除评测对象

```http
DELETE /api/targets/{id}
```

### 3.6 测试评测对象连通性

```http
POST /api/targets/{id}/test
```

**响应**：
```json
{
  "status": "ok",
  "message": "通道正常"
}
```

## 四、评测场景 API

### 4.1 列出所有评测场景

```http
GET /api/scenarios
```

**响应**：
```json
[
  {
    "id": "5b1a8cf7-25bc-4424-97d0-795b61149c0c",
    "name": "社区医院基础服务评测",
    "description": "...",
    "tags": ["health", "basic-service"],
    "cases_count": 2,
    "created_at": "2026-07-09T10:28:40",
    "updated_at": "2026-07-09T10:28:40"
  }
]
```

### 4.2 创建评测场景

```http
POST /api/scenarios
Content-Type: application/json

{
  "name": "场景名称",
  "description": "...",
  "tags": ["tag1", "tag2"],
  "cases": [ ... ]
}
```

### 4.3 获取评测场景详情

```http
GET /api/scenarios/{id}
```

### 4.4 更新评测场景

```http
PUT /api/scenarios/{id}
Content-Type: application/json

{
  "name": "更新后的名称",
  "cases": [ ... ]
}
```

### 4.5 删除评测场景

```http
DELETE /api/scenarios/{id}
```

## 五、评测执行 API

### 5.1 列出所有评测记录

```http
GET /api/runs
```

**响应**：
```json
[
  {
    "id": "1e6c4e72-c578-40e0-b5d7-f1cbb4a62da8",
    "target_id": "aa4cd4e4-1c84-41d0-b3d7-06ee7dd94971",
    "scenario_id": "5b1a8cf7-25bc-4424-97d0-795b61149c0c",
    "status": "completed",
    "started_at": "2026-07-09T10:28:49",
    "completed_at": "2026-07-09T10:29:25"
  }
]
```

### 5.2 启动评测任务

```http
POST /api/runs
Content-Type: application/json

{
  "target_id": "aa4cd4e4-1c84-41d0-b3d7-06ee7dd94971",
  "scenario_id": "5b1a8cf7-25bc-4424-97d0-795b61149c0c"
}
```

**响应**：创建的评测记录 JSON

### 5.3 获取评测记录详情

```http
GET /api/runs/{id}
```

### 5.4 获取评测日志（对话轮次）

```http
GET /api/runs/{id}/logs
```

**响应**：
```json
[
  {
    "case_id": "case-001",
    "round_index": 1,
    "question_msg_id": "b31d9547-1e71-44a6-9d19-c62f1de746b6",
    "latency_ms": 13717,
    "sent_at": "2026-07-09T10:28:49",
    "received_at": "2026-07-09T10:29:03"
  }
]
```

## 六、报告 API

### 6.1 获取报告（JSON）

```http
GET /api/reports/{run_id}
```

**响应**：
```json
{
  "run_id": "1e6c4e72-c578-40e0-b5d7-f1cbb4a62da8",
  "target_id": "aa4cd4e4-1c84-41d0-b3d7-06ee7dd94971",
  "target_name": "社区医院AI客服",
  "scenario_id": "5b1a8cf7-25bc-4424-97d0-795b61149c0c",
  "scenario_name": "社区医院基础服务评测",
  "status": "completed",
  "started_at": "2026-07-09T10:28:49",
  "completed_at": "2026-07-09T10:29:25",
  "summary": {
    "total_cases": 2,
    "passed_cases": 2,
    "failed_cases": 0,
    "total_rules": 3,
    "passed_rules": 3,
    "pass_rate": 1.0
  },
  "cases": [ ... ]
}
```

### 6.2 获取报告（HTML）

```http
GET /api/reports/{run_id}/html
```

**响应**：HTML 文档

## 七、错误响应

所有 API 错误返回统一格式：

```json
{
  "detail": "错误描述信息"
}
```

**常见错误码**：
| HTTP 状态码 | 说明 |
|-------------|------|
| 400 | 请求参数错误 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

## 八、CORS 配置

API 默认允许所有来源的跨域请求（开发模式）。生产环境建议配置具体的允许来源。