企业官网建设流程全解析

开源项目 | 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 的运行质量成为了一个关键问题。

传统的评估方式存在以下局限性：

1. 只关注结果，忽略过程— 仅评估最终回答的质量，无法反映 Agent 的决策能力
2. 缺乏标准化— 不同团队使用不同的评估方法，结果难以对比
3. 无法定位问题— 当 Agent 表现不佳时，难以确定是哪个环节出了问题
4. 缺乏实时性— 评估通常是离线的，无法在 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 核心数据

二、评估体系详解

2.1 六维评估模型

平台的核心是6 维评估体系，每个维度有 3~4 个子指标，共计 20 项：

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.85"tactical":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 技术栈

四、关键特性详解

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 Schema：

classToolCallDetail(BaseModel):"""工具调用详情"""tool_name:strinput_data:Dict[str,Any]output_data:Optional[Any]=Nonesuccess:bool=Trueduration_ms:Optional[float]=Noneerror_message:Optional[str]=None

4.2 三种接入模式

模式 1: LangGraph 自动采集（推荐）

fromsdkimportinstrument_langgraph# 一行接入，自动记录所有节点执行、状态变化、工具调用graph=instrument_langgraph(build_graph())# 运行result=awaitgraph.ainvoke(state,config)

模式 2: LangChain LLM Proxy

fromsdkimportcreate_proxy_llmfromlangchain_openaiimportChatOpenAI# 替换 LLM，自动记录所有 LLM 调用llm=create_proxy_llm(ChatOpenAI(model="gpt-4"))# 正常使用response=awaitllm.ainvoke("Hello")

模式 3: 手动记录（任意框架）

fromsdk.collectorimportget_collector collector=get_collector()# 开始任务collector.start("实现用户登录功能",context={"key_facts":["使用JWT"]})# 记录轨迹collector.record_retrieval("JWT 认证",results,duration_ms=120)collector.record_tool_call("sandbox",{"code":"..."},result)collector.record_think("分析测试结果")# 结束任务 + 触发评估collector.finish(auto_run=True)

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:"):data=json.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 环境要求

6.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. 安装前端依赖cdfrontend&&npminstall&&cd..# 5. 配置环境变量cp.env.example .env# 编辑 .env，填入以下配置：# DEEPSEEK_API_KEY=your_api_key_here# EVAL_ENABLED=true# 6. 启动后端python-mapp.main# 7. 另一个终端启动前端cdfrontend&&npmrun dev

6.3 访问地址

七、项目结构

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 评估相关

8.2 Wiki Agent

8.3 系统运维

九、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 双层记忆

9.3 HITL CRUD

当 AI 决定修改知识库时，会暂停等待用户确认：

# AI 识别到需要更新知识库# → 暂停执行# → 发送 HITL 请求到前端# → 用户确认/取消# → 继续执行或回滚

9.4 四端同步

十、适用场景

10.1 Agent 开发团队

在开发过程中持续监控 Agent 质量，发现改进方向：

# 每次代码变更后自动评估POST/api/v1/evaluations/incremental{"evaluation_id":"previous_eval_id","new_trajectory":[...]}# 查看回归检测GET/api/v1/evaluations/regression/check

10.2 Agent 评测竞赛

标准化的评估流程，支持批量评估和排行榜：

# 批量评估POST/api/v1/evaluations/batch{"task_ids":["task1","task2","task3"]}# 获取评估报告GET/api/v1/reports/summary

10.3 生产环境监控

通过增量评估和回归检测，及时发现 Agent 质量退化：

# 定时回归检测GET/api/v1/evaluations/regression/check?task_id=xxx&threshold=5# 获取趋势报告GET/api/v1/reports/trends?days=30

10.4 评估研究

为 Agent 评估研究提供标准化的评估框架和基准数据：

# 运行单调性基准POST/api/v1/benchmark/monotonicity/run# 获取基准结果GET/api/v1/benchmark/monotonicity

十一、性能基准

11.1 评估器性能

11.2 检索性能

11.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: 评估结果的可信度如何保证？

平台通过以下方式保证评估可信度：

1. 多模型共识: 多个 LLM 独立评分，计算方差
2. 锚点评分: 每个子指标都有详细的评分锚点
3. 单调性验证: 定期运行基准测试验证评估器一致性

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 运行时质量评估解决方案：

相关链接

• 📦GitHub: https://github.com/daetz-coder/Agent-Runtime-Evaluation-Platform
• 📄License: MIT
• 📧Author: zhanyong

版权声明: 本文为原创文章，版权归作者所有，转载请注明出处。

关键词: AI Agent, 评估平台, LLM-as-Judge, LangGraph, FastAPI, RAG, 质量评估, 开源项目