AI导哈

AI代理评估工具包

一个用于评估基于模型上下文协议（MCP）的AI代理的全面工具包，包括数据集管理、自动化评估和Web可视化功能。

  • by smaht-ai
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 smaht-ai/smaht-agent-kit

使用说明

智能代理工具包

MCP驱动的AI代理入门套件：包含示例客户端、评估工具以及适用于Claude Code及更多场景的轻松集成指南。

概述

本工具包提供了一个全面的评估框架，用于测试由模型上下文协议（MCP）工具驱动的人工智能代理。它包括：

  • 数据集管理用于测试人工智能代理能力的结构化真实数据集
  • 自动化评估： copilot_evaluator.py 用于针对测试问题运行Claude代码
  • 网页可视化: copilot_web_visualizer.py 用于评估结果的交互式分析

数据集结构

评估数据集按照特定结构组织在……之下 datasets/ 目录。根据需要更新此目录，添加带有提示和预期结果的Question（问题）项目。

datasets/
└── copilot/
    ├── groundtruth.json          # Main dataset configuration
    ├── Question1/
    │   └── Prompt.txt            # Test prompt for Question1
    └── Question2/
        └── Prompt.txt            # Test prompt for Question2

数据集配置 (groundtruth.json）

主要的数据集文件定义了测试问题及其结构：

{
  "questions": [
    {
      "question_id": "Question1",
      "prompt": "Question1/Prompt.txt",
      "input": [],
      "output": [
      ],
      "snapshots": [
      ]
    }
  ]
}

字段：

  • question_id问题的唯一标识符
  • prompt提示文件的路径（相对于数据集目录）
  • input输入文件列表（当前未使用）
  • output预期用于比较的输出文件列表（目前未使用）
  • snapshots参考截图列表（目前未使用）

问题结构

每个问题目录包含：

  • **Prompt.txt**将发送给AI代理的测试提示
  • **Output/**包含预期输出文件（XML、JSON 等）的目录
  • **Snapshot/**包含用于视觉比较的参考截图的目录

Copilot 评估器copilot_evaluator.py)

评估者使用Claude Code对来自真实数据集的问题进行处理，并执行自动化评估。

用法

python copilot_evaluator.py --dataset datasets/copilot/groundtruth.json [options]

命令行参数

参数 描述 默认值
--dataset 到真实值JSON文件的路径 必需的
--question-ids 要运行的具体问题ID（使用'all'表示所有问题） []
--output 结果输出的基础目录 output
--mcp-config MCP 配置文件的路径 conf/.mcp.json
--claude-md CLAUDE.md 文件的路径 conf/CLAUDE.md
--log-level 日志级别（DEBUG，INFO，WARNING，ERROR） INFO
--timeout 每次执行的超时时间（例如，'600s'（600秒），'5m'（5分钟），'1h'（1小时）） 10m
--debug 启用调试模式 True
--max-turns 每次执行的最大对话轮次 50
--checkpoint 用于恢复的 checkpoint.json 文件路径 None
--skip-eval 跳过运行评估 False
--force-eval 强制重新计算所有评估 False

示例

# Run all questions
python copilot_evaluator.py --dataset datasets/copilot/groundtruth.json

# Run specific questions
python copilot_evaluator.py --dataset datasets/copilot/groundtruth.json --question-ids Question1 Question2

# Run with custom timeout and max turns
python copilot_evaluator.py --dataset datasets/copilot/groundtruth.json --timeout 15m --max-turns 100

# Resume from checkpoint
python copilot_evaluator.py --checkpoint output/copilot_evaluator_20250113_120000/checkpoint.json

输出结构

评估器创建带有时间戳的输出目录：

output/
└── copilot_evaluator_20250113_120000/
    ├── checkpoint.json                    # Progress tracking
    ├── results_20250113_120500.json      # Summary results
    ├── logs/
    │   └── claude_code_runner_20250113_120000.log
    ├── Question1/
    │   ├── .claude/
    │   │   └── settings.local.json       # Claude configuration
    │   ├── .mcp.json                     # MCP configuration
    │   ├── CLAUDE.md                     # Generated documentation
    │   ├── claude_code_result.json       # Execution results
    │   └── [generated files]             # AI agent outputs
    ├── Question1_eval/
    │   ├── claude_code_result.json       # Evaluation execution
    │   ├── eval_result.json              # Evaluation scores
    │   └── eval_validation_tools.json    # Validation tool usage
    └── Question2/
        └── [similar structure]

评估指标

评估者从四个关键维度来衡量绩效：

  1. 准确性问题回答正确的百分比
  2. 完整性问题完全回答的百分比
  3. 验证通过MCP工具验证的百分比（例如，SSL语法、XFD表单验证）

每个指标按0-1分打分，并以Markdown格式提供详细的理由说明。

网页可视化工具（copilot_web_visualizer.py）

基于网页的交互式仪表板，用于分析评估结果，支持图表展示、详细细分以及导出功能。

用法

python copilot_web_visualizer.py results.json [options]

命令行参数

参数 描述 默认值
results_file 结果JSON文件的路径 必需的
--port 运行服务器的端口 3002
--no-browser 不要自动打开浏览器 False
--no-debug 禁用调试模式和自动重载 False

示例

# View results with auto-browser opening
python copilot_web_visualizer.py output/copilot_evaluator_20250113_120000/results_20250113_120500.json

# Run on custom port without opening browser
python copilot_web_visualizer.py results.json --port 8080 --no-browser

仪表板功能

网页可视化工具提供了四种主要视图：

📊 概述选项卡

  • 直方图所有指标下的分数分布
  • 总结统计总题数、成功率、平均分
  • 绩效指标彩色编码指标（红色表示<0.25，橙色表示<0.5，黄色表示<0.75，绿色表示≥0.75）

🎯 雷达标签页

  • 雷达图多维度性能可视化
  • 平均分所有评估指标的综合视图
  • 交互式的悬停以查看详细分数细分

📈 时间线标签

  • 性能趋势显示问题序列中各项指标的折线图
  • 多个指标准确性、完整性、真实值（或“实际数据”）、验证、待办事项完成
  • 模式分析识别性能趋势和异常值

📋 分析选项卡

  • 详细表格逐题解析
  • 交互元素:
    • 将鼠标悬停在提示标签上以查看完整提示
    • 点击成功指标以查看错误详情
    • 查看步数统计并细分工具使用情况
    • 访问单个问题的详细页面
  • 导出选项下载单个结果或完整数据集

个人问题详情

点击任意问题ID查看详细分析：

  • 📈 概述评分细节及理由说明
  • **💬 提示（或指令）**完整测试提示文本
  • 🔄 步骤详细的执行步骤及工具使用方法
  • 🗂️ 输出生成的文件和内容
  • 🎯 真实情况/真实数据预期的输出文件，用于比较
  • ✅ 待办事项任务完成跟踪
  • 🧾 完整结果包含树形/文本视图的完整JSON数据

主要特点

  • 实时提示信息将鼠标悬停在任意元素上以查看详细信息
  • Markdown 支持推理文本支持完整的Markdown格式
  • 响应式设计在桌面和移动设备上均可使用
  • 出口能力将结果下载为JSON文件或单独文件
  • 交互式图表由Plotly驱动，实现丰富的数据可视化

设置和依赖项

先决条件

  • Python 3.8或更高版本
  • Claude CLI 已安装并配置
  • MCP工具已正确配置
  • ANTHROPIC_API_KEY（ANTHROPIC API密钥） .env 文件

安装

pip install -r requirements.txt

所需的依赖项

  • flask>=2.3.0 - 可视化工具的Web服务器
  • plotly>=5.15.0 - 交互式图表
  • python-dotenv>=1.0.0 - 环境变量管理
  • aiohttp>=3.9.0 - 异步HTTP操作
  • markdown>=3.4.0 - Markdown 渲染

工作流程

  1. 准备数据集创建或修改问题 datasets/copilot/
  2. 运行评估执行 copilot_evaluator.py 使用你的数据集
  3. 分析结果使用 copilot_web_visualizer.py 查看并分析结果
  4. 迭代根据需要修改提示、添加问题或调整评价标准

配置

MCP配置

确保您的MCP配置文件（通常为 conf/.mcp.json) 已正确设置为：

  • 所需的MCP服务器
  • API密钥的环境变量
  • 工具权限

环境变量

创建一个 .env 与以下文件一起：

ANTHROPIC_API_KEY=your_api_key_here

故障排除

常见问题

  1. 未找到Claude代码确保已安装 Claude Code CLI 并将其添加到 PATH 中
  2. MCP工具无法正常工作验证MCP配置和服务器状态
  3. 权限错误检查输出目录的文件权限
  4. 超时问题为复杂问题增加超时时间值

相关 MCP