Evaluate AI agents systematically with Agent-EvalKit

使用 Agent-EvalKit 系统性地评估 AI 代理 | 人工智能

使用 Agent-EvalKit 系统性地评估 AI 代理

构建 AI 代理的团队通常通过检查输出是否符合预期的方式来评估它们，这与评估其他软件的方式相同。但那些能够自主选择工具并在多个来源之间按顺序执行操作的代理，其行为是输出级测试无法完全描述的。

一个代理可能会在产生幻觉、编造事实的情况下，给出一个结构良好且具有可操作性的响应，因为其工具返回了空结果。它也可能在跳过可靠流程所需的验证步骤的情况下得出正确的结论。由于这些失败隐藏在最终响应的表面之下，因此要发现它们，需要追踪代理的完整执行路径的评估：代理调用了哪些工具，这些工具返回了哪些数据，以及响应是否忠实地反映了这些数据。

弥补这一差距需要基础设施，而大多数代理团队并没有足够的人员来从零开始构建。你需要具有真实结果的测试用例、用于捕获工具调用和中间状态的可观测性工具，以及评估忠实度和工具使用情况的指标，这些都需要与表面准确性一起进行评估。

Agent-EvalKit 是一个开源工具包（Apache 2.0），它通过与 AI 编程助手（包括 Claude Code、Kiro CLI 和 Kilo Code）集成，使这种评估基础设施变得可用。它将整个工作流程带入你的开发环境，而不是将评估视为部署后的独立工作。你只需用自然语言描述评估目标，工具包将处理每个阶段，从读取代理的源代码并生成有针对性的测试用例，到运行评估并生成包含改进建议的报告，这些建议会引用代码库中的具体位置。以下部分将通过使用 Strands Agents SDK 和 Amazon Bedrock 构建的旅行研究代理作为运行示例，逐步介绍 Agent-EvalKit 在其六个评估阶段的工作方式。

代理评估所需的内容

除了基础设施本身，选择要衡量的内容同样具有挑战性。代理的质量涵盖多个维度，而这些维度没有单一的指标能够涵盖：响应是否基于工具实际返回的内容，代理是否使用了正确的工具和正确的参数，以及最终的输出是否对提问者来说是连贯且有用的。一个响应可能看起来很好，但可能在工具结果为空的情况下悄然产生幻觉；一个代理可能通过一系列错误的工具调用得出一个看似合理的答案，因此每个维度都必须单独检查，而不是从相邻的维度推断出来。

没有一种评估方式能够很好地处理这三个方面。基于代码的评估器能够提供快速且可重复的结果，但会惩罚有效的不同方法。将大型语言模型（LLM）作为评判者的评估器能够提供细致的评估，但需要额外的推理和精心设计的提示。大多数有效的评估策略会结合这两种方法。将评估分数转化为具体的代码更改是许多努力最终陷入停滞的地方，这就是为什么评估工作流程需要以具体的、代码级别的建议结束，而不是以一组数字仪表板结束。

Agent-EvalKit 通过你现有的 AI 编程助手进行操作，而不是作为一个独立的评估平台运行。你的助手，无论是 Claude Code、Kiro CLI 还是 Kilo Code，都会通过在评估过程的每个阶段运用其阅读代码和推理代理行为的能力，成为评估引擎。你可以通过类似 /evalkit.plan 和 /evalkit.data 的斜杠命令来驱动这一流程，并附加自然语言指导，告诉助手哪些质量维度对你的代理最为重要。这种设计将评估保留在你的开发环境中，因此帮助你构建代理的同一助手也能帮助你评估它。

该过程从代理的源代码开始，助手会读取工具定义、系统提示和框架配置，以构建一个详细模型，了解你的代理能做什么、可以调用哪些工具，以及其行为可能在哪些地方出现问题。后续阶段中，工具包生成的每一个工件，从评估计划到最终报告，都基于这种代码层面的理解。

在此基础上，助手会设计一个个性化的评估计划，针对你的代理的能力和风险区域设定指标，然后依次进行后续阶段，生成测试用例、使用 OpenTelemetry 兼容的追踪工具对你的代理进行插装、运行每个测试用例并收集结构化追踪信息，最后根据你的标准评估结果。这一过程最终生成一份报告，其中的优先推荐会引用你代码中的具体位置，将评估结果直接与可操作的修复措施联系起来。例如，如果你指示系统重点关注由空工具结果触发的幻觉，这种指导将影响测试用例的生成、指标的选择以及报告最终突出显示的模式。

以下图表说明了从测试用例到指标评估的这一流程。

该工具包将这些工作组织成六个阶段，每个阶段都会在 eval/ 目录中生成工件，供下一阶段使用。你可以通过 AI 助手使用斜杠命令调用每个阶段，命令后的文本将作为该阶段的自然语言指导。一旦初始工件就位，你可以使用不同的指导重新调用任何阶段，以改变重点或深入分析，而无需从头开始重新构建。

这六个阶段涵盖了完整的评估生命周期，从理解代理的能力到推荐具体的代码改进。

• Plan（/evalkit.plan）读取你的代理代码，以了解其工具和框架，然后生成一个评估计划，将每个指标与具体的评估方法配对。你的指导将决定该计划优先考虑哪些质量维度，这些优先级将在后续阶段的评估代码中体现。

• Data（/evalkit.data）根据评估计划生成测试用例，每个测试用例都有输入和预期结果，针对代理需要处理的具体行为和失败模式。如果你已经有来自生产日志或手动测试的测试数据，你可以将此阶段指向你现有的数据集。

• Trace（/evalkit.trace）通过向你的代理添加 OpenTelemetry 兼容的追踪，使完整的执行路径可见。对于支持的框架，包括 Strands、LangGraph 和 CrewAI，它会检测框架并应用适当的插装。有关当前支持框架的详细信息，请参阅 Agent-EvalKit 仓库。

• 运行代理（/evalkit.run_agent）会将你的代理对每个测试用例进行执行，为每次运行生成一个结构化的跟踪文件，记录完整的工具调用历史、模型响应和中间状态。

• 评估（/evalkit.eval）将你的计划中的指标实现为可执行的评估代码，对收集到的跟踪数据进行运行，并保存结构化的结果。它支持包括 DeepEval 和 Strands Evals SDK 在内的评估库，选择最适合你的代理和指标的方法。

• 报告（/evalkit.report）分析测试用例之间的模式，并生成优先级排序的建议，这些建议会引用你代理代码中的具体位置，每个建议都包括其预期影响，以便你将改进努力集中在最能产生影响的地方。

在这些阶段中，模糊的质量问题会转化为结构化的证据：测试用例、执行跟踪、指标分数和优先级排序的建议，所有这些都与代码中的具体位置相关联。

演示研究：评估一个旅行研究代理

在使用 Strands Agents SDK 和 Amazon Bedrock 开发一个旅行研究代理的过程中，我们注意到代理有时会在响应中提供异常精确的数字。该代理帮助用户使用网络搜索、航班信息、气候数据、货币转换和预算计算等工具来规划旅行，但我们无法确定这种精确性问题的普遍程度或哪些查询触发了它。

Agent-EvalKit 分析了代理的代码，并在计划阶段围绕三个指标设计了一个有针对性的评估：Faithfulness（忠实度）衡量响应是否基于工具实际返回的数据，Tool Parameter Accuracy（工具参数准确性）检查代理是否使用正确的输入调用工具，Response Quality（响应质量）评估输出的连贯性和实用性。随后的数据阶段生成了 100 个包含目的地研究、季节时间安排、行程构建、比较问题和预算计算的多轮测试会话，后续阶段运行了每个会话并捕获了详细的执行跟踪。

结果揭示了质量和可靠性之间的明显差异。响应质量得分为 83.9%，确认代理提供了清晰且可操作的旅行建议，工具参数准确性达到 64.5%，表明代理通常选择了正确的工具，但有时传递了不精确的参数。忠实度得分仅为 32.3%，表明当网络搜索工具返回空或不完整结果时，代理会编造汇率、温度和景点信息，并将这些虚构内容呈现为来自其工具的结果。

下图展示了这种幻觉模式在单次执行中的表现，其中代理接收到一个空的工具响应，并将虚构的数据呈现为来自其工具的结果。

报告将幻觉防护机制确定为最高优先级的修复，建议在系统提示中加入说明，当工具返回空结果时进行披露，并改进所有代码路径中的工具错误处理。在运行 Agent-EvalKit 之前，我们知道代理有时似乎不可靠。运行之后，我们知道了根本原因是空的工具输出触发了幻觉，并且有具体的代码更改可以解决这个问题。

演示说明

以下部分将引导你完成使用 Agent-EvalKit 的前提条件，安装工具包，并对你的代理进行端到端的评估。

先决条件

运行 Agent-EvalKit 评估需要云访问权限以进行基础模型推理，并且需要本地工具来执行评估流程。

• 一个具有 Amazon Bedrock 控制台中启用基础模型的活跃 AWS 账户。Agent-EvalKit 使用 LLM-as-judge 指标，这些指标需要基础模型进行评分，因此在继续之前，请确认您的模型在 Model access 页面上可用。

• Python 3.11 或更高版本和 Git。

• uv 包管理器。在 macOS 和 Linux 上，使用以下命令安装：curl -LsSf https://astral.sh/uv/install.sh | sh。

• 在您的机器上安装并配置了支持的 AI 编码助手（Claude Code、Kiro CLI 或 Kilo Code）。本文中的示例使用了 Claude Code，但该工作流程适用于所有三种助手。请参阅每个助手的文档以获取安装说明。

入门

使用 uv 安装工具包，它会直接从 Agent-EvalKit GitHub 仓库中拉取代码。

uv tool install evalkit --from git+https://github.com/awslabs/Agent-EvalKit.git

初始化一个评估项目并将您的代理代码复制到项目目录中。您的代理目录应包含源代码、工具定义以及运行代理所需的任何配置。有关支持的代理框架和项目结构的详细信息，请参阅 Agent-EvalKit 仓库。

evalkit init my-agent-evaluation
cd my-agent-evaluation
cp -r /path/to/your/agent .

从评估项目内部启动您的 AI 助手。对于 Claude Code，请运行 claude 命令。

claude

对于首次评估，quick 命令会逐步引导您完成所有六个阶段，解释每个阶段的作用以及下一步要运行的命令。

/evalkit.quick <your natural language guidance>
/evalkit.quick Evaluate my agent at ./my_agent for response quality and tool accuracy

如果您需要更多控制，可以单独运行每个阶段。

/evalkit.plan <your natural language guidance>
/evalkit.plan Evaluate my agent at ./my_agent for response quality and tool accuracy
/evalkit.data
/evalkit.trace
/evalkit.run_agent
/evalkit.eval
/evalkit.report

以下视频逐步演示了完整的流程，其中 Agent-EvalKit 对一个配备了网络搜索和规划工具的旅行研究代理进行了评估，覆盖了从代码分析到最终评估报告的所有六个阶段。

最佳实践

当评估代理在每次有意义的更改时运行，而不是作为发布前的检查点时，评估效果最佳。以下实践反映了我们在将 Agent-EvalKit 整合到持续开发周期中时发现的最有用的方法。

• 从狭窄的范围开始，专注于两个或三个指标，这些指标针对您的代理最关键的几个质量维度，随着初始发现的解决和对基线的信心增加，在后续评估中逐步扩展范围。

• 使用领域知识进行引导，并描述在每个阶段中观察到的具体输入、边缘情况和失败模式。您的自然语言指令越具体，生成的测试用例、指标和建议就越相关。

• 在执行之前审查测试用例，因为数据阶段会根据评估计划合成案例，但您对真实用户行为的理解是不可替代的。添加反映您在生产中观察到的模式的场景。

• 在每次重大更改后进行评估，以便尽早发现回归问题并衡量每个改进的影响。通过比较不同代理版本的报告，可以清晰地看到进展，并使开发工作集中在最有价值的修复上。

• 逐步处理建议，从报告中影响最大的项目开始。实施修复后，重新评估以确认改进，然后再处理下一个问题。

• 基于之前的评估，通过重新调用各个阶段来探索新的质量维度，同时重用现有的测试用例和监控工具。例如，最初专注于忠实度的评估可以随后深入检查工具的准确性，而无需重新生成数据或重新监控代理。

• 通过使用 Amazon Bedrock AgentCore Observability 从实际流量中捕获追踪信息，并使用 AgentCore Evaluation 对这些追踪信息运行质量指标，持续监控生产环境中的代理。生产环境监控可以揭示预部署评估无法预见的回归问题和新的故障模式。

• 通过定期将 LLM-as-judge 的评分与领域专家或人工标注者的判断进行比较，确保评估者与人类专家保持一致。当两者出现偏差时，更新评估者的提示，以确保自动化指标继续反映对用户重要的质量维度。

与 CI/CD 集成

对于准备自动化的团队，下图展示了 Agent-EvalKit 如何集成到持续集成和持续交付（CI/CD）流程中，其中代码更改会触发评估，质量门检查指标阈值和回归问题，失败项会作为评估报告中的标记项返回。

一旦流程建立，每一轮测试都会重用前一轮的测试用例和监控工具，因此随着项目的成熟，运行全新评估的成本会逐渐降低。

清理

如果您创建了一个评估项目，请在完成时删除该项目目录。如果您的评估使用了 Amazon Bedrock 的基础模型，请在 AWS Management Console 的 Amazon Bedrock 定价页面上查看使用情况，以了解可能产生的相关费用。

结论

Agent-EvalKit 通过将评估设计、指标计算和报告等每一步都委托给您已经使用的 AI 助手，为 AI 代理评估提供了系统化的框架。旅行研究代理的案例研究展示了这一方法的实际效果，将模糊的质量关注点转化为特定代码行的具体修复，并附带预期的影响。

随着代理承担的任务风险和影响范围增加，超越输出检查的评估成为生产就绪的先决条件。Agent-EvalKit 的设计旨在将这一评估过程融入您已经使用的编写和审查代理代码的开发流程中。

访问 Agent-EvalKit 的 GitHub 仓库，获取完整的文档和示例评估，并使用 GitHub 讨论功能与团队交流问题、反馈或贡献。有关该解决方案的更多信息，请参阅《关于自动化代理评估的实证研究》。

作者简介

'."