# AgentEvalTool 快速开始指南

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

---

## 一、简介

AgentEvalTool 是一个智能体质量评估工具集平台，用于评估 AI 数字员工和 AI 助手的服务质量。本指南帮助你在 5 分钟内完成首次评测。

## 二、前置要求

- Python 3.10+
- Node.js 18+（如需 Web 界面）
- tutu-api 配置文件（包含 token 等连接信息）

## 三、安装

### 3.1 安装后端

```bash
# 克隆项目
git clone <repository-url>
cd AgentEvalTool

# 安装依赖（editable 模式）
pip install -e ".[dev]"
```

### 3.2 配置 tutu-api

创建配置文件 `config/config.json`：

```json
{
  "base_url": "https://api.example.com",
  "token": "your-jwt-token",
  "tenant": "your-tenant-id",
  "chat_channel_id": "your-channel-id",
  "chat_contact_id": "your-contact-id"
}
```

**注意**：token 有效期为 30 天，需定期更新。

## 四、首次评测

### 4.1 添加评测对象

```bash
agenteval target add --name "社区医院AI客服" --config config/config.json
```

记录输出的 target-id。

### 4.2 导入评测场景

使用示例场景或创建自己的场景文件：

```bash
agenteval scenario import data/scenarios/health_basic.yaml
```

记录输出的 scenario-id。

### 4.3 执行评测

```bash
agenteval run start --target-id <target-id> --scenario-id <scenario-id>
```

评测过程会实时显示进度：
- 每个用例的执行状态
- 每轮对话的响应时间
- 每条规则的评估结果

### 4.4 查看报告

```bash
# JSON 格式
agenteval report show <run-id> --format json

# HTML 格式
agenteval report generate <run-id> --format html
```

HTML 报告保存在 `data/reports/` 目录。

## 五、启动 Web 界面（可选）

### 5.1 启动后端服务

```bash
agenteval server start --host 0.0.0.0 --port 8000
```

### 5.2 启动前端开发服务器

```bash
cd frontend/web
npm install
npm run dev
```

访问 `http://localhost:5173` 查看 Web 界面。

## 六、验证安装

### 6.1 检查 CLI 安装

```bash
agenteval --help
```

应显示帮助信息。

### 6.2 检查服务健康

```bash
curl http://localhost:8000/api/health
```

应返回 `{"status":"ok"}`。

### 6.3 测试通道连通性

```bash
agenteval target test <target-id>
```

应返回"通道正常"。

## 七、下一步

- 阅读 [用户使用指南](user-guide-v1.0.md) 了解详细功能
- 阅读 [CLI 命令参考](../api-reference/cli-v1.0.md) 查看所有命令
- 阅读 [架构设计文档](../architecture-v1.0.md) 了解系统设计

## 八、常见问题

### Q: 评测失败，提示"通道连接失败"

**A**: 检查 `config/config.json` 中的配置是否正确，特别是 token 是否过期。

### Q: 前端无法访问

**A**: 确保后端服务已启动，并检查端口是否被占用。

### Q: 如何查看历史评测记录

**A**: 使用 `agenteval run list` 查看所有记录，或使用 Web 界面查看。

## 九、获取帮助

- 查看 [文档索引](../README.md)
- 提交 Issue 或联系 AgentEval Team