如何知道你的AI智能体是否真的有效？系统化评估指南

问题：你构建了一个智能体，但它真的能用吗？

你花了几天甚至几周的时间构建一个AI智能体。它能回答问题、调用工具并进行对话。你手动测试了几次，它似乎能用。但当你准备部署它或与用户分享时，一个挥之不去的问题出现了：你如何真正知道它是可靠的？

手动测试是一个开始，但它很脆弱。你可能会反复测试相同的三个场景，而错过边缘情况。你可能会修改一个提示词，却破坏了你没想到要检查的功能。你甚至可能对智能体“有效”的含义没有清晰的定义。是给出听起来合理的答案就够了，还是需要每次都事实正确？它是否需要以特定顺序使用工具？它是否应该拒绝某些请求？

没有结构化的评估过程，你就是在盲飞。你无法衡量改进，无法捕捉回归，也无法自信地告诉利益相关者你的智能体达到了质量标准。对于基于像Google的智能体开发工具包（ADK）这样的框架构建的智能体来说，这一点尤其重要，因为其行为可能很复杂且涉及多轮对话。

核心问题是评估是事后才考虑的事情。大多数开发者先构建，希望以后再测试。但“以后”通常意味着在发布前进行几次手动抽查。你需要的是一种方法，能够预先定义成功是什么样子，自动针对这些定义运行你的智能体，并获得清晰、可操作的反馈，指出它在哪里失败。

一个好的评估解决方案应该改变什么

一个针对AI智能体的适当评估系统，不应该仅仅是运行几个测试用例。它应该提供：

1. 定义测试用例的结构化方式。 不仅仅是“问它一个问题”，而是一个包含输入、预期输出以及判断成功所需上下文的数据集。
2. 自动化执行。 你应该能够用一个命令针对整个数据集运行你的智能体，而不是手动输入提示。
3. 客观评分。 结果不应该依赖于你的主观感觉。应该有指标——无论是确定性检查还是LLM作为评判的评估——能够产生一致的分数。
4. 可操作的失败分析。 当某些东西失败时，你需要知道为什么。是幻觉吗？它选错了工具吗？它放弃得太早了吗？反馈应该指向一个修复方案。
5. 跟踪进度的方法。 在你做出更改后，你需要看到你的分数是否有所提高，同时没有破坏其他东西。

这不是关于找到一个神奇的“通过/失败”按钮。而是关于创建一个反馈循环，让你能够系统地提高智能体的质量。你进行迭代：定义一个测试，运行它，看它在哪里失败，修复智能体，然后再次运行。随着时间的推移，你会建立起信心，相信你的智能体在各种场景下都能按预期行事。

介绍 google-agents-cli-eval：ADK智能体评估的实用选项

如果你正在使用Google的智能体开发工具包（ADK）构建智能体，并使用 agents-cli 工具链，那么 google-agents-cli-eval 技能为这个评估循环提供了一个结构化框架。它不是一个独立的应用程序，而是集成到 agents-cli 工具中的一组命令和方法论。

该技能围绕Google所谓的“质量飞轮”设计——一个迭代过程，包括准备数据、运行推理、评分结果、分析失败和优化智能体。它专门为ADK智能体量身定制，并利用智能体平台的评估服务来实现一些高级功能。

重要背景： 此技能假设你已经在使用 agents-cli 并且有一个基于ADK的智能体项目。它不是适用于任何AI模型的通用评估工具。它与ADK生态系统深度集成。

评估工作流程如何运作

该过程遵循一个清晰的五阶段循环。你并不总是需要使用每个阶段，但理解这个流程是关键。

阶段1：准备你的评估数据

你需要测试用例。该技能建议从一个简单的JSON数据集文件开始，通常在 tests/eval/datasets/ 目录下搭建。一个基本的数据集可能看起来像这样：

[
  {
    "input": "伦敦的天气怎么样？",
    "expected_output": "伦敦当前的天气是...",
    "tools_used": ["weather_api"]
  }
]

对于更复杂的多轮对话，你可以使用 agents-cli eval dataset synthesize 命令。这会对你的实时智能体运行一个模拟用户，以生成真实的对话轨迹，然后可以用作评估数据。当你还没有真实用户日志时，这很有用。

阶段2：针对数据运行你的智能体

如果你手动创建了数据集，你需要在其上运行你的智能体。命令 agents-cli eval generate 会针对数据集中的每个输入执行你的智能体，并将完整的对话轨迹（包括工具调用和中间步骤）保存到 artifacts/traces/ 目录。

如果你在阶段1使用了 synthesize 命令，你可以跳过此步骤，因为它已经生成了轨迹。

阶段3：对结果评分（核心步骤）

这是评估发生的地方。agents-cli eval grade 命令获取阶段2的轨迹，并根据你定义的指标对它们进行评分。它会生成一个详细的结果文件（JSON和HTML格式），其中包含分数，更重要的是，还包括评判模型对每个分数的理由。

你可以使用快捷命令 agents-cli eval run 将阶段2和阶段3合并，用于常见情况。

阶段4：分析失败

阶段3生成的HTML报告是你理解出错原因的主要工具。你可以在浏览器中打开它，查看每个用例的分数和评判的推理。

对于包含许多失败的较大数据集，agents-cli eval analyze 命令可以提供帮助。它使用LLM对失败进行聚类并识别根本原因（例如，“30%的失败是由于对话过早终止”）。当你有几十个用例时，这比逐个阅读每个失败报告更高效。

阶段5：优化和修复

根据失败分析，你编辑你的智能体。这可能意味着：

• 调整系统提示或指令。
• 更改工具描述以更好地引导智能体。
• 修改智能体的编排逻辑。
• 如果预期行为有误，则更新评估数据集。

该技能提供了常见失败到修复的映射。例如，如果 multi_turn_task_success 指标很低，这意味着智能体没有完成用户的目标——寻找工具选择、缺失步骤或过早放弃的问题。

还有一个 agents-cli eval optimize 命令，它使用ADK的GEPA提示优化。谨慎使用。 它成本高昂（进行多次LLM调用）且耗时。最好在你手动修复了明显问题后作为最后一步使用，并且仅当剩余的失败明显与提示相关时。

为你的智能体选择正确的指标

该技能带有一组内置指标。选择哪些指标取决于你最关心什么。

• multi_turn_task_success：对大多数智能体来说最重要的指标。智能体最终是否完成了用户的要求？这是一个用于目标完成的综合指标。
• multi_turn_trajectory_quality：智能体的推理路径是否合乎逻辑？它采取了高效的步骤，还是漫无目的？
• multi_turn_tool_use_quality：专门评估智能体在整个对话中使用工具的情况。它是否调用了正确的工具并使用了正确的参数？
• final_response_quality：评判智能体最后一次响应的质量，不需要参考答案。适用于开放式任务。
• hallucination：检查智能体是否提出了其上下文或工具不支持的事实性主张。对RAG智能体至关重要。
• safety：检查策略违规。

你可以运行 agents-cli eval metric list 查看所有可用的内置指标。如果没有合适的，你可以使用LLM评判或确定性Python代码编写自定义指标。

何时使用此技能（以及何时不用）

适合使用：

• 你正在使用Google ADK构建智能体。
• 你正在使用 agents-cli 工具链进行开发。
• 你想要一个结构化、可重复的方式来测试智能体质量。
• 你的智能体涉及多轮对话和工具使用。
• 你熟悉命令行工具和JSON配置。

不适合使用：

• 你不使用ADK或 agents-cli。此技能与该生态系统紧密耦合。
• 你需要对单个提示进行简单的一次性测试。手动测试或更简单的脚本可能更快。
• 你正在寻找基于图形界面的评估平台。这是一个命令行驱动的工作流程。
• 你的智能体是纯生成式的（没有工具，没有多轮逻辑）。更简单的指标可能就足够了。

开始前需要检查什么

在开始之前，请检查以下内容：

1. 你的 agents-cli 版本。 该技能需要 agents-cli。通过 uv tool install google-agents-cli 安装（你需要先安装 uv）。
2. 你的项目结构。 如果你使用 /google-agents-cli-scaffold 技能创建了项目，你很可能已经有了 tests/eval/ 目录和 eval_config.yaml 设置。如果没有，你需要创建它们。
3. 你的智能体的稳定性。 评估过程假设你的智能体可以运行而不崩溃。如果你的智能体处于非常早期、不稳定的状态，请先修复关键错误。
4. 你对“好”的定义。 在编写评估用例之前，思考一下对你的智能体来说成功意味着什么。它应该做什么？它不应该做什么？这将指导你的指标选择和数据集创建。

安全性和仓库信号

• 仓库： 该技能是GitHub上官方 google/agents-cli 仓库的一部分，由Google维护。这表明了一定程度的维护和与ADK路线图的一致性。
• 许可证： Apache-2.0，这是一个宽松且标准的开源许可证。
• 安全级别： 在技能元数据中标记为“低”。这可能指的是技能本身的风险状况，而不是你的智能体的。评估命令本身除了运行你的智能体外，不会在你的系统上执行任意代码，但请始终检查你运行的命令。
• 主题： 仓库主题（google-cloud, gemini, agents, adk）确认了其对Google AI生态系统的关注。

开始使用：实用的第一步清单

1. 安装工具链： 确保已安装 uv，然后运行 uv tool install google-agents-cli。
2. 按需搭建： 如果开始一个新项目，考虑使用 /google-agents-cli-scaffold 技能来获得标准目录结构。
3. 创建最小数据集： 从在 tests/eval/datasets/basic-dataset.json 中创建1-2个简单测试用例开始。专注于一个核心用例。
4. 运行完整评估： 执行 agents-cli eval run。这将针对数据集运行你的智能体并进行评分。
5. 检查HTML报告： 打开生成的 results_<timestamp>.html 文件。查看分数以及评判对任何失败的理由。
6. 修复一个问题： 根据失败情况，对你的智能体进行一次有针对性的更改（例如，澄清一个提示指令）。
7. 重新运行并比较： 再次运行 agents-cli eval run。使用 agents-cli eval compare <旧结果>.json <新结果>.json 查看你的更改是否有帮助。

这个迭代过程——定义、运行、评分、修复、比较——是该技能的核心。它将智能体质量从一个猜测游戏转变为一个可衡量、可改进的属性。从小处开始，首先专注于你最重要的用例，随着智能体的成熟逐步扩展你的测试覆盖范围。

有关完整的参考文档，包括数据集模式和指标详情，请访问 google-agents-cli-eval 技能页面。