开源项目 | Agent Runtime Evaluation Platform — AI Agent 运行时全维度质量评估平台 GitHub: https://github.com/daetz-coder/Agent-Runtime-Evaluation-Platform License: MIT | Author: zhanyong | ️ Tags: AI Agent, 评估平台, LLM-as-Judge, LangGraph, FastAPI, RAG前言随着 AI Agent 在生产环境中的广泛应用如何科学地评估 Agent 的运行质量成为了一个关键问题。传统的评估方式存在以下局限性只关注结果忽略过程— 仅评估最终回答的质量无法反映 Agent 的决策能力缺乏标准化— 不同团队使用不同的评估方法结果难以对比无法定位问题— 当 Agent 表现不佳时难以确定是哪个环节出了问题缺乏实时性— 评估通常是离线的无法在 Agent 运行过程中提供反馈Agent Runtime Evaluation Platform正是为了解决这些问题而诞生的。本文将深入介绍这个开源项目的设计理念、技术架构、核心功能以及实际使用方法。一、项目简介Agent Runtime Evaluation Platform是一个全栈 AI Agent 评估系统核心理念是不仅评估最终回答质量更评估 Agent 在执行过程中的决策质量。1.1 核心能力平台通过 SDK 采集 Agent 的运行轨迹Trajectory然后使用LLM-as-Judge从 6 个维度对轨迹进行量化评分规划质量Planning— Agent 是否制定了合理的执行计划战术决策Tactical— 每一步决策是否合理高效工具使用Tool Use— 工具调用是否正确且高效记忆保持Memory— 是否有效利用历史信息重规划Replan— 遇到失败后是否合理调整策略检索质量Retrieval— RAG 检索是否精准可靠1.2 核心数据指标数值说明评估维度 × 子指标6 × 3~4 20 项覆盖 Agent 执行全生命周期轨迹动作类型14 种Pydantic Schema 约束类型安全SDK 接入模式3 种Instrument / Proxy / Callback单次全评估耗时15~30s6 评估器 asyncio.gather 并行检索基准Wiki AgentTop-1:75%, MRR:0.825四级混合检索效果综合分单调递减验证93.1 → 20.0评估器可信度验证二、评估体系详解2.1 六维评估模型平台的核心是6 维评估体系每个维度有 3~4 个子指标共计 20 项维度权重子指标评估重点规划质量Planning20%覆盖率、顺序性、粒度、完整性Agent 是否制定了合理的执行计划战术决策Tactical20%相关性、效率、正确性每一步决策是否合理高效工具使用Tool Use15%选择质量、参数准确性、结果利用工具调用是否正确且高效记忆保持Memory15%保持力、相关性、一致性是否有效利用历史信息重规划Replan15%触发适当性、适应质量、学习能力遇到失败后是否合理调整策略检索质量Retrieval15%相关性、证据准确性、覆盖度 幻觉检测RAG 检索是否精准可靠2.2 质量等级划分┌─────────────────────────────────────────────────────────┐ │ 质量等级划分 │ ├─────────────┬─────────────┬─────────────┬───────────────┤ │ 优秀 │ 良好 │ 一般 │ 较差 │ │ ≥ 80 分 │ ≥ 60 分 │ ≥ 40 分 │ 40 分 │ └─────────────┴─────────────┴─────────────┴───────────────┘2.3 智能权重归一化当某个维度不适用时例如 Agent 没有使用检索系统会自动标记并从加权总分中剔除权重重新归一化# 示例如果没有检索行为原始权重{planning:0.20,tactical:0.20,tool_use:0.15,memory:0.15,replan:0.15,retrieval:0.15# 不适用}归一化后{planning:0.235,# 0.20 / 0.85tactical:0.235,tool_use:0.176,memory:0.176,replan:0.176,retrieval:0.0# 已剔除}三、系统架构3.1 整体架构图┌─────────────────────────────────────────────────────────────────────┐ │ Frontend (Vue 3 ECharts) │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Dashboard │ │ Evaluation │ │ Wiki │ │ │ │ 仪表盘 │ │ 评估详情 │ │ 知识管理 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └───────────────────────────────┬─────────────────────────────────────┘ │ HTTP / SSE ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ FastAPI Server (Async 全链路) │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Middleware Chain │ │ │ │ CORS → CorrelationId → Auth → RateLimit → Prometheus │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Tasks API │ │Evaluations │ │ Reports │ │ │ │ 任务管理 │ │ 评估引擎 │ │ 报表分析 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Wiki Agent │ │ Benchmark │ │ System │ │ │ │ RAG 知识库 │ │ 基准测试 │ │ 系统管理 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └───────────────────────────────┬─────────────────────────────────────┘ │ ┌───────────────────────┼───────────────────────┐ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ SDK │ │ Evaluators │ │ Database │ │ Collector │ │ × 6 并行 │ │ SQLite / PG │ │ │ │ │ │ │ │ Pydantic │ │ LLM-as-Judge │ │ SQLAlchemy │ │ Schema │ │ 共识评估 │ │ Async │ └───────────────┘ └───────────────┘ └───────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ AI Model Layer │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ DeepSeek │ │ GLM-4 │ │ Qwen-Plus │ │ │ │ 推理 评估 │ │ 推理 评估 │ │ 推理 评估 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────────────┘3.2 数据流Agent 运行 → SDK 采集轨迹 → 存储到 DB → 触发评估 → 6 维并行评分 → 汇总报告 │ │ │ ← SSE 实时推送评估进度 ← │ └──────────────────────────────────────────────────────────────┘3.3 技术栈类别技术版本用途后端框架FastAPI Uvicorn0.109REST API SSE 实时流Agent 编排LangGraph LangChain0.2Agent 状态图、评估工作流AI 模型DeepSeek / GLM / Qwen / OpenAI-LLM 推理 LLM-as-Judge向量检索Milvus BM25 RRF Cross-Encoder2.4四级混合检索数据库SQLAlchemy Async SQLite / PostgreSQL2.0持久化存储缓存Redis可选7.2LLM 响应缓存、限流前端Vue 3 TypeScript Element Plus ECharts3.5管理面板与可视化SDKPython SDKPydantic httpx-零侵入轨迹采集四、关键特性详解4.1 Pydantic Schema SDK — 类型安全的轨迹采集平台定义了14 种标准动作类型ActionType每种类型都有独立的 Pydantic 模型# 14 种 ActionType 分类规划类:-PLAN# 初始规划-PLAN_UPDATE# 动态规划更新-REPLAN# 重规划工具类:-TOOL_CALL# 工具调用-TOOL_RESULT# 工具返回-TOOL_DECISION# 工具选择决策记忆类:-MEMORY_WRITE# 记忆写入-MEMORY_READ# 记忆读取状态类:-STATE_CHANGE# 状态变化-NODE_EXECUTE# 节点执行思考类:-THINK# 思考过程异常类:-FAILURE# 失败/异常事件检索类:-RETRIEVAL# 知识库检索-EVIDENCE# 证据池构建每种 ActionType 都有对应的 Pydantic SchemaclassToolCallDetail(BaseModel):工具调用详情tool_name:strinput_data:Dict[str,Any]output_data:Optional[Any]Nonesuccess:boolTrueduration_ms:Optional[float]Noneerror_message:Optional[str]None4.2 三种接入模式模式 1: LangGraph 自动采集推荐fromsdkimportinstrument_langgraph# 一行接入自动记录所有节点执行、状态变化、工具调用graphinstrument_langgraph(build_graph())# 运行resultawaitgraph.ainvoke(state,config)模式 2: LangChain LLM Proxyfromsdkimportcreate_proxy_llmfromlangchain_openaiimportChatOpenAI# 替换 LLM自动记录所有 LLM 调用llmcreate_proxy_llm(ChatOpenAI(modelgpt-4))# 正常使用responseawaitllm.ainvoke(Hello)模式 3: 手动记录任意框架fromsdk.collectorimportget_collector collectorget_collector()# 开始任务collector.start(实现用户登录功能,context{key_facts:[使用JWT]})# 记录轨迹collector.record_retrieval(JWT 认证,results,duration_ms120)collector.record_tool_call(sandbox,{code:...},result)collector.record_think(分析测试结果)# 结束任务 触发评估collector.finish(auto_runTrue)4.3 多模型共识评估为了提升评估的可信度平台支持多个 LLM 独立评分然后计算均值和方差# API 调用POST/api/v1/evaluations/consensus{task_id:xxx,models:[deepseek-chat,glm-4-plus,qwen-plus]}# 响应示例{mean_score:78.5,std_score:3.2,# 标准差越小 一致性越高 越可信model_count:3,individual_scores:{deepseek-chat:80,glm-4-plus:76,qwen-plus:79.5}}4.4 四阶段轨迹压缩为了减少 LLM Judge 的 token 消耗平台实现了 4 阶段压缩管线原始轨迹 │ ▼ ┌─────────────────────────────────────┐ │ Stage 1: 重要性过滤 │ │ 保留高价值 action_type │ │ (PLAN, TOOL_CALL, RETRIEVAL 等) │ └─────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ Stage 2: Think 截断 │ │ 长思考步骤截断到 200 字符 │ └─────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ Stage 3: 滑动窗口 │ │ 保留最近 30 步 │ │ (plan/failure 锚点兜底) │ └─────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ Stage 4: 格式化输出 │ │ 结构化文本送给评估器 │ └─────────────────────────────────────┘ │ ▼ 压缩后的轨迹4.5 SSE 流式评估评估进度实时推送到前端支持 6 维度并行评估# 客户端代码importhttpxasyncwithhttpx.AsyncClient()asclient:asyncwithclient.stream(POST,/api/v1/evaluations/stream,json{...})asresponse:asyncforlineinresponse.aiter_lines():ifline.startswith(data:):datajson.loads(line[5:])print(f维度{data[dimension]}:{data[score]}分)4.6 增量评估与回归检测当轨迹发生变化时系统会自动检测受影响的维度只重算变化部分# 增量评估 APIPOST/api/v1/evaluations/incremental{evaluation_id:xxx,new_trajectory:[...]}# 响应{reused_dimensions:[planning,tactical],# 复用原有评分re_evaluated_dimensions:[tool_use,memory],# 重新评估overall_score:82.5}4.7 Replay 调试器可以回放 Agent 执行的每一步查看原始的 LLM Prompt 和 Response# APIGET/api/v1/evaluations/{id}/replay# 响应{steps:[{step:1,action_type:plan,timestamp:2026-07-07T10:00:00Z,llm_trace:{model:deepseek-chat,prompt:...,response:...,latency_ms:1200}},...]}五、功能演示5.1 评估流程演示演示内容创建评估任务6 维度并行评估实时推送评估进度评估结果展示雷达图、详细分数、反馈5.2 Wiki Agent — HITL 知识管理演示内容用户发起对话AI 检索知识库并回复AI 识别到需要更新知识库暂停等待用户确认Human-in-the-Loop用户确认后自动执行 CRUD 操作5.3 系统管理演示内容系统健康检查Sessions、Messages、Checkpoints 状态BM25、Vectors 索引状态Redis 缓存状态六、快速开始6.1 环境要求依赖版本必需Python3.11✅Node.js18✅前端Redis7.2❌可选用于缓存PostgreSQL14❌可选默认 SQLite6.2 安装步骤# 1. 克隆项目gitclone https://github.com/daetz-coder/Agent-Runtime-Evaluation-Platform.gitcdAgent-Runtime-Evaluation-Platform# 2. 创建虚拟环境推荐python-mvenv venvsourcevenv/bin/activate# Linux/Mac# 或venv\Scripts\activate# Windows# 3. 安装后端依赖pipinstall-e.[dev]# 4. 安装前端依赖cdfrontendnpminstallcd..# 5. 配置环境变量cp.env.example .env# 编辑 .env填入以下配置# DEEPSEEK_API_KEYyour_api_key_here# EVAL_ENABLEDtrue# 6. 启动后端python-mapp.main# 7. 另一个终端启动前端cdfrontendnpmrun dev6.3 访问地址服务地址说明前端仪表盘http://localhost:3000Vue 3 管理界面API 文档http://localhost:8000/docsSwagger UIReDoc 文档http://localhost:8000/redocReDoc 文档健康检查http://localhost:8000/health系统状态七、项目结构Agent-Runtime-Evaluation-Platform/ ├── app/ # 后端应用 │ ├── evaluators/ # 6 个评估器 共识评估 轨迹压缩 │ │ ├── planning_evaluator.py # 规划质量评估器 │ │ ├── tactical_evaluator.py # 战术决策评估器 │ │ ├── tool_use_evaluator.py # 工具使用评估器 │ │ ├── memory_evaluator.py # 记忆保持评估器 │ │ ├── replan_evaluator.py # 重规划评估器 │ │ ├── retrieval_evaluator.py # 检索质量评估器 │ │ ├── consensus.py # 多模型共识引擎 │ │ └── trajectory_compressor.py # 4阶段轨迹压缩 │ ├── graphs/ # LangGraph 评估工作流 │ ├── services/ # 业务逻辑层 │ │ ├── evaluation_service.py # 评估服务 │ │ ├── replay_service.py # Replay 调试器 │ │ ├── judge_service.py # Judge 透明度 │ │ └── incremental_eval.py # 增量评估 │ ├── core/ # 基础设施 │ │ ├── config.py # 配置管理 │ │ ├── cache.py # Redis 缓存 │ │ └── logging.py # 日志配置 │ ├── api/ # REST API 中间件 │ │ └── v1/endpoints/ # API 端点 │ ├── wiki_agent/ # Wiki Agent 子系统 │ │ ├── agent/ # 智能体层 │ │ │ ├── graph.py # LangGraph 编排 │ │ │ ├── context_retriever.py # 四路记忆检索 │ │ │ └── tools/ # 工具集 │ │ │ ├── search_tools.py # 混合搜索 │ │ │ ├── vector_store.py # Milvus 向量存储 │ │ │ └── bm25_index.py # BM25 倒排索引 │ │ ├── wiki/ # 知识管理层 │ │ ├── session/ # 会话管理层 │ │ └── routers/ # API 路由 │ ├── models/ # Pydantic schema 定义 │ └── db/ # SQLAlchemy ORM Alembic 迁移 ├── frontend/ # Vue 3 前端 │ ├── src/ │ │ ├── views/ # 页面组件 │ │ ├── components/ # 通用组件 │ │ └── api/ # API 调用 │ └── package.json ├── sdk/ # 独立 SDK 包 │ ├── collector.py # 轨迹收集器 │ ├── schemas.py # Pydantic Schema │ └── adapters/ # 适配器 │ ├── langgraph.py # LangGraph 适配器 │ ├── llm_proxy.py # LLM Proxy 适配器 │ └── callback.py # LangChain Callback ├── scripts/ # 基准测试脚本 │ ├── benchmark_evaluators.py # 评估器基准 │ ├── benchmark_multimodel.py # 多模型基准 │ └── eval_retrieval_standalone.py # 检索评估 ├── tests/ # 测试 ├── docs/ # 文档 │ ├── architecture.md # 架构文档 │ ├── api.md # API 文档 │ └── developer_guide.md # 开发者指南 ├── pyproject.toml # Python 项目配置 └── README.md # 项目说明八、API 接口概览8.1 评估相关方法路径说明POST/api/v1/evaluations/创建并运行评估POST/api/v1/evaluations/streamSSE 流式评估POST/api/v1/evaluations/quick同步评估阻塞POST/api/v1/evaluations/batch批量评估POST/api/v1/evaluations/consensus多模型共识评估POST/api/v1/evaluations/incremental增量评估GET/api/v1/evaluations/{id}获取评估详情GET/api/v1/evaluations/{id}/replayReplay 调试器GET/api/v1/evaluations/{id}/judge-rawJudge 透明度GET/api/v1/evaluations/diffTrajectory 对比GET/api/v1/evaluations/regression/check回归检测8.2 Wiki Agent方法路径说明POST/api/chat/streamSSE 流式对话POST/api/chat/message同步对话POST/api/chat/confirmHITL 确认/取消GET/api/wiki/tree知识库目录树GET/api/wiki/search?q搜索知识库POST/api/wiki/page/{path}创建页面PUT/api/wiki/page/{path}更新页面DELETE/api/wiki/page/{path}删除页面8.3 系统运维方法路径说明GET/api/v1/system/health健康检查GET/api/v1/system/metricsPrometheus 指标GET/settings/promptsPrompt 版本管理九、Wiki Agent — RAG 知识库问答项目还包含一个完整的Wiki Agent子系统基于 RAG检索增强生成实现知识库问答。9.1 四级混合检索用户查询 │ ▼ ┌─────────────────────────────────────┐ │ Level 1: Query 改写 │ │ LLM 自动优化查询 │ └─────────────────────────────────────┘ │ ├─────────────────┬─────────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Semantic │ │ BM25 │ │ Memory │ │ Search │ │ Search │ │ Search │ │ (Milvus) │ │ (倒排索引)│ │ (用户/会话)│ └──────────┘ └──────────┘ └──────────┘ │ │ │ └─────────────────┼─────────────────┘ ▼ ┌──────────────┐ │ RRF 融合 │ │ (Reciprocal │ │ Rank Fusion)│ └──────────────┘ │ ▼ ┌──────────────┐ │ Cross-Encoder│ │ 重排 │ │ (bge-reranker)│ └──────────────┘ │ ▼ Top-K 结果9.2 双层记忆记忆类型存储位置生命周期用途User MemorySQLite长期用户偏好、历史事实Session Memory内存 Redis短期当前会话上下文9.3 HITL CRUD当 AI 决定修改知识库时会暂停等待用户确认# AI 识别到需要更新知识库# → 暂停执行# → 发送 HITL 请求到前端# → 用户确认/取消# → 继续执行或回滚9.4 四端同步组件用途同步时机Markdown人类可读实时Milvus向量检索异步BM25关键词检索异步Git版本控制提交时十、适用场景10.1 Agent 开发团队在开发过程中持续监控 Agent 质量发现改进方向# 每次代码变更后自动评估POST/api/v1/evaluations/incremental{evaluation_id:previous_eval_id,new_trajectory:[...]}# 查看回归检测GET/api/v1/evaluations/regression/check10.2 Agent 评测竞赛标准化的评估流程支持批量评估和排行榜# 批量评估POST/api/v1/evaluations/batch{task_ids:[task1,task2,task3]}# 获取评估报告GET/api/v1/reports/summary10.3 生产环境监控通过增量评估和回归检测及时发现 Agent 质量退化# 定时回归检测GET/api/v1/evaluations/regression/check?task_idxxxthreshold5# 获取趋势报告GET/api/v1/reports/trends?days3010.4 评估研究为 Agent 评估研究提供标准化的评估框架和基准数据# 运行单调性基准POST/api/v1/benchmark/monotonicity/run# 获取基准结果GET/api/v1/benchmark/monotonicity十一、性能基准11.1 评估器性能指标数值单次评估耗时15~30s并发评估数6asyncio.gatherToken 消耗压缩后约 2000~4000 tokens/维度11.2 检索性能指标数值Top-1 准确率75%MRR0.825检索延迟 100ms11.3 单调性验证优秀轨迹: 93.1 分 良好轨迹: 82.4 分 一般轨迹: 65.7 分 较差轨迹: 45.2 分 极差轨迹: 28.8 分 空轨迹: 20.0 分 单调性: ✅ 通过非递增容差 0.05十二、常见问题Q1: 如何接入现有的 Agent 项目根据你的框架选择对应的接入模式LangGraph 项目: 使用instrument_langgraph()一行接入LangChain 项目: 使用create_proxy_llm()替换 LLM其他框架: 使用get_collector()手动记录Q2: 评估结果的可信度如何保证平台通过以下方式保证评估可信度多模型共识: 多个 LLM 独立评分计算方差锚点评分: 每个子指标都有详细的评分锚点单调性验证: 定期运行基准测试验证评估器一致性Q3: 如何自定义评估维度可以通过继承BaseEvaluator类实现自定义评估器fromapp.evaluators.baseimportBaseEvaluatorclassCustomEvaluator(BaseEvaluator):WEIGHTS{custom_metric_1:0.5,custom_metric_2:0.5}asyncdefevaluate(self,goal,trajectory,**kwargs):# 自定义评估逻辑...Q4: 支持哪些 LLM目前支持DeepSeek (deepseek-chat, deepseek-v4-flash)智谱 GLM (glm-4-plus, glm-4-flash)通义千问 (qwen-plus)OpenAI (gpt-4, gpt-4o)十三、总结Agent Runtime Evaluation Platform提供了一个完整的 AI Agent 运行时质量评估解决方案特性说明✅ 6 维评估体系覆盖 Agent 执行全生命周期✅ 14 种标准化动作类型Pydantic Schema 约束✅ 3 种 SDK 接入模式零侵入采集✅ 多模型共识提升评估可信度✅ SSE 流式评估实时反馈✅ 增量评估 回归检测高效运维✅ Replay 调试器快速定位问题✅ RAG 知识库Wiki Agent 子系统相关链接GitHub: https://github.com/daetz-coder/Agent-Runtime-Evaluation-PlatformLicense: MITAuthor: zhanyong版权声明: 本文为原创文章版权归作者所有转载请注明出处。关键词: AI Agent, 评估平台, LLM-as-Judge, LangGraph, FastAPI, RAG, 质量评估, 开源项目
开源项目 | Agent Runtime Evaluation Platform — AI Agent 运行时全维度质量评估平台 GitHub: https://github.com/daetz-coder/Agent-Runtime-Evaluation-Platform License: MIT | Author: zhanyong | ️ Tags: AI Agent, 评估平台, LLM-as-Judge, LangGraph, FastAPI, RAG前言随着 AI Agent 在生产环境中的广泛应用如何科学地评估 Agent 的运行质量成为了一个关键问题。传统的评估方式存在以下局限性只关注结果忽略过程— 仅评估最终回答的质量无法反映 Agent 的决策能力缺乏标准化— 不同团队使用不同的评估方法结果难以对比无法定位问题— 当 Agent 表现不佳时难以确定是哪个环节出了问题缺乏实时性— 评估通常是离线的无法在 Agent 运行过程中提供反馈Agent Runtime Evaluation Platform正是为了解决这些问题而诞生的。本文将深入介绍这个开源项目的设计理念、技术架构、核心功能以及实际使用方法。一、项目简介Agent Runtime Evaluation Platform是一个全栈 AI Agent 评估系统核心理念是不仅评估最终回答质量更评估 Agent 在执行过程中的决策质量。1.1 核心能力平台通过 SDK 采集 Agent 的运行轨迹Trajectory然后使用LLM-as-Judge从 6 个维度对轨迹进行量化评分规划质量Planning— Agent 是否制定了合理的执行计划战术决策Tactical— 每一步决策是否合理高效工具使用Tool Use— 工具调用是否正确且高效记忆保持Memory— 是否有效利用历史信息重规划Replan— 遇到失败后是否合理调整策略检索质量Retrieval— RAG 检索是否精准可靠1.2 核心数据指标数值说明评估维度 × 子指标6 × 3~4 20 项覆盖 Agent 执行全生命周期轨迹动作类型14 种Pydantic Schema 约束类型安全SDK 接入模式3 种Instrument / Proxy / Callback单次全评估耗时15~30s6 评估器 asyncio.gather 并行检索基准Wiki AgentTop-1:75%, MRR:0.825四级混合检索效果综合分单调递减验证93.1 → 20.0评估器可信度验证二、评估体系详解2.1 六维评估模型平台的核心是6 维评估体系每个维度有 3~4 个子指标共计 20 项维度权重子指标评估重点规划质量Planning20%覆盖率、顺序性、粒度、完整性Agent 是否制定了合理的执行计划战术决策Tactical20%相关性、效率、正确性每一步决策是否合理高效工具使用Tool Use15%选择质量、参数准确性、结果利用工具调用是否正确且高效记忆保持Memory15%保持力、相关性、一致性是否有效利用历史信息重规划Replan15%触发适当性、适应质量、学习能力遇到失败后是否合理调整策略检索质量Retrieval15%相关性、证据准确性、覆盖度 幻觉检测RAG 检索是否精准可靠2.2 质量等级划分┌─────────────────────────────────────────────────────────┐ │ 质量等级划分 │ ├─────────────┬─────────────┬─────────────┬───────────────┤ │ 优秀 │ 良好 │ 一般 │ 较差 │ │ ≥ 80 分 │ ≥ 60 分 │ ≥ 40 分 │ 40 分 │ └─────────────┴─────────────┴─────────────┴───────────────┘2.3 智能权重归一化当某个维度不适用时例如 Agent 没有使用检索系统会自动标记并从加权总分中剔除权重重新归一化# 示例如果没有检索行为原始权重{planning:0.20,tactical:0.20,tool_use:0.15,memory:0.15,replan:0.15,retrieval:0.15# 不适用}归一化后{planning:0.235,# 0.20 / 0.85tactical:0.235,tool_use:0.176,memory:0.176,replan:0.176,retrieval:0.0# 已剔除}三、系统架构3.1 整体架构图┌─────────────────────────────────────────────────────────────────────┐ │ Frontend (Vue 3 ECharts) │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Dashboard │ │ Evaluation │ │ Wiki │ │ │ │ 仪表盘 │ │ 评估详情 │ │ 知识管理 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └───────────────────────────────┬─────────────────────────────────────┘ │ HTTP / SSE ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ FastAPI Server (Async 全链路) │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Middleware Chain │ │ │ │ CORS → CorrelationId → Auth → RateLimit → Prometheus │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Tasks API │ │Evaluations │ │ Reports │ │ │ │ 任务管理 │ │ 评估引擎 │ │ 报表分析 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Wiki Agent │ │ Benchmark │ │ System │ │ │ │ RAG 知识库 │ │ 基准测试 │ │ 系统管理 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └───────────────────────────────┬─────────────────────────────────────┘ │ ┌───────────────────────┼───────────────────────┐ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ SDK │ │ Evaluators │ │ Database │ │ Collector │ │ × 6 并行 │ │ SQLite / PG │ │ │ │ │ │ │ │ Pydantic │ │ LLM-as-Judge │ │ SQLAlchemy │ │ Schema │ │ 共识评估 │ │ Async │ └───────────────┘ └───────────────┘ └───────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ AI Model Layer │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ DeepSeek │ │ GLM-4 │ │ Qwen-Plus │ │ │ │ 推理 评估 │ │ 推理 评估 │ │ 推理 评估 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────────────┘3.2 数据流Agent 运行 → SDK 采集轨迹 → 存储到 DB → 触发评估 → 6 维并行评分 → 汇总报告 │ │ │ ← SSE 实时推送评估进度 ← │ └──────────────────────────────────────────────────────────────┘3.3 技术栈类别技术版本用途后端框架FastAPI Uvicorn0.109REST API SSE 实时流Agent 编排LangGraph LangChain0.2Agent 状态图、评估工作流AI 模型DeepSeek / GLM / Qwen / OpenAI-LLM 推理 LLM-as-Judge向量检索Milvus BM25 RRF Cross-Encoder2.4四级混合检索数据库SQLAlchemy Async SQLite / PostgreSQL2.0持久化存储缓存Redis可选7.2LLM 响应缓存、限流前端Vue 3 TypeScript Element Plus ECharts3.5管理面板与可视化SDKPython SDKPydantic httpx-零侵入轨迹采集四、关键特性详解4.1 Pydantic Schema SDK — 类型安全的轨迹采集平台定义了14 种标准动作类型ActionType每种类型都有独立的 Pydantic 模型# 14 种 ActionType 分类规划类:-PLAN# 初始规划-PLAN_UPDATE# 动态规划更新-REPLAN# 重规划工具类:-TOOL_CALL# 工具调用-TOOL_RESULT# 工具返回-TOOL_DECISION# 工具选择决策记忆类:-MEMORY_WRITE# 记忆写入-MEMORY_READ# 记忆读取状态类:-STATE_CHANGE# 状态变化-NODE_EXECUTE# 节点执行思考类:-THINK# 思考过程异常类:-FAILURE# 失败/异常事件检索类:-RETRIEVAL# 知识库检索-EVIDENCE# 证据池构建每种 ActionType 都有对应的 Pydantic SchemaclassToolCallDetail(BaseModel):工具调用详情tool_name:strinput_data:Dict[str,Any]output_data:Optional[Any]Nonesuccess:boolTrueduration_ms:Optional[float]Noneerror_message:Optional[str]None4.2 三种接入模式模式 1: LangGraph 自动采集推荐fromsdkimportinstrument_langgraph# 一行接入自动记录所有节点执行、状态变化、工具调用graphinstrument_langgraph(build_graph())# 运行resultawaitgraph.ainvoke(state,config)模式 2: LangChain LLM Proxyfromsdkimportcreate_proxy_llmfromlangchain_openaiimportChatOpenAI# 替换 LLM自动记录所有 LLM 调用llmcreate_proxy_llm(ChatOpenAI(modelgpt-4))# 正常使用responseawaitllm.ainvoke(Hello)模式 3: 手动记录任意框架fromsdk.collectorimportget_collector collectorget_collector()# 开始任务collector.start(实现用户登录功能,context{key_facts:[使用JWT]})# 记录轨迹collector.record_retrieval(JWT 认证,results,duration_ms120)collector.record_tool_call(sandbox,{code:...},result)collector.record_think(分析测试结果)# 结束任务 触发评估collector.finish(auto_runTrue)4.3 多模型共识评估为了提升评估的可信度平台支持多个 LLM 独立评分然后计算均值和方差# API 调用POST/api/v1/evaluations/consensus{task_id:xxx,models:[deepseek-chat,glm-4-plus,qwen-plus]}# 响应示例{mean_score:78.5,std_score:3.2,# 标准差越小 一致性越高 越可信model_count:3,individual_scores:{deepseek-chat:80,glm-4-plus:76,qwen-plus:79.5}}4.4 四阶段轨迹压缩为了减少 LLM Judge 的 token 消耗平台实现了 4 阶段压缩管线原始轨迹 │ ▼ ┌─────────────────────────────────────┐ │ Stage 1: 重要性过滤 │ │ 保留高价值 action_type │ │ (PLAN, TOOL_CALL, RETRIEVAL 等) │ └─────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ Stage 2: Think 截断 │ │ 长思考步骤截断到 200 字符 │ └─────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ Stage 3: 滑动窗口 │ │ 保留最近 30 步 │ │ (plan/failure 锚点兜底) │ └─────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ Stage 4: 格式化输出 │ │ 结构化文本送给评估器 │ └─────────────────────────────────────┘ │ ▼ 压缩后的轨迹4.5 SSE 流式评估评估进度实时推送到前端支持 6 维度并行评估# 客户端代码importhttpxasyncwithhttpx.AsyncClient()asclient:asyncwithclient.stream(POST,/api/v1/evaluations/stream,json{...})asresponse:asyncforlineinresponse.aiter_lines():ifline.startswith(data:):datajson.loads(line[5:])print(f维度{data[dimension]}:{data[score]}分)4.6 增量评估与回归检测当轨迹发生变化时系统会自动检测受影响的维度只重算变化部分# 增量评估 APIPOST/api/v1/evaluations/incremental{evaluation_id:xxx,new_trajectory:[...]}# 响应{reused_dimensions:[planning,tactical],# 复用原有评分re_evaluated_dimensions:[tool_use,memory],# 重新评估overall_score:82.5}4.7 Replay 调试器可以回放 Agent 执行的每一步查看原始的 LLM Prompt 和 Response# APIGET/api/v1/evaluations/{id}/replay# 响应{steps:[{step:1,action_type:plan,timestamp:2026-07-07T10:00:00Z,llm_trace:{model:deepseek-chat,prompt:...,response:...,latency_ms:1200}},...]}五、功能演示5.1 评估流程演示演示内容创建评估任务6 维度并行评估实时推送评估进度评估结果展示雷达图、详细分数、反馈5.2 Wiki Agent — HITL 知识管理演示内容用户发起对话AI 检索知识库并回复AI 识别到需要更新知识库暂停等待用户确认Human-in-the-Loop用户确认后自动执行 CRUD 操作5.3 系统管理演示内容系统健康检查Sessions、Messages、Checkpoints 状态BM25、Vectors 索引状态Redis 缓存状态六、快速开始6.1 环境要求依赖版本必需Python3.11✅Node.js18✅前端Redis7.2❌可选用于缓存PostgreSQL14❌可选默认 SQLite6.2 安装步骤# 1. 克隆项目gitclone https://github.com/daetz-coder/Agent-Runtime-Evaluation-Platform.gitcdAgent-Runtime-Evaluation-Platform# 2. 创建虚拟环境推荐python-mvenv venvsourcevenv/bin/activate# Linux/Mac# 或venv\Scripts\activate# Windows# 3. 安装后端依赖pipinstall-e.[dev]# 4. 安装前端依赖cdfrontendnpminstallcd..# 5. 配置环境变量cp.env.example .env# 编辑 .env填入以下配置# DEEPSEEK_API_KEYyour_api_key_here# EVAL_ENABLEDtrue# 6. 启动后端python-mapp.main# 7. 另一个终端启动前端cdfrontendnpmrun dev6.3 访问地址服务地址说明前端仪表盘http://localhost:3000Vue 3 管理界面API 文档http://localhost:8000/docsSwagger UIReDoc 文档http://localhost:8000/redocReDoc 文档健康检查http://localhost:8000/health系统状态七、项目结构Agent-Runtime-Evaluation-Platform/ ├── app/ # 后端应用 │ ├── evaluators/ # 6 个评估器 共识评估 轨迹压缩 │ │ ├── planning_evaluator.py # 规划质量评估器 │ │ ├── tactical_evaluator.py # 战术决策评估器 │ │ ├── tool_use_evaluator.py # 工具使用评估器 │ │ ├── memory_evaluator.py # 记忆保持评估器 │ │ ├── replan_evaluator.py # 重规划评估器 │ │ ├── retrieval_evaluator.py # 检索质量评估器 │ │ ├── consensus.py # 多模型共识引擎 │ │ └── trajectory_compressor.py # 4阶段轨迹压缩 │ ├── graphs/ # LangGraph 评估工作流 │ ├── services/ # 业务逻辑层 │ │ ├── evaluation_service.py # 评估服务 │ │ ├── replay_service.py # Replay 调试器 │ │ ├── judge_service.py # Judge 透明度 │ │ └── incremental_eval.py # 增量评估 │ ├── core/ # 基础设施 │ │ ├── config.py # 配置管理 │ │ ├── cache.py # Redis 缓存 │ │ └── logging.py # 日志配置 │ ├── api/ # REST API 中间件 │ │ └── v1/endpoints/ # API 端点 │ ├── wiki_agent/ # Wiki Agent 子系统 │ │ ├── agent/ # 智能体层 │ │ │ ├── graph.py # LangGraph 编排 │ │ │ ├── context_retriever.py # 四路记忆检索 │ │ │ └── tools/ # 工具集 │ │ │ ├── search_tools.py # 混合搜索 │ │ │ ├── vector_store.py # Milvus 向量存储 │ │ │ └── bm25_index.py # BM25 倒排索引 │ │ ├── wiki/ # 知识管理层 │ │ ├── session/ # 会话管理层 │ │ └── routers/ # API 路由 │ ├── models/ # Pydantic schema 定义 │ └── db/ # SQLAlchemy ORM Alembic 迁移 ├── frontend/ # Vue 3 前端 │ ├── src/ │ │ ├── views/ # 页面组件 │ │ ├── components/ # 通用组件 │ │ └── api/ # API 调用 │ └── package.json ├── sdk/ # 独立 SDK 包 │ ├── collector.py # 轨迹收集器 │ ├── schemas.py # Pydantic Schema │ └── adapters/ # 适配器 │ ├── langgraph.py # LangGraph 适配器 │ ├── llm_proxy.py # LLM Proxy 适配器 │ └── callback.py # LangChain Callback ├── scripts/ # 基准测试脚本 │ ├── benchmark_evaluators.py # 评估器基准 │ ├── benchmark_multimodel.py # 多模型基准 │ └── eval_retrieval_standalone.py # 检索评估 ├── tests/ # 测试 ├── docs/ # 文档 │ ├── architecture.md # 架构文档 │ ├── api.md # API 文档 │ └── developer_guide.md # 开发者指南 ├── pyproject.toml # Python 项目配置 └── README.md # 项目说明八、API 接口概览8.1 评估相关方法路径说明POST/api/v1/evaluations/创建并运行评估POST/api/v1/evaluations/streamSSE 流式评估POST/api/v1/evaluations/quick同步评估阻塞POST/api/v1/evaluations/batch批量评估POST/api/v1/evaluations/consensus多模型共识评估POST/api/v1/evaluations/incremental增量评估GET/api/v1/evaluations/{id}获取评估详情GET/api/v1/evaluations/{id}/replayReplay 调试器GET/api/v1/evaluations/{id}/judge-rawJudge 透明度GET/api/v1/evaluations/diffTrajectory 对比GET/api/v1/evaluations/regression/check回归检测8.2 Wiki Agent方法路径说明POST/api/chat/streamSSE 流式对话POST/api/chat/message同步对话POST/api/chat/confirmHITL 确认/取消GET/api/wiki/tree知识库目录树GET/api/wiki/search?q搜索知识库POST/api/wiki/page/{path}创建页面PUT/api/wiki/page/{path}更新页面DELETE/api/wiki/page/{path}删除页面8.3 系统运维方法路径说明GET/api/v1/system/health健康检查GET/api/v1/system/metricsPrometheus 指标GET/settings/promptsPrompt 版本管理九、Wiki Agent — RAG 知识库问答项目还包含一个完整的Wiki Agent子系统基于 RAG检索增强生成实现知识库问答。9.1 四级混合检索用户查询 │ ▼ ┌─────────────────────────────────────┐ │ Level 1: Query 改写 │ │ LLM 自动优化查询 │ └─────────────────────────────────────┘ │ ├─────────────────┬─────────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Semantic │ │ BM25 │ │ Memory │ │ Search │ │ Search │ │ Search │ │ (Milvus) │ │ (倒排索引)│ │ (用户/会话)│ └──────────┘ └──────────┘ └──────────┘ │ │ │ └─────────────────┼─────────────────┘ ▼ ┌──────────────┐ │ RRF 融合 │ │ (Reciprocal │ │ Rank Fusion)│ └──────────────┘ │ ▼ ┌──────────────┐ │ Cross-Encoder│ │ 重排 │ │ (bge-reranker)│ └──────────────┘ │ ▼ Top-K 结果9.2 双层记忆记忆类型存储位置生命周期用途User MemorySQLite长期用户偏好、历史事实Session Memory内存 Redis短期当前会话上下文9.3 HITL CRUD当 AI 决定修改知识库时会暂停等待用户确认# AI 识别到需要更新知识库# → 暂停执行# → 发送 HITL 请求到前端# → 用户确认/取消# → 继续执行或回滚9.4 四端同步组件用途同步时机Markdown人类可读实时Milvus向量检索异步BM25关键词检索异步Git版本控制提交时十、适用场景10.1 Agent 开发团队在开发过程中持续监控 Agent 质量发现改进方向# 每次代码变更后自动评估POST/api/v1/evaluations/incremental{evaluation_id:previous_eval_id,new_trajectory:[...]}# 查看回归检测GET/api/v1/evaluations/regression/check10.2 Agent 评测竞赛标准化的评估流程支持批量评估和排行榜# 批量评估POST/api/v1/evaluations/batch{task_ids:[task1,task2,task3]}# 获取评估报告GET/api/v1/reports/summary10.3 生产环境监控通过增量评估和回归检测及时发现 Agent 质量退化# 定时回归检测GET/api/v1/evaluations/regression/check?task_idxxxthreshold5# 获取趋势报告GET/api/v1/reports/trends?days3010.4 评估研究为 Agent 评估研究提供标准化的评估框架和基准数据# 运行单调性基准POST/api/v1/benchmark/monotonicity/run# 获取基准结果GET/api/v1/benchmark/monotonicity十一、性能基准11.1 评估器性能指标数值单次评估耗时15~30s并发评估数6asyncio.gatherToken 消耗压缩后约 2000~4000 tokens/维度11.2 检索性能指标数值Top-1 准确率75%MRR0.825检索延迟 100ms11.3 单调性验证优秀轨迹: 93.1 分 良好轨迹: 82.4 分 一般轨迹: 65.7 分 较差轨迹: 45.2 分 极差轨迹: 28.8 分 空轨迹: 20.0 分 单调性: ✅ 通过非递增容差 0.05十二、常见问题Q1: 如何接入现有的 Agent 项目根据你的框架选择对应的接入模式LangGraph 项目: 使用instrument_langgraph()一行接入LangChain 项目: 使用create_proxy_llm()替换 LLM其他框架: 使用get_collector()手动记录Q2: 评估结果的可信度如何保证平台通过以下方式保证评估可信度多模型共识: 多个 LLM 独立评分计算方差锚点评分: 每个子指标都有详细的评分锚点单调性验证: 定期运行基准测试验证评估器一致性Q3: 如何自定义评估维度可以通过继承BaseEvaluator类实现自定义评估器fromapp.evaluators.baseimportBaseEvaluatorclassCustomEvaluator(BaseEvaluator):WEIGHTS{custom_metric_1:0.5,custom_metric_2:0.5}asyncdefevaluate(self,goal,trajectory,**kwargs):# 自定义评估逻辑...Q4: 支持哪些 LLM目前支持DeepSeek (deepseek-chat, deepseek-v4-flash)智谱 GLM (glm-4-plus, glm-4-flash)通义千问 (qwen-plus)OpenAI (gpt-4, gpt-4o)十三、总结Agent Runtime Evaluation Platform提供了一个完整的 AI Agent 运行时质量评估解决方案特性说明✅ 6 维评估体系覆盖 Agent 执行全生命周期✅ 14 种标准化动作类型Pydantic Schema 约束✅ 3 种 SDK 接入模式零侵入采集✅ 多模型共识提升评估可信度✅ SSE 流式评估实时反馈✅ 增量评估 回归检测高效运维✅ Replay 调试器快速定位问题✅ RAG 知识库Wiki Agent 子系统相关链接GitHub: https://github.com/daetz-coder/Agent-Runtime-Evaluation-PlatformLicense: MITAuthor: zhanyong版权声明: 本文为原创文章版权归作者所有转载请注明出处。关键词: AI Agent, 评估平台, LLM-as-Judge, LangGraph, FastAPI, RAG, 质量评估, 开源项目
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
