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