evalview-mcp

AI Agent 的快照测试。
记录 Agent 今天的行为。行为悄然改变时，及时通知你。

---

你的 Agent 返回 200，看起来一切正常。但一次模型更新、提供商变更，或一行提示词编辑，可能让它跳过澄清、调用错误的工具，或悄悄降低输出质量。你的测试依然通过。用户却比你更早发现问题。

EvalView 为 Agent 的行为创建快照——它调用哪些工具、按什么顺序调用，以及输出什么——并在行为发生变化时立即通知你。 就像 Jest 快照，但适用于工具调用型、多轮对话的 Agent。

_{↑ 30 秒实时演示——无需 API 密钥}

快速开始

OpenAI 适配器迁移： OpenAI 已于 2026 年 8 月 26 日 关闭 Assistants API。 最新发布的 EvalView 版本 0.8.1 仍使用该 API；Responses API 迁移目前尚未发布，仍处于源代码阶段。如果你使用 openai-assistants，请在运行测试前参阅 迁移指南。仅凭 assistant_id 无法保留 Agent 的配置。其他适配器不受影响。

pip install evalview

evalview snapshot    # Record your agent's current behavior as the baseline
evalview check       # After any change, diff against the baseline

整个流程就是这样。check 会返回以下结果之一：

  ✓ login-flow        PASSED          behavior matches baseline
  ⚠ refund-request    TOOLS_CHANGED   called a different tool, or in a different order
  ✗ billing-dispute   REGRESSION      score dropped — output quality fell

它会比较完整轨迹——工具名称、参数和调用顺序——而不只是最终字符串。确定性的工具及序列差异比较可离线运行，无需 API 密钥。只有在需要评估输出质量时，才添加大模型裁判。

执行 Agent 仍可能产生后端 API 费用：--no-judge 只会跳过裁判，不会跳过这些调用。基于嵌入的语义比较为可选功能。

还没有 Agent？30 秒内即可查看效果：

evalview demo

为什么使用快照测试（而不是断言）？

大多数评估工具都要求你写下“好的表现”是什么样的——断言、指标、评分标准。这需要大量前期工作，而且你只能发现自己预先写了断言的故障。

EvalView 反其道而行：它会记录你的 Agent 当前的实际行为，并标记任何偏离。 无需编写任何断言，就能发现你从未预料到的回归。当新行为正确时，evalview snapshot 会将其接受为新的基线——就像在 Jest 中更新快照一样。

	EvalView	基于断言的评估工具
设置	记录当前行为	先编写断言／指标
可发现的问题	与基线的任何偏离	仅限你编写断言的情况
非确定性	多变体基线（最多 5 条有效路径）	由你处理
比较单位	完整的工具调用轨迹	通常是最终输出

因此，EvalView 是一个合并时的回归关卡，它承担的职责不同于可观测性工具（Langfuse、LangSmith）或指标评分工具（promptfoo、DeepEval、Braintrust）。许多团队会用其中一种工具进行可视化，并且用 EvalView 作为关卡。坦诚比较 →

EvalView 每天公开测试自身

每天 09:00 UTC、每次拉取请求以及向 main 推送时， Core Dogfood 都会运行非实时测试套件、 类型检查、本地模拟 Agent 的 snapshot／check、evalview demo、端到端 流程，以及 evalview monitor 冒烟测试。它不会使用付费 API 凭据，也 不会发起付费推理调用。GitHub Runner 的使用费用另计。

Live Provider Checks 只会在维护者明确选择在 main 上使用付费 API 时，测试真实评估器和 聊天助手。它们没有自动运行计划。其徽章记录最近一次手动运行；核心徽章为绿色 并不能证明实时服务提供方运行正常，也不能排除服务提供方行为发生偏移。

包 CI、核心 dogfood 和实时检查各有独立徽章。失败或未完成的 检查会在各自范围内保持可见，并保留日志和报告作为 构件。持续出现的问题使用独立的 dogfood-core 和 dogfood-live 标签。 服务提供方中断、配额耗尽或缺少凭据意味着实时状态 无法确认；这并不能证明 Agent 出现回归。

历史事件 incident #264 仍可供维护者审查来自两个范围的新证据。两个工作流都不会自动关闭该事件。 信任警告是需要调查的证据， 并不能证明存在作弊，也不能证明某个特定根本原因。

核心运行记录 → · 手动实时运行记录 → · 运行与分诊指南 →

CI：阻止每个 PR 中的回归

# .github/workflows/evalview.yml
name: EvalView
on: [pull_request]
jobs:
  agent-check:
    runs-on: ubuntu-latest
    permissions: { pull-requests: write }
    steps:
      - uses: actions/checkout@v4
      - uses: hidai25/[email protected]
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}

你会收到一条 PR 评论，其中包含差异、成本／延迟变化，以及通过／失败关卡。CI/CD 指南 →

兼容你的技术栈

LangGraph · CrewAI · OpenAI · Claude · Mistral · Ollama · MCP · 任何 HTTP API。

evalview check --agent http://localhost:8000/invoke

框架详情 →

将其用作库

from evalview import gate

result = gate(test_dir="tests/")
result.passed   # bool
result.diffs    # per-test scores and tool diffs

Python API →

更多功能

EvalView 还支持多轮测试、统计／pass@k 运行、记录／回放磁带、模型偏移金丝雀、带 Slack 警报的生产环境监控，以及根据事件自动生成回归测试。这些是高级用户功能——从 snapshot 和 check 开始，需要时再使用其他功能。

→ 完整功能参考 · 入门指南 · 常见问题

→ 文档索引 · OpenAI 迁移指南 · 发布流程

我为什么构建 EvalView

一个看起来表现出色的 Agent 不断将整份文档拉入上下文，导致一个问题花费了 42.93 美元。这段经历促使我构建了 EvalView。我在《我在经营一家 AI 赌场。后来，我开始为我的 Agent 编写测试》中写下了这段经历。这篇发表于 2025 年 12 月的文章讲述了项目的起源；有关设置和命令，请参阅当前文档。

贡献

这是一个刚起步的项目，主要由一位开发者构建。问题反馈、PR，以及“我试用了，觉得 X 让人困惑”之类的反馈都非常有价值。

• 提交问题 · 讨论区 · CONTRIBUTING.md

许可证： Apache 2.0

---