评估 AI Agent：摆脱“凭感觉检查”

TL;DR

你的 Agent 可能陷入循环、耗尽 token，或给出完全幻觉的回答，但表面上仍然看起来没问题。“凭感觉检查”捕捉不到这些问题。本文是我们 AI Agent Clinic 节目《如何真正评估（任何）AI Agent：超越凭感觉检查》背后的实战指南；我们在节目中用 60 分钟为一个 LangGraph Agent 搭建了评估流水线。本文包括以下内容：

评估 AI Agent：摆脱“凭感觉检查”

当团队开始构建 AI Agent 时，测试通常看起来都差不多：接入一个模型，给它几个工具，在终端里运行三四个提示词，然后用肉眼判断输出。如果答案看起来合理，就发布。

但在实践中，这种方法很快就会失效。你为了修复某个工作流中的边缘情况而调整系统提示词，结果 Agent 突然不再调用另一个工作流中必需的工具。

更糟的是，Agent 的失败方式不同于传统软件。一个 Agent 可能卡在重试循环中，发起多次工具调用，却仍返回一个礼貌、听起来可信的最终答案。

在生产环境中，这种隐藏的失败代价高昂：

• 它会悄然推高云端账单和 token 用量。
• 它会耗尽下游 API 的速率限制和配额。
• 它会让用户只能盯着加载动画等待。
• 它可能在外部系统中触发重复的副作用，而表面上看起来一切“正常”。
• 它会侵蚀用户信任，而第一次留下的坏印象很难挽回。

在开发生命周期中集成一套可靠的评估套件，在最初原型阶段似乎是额外开销——直到你修改系统提示词后引发意料之外的破坏性变更。关键在于认识到，评估是一个渐进式过程：任何可重复的评估系统（无论多么简单）都优于临时抽查或完全没有系统。你不需要在第 0 天就构建复杂的自动化评分架构。相反，应从简单、可重复的检查开始，随着 Agent 能力和生产需求的增长，逐步将评估演进为更复杂、自动化的框架。

将这些决策整合到评估框架中，可以大幅简化可重复评估系统的建立。要超越简单的主观检查，依赖两大核心支柱：人工监督和有针对性的工具。本文将探讨如何使用开源 agent-eval 工具包搭建评估框架。我们将演示，如何结合人工审阅的轨迹与自动化验证，在开发早期发现静默回归，并在 Agent 进入生产环境时无缝扩展。

---

入门：高层构建模块

1. 用关键用户旅程定义成功

在编写测试代码之前，你需要就“好的结果”究竟是什么形成共同认知。测试应锚定于关键用户旅程（CUJ），而不是抽象的基准测试。

CUJ 用用户角色、目标、约束条件和验证条件来定义用户期望系统达成的结果：

“作为一名运营分析师，我希望 Agent 能够接收一封交易对手方交易差异邮件，识别存在争议的交易，在 30 秒内根据我们的内部账本验证交易经济条款，并起草一份回复，将我们的内部交易 ID 反向转换为经纪商的命名方式，全程无需人工干预。”

该陈述中的每一项条款都会成为一个评估点：Agent 是否解析出了正确的交易 ID？是否在起草回复前检查了账本？是否将内部 ID 映射回外部命名方式？

CUJ 的每一项条款都会成为一个评估点。

预先定义这些期望，会迫使产品利益相关方、下游用户和工程师就“成功”的衡量方式达成一致。

2. 从模拟用户开始，逐步过渡到真实流量

你不需要等待六个月的生产日志，才能构建初始黄金数据集。相反，应将每个 CUJ 拆解成具体的场景（包括顺利路径和边缘情况），并将其输入用户模拟器 LLM（我们推荐 ADK 用户模拟）。模拟器预先设定了角色和行为约束，例如只提供不完整工单编号、缺乏耐心的分析师，或提出多部分调试问题的开发者；它能够复现真实用户杂乱的措辞、拼写错误和多轮交互复杂性。

ADK 用户模拟的示例场景。

通过使用合成用户和真实场景测试 Agent，你可以在用户实际交互前记录完整的执行轨迹（包括工具日志）。这使你能够定位并解决相对于发布标准的性能缺口。随着真实流量开始进入，你可以逐步用真实生产轨迹替换这些合成设置。

3. 覆盖全栈进行度量

单一的顶层评分永远无法告诉你 Agent _为什么_失败。为了定位根本原因，应叠加四类检查：单元测试、确定性指标、LLM-as-a-judge 评分量规，以及集成测试。

从单元测试到集成测试的四层检查。

四个常见陷阱应避免

陷阱 1：丢弃测试，破坏基线

设置评估指标需要反复试验，因此很容易想要删除一个噪声测试，或在不同运行之间更换样本查询。但每次增加或删除测试，都会使基线失效：你无法判断分数变化究竟是因为 Agent 变好了，还是因为测试套件变了。在调优某项功能时，应保持黄金数据集冻结，每次只改变一个变量；只有在确认底层需求已经变化时，才停用测试。

删除测试改变的是基线，而不是 Agent。

陷阱 2：依赖模糊的 1 到 5 分裁判评分，而非布尔检查

LLM 在对定性 1 到 5 分量表评分时以不稳定著称；“3 分”和“4 分”之间的边界很模糊，而且常常会在不同运行之间变化。

只要可能，就应将裁判评分量规转化为布尔值（通过/失败）问题，而不是开放式评分量表。不要问 “这个回答从 1 到 5 分有多大帮助？”，而应问 “Agent 在调用退款工具前是否验证了账户 ID？（是/否）”。（我们推荐 Adaptive Rubrics ）

陷阱 3：评估文案，却忽略运营成本

一个通过所有质量检查的回答，如果耗时 40 秒、进行了 12 次冗余工具调用，并且每次查询成本为 60 美分，那么它在生产环境中仍然是失败的。

务必评估整个系统，而不只是最终文本。在回答质量之外，还应追踪延迟、token 消耗（提示词 token、推理 token 和生成 token）、API 成本以及工具调用次数。

陷阱 4：为不同 Agent 框架构建不同评估流水线

切换编排框架常常迫使团队废弃并重写整套测试套件。尽管大多数框架都会输出 OpenTelemetry 轨迹，但它们对于工具调用、步骤和 token 并未采用相同的语义约定。围绕 OpenInference 等开放规范对轨迹进行标准化，可以将评估与编排框架解耦。agent-eval 工具包等工具原生支持这一能力，且只需极少配置。

---

从 Day 0 到 Day 2 的实用落地路径

你无需从零构建可观测性平台。可以借助 agent-eval 工具包等开源工具，在几小时内搭建评估流水线；该工具将 OpenTelemetry 轨迹采集与 Gemini 平台上的 Agent Evaluation 服务（此前为 Vertex AI Evaluation）配对使用。不过，构建实际的评估策略仍需要更多思考。

Day 0：场景、模拟与“红笔”

从小处着手，并紧贴原始数据：

1. 起草覆盖主要 CUJ 的场景，并通过你的 Agent 运行模拟。
2. 忽略汇总分数，从头到尾阅读真实执行轨迹：提示词、中间推理步骤、工具参数和最终输出。
3. 用一支红笔为轨迹评分，标出 Agent 犹豫、幻觉出参数、选择错误工具或冗长赘述的每一个位置。

一条使用红笔评分的 Agent 轨迹。

**为什么红笔很重要：**与自动生成图表相比，人工阅读 20 条轨迹感觉很慢，但它能节省数天的无效工作。与其猜测假想的失败模式、编写无法命中问题的通用评分量规，不如花一小时用红笔了解系统在现实中究竟如何失效。汇总这些记录后，你会得到一份高信号清单，明确知道下一步需要构建哪些确定性断言和布尔裁判检查。

Day 1：节奏、信号与测试框架

一旦有了初始检查清单，agent-eval 工具包等工具就会接管繁重工作，并对执行进行标准化。它可帮助你完成以下工作：

• **脚手架与执行：**为你的黄金数据集生成脚手架，并通过 HTTP（--base-url）或离线方式，针对 Agent 执行多轮场景。
• **框架无关的轨迹摄取：**无论使用 Google ADK、LangGraph 还是自定义运行时构建，都能获取遵循 OpenInference 约定的结构化 OpenTelemetry 轨迹。
• **Agent Evaluation 集成：**将这些轨迹路由至 Gemini 平台上的 Agent Evaluation 服务，以运行确定性检查和布尔裁判评分量规，而无需编写专用 API 代码。

为评估流水线建立固定的运行节奏：

• **每次变更都运行：**无论调整提示词、更换模型，还是修改工具文档字符串，都应执行完全相同的一组测试，并将差异与基线进行比较。

agent-eval HTML 报告中的长期指标。

• **根据轨迹验证裁判：**绝不能盲目信任新的 LLM-as-a-judge 指标。应将自动评分与 Day 0 时人工评分的轨迹进行比较。如果裁判给一条被你用红笔标注过的问题轨迹判定通过，就应收紧评分提示词，直到自动化信号与你的工程判断一致。

调优循环：50 到 60 次调参迭代，而非重写

Day 1 的框架启用后，优化将变成一种严谨、机械化的循环：

示例 Agent 的一次调优循环。

在真实部署中，达到生产质量通常需要进行 50 到 60 次小规模迭代。你不是每天早晨都重写整个系统提示词，而是在逐步调整各个独立的旋钮：一次调整澄清某个工具参数的描述，下一次添加负向约束，再下一次修改 JSON 输出模式。

例如，在每次评估运行结束后，agent-eval 框架会构建一份交互式一体化 HTML 报告。这份报告会将通过/失败的布尔指标与关键运营指标对齐展示，包括延迟、token 用量、API 支出、缓存利用率，以及详细的工具调用执行路径。此外，报告还会纳入 Gemini 针对失败对话轮次生成的自动化根因分析，精准指出触发失败的提示词指令或参数设置，从而为下一次调整提供指引。

这些数据取代了猜测。某项提示词改动在人工抽查中可能显得聪明得多，但测试套件可能会显示：延迟翻倍，工具调用幻觉上升了 15%。

对构建 Agent 的团队而言，教训是：小幅、可度量的改动，每一次都胜过大规模重写。

Day 2：合并门禁与共享仪表板

一旦你信任评估流水线输出的信号，就应将其转化为永久性的回归安全网：

• **使用无头 CLI 设置 CI/CD 拉取请求门禁：**在构建流水线中（例如 Cloud Build 或 GitHub Actions）以无头方式执行 agent-eval 等工具。每次拉取请求时，它都会运行黄金数据集，并执行两项合并规则：

1. 全局通过阈值： 测试套件必须达到最低通过标准（例如，95% 的布尔检查成功）。
2. 核心评估指标零回归： 即使总体分数保持稳定，只要任何此前通过的指标发生回归，构建就会失败。这可以防止开发者无意中用一项次要边缘情况的改进，交换掉关键能力。

• **共享仪表板和

TL;DR

Your agent can loop, burn tokens, or give a completely hallucinated answer and still look fine. A vibe check won't catch that. This post is the playbook behind our AI Agent Clinic episode How to Actually Evaluate (Any) AI Agent: Beyond the Vibe Check, where we build an eval pipeline for a LangGraph agent in 60 minutes. Here's what's inside:

Evaluating AI agents: moving past the vibe check

When teams start building an AI agent, testing usually looks the same. You wire up a model, hand it a few tools, run three or four prompts in a terminal, and eyeball the output. If the answer looks reasonable, you ship it.

In practice, this breaks down fast. You tweak a system prompt to fix an edge case in one workflow, and suddenly the agent stops calling a required tool in another.

Worse, agents fail differently than standard software. An agent can get stuck in a retry loop, fire off multiple tool calls, yet still return a polite, plausible-sounding final answer.

In production, that hidden failure is costly:

• It quietly spikes your cloud bill and token usage.
• It exhausts downstream API rate limits and quotas.
• It leaves users staring at a loading spinner.
• It can trigger duplicate side effects in external systems, all while looking "fine" on the surface.
• It erodes user trust, and first impressions are hard to win back.

Integrating a reliable evaluation suite into your development lifecycle can seem like extra overhead during initial prototyping, right up until modifying your system prompt causes unexpected breaking changes. The key is recognizing that evaluation is a progressive journey: any repeatable evaluation system (no matter how simple) is better than relying on ad-hoc spot checks or no system at all. You don't need an elaborate automated grading architecture on Day 0. Instead, start with simple, repeatable checks and evolve your evaluation into a more complex, automated framework as your agent's capabilities and production demands grow.

Establishing a repeatable evaluation system is made substantially easier by integrating these decisions into an evaluation framework. Transitioning beyond simple subjective checks relies on two core pillars: human oversight and targeted tools. In this article, we explore how to set up an evaluation framework using the open-source agent-eval toolkit. We'll demonstrate how combining manually reviewed traces with automated verification helps detect silent regressions early in development and scales seamlessly as your agent transitions to production.

---

Getting started: the high-level building blocks

1. Define success with critical user journeys

Before writing test code, you need a shared vision of what a good outcome actually looks like. Anchor your tests in critical user journeys (CUJs) rather than abstract benchmarks.

A CUJ defines what a user expects the system to achieve, structured around their persona, goals, constraints, and verification conditions:

"As an operations analyst, I expect the agent to ingest a counterparty trade discrepancy email, identify the disputed transaction, verify the trade economics against our internal ledger within 30 seconds, and draft a response reverse-translating our internal trade IDs back into the broker's nomenclature without human intervention."

Every clause in that statement becomes an evaluation point: Did the agent resolve the correct transaction ID? Did it check the ledger before drafting? Did it map internal IDs back to the external nomenclature?

Every clause of a CUJ becomes an evaluation point.

Defining these expectations upfront forces product stakeholders, downstream users, and engineers to agree on defining how “success” is measured.

2. Start with simulated users, graduate to real traffic

You do not need six months of production logs to build your initial golden dataset. Instead, break each CUJ down into concrete scenarios (both happy paths and edge cases) and feed them into a user simulator LLM (we like ADK user simulations). Primed with a persona and behavioral constraints (for example, an impatient analyst giving incomplete ticket numbers, or a developer asking a multi-part debugging question), the simulator mirrors the messy phrasing, typos, and multi-turn complexity of real users.

Example scenarios for ADK user simulations.

By testing your agent against a synthetic user and realistic scenarios, you can record comprehensive execution traces (including tool logs) prior to user interaction. This enables you to pinpoint and resolve any performance gaps against your release standards. As live traffic begins to flow, you can progressively replace these synthetic setups with real production traces.

3. Measure across the full stack

A single top-line score will never tell you why an agent failed. To isolate root causes, layer four types of checks: unit tests, deterministic metrics, LLM-as-a-judge rubrics, and integration tests.

Four layers of checks, from unit tests to integration tests.

Four common traps to avoid

Trap 1: Throwing tests out and breaking your baseline

Setting up evaluation metrics involves trial and error, and it is tempting to delete a noisy test or swap out sample queries between runs. Every time you add or remove a test, though, you invalidate your baseline: you cannot tell if a score changed because the agent got better or because the test suite moved. Keep your golden dataset frozen while you tune a feature, change one variable at a time, and only retire a test when you are certain the underlying requirement has changed.

Deleting tests moves the baseline, not the agent.

Trap 2: Relying on fuzzy 1-to-5 judge scores instead of boolean checks

LLMs are notoriously inconsistent at grading qualitative 1-to-5 scales; the boundary between a "3" and a "4" is fuzzy and often shifts from run to run.

Whenever possible, turn your judge rubrics into boolean (pass/fail) questions rather than open-ended rating scales. Rather than asking "How helpful was this answer from 1 to 5?" , ask "Did the agent verify the account ID before calling the refund tool? (Yes/No)". (We like Adaptive Rubrics )

Trap 3: Evaluating the prose while ignoring the operational bill

A response that passes every quality check is still a production failure if it took 40 seconds, made twelve redundant tool calls, and cost sixty cents per query.

Always evaluate the whole system rather than just the final text. Track latency, token consumption (prompt, reasoning, and completion tokens), API cost, and tool-call counts right alongside answer quality.

Trap 4: Building a different eval pipeline for a different agentic framework

Switching orchestration frameworks often forces teams to scrap and rewrite their entire testing suite. While most frameworks emit OpenTelemetry traces, they don’t use the same semantic conventions for tool calls, steps, and tokens. Standardizing your traces around open specifications like OpenInference solves this by decoupling evaluation from your orchestration framework. Tools like the agent-eval toolkit support this natively, with minimal setup.

---

A practical Day 0 to Day 2 rollout

You do not need to build an observability platform from scratch. You can stand up the evaluation pipeline in a couple of hours using open-source utilities like the agent-eval toolkit which pairs OpenTelemetry trace capture with the Agent Evaluation service on the Gemini platform (formerly Vertex AI Evaluation). But building your actual evaluation strategy requires more thought.

Day 0: Scenarios, simulations, and the "red pen"

Start small and stay close to the raw data:

1. Draft scenarios covering your main CUJs and run simulations through your agent.
2. Ignore aggregate scores and read the actual execution traces from top to bottom: the prompts, intermediate reasoning steps, tool arguments, and final outputs.
3. Grade the traces with a red pen , marking every spot where the agent hesitated, hallucinated a parameter, picked the wrong tool, or rambled.

One agent trace, graded with a red pen.

Why the red pen matters: Manually reading twenty traces feels slow compared to auto-generating a chart, but it saves days of wasted effort. Instead of guessing at hypothetical failure modes and writing generic rubrics that miss the mark, an hour with a red pen shows you how your system actually breaks in reality. Aggregating those notes gives you a high-signal list of the exact deterministic assertions and boolean judge checks you need to build next.

Day 1: Cadence, signal, and the testing framework

Once you have that initial list of checks, tools like agent-eval toolkit takes over the heavy lifting and standardizes execution. Helping you with things like:

• Scaffolding and execution: Scaffold your golden dataset and execute multi-turn scenarios against your agent over HTTP (--base-url) or offline.
• Framework-agnostic trace ingestion: Get structured OpenTelemetry traces with OpenInference conventions, whether you build with Google ADK, LangGraph, or a custom runtime.
• Agent Evaluation integration: Routes those traces into the Agent Evaluation service on Gemini platform to run your deterministic checks and boolean judge rubrics without bespoke API code.

Establish a regular cadence of runs with your eval pipeline:

• Run on every change: Whenever you adjust a prompt, swap a model, or edit a tool docstring, execute the exact same test battery and compare the delta against your baseline.

Metrics over time in the agent-eval HTML report.

• Validate the judge against your traces: Never trust a new LLM-as-a-judge metric blindly. Compare the automated scores against the traces you graded by hand on Day 0. If the judge gives a passing score to a trace you marked up with red ink, tighten the grading prompt until the automated signal matches your engineering judgment.

The tuning loop: 50 to 60 iterations of turning knobs, not rewrites

Once your Day 1 framework is active, optimization becomes a disciplined, mechanical loop:

One turn of the tuning loop on a sample agent.

In a real deployment, reaching production quality often takes 50 to 60 small iterations. You are not rewriting the entire system prompt every morning; you are gradually turning individual knobs. One tweak clarifies a tool parameter description. The next adds a negative constraint. The next adjusts the JSON output schema.

For instance, upon completion of each evaluation run, the agent-eval framework constructs an interactive, all-in-one HTML report. This report aligns pass/fail boolean metrics alongside key operational metrics, including latency, token usage, API expenditure, cache utilization, and detailed tool-call execution paths. Additionally, it incorporates automated Gemini root-cause analyses for failed conversational turns, pinpointing the exact prompt directive or parameter setting that triggered the failure to guide your next adjustment.

That data replaces hunches. A prompt change might feel much smarter in manual spot-checking, only for the test battery to reveal that latency doubled and tool-call hallucinations ticked up by 15%.

The lesson for teams building agents: small, measured changes beat big rewrites every time.

Day 2: Merge gates and shared dashboards

Once you trust the signal coming out of your eval pipeline, turn it into a permanent regression safety net:

• CI/CD pull request gates with headless CLI: Execute tools like agent-eval headlessly in your build pipeline (such as Cloud Build or GitHub Actions). On every pull request, it runs your golden dataset and enforces two merge rules:

1. A global pass threshold: The suite must meet a minimum pass bar (for example, 95% boolean success).
2. Zero regressions on core evaluation metrics: Even if the overall score holds steady, the build fails if any previously passing metric regresses. This prevents developers from accidentally trading a critical capability for a minor edge-case improvement.

• Shared dashboards and centralized storage: Configure your eval processes to export run artifacts—including raw trace JSONL, prompt hashes, model versions, latency profiles, and scorecard summaries—into a central data warehouse like BigQuery or Cloud Storage. Publishing these metrics to a shared team dashboard gives everyone visibility into accuracy, latency percentiles, and token budgets across releases.

After launch, real production traces flow back into the golden dataset.

See it in action

---

Frequently asked questions

What are the issues with manual "vibe checks" for AI agents?

Running three or four prompts in a terminal only shows you the final text response. An agent can loop on retries, hallucinate tool parameters, burn token budgets, or trigger duplicate side effects while still returning a polite answer. Automated trace evaluation checks intermediate tool calls, state transitions, latency percentiles, and API cost alongside answer quality so silent regressions don't ship.

How do I evaluate an AI agent from scratch?

Treat evaluation as a progressive rollout from Day 0 to Day 2 rather than an all-or-nothing jump. On Day 0 , break your critical user journeys (CUJs) into a handful of test scenarios and run them through ADK user simulations. Read those first 5 to 20 execution traces with a "red pen" to see where the agent hesitates, picks the wrong tool, or rambles.

On Day 1 , turn those red-pen notes into automated checks so you can tune one variable at a time. Once your pass rates stabilize, lock those checks into Day 2 CI/CD pull request gates.

Why use boolean (pass/fail) checks instead of 1-to-5 rating scales for LLM-as-a-judge?

LLM judges don't grade 1-to-5 scales consistently because the boundary between a "3" and a "4" shifts from run to run. With Adaptive Rubrics, you split broad quality goals into strict Yes/No questions like "Did the agent verify the account ID before refunding?" Pair those boolean rubrics with deterministic computation metrics for tool parameters and reference checks, plus trace assertions for latency and token budgets.

Can I use the same evaluation pipeline across LangGraph, Google ADK, and custom agent frameworks?

Yes, if you decouple your evaluation pipeline from your agent framework by standardizing OpenTelemetry traces on OpenInference semantic conventions. The open-source agent-eval toolkit routes those traces straight to the Agent Evaluation service on the Gemini platform (formerly Vertex AI Evaluation). You don't have to rewrite grading code when switching orchestration frameworks.

What happens after my agent is deployed to production?

Once your Day 2 pipeline exports traces and scorecards to BigQuery or Cloud Storage, you can compare live traffic against your pre-production baseline. When users hit edge cases your initial scenarios missed, ambient quality agents like The Outer Loop help you diagnose those failing production traces. You can then promote those real traces straight into your Day 0 golden dataset so your test suite evolves with live usage.