AWS 开源 UAEF：跨框架的智能体闭环评估系统

在 AWS 上构建 AI 智能体的团队会使用多种框架，包括 LangGraph、LangChain、Strands Agents 和 Amazon Bedrock AgentCore。每个框架记录智能体执行过程的方式各不相同，因此消息、工具调用以及智能体之间交接的结构也彼此不同。评估工具往往遵循同样的边界：团队针对单一框架的轨迹格式构建指标、评分逻辑和结果存储，而在切换框架或在多个框架上运行智能体时，就必须重新构建这些内容。

这种耦合使得一个基本的开发问题变得更难回答：对提示词、模型或工具的更改是否改进了智能体？回答这个问题需要跨不同智能体版本的一致指标，以及一个可供比较的历史结果共享记录。智能体质量还涵盖单一准确率分数无法捕捉的多个维度：工具调用、响应质量、负责任的 AI、性能、多轮对话、多智能体协作以及推理。

在这篇文章中，我们介绍通用智能体评估框架（Universal Agent Evaluation Framework，UAEF）。来自电信、医疗健康和金融服务行业的 12 个组织的客户使用 UAEF，以一套一致的指标评估其 AI 智能体，并在发布前比较不同智能体版本。UAEF 是一个与框架无关的评估系统：它使用适配器将来自各框架的轨迹转换为通用格式，然后用涵盖 7 个维度的 36 个内置指标对这些轨迹进行评分。它将结果存储在 Amazon DynamoDB 和 Amazon Simple Storage Service（Amazon S3）中，并生成报告和洞察，为智能体的下一次迭代提供依据。本文介绍 UAEF 的工作原理，提供选择指标和准备数据集的操作指南，并给出每个受支持框架的可运行 notebook。

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 Resource Name (ARN) 或 HTTP 端点，它会针对每个数据集输入调用智能体，收集响应，并在一步中完成适配。无论哪种方式，输出都是相同的 AgentTrace。

由于每个指标、模式和报告都基于 AgentTrace 而非框架原生格式运行，因此后续的评分无论轨迹来自何处都是相同的。正是这种“先规范化、后评分”的分离，使团队能够在同一尺度上比较基于不同框架构建的智能体。

评估引擎

评估引擎从 7 个质量维度对规范轨迹进行评分，每个维度捕捉智能体行为的一个独特方面，这是单一准确率数字无法体现的。工具调用（Tool calling）衡量智能体是否选择了正确的工具、以合理的顺序调用它们，并传递了有效参数。响应质量（Response quality）衡量最终答案是否相关、完整、准确，并基于所提供的上下文而非凭空捏造。

负责任的 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 库还建模了更细粒度的结构。一个实验包含多个运行（run），每个运行记录被测的智能体设计：框架、模型、工具、系统提示词和参数。运行还可以记录配置快照和 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 库，您可以在笔记本、脚本和持续集成与持续交付（CI/CD）流水线中以代码方式评估智能体。您也可以使用可部署的 AWS 服务，通过低代码 Web 界面评估智能体：上传数据集、选择框架和指标、运行评估并查看得分。两种路径运行完全相同的评估引擎并写入相同的存储，因此结果不取决于由哪条路径产生。您可以从界面开始，之后转到代码，而无需改变结果的评分或比较方式。

使用 UAEF 评估智能体：实战手册

知道 UAEF 能测量什么，与知道您应该测量什么是两回事。旅行预订智能体和政策问答智能体会以不同方式出错，在每个维度上对两者都进行评分会浪费时间和 Amazon Bedrock 调用。请使用这份实战手册挑选与您的智能体相匹配的指标，然后在出现新问题时再添加更多指标。

开始使用

UAEF 在 awslabs/uaef GitHub 仓库中以 Apache 2.0 许可证开源。它包含 Python 库、框架适配器、内置指标、用于可部署服务的 AWS Cloud Development Kit (AWS CDK) 基础设施、Web 界面，以及针对每个受支持框架的可运行笔记本。安装指南涵盖系统要求、从已构建的软件包安装以及开发环境搭建。

服务部署指南涵盖通过 Web 界面将 UAEF 部署为服务、配置参考以及资源清理。

看它实际运行

在 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()。有关完整示例，请参阅后文的“示例笔记本”部分。确定性指标（如工具调用和性能）直接从追踪记录中计算得出，而其他指标则调用 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 库共享同一评估引擎，因此团队可以从低代码起步，再迁移到代码方式，而无需改变评分或存储的工作方式。

要开始使用，请查看开源代码库。