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 健康检查

GET /api/health

响应：

{
  "status": "ok"
}

三、评测对象 API

3.1 列出所有评测对象

GET /api/targets

响应：

[
  {
    "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 创建评测对象

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 获取评测对象详情

GET /api/targets/{id}

3.4 更新评测对象

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

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

3.5 删除评测对象

DELETE /api/targets/{id}

3.6 测试评测对象连通性

POST /api/targets/{id}/test

响应：

{
  "status": "ok",
  "message": "通道正常"
}

四、评测场景 API

4.1 列出所有评测场景

GET /api/scenarios

响应：

[
  {
    "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 创建评测场景

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

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

4.3 获取评测场景详情

GET /api/scenarios/{id}

4.4 更新评测场景

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

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

4.5 删除评测场景

DELETE /api/scenarios/{id}

五、评测执行 API

5.1 列出所有评测记录

GET /api/runs

响应：

[
  {
    "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 启动评测任务

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

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

响应：创建的评测记录 JSON

5.3 获取评测记录详情

GET /api/runs/{id}

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

GET /api/runs/{id}/logs

响应：

[
  {
    "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）

GET /api/reports/{run_id}

响应：

{
  "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）

GET /api/reports/{run_id}/html

响应：HTML 文档

七、错误响应

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

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

常见错误码：

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

八、CORS 配置

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