agenteval-debugger

AgentEval

面向学习者的 AI Agent 执行调试器。3 行代码接入 LangGraph，自动生成教学注释，支持 LLM 节点安全回放。

为什么需要 AgentEval

2025-2026 年 AI Agent 进入生产部署爆发期，但 Gartner 报告显示 88% 的 Agent 试点项目无法跨越生产环境鸿沟，首要原因是缺乏可观测性与调试能力。

现有 Agent 可观测工具（LangSmith、Langfuse、Phoenix）都面向资深工程师和企业场景，初学者上手门槛高，且不解释"Agent 为什么这么调"。

AgentEval 面向学习者和初学者，让你看懂 Agent 每一步在干什么。

特性

• 教学化注释 — 每个 span 自动解释"这一步在干什么、为什么"，现有工具不做这个
• 安全回放 — LLM 节点可修改输入重跑，tool 节点用录播响应避免副作用（不会重复发邮件/删数据）
• AI 诊断（V2） — 选中一条 trace，由无状态诊断 Agent（LangGraph 实现，吃自己的狗粮）生成自然语言诊断报告：哪一步可能出错、为什么、怎么改
• Trace 对比（V2） — 两次执行并排 diff，定位"以前能跑现在不能"
• 3 行代码接入 — 比现有方案更简单，降低学习者门槛
• 零配置 — pip install 即用，不需要 Docker、不需要装数据库

快速开始

安装

# 推荐：PyPI 安装（含 Web 界面与示例依赖）
pip install "agenteval-debugger[web,examples]"

# 或从源码安装
git clone https://github.com/Xhan-985/agent-eval-platform.git
cd agent-eval-platform
pip install -e ".[web,examples]"

只使用 SDK（不打开 Web 界面）时 pip install agenteval-debugger 即可；[web] 用于页面，[examples] 用于运行示例。

💡 推荐在独立虚拟环境中安装，避免与机器上已有的包（如 TensorFlow、旧版 protobuf 等）产生依赖冲突：

# Windows
python -m venv agenteval-venv
agenteval-venv\Scripts\activate
pip install "agenteval-debugger[web,examples]"

# macOS / Linux
python -m venv agenteval-venv
source agenteval-venv/bin/activate
pip install "agenteval-debugger[web,examples]"

国内网络环境可用镜像加速（清华源示例）：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "agenteval-debugger[web,examples]"

接入你的 LangGraph Agent

import agenteval
agenteval.init(verbose=True)  # verbose=True 时自动打印带注释的 trace

graph = build_my_langgraph()          # 你的 LangGraph
traced_graph = agenteval.wrap(graph)  # 一行包装，自动注入采集

result = traced_graph.invoke({"messages": [("user", "LangGraph 是什么？")]})
# 自动输出带教学注释的 trace

就这么简单，3 行代码接入。默认静默采集，任何时刻可用 agenteval.last_trace() 拿到最近一次执行的 trace JSON。如果你的调用函数签名包含 **kwargs，也可以用 @agenteval.trace 装饰器（详见 开发交接文档）。

给 Agent 命名：列表页的"Agent"列默认显示 LangGraph 图的默认名（LangGraph），用 agenteval.wrap(graph, name="我的搜索Agent") 可以给每次执行的 agent 起个有意义的名字，方便在列表里区分不同任务。

安全 replay（LLM 节点重跑）

Web 详情页选中 LLM span 后，可修改 input 并重跑；tool span 只回放录播响应，不会真实执行（避免发邮件、写库等副作用）。

import agenteval
from langchain_openai import ChatOpenAI

agenteval.init(
    verbose=True,
    llm_factory=lambda model_name: ChatOpenAI(model=model_name, api_key="sk-..."),
)

llm_factory 接收模型名并返回一个 ChatModel 实例。不配置时 replay 会给出明确提示，其他功能不受影响。

AI 诊断（V2）

对任意一条（或两条）trace 运行诊断 Agent，输出中文 Markdown 报告：

import agenteval
from langchain_openai import ChatOpenAI

agenteval.init(
    llm_factory=lambda model_name: ChatOpenAI(
        model=model_name,
        base_url="https://api.deepseek.com",
        api_key="sk-...",
    ),
)

report = agenteval.diagnose("你的-trace-id", question="为什么这一步报错？")
print(report)

也可以带第二个 trace_id 让诊断 Agent 做对比诊断（内部使用 compare_traces 工具）。 Web 侧边栏"AI 诊断"页提供同样的能力，无需写代码。要求模型支持 tool calling （DeepSeek / OpenAI 兼容模型均可）；未配置 llm_factory 时页面和 API 都会给出明确提示。

导出 Langfuse 格式（V2）

from agenteval.export.langfuse import export_to_jsonl

export_to_jsonl("agenteval.db", "你的-trace-id", "export.jsonl")

生成 Langfuse 字段命名（traces + observations）的 JSONL 文件，方便迁移到 Langfuse 生态。

使用 DeepSeek / OpenAI 兼容 API

OpenAI 兼容接口只需配置 base_url：

agenteval.init(
    llm_factory=lambda model_name: ChatOpenAI(
        model=model_name,
        base_url="https://api.deepseek.com",  # 默认 OpenAI 端点可省略
        api_key="sk-...",
    ),
)

DeepSeek 模型名形如 deepseek-v4-flash / deepseek-v4-pro。API key 建议放环境变量 OPENAI_API_KEY 或本地 .env（已被 gitignore），不要写进代码。

agenteval-web 启动时会自动读取当前目录的 .env；也可以把 OPENAI_BASE_URL=https://api.deepseek.com 写进 .env，Web 侧边栏会自动带出， 避免每次手动改 Base URL。

启动 Web 界面

安装时带上 [web] 依赖后，一条命令即可打开可视化页面：

agenteval-web          # 或 python -m agenteval web

浏览器会自动打开 http://localhost:8501，页面包含：

• 仪表盘：落地首页，KPI 概览（Trace 总数 / 成功率 / 总 Token / 平均耗时 / 错误数）、近 14 天趋势图、状态分布、最近 Trace 表
• 列表页：可交互表格（行选中进详情），支持按 Agent / 状态 / 关键词搜索与分页
• 详情页：顶部摘要卡（状态徽标、Agent、模型、总耗时、总 Token、span 数）+ 三视图 tabs
  • 时间线：横向瀑布图，按 span 起止与耗时排布、按类型着色、出错节点标红
  • 调用树：graphviz 树状图，节点带类型图标、教学注释、耗时
  • Span 列表：平铺表，按类型/错误筛选
• span 详情：下拉选 span 查看全文注释、耗时、token 用量、可折叠 input / output
• replay 面板：LLM span 可改输入重跑（结构化原/新 output 对比 + replay 历史），tool span 显示录播响应（不真实执行）
• AI 诊断页（V2）：选一条 trace（可选第二条做对比、可选问题），一键生成四段式诊断报告（概述 / 可疑步骤 / 原因分析 / 修改建议），可疑步骤带 span_id；诊断过程本身会作为一条 trace 入库（agent_name = "AgentEval 诊断助手"）
• Trace 对比页（V2）：两个 trace 并排选择，展示状态 / 耗时 / span 级差异表格

注意事项：

• 页面默认读取当前目录的 agenteval.db（与运行 Agent 时一致）；如果 Agent 在其他目录运行，用环境变量 AGENTEVAL_DB=/path/to/agenteval.db 指定，或在页面侧边栏手动填写数据库路径
• replay 的模型配置在页面侧边栏（模型名 / API Base URL / API Key），也可以用代码里的 init(llm_factory=...)
• 界面为中文、单机本地工具（Streamlit），不会上传任何数据

示例

见 examples/ 目录：

• react_agent_trace.py — ReAct Agent 完整示例（fake / real 双模式）
• replay_demo.py — 安全 replay 演示（fake / real 双模式）

路线图

适合谁

• Agent 学习者：刚学 LangGraph，想看懂 Agent 执行过程
• 教学者：给学生演示 Agent 工作原理
• 初学者调试：Agent 出错时定位是哪一步的问题

不适合谁

• 企业级生产监控（用 Langfuse）
• 资深工程师的 OTel 工具链（用 Phoenix）

与现有工具对比

已知限制

• 只支持同步 invoke，不支持 ainvoke / stream（调用会明确报错）
• 只支持 LangGraph；LangChain 原生 chain、OpenAI Agents SDK 等暂不支持（见路线图 v0.3.0）
• 只支持单次串行调用，多次 invoke 请串行执行
• RAG 检索（retriever）调用暂以 node span 呈现，不单独标注
• 诊断 Agent 只分析本地 SQLite 中的 trace；报告质量依赖所配置的模型，模型需支持 tool calling

贡献

欢迎 Issue 和 PR。开发前请阅读 开发交接文档。

License

MIT