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

构建 AI 代理的团队通常像评估其他软件一样评估它们：检查输出是否符合预期。但是，自主选择工具并跨多个来源排序操作的代理会产生输出级测试无法完全表征的行为。一个代理可能会提供结构良好、可操作的响应，同时产生幻觉，因为其工具返回了空结果而捏造事实。它也可能在跳过可靠过程所需的验证步骤的情况下得出正确结论。由于这些失败隐藏在最终响应的表面之下，捕获它们需要追溯代理完整执行路径的评估：代理调用了哪些工具，这些工具返回了什么数据，以及响应是否忠实地反映了这些数据。

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

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

代理评估需要什么

除了基础设施本身，选择衡量什么同样要求很高。代理质量跨越多个维度，没有单一指标可以捕获：响应是否基于工具实际返回的内容、代理是否以正确的参数调用了正确的工具、以及最终输出是否连贯且对提问者有用。一个响应可能读起来很好，同时悄悄地对空工具结果产生幻觉；代理可能通过一系列错误的工具调用得出一个看似合理的答案，因此每个维度都必须单独检查，而不是从相邻维度推断。

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

Agent-EvalKit 的工作原理

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

该过程从你的代理源代码开始，助手读取工具定义、系统提示和框架配置，以构建代理做什么、可以调用哪些工具以及其行为可能在哪里崩溃的详细模型。工具包在后续阶段产生的每个工件，从评估计划到最终报告，都建立在这个代码级别的理解之上。

基于此基础，助手设计一个个性化的评估计划，其中指标针对代理的能力和风险领域，然后通过后续阶段生成测试用例、用 OpenTelemetry 兼容的追踪仪器化代理、在收集结构化追踪的同时运行每个测试用例、并根据你的标准评估结果。该过程以一份报告结束，其中优先建议引用代码中的特定位置，将评估结果直接连接到可操作的修复。如果你指示系统关注由空工具结果触发的幻觉，例如，该指导将影响测试用例生成、指标选择以及报告最终强调的模式。

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

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

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

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

数据 (/evalkit.data) 生成基于评估计划的测试用例，每个测试用例都有输入和预期结果，针对代理需要处理的特定行为和故障模式。如果你已经有来自生产日志或手动测试的测试数据，你可以改为将这一阶段指向你现有的数据集。

追踪 (/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 分析了代理的代码，在计划阶段，设计了一个围绕三个指标的集中评估：忠实度衡量响应是否基于工具实际返回的数据；工具参数准确性检查代理是否以正确的输入调用工具；响应质量评估输出有多连贯和有用。数据阶段随后生成了 100 个多轮测试会话，涵盖目的地研究、季节时机、行程构建、比较问题和预算计算，后续阶段运行每个会话并捕获详细的执行追踪。

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

下图显示了单个执行中的这种幻觉模式，代理收到空工具响应并呈现虚构数据，就好像它来自其工具一样。

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

演练

以下各节将引导你完成 Agent-EvalKit 的先决条件、安装工具包并针对你的代理运行端到端评估。

先决条件

运行 Agent-EvalKit 评估需要云访问基础模型推理和本地工具进行评估工作流。

一个有效的 AWS 账户，在 Amazon Bedrock 控制台中启用了基础模型。Agent-EvalKit 使用 LLM 作为评判指标，需要基础模型进行评分，因此在继续之前，请确认您的模型在“模型访问”页面上可用。

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 /evalkit.quick Evaluate my agent at ./my_agent for response quality and tool accuracy

为了获得更多控制，您可以单独运行每个阶段。