AWS 开源 UAEF：跨框架闭环评测 AI 智能体
UAEF: A framework-agnostic system for closed-loop evaluation of AI agents
AWS 发布开源框架 UAEF（Universal Agent Evaluation Framework），通过适配器把 LangGraph、LangChain、Strands Agents、Amazon Bedrock AgentCore 和 Langfuse 的 trace 统一为 AgentTrace，再用 7 个维度共 36 项内置指标打分。
在 AWS 上构建 AI agent 的团队会使用多种框架，包括 LangGraph、LangChain、Strands Agents 和 Amazon Bedrock AgentCore。每个框架都以自己的方式记录 agent 的执行过程，因此消息、工具调用以及 agent 之间交接的结构各不相同。评估工具往往也遵循同样的边界：团队针对单一框架的 trace 格式构建指标、评分逻辑和结果存储，而当他们切换框架或在多个框架上运行 agent 时，就必须重新构建这些内容。
这种耦合使得一个基本的开发问题更难回答：对提示词、模型或工具的更改是否改进了 agent？要回答这个问题，需要跨 agent 各版本的一致指标，以及可供比较的过往结果共享记录。Agent 质量还涵盖单一准确率分数无法捕捉的多个维度：工具调用、响应质量、负责任 AI、性能、多轮对话、多 agent 协调和推理。
在本文中，我们介绍通用 Agent 评估框架（UAEF）。来自电信、医疗保健和金融服务行业 12 个组织的客户使用 UAEF，以一套一致的指标评估其 AI agent，并在发布前比较 agent 版本。UAEF 是一个与框架无关的评估系统：它使用适配器将来自各框架的 trace 转换为通用格式，然后用覆盖 7 个维度的 36 个内置指标对这些 trace 进行评分。它将结果存储在 Amazon DynamoDB 和 Amazon Simple Storage Service（Amazon S3）中，并生成报告和洞察，为 agent 的下一轮迭代提供依据。本文介绍 UAEF 的工作原理，提供选择指标和准备数据集的行动指南，并指向每个受支持框架的可运行 notebook。
UAEF：面向 agent 框架的单一评估层
UAEF 是一个与框架无关的 AI agent 评估系统。它接收团队已有的 agent，并在受支持的框架和运行时中以相同方式对其进行评分。UAEF 接收两个输入：被测 agent 和用于运行它的数据集。数据集为每个测试用例提供输入，还可以包含真实答案，即每个输入的预期输出。真实答案是可选的，只有将 agent 响应与参考进行比较的指标才会使用它。要评估工具调用，真实答案还必须包含每个测试用例的预期工具调用：agent 应调用哪些工具、以什么顺序调用以及使用什么参数。此后的一切都在 UAEF 内部完成。
图 1 展示了单次评估所经历的路径，从输入到报告和洞察。首先，适配器读取智能体的原生执行记录，包括其消息、工具调用以及智能体之间的交接，并将其规范化为一个统一的规范轨迹，这样无论智能体由哪个框架生成，后续步骤都完全相同。接下来，UAEF 在数据存储之前筛查轨迹中的个人身份信息（PII），例如电子邮件地址、电话号码和信用卡号。然后，评估引擎根据 7 个质量维度中的 36 项内置指标对轨迹进行评分。当你持久化一次运行时，UAEF 会将其作为实验记录在 Amazon DynamoDB 和 Amazon S3 中：Amazon DynamoDB 保存用于列出和比较的每次实验元数据，Amazon S3 保存完整结果。运行记录存储后，团队可以将智能体版本与基线进行比较，以检测回归，并生成解释变化内容及原因的报告和洞察。这些报告形成闭环：团队评估智能体，了解哪些方面出现回归或改进，更改提示词、模型或工具，然后再次评估。
图 1：UAEF 闭环评估数据流
本节其余部分按顺序遵循该流程：使 UAEF 与框架无关的适配器、评估引擎及其指标、PII 检测、实验存储与比较，以及形成闭环的报告。
规范轨迹与适配器
适配器是使 UAEF 与框架无关的关键。适配器读取智能体运行的记录，包括其消息、工具调用以及智能体之间的交接。它将该记录转换为一种称为 AgentTrace 的规范表示，这是 UAEF 其余部分唯一评分的内容。由于这种转换，UAEF 可以与智能体配合工作，无论它是用哪个 SDK 构建的（例如 LangGraph、LangChain 或 Strands Agents）。它可以在本地运行、在 HTTP 端点之后运行，或在 Amazon Bedrock AgentCore 等托管运行时上运行，无论轨迹是否在 Langfuse 中或根本没有被捕获。UAEF 为每种情况都提供了适配器，它们产生相同的 AgentTrace，因此指标、分数和比较在所有这些情况下保持一致。
轨迹通过两种方式到达 UAEF。如果轨迹已经存在，来自过去的运行、日志或可观测性存储，则将其交给 UAEF，由匹配的适配器进行规范化。如果不存在，UAEF 会为你调用智能体：给定运行时 Amazon Resource Name（ARN）或 HTTP 端点，它会在每个数据集输入上调用智能体，收集响应，并一步完成适配。无论哪种方式，输出都是相同的 AgentTrace。
由于每个指标、模式和报告都基于 AgentTrace 而非框架原生格式运行，因此无论轨迹来自何处，后续评分都完全相同。这种分离——先规范化、后评分——正是让团队能够在单一尺度上比较基于一个框架构建的智能体与基于另一个框架构建的智能体的原因。
评估引擎
评估引擎在 7 个质量维度上对规范轨迹进行评分，每个维度捕捉智能体行为的一个不同方面，而单一的准确率数字会掩盖这些方面。工具调用衡量智能体是否选择了正确的工具、是否以合理的顺序调用它们，以及是否传递了有效的参数。响应质量衡量最终答案是否相关、完整、准确，并且基于提供的上下文而非幻觉。
负责任 AI 衡量安全性、偏见、毒性和对提示注入的抵抗能力。性能衡量延迟、token 使用量和吞吐量方面的运营成本。多轮衡量智能体维持对话的能力，包括上下文保留、连贯性和跨轮次的目标完成情况。多智能体衡量协作智能体系统中的协调能力，例如任务委派和分工。推理衡量智能体思维链的内部逻辑，包括一致性和无谬误性。
每个维度由一个或多个内置指标计算得出，共 36 个内置指标，每个指标返回 [0, 1] 区间内的归一化分数，其中 1 为最佳，因此各维度和总体结果共享同一尺度。指标分为两类。确定性指标直接从轨迹和真实标注计算分数，并在重复运行时精确复现。大语言模型（LLM）作为评判者的指标通过在 Amazon Bedrock 上提示评判模型，对难以用闭式定义描述的品质（如响应相关性或安全性）进行评分。你还可以添加自定义指标，或使用 RAGAS 和 DeepEval 集成。
由于评判指标会将智能体自身的输出反馈到提示中，该内容被视为不可信输入：能够影响其评判者的智能体也能影响自己的分数。评分标准与内容分开发送，内容经过转义，因此无法突破其分隔符而被当作指令读取。每个评判响应都会被严格解析，并且必须引用其所评分内容中的逐字片段。证据未找到的分数会被拒绝，而不是被记录。评判分数是评估信号，不是安全决策，不应作为安全控制的依据。若要对智能体本身实施运行时强制，请在其自身的调用路径中应用 Amazon Bedrock Guardrails。完整模型见 SECURITY.md。
实验管理与比较
UAEF 将每次评估记录为一个实验，以便日后比较不同智能体版本的结果。使用 persist=True 调用 evaluate() 或 batch_evaluate() 会创建一个新实验，由可选名称和目标标识，并写入两个角色互补的存储。Amazon DynamoDB 为每个实验保存一行，包含用于列出和比较的元数据：评估次数、每个指标的平均分数以及总体平均值。Amazon S3 保存一个 JSON 文件，包含完整评估结果，包括各指标分数和评判者的推理过程。处理敏感数据的团队可以为存储副本开启 PII 脱敏。
该 Python 库还对更细粒度的结构进行建模。一个实验包含多次运行，每次运行记录被测的智能体设计：框架、模型、工具、系统提示和参数。一次运行还可以记录配置快照和 Git 提交。你可以将一次运行标记为其所在实验的基线。这将每个分数与产生它的变更（无论是新提示、不同模型还是新增工具）关联起来。
比较基于已存储的各指标平均值进行。对于两次运行共有的每个指标，比较引擎会计算绝对变化和百分比变化，然后使用可配置的阈值（默认 5%）将该指标归类为回归、改进或未变化。一次调用中可以将多次运行与单个基线进行比较。回归检测器还会为每个回归分配严重程度：轻微（5–10%）、中等（10–20%）或严重（超过 20%）。它按维度对回归进行分组，例如可以显示提示词变更是否影响了工具调用但未影响响应质量。
在 Web UI 中，Compare 标签页会列出已存储的实验，并可按框架或数据集进行筛选。您选择两个或更多实验，第一个用作基线，UI 会显示各指标得分，并高亮显示回归和改进。UI 调用的是同一个库比较引擎，因此结果与 Python API 返回的结果一致。
报告与洞察生成
评估存储后，UAEF 会从三个层面进行报告，每个层面回答不同的问题：本次运行表现如何？为什么得到这样的分数？与早期版本相比如何？
结果视图。评估完成后，Web UI 会显示实验摘要：总体得分、已评估的测试用例数量、框架以及运行失败的查询。各指标平均值会与维度雷达图和指标柱状图一同显示。表格列出每个测试用例及其查询、智能体的响应、预期答案和得分。展开某一行会显示完整响应及其维度和指标得分。对于多轮对话，它会显示每一轮及其各自的得分和智能体调用的工具。
详细报告。从结果视图或实验列表中，您可以按需生成统计报告。UAEF 从 Amazon S3 加载已存储的结果，并在新的浏览器标签页中打开报告。报告按维度和指标细分结果，显示每个指标的置信区间和离群值、得分分布、指标之间的相关性、负责任 AI 摘要以及报告失败的测试用例。报告最后给出建议，指出得分最低的维度和在测试用例间变化最大的指标。报告仅根据得分计算，不使用 LLM，因此相同结果会生成相同报告。
LLM 生成的洞察。在 Python 库中，您可以将报告传递给 Amazon Bedrock 上的模型进行分析。对于单次运行，分析涵盖优势、关键弱点、关于根本原因的假设以及按优先级排序的建议。对于多次运行的比较，分析涵盖总体趋势、回归和改进的可能原因、每个回归带来的风险以及后续步骤。这些洞察会提示在下次评估前应在提示词、模型或工具中更改什么。
两种使用方式
你可以在同一引擎上以两种方式运行 UAEF。使用 Python 库，你可以在 notebook、脚本以及持续集成与持续交付（CI/CD）流水线中以代码方式评估 agent。你可以使用可部署的 AWS 服务，通过低代码 Web 界面评估 agent。你上传数据集、选择框架和指标、运行评估并查看评分。两条路径运行相同的评估引擎并写入相同的存储，因此结果不取决于由哪条路径产生。你可以从界面开始，然后转向代码，而无需改变结果的评分或比较方式。
使用 UAEF 评估 agent：一份操作手册
了解 UAEF 能测量什么，与了解你应该测量什么，是两回事。旅行预订 agent 和政策问答 agent 的失败方式不同，对两者在所有维度上评分既浪费时间，又浪费 Amazon Bedrock 调用。使用本操作手册选择与你的 agent 匹配的指标，然后随着新问题的出现再添加更多指标。
入门
UAEF 在 awslabs/uaef GitHub 仓库中以 Apache 2.0 许可证开源。它包括 Python 库、框架适配器、内置指标、用于可部署服务的 AWS Cloud Development Kit（AWS CDK）基础设施、Web 界面，以及针对每个受支持框架的可运行 notebook。安装指南涵盖要求、从构建好的包安装以及开发环境设置。
服务部署指南涵盖将 UAEF 作为带 Web 界面的服务进行部署、配置参考以及拆除。
实际演示
在 UAEF Web 界面中完成一次完整评估，从上传标准答案到各维度评分。
选择指标
从你的场景出发，而不是从指标列表出发。找到与你的 agent 匹配的列，从该列中勾选的指标开始。需要标准答案列显示哪些指标会与参考答案或预期工具调用进行比较。
| 维度 | 指标 | 需要标准答案 | 场景 | |||||||
| RAG / 知识问答 | 通用问答 | 工具使用 agent | 多轮对话 | 推理 | 安全与合规 | 多 agent | 生产监控 | |||
| 响应质量 | answer_relevance | ✓ | ✓ | ✓ | ||||||
| accuracy | ✓ | ✓ | ✓ | |||||||
| completeness | ✓ | ✓ | ✓ | |||||||
| hallucination_score | ✓ | |||||||||
| ragas_faithfulness | ✓ | |||||||||
| ragas_context_precision | ✓ | ✓ | ||||||||
| ragas_context_recall | ✓ | ✓ | ||||||||
| 工具调用 | tool_selection_accuracy | ✓ | ✓ | ✓ | ||||||
| tool_sequence_correctness | ✓ | ✓ | ✓ | |||||||
| parameter_quality | ✓ | ✓ | ||||||||
| mcp_compliance | ✓ | |||||||||
| 多轮 | context_retention | ✓ | ||||||||
| coherence | ✓ | ✓ | ||||||||
| conversation_completeness | ✓ | ✓ | ||||||||
| user_satisfaction | ✓ | |||||||||
| turn_efficiency | ✓ | |||||||||
| 推理 | chain_of_thought_coherence | ✓ | ||||||||
| logical_consistency | ✓ | |||||||||
| reasoning_step_correctness | ✓ | |||||||||
| fallacy_detection | ✓ | |||||||||
| 负责任 AI | safety_score | ✓ | ✓ | ✓ | ||||||
| toxicity_score | ✓ | |||||||||
| bias_score | ✓ | |||||||||
| prompt_injection_detection | ✓ | |||||||||
| 多 agent | workflow_completion | ✓ | ✓ | |||||||
| delegation_quality | ✓ | |||||||||
| agent_utilization | ✓ | |||||||||
| coordination_efficiency | ✓ | |||||||||
| 性能 | latency_score | ✓ | ||||||||
| token_efficiency | ✓ | |||||||||
| cost_efficiency | ✓ | |||||||||
| throughput | ✓ | |||||||||
该表显示了每个场景推荐的起始指标。有关受支持指标的完整列表，请参阅指标目录。
将你选定的指标作为 metrics 参数传给 evaluate() 或 batch_evaluate()。完整示例请参阅随后的“示例 notebook”部分。确定性指标（例如工具调用和性能）直接从 trace 计算，而其他指标则调用 LLM 评判器。当没有标准答案时，UAEF 会自动跳过需要参考答案的指标，因此部分标注的数据集和未标注的生产流量仍然值得评估。
选择流水线
指标决定你测量什么。六个独立的选择决定评估如何运行。用每一行中的问题来确定它。
| 选择 | 问自己 | 然后使用 | 在代码中 |
| 被动或主动 | 我已经有 trace 了，还是需要在受控条件下生成它们？ | 被动：评估已有的 trace。主动：调用 invoke_* 辅助函数，让 UAEF 运行 agent。 | evaluate(trace=recorded, adapter=“langgraph”) 或 raw = invoke_http_agent_for_framework( ENDPOINT, query, “strands”) |
| 单条 trace 或数据集 | 我是在调试一个案例，还是在衡量一个发布版本？ | 对单条 trace 或对话使用 evaluate()。对数据集使用 batch_evaluate()。 | evaluate(trace=trace) 或 batch_evaluate(traces=traces, max_workers=4) |
| 单轮或多轮a | 是否有任何测试用例依赖于更早的轮次？ | 多轮：向数据集添加 session_id 和 turn_id，并将每一轮都传给 adapter，由它组装每个对话。 | sessions = adapter.transform_to_canonical( turn_payloads) batch_evaluate(traces=sessions) |
| 单 agent 或多 agent | 是否有多个 agent 处理同一个请求？ | 无需配置。adapter 返回 AgentTrace 或 MultiAgentTrace，UAEF 会选择匹配的评估器。 | adapter = get_adapter(FRAMEWORK) trace = adapter.transform_to_canonical(raw) |
| 离线或在线 | 我是在发布前测试，还是在监控生产环境？ | 离线：在开发和 CI 中使用准备好的数据集。在线：实时对话，逐轮评分。 | batch_evaluate(…) 或 OnlineEvaluator().evaluate_response( trace=trace) |
| 临时或持久化b | 我会将本次运行与之后的运行进行比较吗？ | 持久化：设置 persist=True 并指定实验名称。否则，使用返回的结果。 | batch_evaluate(traces=traces, persist=True, experiment_name=“Support agent v2”) |
a 多轮 – 详情请参阅多轮评估工作流指南。
b 只有持久化的运行才能进行比较。
准备数据集
在 CSV 或 XLSX 文件中为每个测试用例提供一行。只有 Question 是必需的。
| 列 | 必需 | 用途 |
Question |
是 | 发送给 agent 的输入 |
Answer |
否 | 预期响应 |
context |
否 | 用于检索式评估的参考文档 |
expected_tool_calls |
否 | 预期工具调用，以 JSON 数组表示 |
session_id |
仅多轮 | 将行分组为一个对话 |
turn_id |
仅多轮 | 对对话内的轮次排序，从 1 开始 |
Question 和 Answer 匹配时不区分大小写，并接受常见别名，例如 Query 和 Expected_Output，因此现有测试文件通常无需重命名即可使用。
多轮数据集。共享同一个 session_id 的行会按顺序发送到同一个 agent 会话，因此后续轮次可以依赖之前的轮次。你的 agent 端点必须维护自己的对话状态，因为 UAEF 在发送每一轮时只附带其会话 ID，而不会重放历史记录。请使用小写的 session_id 和 turn_id。否则，该文件将按单轮进行评估。
保护敏感数据。在共享或持久化来自真实流量的数据集之前，请使用 uaef.security.PIIDetector 检测并脱敏个人身份信息，例如电子邮件地址、电话号码和信用卡号。
示例 notebook
如果你想查看更多示例，请查看我们的 notebooks/ 文件夹。这些 notebook 涵盖批量评估、多轮对话、多 agent 以及跨框架的实验管理等场景，涉及的框架包括 LangGraph、Strands Agents 和 Amazon Bedrock AgentCore。
| Notebook | 涵盖内容 |
00_langgraph.ipynb |
LangGraph：单轮、批量、多轮和多 agent 评估 |
02_langchain.ipynb |
LangChain agents |
04_json.ipynb |
通过通用 JSON 适配器支持的自定义框架 |
05_strands.ipynb |
Strands Agents，包括多 agent |
06_agentcore.ipynb |
Amazon Bedrock AgentCore，包括多 agent |
07_langfuse.ipynb |
已在 Langfuse 中收集的 trace |
01_langgraph_ragas_deepeval.ipynb |
RAGAS 和 DeepEval 集成 |
08_experiment_management.ipynb |
实验、基线和回归检测 |
10_reporting_pipeline.ipynb |
基于已存储结果的报告和仪表板 |
11_pii_detection.ipynb |
trace 中的 PII 检测与脱敏 |
清理
运行该库本身不会创建任何内容，但持久化一次运行会将实验元数据写入 Amazon DynamoDB，并将完整结果写入 Amazon S3。当你不再需要保存的实验时，请删除这两者。默认名称是 uaef-experiments 和 uaef-results，可通过 UAEF_DYNAMODB_TABLE 和 UAEF_S3_BUCKET 环境变量覆盖。存储桶必须先清空才能删除。
如果你部署了该服务，服务部署指南 中提供了两种部署模式的拆除步骤。在假定拆除已完成之前，请阅读其中关于保留资源的说明：DynamoDB 表、S3 存储桶和 Amazon Cognito 用户池在创建时带有保留策略，因此删除堆栈后它们及其内容仍会保留。这是有意为之，这样拆除操作不会销毁已保存的实验，但这也意味着在你自行移除它们之前，存储会持续产生费用。
结论
UAEF 将 agent 评估与生成该 agent 的框架分离。适配器将来自 LangGraph、LangChain、Strands Agents、Amazon Bedrock AgentCore 和 Langfuse 的 trace 转换为通用格式，通用 JSON 适配器则可处理其他框架。随后，无论团队如何构建 agent，都同样适用 7 个维度上的 36 项内置指标。UAEF 可以评估单条 trace，也可以对历史 trace 运行批量评估，然后按实验将结果存储在 Amazon DynamoDB 和 Amazon S3 中。团队随后可以跨 agent 版本比较运行结果、检测回归，并利用生成的报告和洞察来决定下一轮迭代中要更改什么。Web UI 和 Python 库共享同一评估引擎，因此团队可以从低代码起步，再转向代码，而无需改变评分或存储的工作方式。
要开始使用，请参阅 开源仓库。
关于作者
Samaneh Aminikhanghahi
Samaneh 是 AWS Forward Deployed Engineer (FDE) 团队的应用科学家，她与不同垂直领域的客户合作，加速他们对生成式 AI 的采用。她专注于智能体 AI 框架、构建稳健的评估系统，以及实施负责任 AI 实践，以推动可持续的业务成果。
Yuxuan Zhou
Yuxuan 是 AWS Forward Deployed Engineer (FDE) 团队的数据科学家，她帮助企业客户构建和扩展生成式 AI 解决方案。她为 AWS 客户交付了金融服务、保险、制造、医疗健康以及媒体和娱乐领域的项目。她专注于智能体检索增强生成 (RAG)、面向长上下文推理的上下文工程，以及 AI 智能体的评估框架。她的研究还涵盖 LLM 校准和多模态视觉语言模型。
Tristan Sylvain
Tristan 是 AWS Forward Deployed Engineer (FDE) 团队的应用科学家，他与客户合作设计和部署生成式 AI 解决方案。他交付了金融服务、物流和工业领域的项目。他的研究专长涵盖 LLM 应用、表征学习、计算机视觉和医疗数据中的泛化，以及时间序列预测。
Amulya Cherian
Amulya 是 AWS Professional Services 的副交付顾问，专注于 AI/ML。她为 AWS 客户交付了多个行业的生成式 AI 项目，包括金融、媒体和娱乐以及医疗健康。
Elaine Wu
Elaine 是 AWS Forward Deployed Engineer (FDE) 团队的深度学习架构师，专注于为大型企业构建稳健的 RAG 和智能体 AI 解决方案。她为 AWS 客户解决了制造、能源、医疗健康、零售、企业软件和金融服务等行业的现实业务挑战。加入 AWS 之前，Elaine 在伊利诺伊大学厄巴纳-香槟分校获得信息科学硕士学位。
Vidya Sagar Ravipati
Vidya 是 AWS Forward Deployed Engineer (FDE) 团队的应用科学经理，他利用在大规模分布式系统方面的丰富经验以及对机器学习的热忱，帮助不同行业垂直领域的 AWS 客户加速其 AI 和云采用。
Meghana Ashok
Meghana 是 AWS Forward Deployed Engineer (FDE) 团队的高级机器学习工程师，她在工程、研究和 GenAI 解决方案的交汇处工作。她专注于设计和构建可扩展的 AI 架构，弥合前沿生成式 AI 研究与生产就绪系统之间的差距。Meghana 热衷于将复杂的 GenAI 概念转化为稳健、可部署的解决方案，通过将深厚的技术工程专业知识与对 AI 驱动的自动化和智能系统的前瞻性方法相结合来推动创新。
来源：AWS Machine Learning Blog · aws.amazon.com