如何自动评估AI Agent质量？Bedrock AgentCore Evaluation SDK完整指南（Span采集+批量评估+第三方评估器）

如何自动评估AI Agent质量Bedrock AgentCore Evaluation SDK完整指南Span采集批量评估第三方评估器【免费下载链接】bedrock-agentcore-sdk-pythonPython SDK for transforming any AI agent into a production-ready application. Framework-agnostic primitives for runtime, memory, authentication, and tools with AWS-managed infrastructure.项目地址: https://gitcode.com/gh_mirrors/be/bedrock-agentcore-sdk-pythonbedrock-agentcore-sdk-python是 AWS Bedrock AgentCore 的官方 Python SDK帮你把任意 AI Agent 变成生产级应用。它内置的Evaluation评估模块是自动评估 AI Agent 质量的核心工具从 CloudWatch 自动采集 Agent 运行 Span一键触发按需评估或批量评估还能接入 autoevals、deepeval 等第三方评估器让 Agent 的准确性、有用性、安全性变得可量化、可回归。 为什么 AI Agent 需要自动化评估大模型驱动的智能体AI Agent行为具有不确定性同一个问题今天答对明天可能答错。手动人工测试无法覆盖所有场景更别提版本迭代后的回归验证。Bedrock AgentCore Evaluation SDK 解决的正是这个问题它的核心思路是全链路记录Agent 每次运行都会产生 Span链路追踪数据记录完整的工具调用轨迹数据集驱动定义评估场景问题 预期行为批量回放多维度打分用内置或第三方评估器自动给出分数与解释️ 一图看懂 AgentCore 的运行与评估链路Agent 部署在 AWS 云端后每次用户请求都会经过 Runtime → Agent 框架 → 工具网关的完整链路这条链路上的每一步都会被记录为 Span成为评估的原材料 Evaluation SDK 核心组件速览整个评估体系位于src/bedrock_agentcore/evaluation/目录关键组件如下组件模块路径作用EvaluationClientsrc/bedrock_agentcore/evaluation/client.py采集 Span 并发起评估请求Span 采集器src/bedrock_agentcore/evaluation/agent_span_collector/agent_span_collector.py从 CloudWatch 拉取并轮询等待 Span按需评估运行器src/bedrock_agentcore/evaluation/runner/on_demand/on_demand_runner.py端到端执行评估数据集批量评估运行器src/bedrock_agentcore/evaluation/runner/batch/batch_evaluation_runner.py调用 Batch Evaluation API 异步跑批数据集模型src/bedrock_agentcore/evaluation/runner/dataset_types.py定义场景、对话轮次、仿真角色数据集管理src/bedrock_agentcore/evaluation/dataset_client.py在云端创建/管理评估数据集第三方评估器src/bedrock_agentcore/evaluation/custom_code_based_evaluators/third_party/autoevals、deepeval 适配器Strands 集成src/bedrock_agentcore/evaluation/integrations/strands_agents_evals/对接 Strands Evals 框架 Span 采集把 Agent 运行轨迹变成评估数据Span是 OpenTelemetry 的链路追踪单元Agent 每调用一次模型、执行一次工具都会留下带时间戳的 Span。CloudWatchAgentSpanCollector是采集的核心它用 CloudWatch Logs Insights 按attributes.session.id精确过滤出指定会话的 Span同时查询aws/spans和自定义日志组两个来源。两个贴心的工程细节值得了解轮询等待Span 写入 CloudWatch 有延迟采集器会每 30 秒轮询一次最长等待 300 秒避免查了个空时间窗口缓冲查询结束时间自动放宽 60 秒防止刚写入的 Span 被漏掉相关查询逻辑在src/bedrock_agentcore/evaluation/utils/cloudwatch_span_helper.py如果你只想要原始 Span 数据也可以直接调用fetch_spans_from_cloudwatch函数。⚡ 按需评估On-Demand三步跑完一个评估数据集OnDemandEvaluationDatasetRunner是本地/CI 环境跑评估的主力执行过程分三个阶段Phase 1 并发调用 Agent数据集中的每个场景Scenario并发执行Phase 2 等待 Span 入库按配置延迟等待 CloudWatch 完成数据摄入Phase 3 采集 评估并发拉取 Span 并调用评估 API返回每个场景、每个评估器的分数它支持两种场景类型定义在src/bedrock_agentcore/evaluation/runner/dataset_types.pyPredefinedScenario预定义场景固定的多轮对话可附带expected_trajectory预期工具调用序列和每轮的expected_responseSimulatedScenario仿真场景预览版由一个带角色画像ActorProfile性格、背景、目标的模拟用户与 Agent 多轮博弈更接近真实用户行为评估还可以提供参考答案ReferenceInputs自然语言断言、预期轨迹、预期回复让 LLM 评估器判断 Agent 是否达标。 批量评估Batch大规模回归测试的正确姿势按需评估适合开发迭代批量评估则面向大规模回归。BatchEvaluationRunner预览版基于 AgentCore 的 Batch Evaluation API 工作调用StartBatchEvaluation异步启动任务随后轮询GetBatchEvaluation获取进度自动把场景中的断言、预期轨迹转换为云端 Ground Truth 格式支持从 CloudWatch 读取历史线上会话数据CloudWatchDataSourceConfig做在线评估结果汇总为BatchEvaluationSummary每个评估器的统计值EvaluatorStatistics和失败场景清单FailedScenario方便直接生成回归报告简单说小批量调试用 On-Demand全量回归用 Batch。 第三方评估器接入 autoevals 与 deepeval不用自己从零写评估逻辑。src/bedrock_agentcore/evaluation/custom_code_based_evaluators/third_party/目录内置了两大主流评估框架的官方适配器autoevalsautoevals/adapter.py提供忠实度、相关性等经典 LLM 评估指标deepevaldeepeval/adapter.py可直接用其 G-Eval、答案相关性等指标适配器层有一个巧妙设计——Span 映射器span_mappers/它把 AgentCore 的 ADOT Span 自动翻译成第三方框架期望的输入字段你无需手写任何格式转换代码。而且适配器保证永不抛异常字段提取失败或指标计算失败都会以规范的错误码FIELD_EXTRACTION_ERROR/METRIC_ERROR返回批量跑几百个场景也不会中断。✍️ 自定义评估器一行装饰器写出专属指标想评估回复必须包含免责声明这类业务专属规则用custom_code_based_evaluator()装饰器即可custom_code_based_evaluator() def handler(input: EvaluatorInput, context) - EvaluatorOutput: return EvaluatorOutput(value1.0, labelPass)装饰器会自动完成 Lambda 事件解析会话 Span、目标 Trace ID、参考答案等和结果序列化部署为 Lambda 函数后就能作为评估器被评估服务调用。实现细节见src/bedrock_agentcore/evaluation/custom_code_based_evaluators/decorator.py。 Strands 框架集成本地开发到生产无缝衔接如果你的 Agent 基于Strands Agents框架集成体验最丝滑pip install bedrock-agentcore[strands-agents-evals]evaluator create_strands_evaluator(Builtin.Helpfulness)它提供两种模式本地模式用内存遥测捕获 Strands 的 OpenTelemetry Span经convert_strands_to_adotsrc/bedrock_agentcore/evaluation/span_to_adot_serializer/转换为 ADOT 格式开发阶段就能评估无需部署生产模式直接用部署在 AgentCore Runtime 上的 Agent 的 CloudWatch Span 评估评估工作流沿用 Strands Evals 的Experiment/Case写法迁移成本几乎为零。 快速上手5 分钟跑通第一次 AI Agent 评估第 1 步安装 SDKpip install bedrock-agentcore第 2 步对已有会话发起评估from bedrock_agentcore.evaluation import EvaluationClient client EvaluationClient(region_nameus-west-2) results client.run( evaluator_ids[accuracy, toxicity], session_idsess-123, agent_idmy-agent, ) for r in results: print(f{r[evaluatorId]}: {r.get(value)} - {r.get(explanation)})run()会自动从 CloudWatch 定位该会话的 Span默认回看 7 天完成采集与评估返回每个评估器的分数和文字解释。第 3 步可选管理评估器EvaluationClient还支持透传控制面 APIcreate_evaluator、list_evaluators、update_evaluator等以及在线评估配置的增删改查无需再手动写 boto3 代码。❓ 常见问题与最佳实践QSpan 查询不到怎么办确认 Agent 已开启 ADOT 链路追踪并等待 CloudWatch 摄入延迟分钟级。采集器的 300 秒轮询窗口可以覆盖大部分场景。Q评估数据集从哪里来可以用FileDatasetProvider从本地文件加载也可用DatasetManagementServiceProvider对接云端数据集服务src/bedrock_agentcore/evaluation/dataset_client.py。Q如何回归对比版本好坏推荐组合拳开发期用 On-Demand 小数据集快速迭代 → 上线前用 Batch 全量回归 → 用EvaluatorStatistics对比两个版本的关键指标均值。Q预览功能要注意什么BatchEvaluationRunner和SimulatedScenario目前为预览状态预览接口未来可能变化生产环境请留意版本更新。 小结Bedrock AgentCore Evaluation SDK 让 AI Agent 质量评估形成了完整闭环Span 自动采集 → 数据集场景回放 → 内置/第三方评估器打分 → 批量回归报告。无论你是想快速验证一个新 Prompt 的效果还是为生产 Agent 建立持续评估体系这套框架都能让你少写样板代码、多关注 Agent 本身的行为质量。【免费下载链接】bedrock-agentcore-sdk-pythonPython SDK for transforming any AI agent into a production-ready application. Framework-agnostic primitives for runtime, memory, authentication, and tools with AWS-managed infrastructure.项目地址: https://gitcode.com/gh_mirrors/be/bedrock-agentcore-sdk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考