AgentEvalTool/docs/guides/user-guide-v1.0.md

AgentEvalTool 用户使用指南

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

---

一、概述

本指南详细介绍 AgentEvalTool 的各项功能和使用方法，帮助用户充分利用平台进行智能体质量评估。

二、评测对象管理

2.1 添加评测对象

评测对象代表被评估的智能体服务。

agenteval target add --name "对象名称" --config config/config.json

参数说明：

• --name: 对象名称（必填）
• --config: 通道配置文件路径（必填）

配置文件格式（tutu-api）：

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

2.2 查看评测对象

# 列出所有对象
agenteval target list

# 查看对象详情
agenteval target get <id>

2.3 更新评测对象

agenteval target update <id> --config config/config.json

2.4 删除评测对象

agenteval target remove <id>

2.5 测试连通性

agenteval target test <id>

验证消息通道是否正常连接。

三、评测场景管理

3.1 场景文件格式

评测场景使用 YAML 格式定义：

name: 场景名称
description: 场景描述
tags:
  - tag1
  - tag2
cases:
  - id: case-001
    type: single  # single 或 multi_turn
    messages:
      - "你好，我想咨询一个问题"
    expectations:
      keywords:
        - "你好"
        - "咨询"
      excluded_keywords:
        - "错误"
    eval_rules:
      - type: keyword_match
        config:
          keywords: ["你好", "咨询"]
      - type: response_time
        config:
          threshold_ms: 30000

3.2 导入场景

agenteval scenario import path/to/scenario.yaml

3.3 校验场景

agenteval scenario validate path/to/scenario.yaml

3.4 导出场景

agenteval scenario export <id> > path/to/scenario.yaml

3.5 查看场景

# 列出所有场景
agenteval scenario list

# 查看场景详情
agenteval scenario get <id>

3.6 删除场景

agenteval scenario remove <id>

四、评测执行

4.1 启动评测

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

可选参数：

• --output-json: 运行结束后输出 JSON 报告

执行过程：

1. 验证对象和场景存在
2. 逐个执行用例
3. 发送消息并等待回复
4. 应用评估规则
5. 记录结果
6. 生成摘要

4.2 查看评测状态

agenteval run status <run-id>

4.3 查看评测列表

agenteval run list

4.4 查看评测日志

agenteval run logs <run-id>

显示所有对话轮次的详细信息。

五、报告管理

5.1 查看报告（JSON）

agenteval report show <run-id> --format json

报告内容：

• 运行基本信息（ID、对象、场景、时间）
• 执行摘要（总用例数、通过数、失败数、通过率）
• 用例详情（每轮对话、评估结果）

5.2 生成报告（HTML）

agenteval report generate <run-id> --format html

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

5.3 对比报告

agenteval report compare <run-id-1> <run-id-2>

对比两次评测的结果差异。

六、评估规则

6.1 关键词匹配规则（keyword_match）

检查回复是否包含指定关键词。

eval_rules:
  - type: keyword_match
    config:
      keywords: ["关键词1", "关键词2"]
      excluded_keywords: ["排除词1"]

6.2 响应时间规则（response_time）

检查响应时间是否在阈值内。

eval_rules:
  - type: response_time
    config:
      threshold_ms: 30000  # 30秒

6.3 LLM 评分规则（llm_score）

调用 LLM 对回复质量打分（需配置外部 LLM API）。

eval_rules:
  - type: llm_score
    config:
      api_url: "https://api.openai.com/v1/chat/completions"
      api_key: "your-api-key"
      model: "gpt-4"
      prompt_template: "请评估以下回复的质量：{reply}"
      min_score: 0.7

七、Web 界面

7.1 启动服务

# 启动后端
agenteval server start --host 0.0.0.0 --port 8000

# 启动前端（开发模式）
cd frontend/web
npm install
npm run dev

7.2 功能页面

• 首页：评测运行概览
• 评测对象页：列表、新增/编辑、连通性测试
• 评测场景页：列表、YAML 在线编辑、校验
• 评测执行页：运行列表、实时日志、触发运行
• 报告页：报告列表、报告详情（得分、明细、失败项）

八、OpenClaw 集成

8.1 插件调用方式

OpenClaw 通过调用 CLI 完成评测：

import subprocess

# 触发评测
subprocess.run([
    "agenteval", "run", "start",
    "--target-id", "<target-id>",
    "--scenario-id", "<scenario-id>",
], check=True)

# 获取报告
report = subprocess.check_output([
    "agenteval", "report", "show", "<run-id>", "--format", "json",
])

8.2 定时评测

在 OpenClaw 中配置定时任务：

skill: agenteval_skill
schedule: "0 9 * * *"  # 每天早上 9 点
config:
  target_id: "<target-id>"
  scenario_id: "<scenario-id>"
  report_format: "json"

九、最佳实践

9.1 场景设计

• 覆盖核心业务场景
• 包含正常和异常用例
• 设置合理的响应时间阈值
• 使用多维度评估规则

9.2 Token 管理

• 定期检查 token 有效期
• 建立 token 更新流程
• 使用环境变量或密钥管理服务

9.3 数据备份

• 定期备份 data/ 目录
• 导出重要场景文件
• 保留关键评测报告

9.4 性能优化

• 避免并发评测同一目标
• 合理设置响应时间阈值
• 使用 LLM 评分时注意成本

十、故障排查

10.1 通道连接失败

原因：

• Token 过期
• 网络问题
• 配置错误

解决：

# 测试连通性
agenteval target test <id>

# 检查配置
cat config/config.json

10.2 评测超时

原因：

• 目标智能体响应慢
• 阈值设置过低

解决：

• 调整 response_time 规则的 threshold_ms
• 检查目标智能体状态

10.3 报告生成失败

原因：

• 数据目录权限问题
• 磁盘空间不足

解决：

# 检查权限
ls -la data/

# 检查磁盘空间
df -h data/

十一、获取帮助

• 快速开始指南
• CLI 命令参考
• Web API 参考
• 架构设计文档
• 部署文档