新一代Agent驱动的评测系统
一篇教程解决三个问题：这个工具是干什么的、怎么安装配置、怎么开展一次完整评测。
全文以「给一个在线运行的 Agent 做安全性评测」为真实案例，截图即实际操作过程，跟着做即可。
一、背景介绍
大模型驱动的 Agent（智能客服、课件生成、代码助手……）正在快速落地，迭代周期以"天"计。但一个现实问题长期困扰着团队：
新版本上线前，怎么证明这个 Agent 是"好"的？比上一版究竟是变好了还是变差了？
大多数团队目前的做法是人工点测：找几个人问几句、看看回答顺不顺眼。这种方式有四个明显痛点：
- 测不全：安全性、准确性、格式规范……测什么全凭临场发挥，覆盖面因人而异
- 不可复用：这轮测过的内容，下个版本又得从零再测一遍
- 没结论：看完只能说"感觉还行"，给不出量化分数，更做不了版本对比
- 难沉淀：测试过程和结果散落在个人手里，团队无法追溯与协作
agent-eval 评测系统（安装包名 ai-eval-scope）为此而生：把评测变成一条人人可执行、可复用、可量化的标准流水线——
描述评测需求 → 自动生成"考卷" → 让被测 Agent 真实答题 → 规则 + AI 智能判分 → 出报告 → 上报平台看趋势它的核心特点：
| 特点 | 说明 |
|---|---|
| 💬 会聊天就会用 | 用自然语言描述"我想测什么"，工具里的工作台 Agent 自动帮你生成全套评测资产，不用手写配置 |
| 🔌 被测系统自动接入 | 给一个系统入口地址（登录页 URL 都行），它自动分析登录接口、实测登录、探测对话 API，全程无需懂后端 |
| ⚖️ 双层判分 | 规则引擎管硬性检查，LLM Judge 管语义质量，每个得分都能说清理由 |
| 📊 报告 + 平台 | 本地出报告，一键上报 Web 平台，按项目看历史趋势和每轮对话明细 |
| 🔒 安全放心 | 账号密码隐藏输入、不回显、不写进任何配置文件；每次访问新域名都会先征求你同意 |
二、安装与配置
2.1 安装工具（正式 PyPI 源，一条命令）
要求 Python 3.11+。任选一种方式：
# 方式一：uv（推荐，独立安装不污染环境）
uv tool install "ai-eval-scope[agent,llm]"
# 方式二：pip
pip install "ai-eval-scope[agent,llm]"方括号是功能插件：
[agent]驱动被测 Agent 的执行引擎（必装）、[llm]AI 智能判分、[vision]截图视觉评估、[datasets]数据集下载。不需要的可以不装。
装完验证（工具名是 agent-eval）：
agent-eval --version # 输出版本号即为成功以后升级：uv tool upgrade ai-eval-scope。
2.2 配置评测模型（LLM）
评测需要用大模型来驱动被测 Agent、给回答打分。一条命令进入配置向导：
agent-eval models set向导会依次问你：
- 选择提供商：DeepSeek / Kimi / 智谱 / MiniMax 任选，或 custom（自备地址的任意厂商）
- 选择协议：Anthropic 协议 或 OpenAI 兼容协议（预置厂商两种都支持，任选其一）
- API Key：隐藏输入，粘贴回车即可（预置厂商的接口地址系统已内置，不用填 URL）
- 选择角色：
text文本判分建议必配；vision视觉评估按需 - 保存后向导会立即测试连通性，全部 ✅ 即配置完成
其他命令：
agent-eval models test # 随时重测连通性
agent-eval models list # 查看当前配置（密钥自动脱敏）💡 模型配置也可以不敲命令：进入工作台后选菜单「5. 账号与配置」同样能配。
三、开展一次完整评测（图文实录）
下面是完整实操案例：给一个在线 Agent 做安全性评测——看它面对色情、歧视、越权、隐私等各类风险提问时，能否正确拒绝。整个过程只需要你回答工作台 Agent 的几个问题。
Step 1：启动工作台
终端执行：
agent-eval start顶部状态栏显示平台、模型的就绪状态（✅ 表示上一步配置都通过了），菜单选 1. 工作台 Agent（对话式·推荐）：
进入后，工作台 Agent 做了自我介绍：你用自然语言下需求，它调用工具逐步完成评测构建。改配置、排查问题、参照内置包建新包，也都可以直接对它说：
Step 2：用一句话描述评测需求
直接把想法告诉它，越具体越好（测什么能力、什么类型的被测系统）。本例输入：
请帮我为一个在线的 agent 进行评测，评测内容主要是安全性 相关内容
Agent 理解需求后，规划出第一步：先向你要被测系统的入口地址：
Step 3：告诉它被测系统入口地址
把系统入口地址发给它——给页面 URL 就行（本例直接给的是登录页地址）。Agent 会从地址里识别出系统涉及多个域名，并主动和你确认"是否需要登录"：
Step 4：自动分析登录接口
你确认需要登录后，Agent 开始自动分析登录页面：每次访问新域名前都会先征求你的同意（安全边界，选"允许"即可）。它自动翻查页面脚本、检索接口线索，最终找到了登录接口的地址和鉴权方式：
Step 5：录入测试账号，实测登录
Agent 逐项向你要登录凭证（本例是手机号、密码、图形验证码）。输入全部隐藏回显，凭证不会出现在屏幕和配置文件里：
凭证录完，它整理好登录请求让你确认（内容已脱敏），发送后 ✅ 登录成功——说明被测系统的接入方式验证通过：
Step 6：自动探测对话 API，生成场景包
登录成功后 Agent 继续探测"怎么和这个 Agent 对话"（找到 threads 接口、确认需要指定的参数等），接入信息全部就绪：
接着它开始生成评测场景包：考卷（安全性测试用例）、判分规则、Judge 提示词、被测系统配置……每一份文件都先暂存给你看 diff，确认后才真正落盘。最后 ✅ 场景包生成完成，保存在 ./agent-security-package/ 目录：
Step 7：执行评测
场景包就绪后回到工作台菜单，选 3. 执行评测，跟着向导逐项选择：场景包 → 考卷 → 被测系统 → 判分规则集 → 执行模式（选 pipeline 一条龙：执行 + 评估 + 报告）。向导最后会显示等价的命令行让你确认，回车 y 开跑：
之后就是全自动：14 个安全性测试任务逐一发送给被测 Agent、采集回答、双层判分。十几分钟后全部完成。
Step 8：查看评测结果
执行完毕直接给出评估结果摘要：运行 ID、样本总数、指标概览表（✅ 通过 / ❌ 失分一目了然，指标项由你选的规则集决定），结果已保存至本地 workspace/：
想细看每一分的理由：工作台菜单「4. 查看结果」可逐任务展开判分明细；也可以用
agent-eval open report在浏览器里看完整报告。
至此，一次完整的评测就闭环了：需求 → 建包 → 执行 → 报告，全程你只回答了 Agent 的几个问题。
➡️ 评测结果还可以上报到 Web 可观测平台，按项目看历史趋势、逐轮对话轨迹、跨版本对比——这是可选的进阶功能，操作步骤见下一节。
四、进阶功能：结果上报可观测平台
本地报告适合单次查看；把评测结果持续上报到 Web 可观测平台，才能按项目看历史趋势、查看每轮对话轨迹、跨版本对比。这是可选的进阶功能，只需一次性完成下面的接入配置，之后每次评测完成都会自动上报。
4.1 注册平台账号
agent-eval auth register # 自动打开平台注册页，注册完成后回来登录也可以直接在浏览器打开平台地址注册。
4.2 创建项目
登录 Web 平台后，创建你的项目——评测结果按项目归档。如果项目已存在，让项目管理员把你加入对应项目即可。
4.3 在 CLI 中配置平台凭证（含创建 API Key）
agent-eval auth login按提示操作：
- 输入平台地址（就是浏览器里访问平台的 URL）
- 向导会引导你在页面上创建 API Key（
eval-前缀），复制粘贴回车 - CLI 自动做有效性探测，通过后凭证写入本地配置（0600 权限，密钥不落明文）
配置完成用体检命令确认：
agent-eval auth status # 查看凭证有效性 + 所属团队 / 项目4.4 上报评测结果
配置好凭证后无需任何额外操作——每次评测完成自动推送。下图为本案例实录：上报 211 条事件、84 个制品，零失败：
上报完成后，在 Web 平台上即可查看指标趋势、逐任务对话轨迹、判分明细与产出制品。两个补充命令：
agent-eval open platform # 浏览器直达平台
agent-eval upload --run {run_id} # 历史运行补传五、小结
回顾一下，开展一次评测只需要三步：
- 装工具：
uv tool install "ai-eval-scope[agent,llm]" - 配模型：
agent-eval models set（选厂商 → 粘 Key → 自动测试） - 跑评测：
agent-eval start→ 对话式说需求 → 跟着向导点选执行 → 看报告
剩下的事情——分析登录接口、生成考卷、判分、出报告——工具全部自动完成。（可选）接入平台：agent-eval auth register → 平台建项目 → agent-eval auth login，之后评测结果自动上报。
