AWS 开源 UAEF 实现跨框架智能体闭环评测
AWS 开源 Universal Agent Evaluation Framework(UAEF),用统一评测引擎解耦智能体框架与评测逻辑,支持 LangGraph、LangChain、Strands Agents 与 Bedrock AgentCore 等框架的追踪格式。它覆盖工具调用、响应质量、负责任 AI、性能、多轮对话、多智能体协同与推理等维度,并已在电信、医疗、金融 12 家机构落地使用。
报道正文
本文目录14 个章节
在 AWS 上构建 AI agent 的团队会使用多种框架,包括 LangGraph、LangChain、Strands Agents 和 Amazon Bedrock AgentCore。每个框架都以自己的方式记录 agent 的执行过程,因此消息、工具调用以及 agent 之间交接的结构各不相同。评估工具往往也遵循同样的边界:团队针对单一框架的 trace 格式构建指标、评分逻辑和结果存储,而当他们切换框架或在多个框架上运行 agent 时,就必须重新构建这些内容。
这种耦合使得一个基本的开发问题更难回答:对提示词、模型或工具的更改是否改进了 agent?要回答这个问题,需要跨 agent 版本的一致指标,以及可供比较的过往结果共享记录。Agent 质量还涵盖多个维度,单一的准确率分数无法捕捉:工具调用、响应质量、负责任 AI、性能、多轮对话、多 agent 协调和推理。
在这篇文章中,我们介绍通用 Agent 评估框架(Universal Agent Evaluation Framework,UAEF)。来自电信、医疗保健和金融服务行业 12 个组织的客户使用 UAEF,以一套一致的指标评估其 AI agent,并在发布前比较 agent 版本。UAEF 是一个框架无关的评估系统:它使用适配器将每个框架的 trace 转换为通用格式,然后用 7 个维度下的 36 个内置指标对这些 trace 进行评分。它将结果存储在 Amazon DynamoDB 和 Amazon Simple Storage Service(Amazon S3)中,并生成报告和洞察,为 agent 的下一次迭代提供依据。本文介绍了 UAEF 的工作原理,提供了选择指标和准备数据集的 playbook,并给出了每个受支持框架的可运行 notebook。
UAEF:面向 agent 框架的统一评估层
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 Resource Name(ARN)或 HTTP 端点,它会针对每个数据集输入调用智能体,收集响应,并在一步中完成适配。无论哪种方式,输出都是相同的 AgentTrace。
由于每个指标、模式和报告都基于 AgentTrace 而非框架原生格式运行,因此无论追踪数据来自何处,后续的评分都是完全相同的。这种分离——先规范化、后评分——正是让团队能够在同一尺度上比较基于一种框架构建的智能体与基于另一种框架构建的智能体的原因。
评估引擎
评估引擎会跨 7 个质量维度对规范追踪数据进行评分,每个维度都捕捉智能体行为的一个不同方面,而单一的准确率数字会掩盖这些方面。工具调用衡量智能体是否选择了正确的工具、是否以合理的顺序调用它们,以及是否传入了有效的参数。响应质量衡量最终答案是否相关、完整、准确,并且基于所提供的上下文而非凭空捏造。
负责任 AI 衡量安全性、偏见、毒性以及抵御提示注入的能力。性能衡量延迟、token 使用量和吞吐量方面的运营成本。多轮衡量智能体维持对话的能力,包括上下文保持、连贯性以及跨轮次的目标完成情况。多智能体衡量协作智能体系统中的协调能力,例如任务委派和分工。推理衡量智能体思维链的内部逻辑,包括一致性和无谬误性。
每个维度由一个或多个内置指标计算得出,共 36 个内置指标,每个指标返回 [0, 1] 区间内的归一化分数,其中 1 为最佳,因此各维度和总体结果共享同一量纲。指标分为两类。确定性指标直接从轨迹和基准真值计算分数,并在重复运行时精确复现。大语言模型(LLM)作为评判者的指标通过在 Amazon Bedrock 上提示评判模型,对难以用闭式定义描述的品质(如响应相关性或安全性)进行评分。你还可以添加自定义指标,或借助 RAGAS 和 DeepEval 集成。
由于评判指标会将智能体自身的输出反馈到提示中,该内容被视为不可信输入:能够影响其评判者的智能体也能影响自己的分数。评分标准与内容分开发送,内容会被转义,使其无法突破分隔符而被当作指令读取。每个评判响应都会被严格解析,并且必须引用其所评分内容中的逐字片段。如果找不到证据,该分数会被拒绝而非记录。评判分数是评估信号,而非安全决策,不应作为安全控制的关卡。若要在智能体本身上实施运行时强制执行,请在其自身的调用路径中应用 Amazon Bedrock Guardrails。完整模型见 SECURITY.md。
实验管理与比较
UAEF 将每次评估记录为一个实验,以便日后比较不同 agent 版本的结果。调用 evaluate() 或 batch_evaluate() 时传入 persist=True,就会创建一个新实验,通过可选名称和目标来标识,并将其写入两个角色互补的存储。Amazon DynamoDB 为每个实验保存一行记录,其中包含用于列出和比较的元数据:评估次数、各指标的平均分以及总体平均分。Amazon S3 保存一个 JSON 文件,内含完整的评估结果,包括各指标得分和评判者的推理过程。处理敏感数据的团队可以为存储副本开启 PII 脱敏。
该 Python 库还建模了更细粒度的结构。一个实验包含多次运行,每次运行记录被测的 agent 设计:框架、模型、工具、系统提示词和参数。一次运行还可以记录配置快照和 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)流水线中以代码方式评估智能体。你可以使用可部署的 AWS 服务,通过低代码 Web 界面评估智能体。你上传数据集、选择框架和指标、运行评估并查看得分。两种路径运行相同的评估引擎并写入相同的存储,因此结果不取决于由哪条路径产生。你可以从界面开始,然后转向代码,而无需改变结果的评分或比较方式。
使用 UAEF 评估智能体:实战指南
了解 UAEF 能衡量什么,与了解你应该衡量什么,是两回事。旅行预订智能体和策略问答智能体的失败方式各不相同,对两者都按每个维度打分既浪费时间,也浪费 Amazon Bedrock 调用次数。使用本指南来选择与你的智能体相匹配的指标,然后随着新问题的出现再逐步增加。
快速上手
UAEF 是开源的,采用 Apache 2.0 许可证,托管在 awslabs/uaef GitHub 仓库中。它包含 Python 库、框架适配器、内置指标、用于可部署服务的 AWS Cloud Development Kit(AWS CDK)基础设施、Web 界面,以及针对每个受支持框架的可运行 notebook。安装指南涵盖了环境要求、从构建好的包安装以及开发环境搭建。
服务部署指南涵盖了如何将 UAEF 作为带 Web 界面的服务进行部署、配置参考以及拆除。
实际效果
在 UAEF Web 界面中完成的一次完整评估,从上传标准答案到各维度得分。
选择指标
从你的场景出发,而不是从指标列表出发。找到与你的智能体相匹配的那一列,从该列中已勾选的指标开始。需要标准答案一列显示了哪些指标需要与参考答案或预期工具调用进行对比。
| 维度 | 指标 | 需要真实标注 | 场景 |
|---|---|---|---|
| RAG / 知识问答 | 通用问答 | 工具调用智能体 | 多轮对话 |
| 响应质量 | 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()。如需查看完整示例,请参阅随后的“示例笔记本”部分。确定性指标(例如工具调用和性能)直接根据 trace 计算得出,而其他指标则会调用 LLM 评判器。当不存在标准答案时,UAEF 会自动跳过需要参考答案的指标,因此部分标注的数据集和未标注的生产流量仍然值得评估。
选择流水线
指标决定你要衡量什么。六个相互独立的选择决定评估如何运行。用每一行中的问题来确定这些选择。
| 选择 | 问自己 | 然后使用 | 在代码中 |
|---|---|---|---|
| 被动或主动 | 我已经有 trace 了,还是需要在受控条件下生成 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:单次、批量、多轮以及多智能体评估 |
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 库共享同一评估引擎,因此团队可以从低代码起步,再转向代码,而无需改变评分或存储的工作方式。
要开始使用,请参阅开源仓库。
