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]

命令行参数

示例

# 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]

命令行参数

示例

# 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

仪表板功能

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

📊 概述选项卡

• 直方图所有指标下的分数分布
• 总结统计总题数、成功率、平均分
• 绩效指标彩色编码指标（红色表示\=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. 超时问题为复杂问题增加超时时间值