AgentEvals（agentevals-cli）Agent评测方法与步骤

AgentEvalsagentevals-cliAgent评测方法与步骤框架定位与核心原理业内常说的AgentEvals官方全称为agentevals-cli是 Strands Labs 开源的框架无关、OpenTelemetry(OTel) Trace 驱动的Agent评测工具核心设计理念是「一次采集Agent执行链路多次离线评测打分」——无需重复调用大模型、无需重新运行Agent直接基于已有的全链路Trace数据完成过程级判分大幅降低评测成本是工具型Agent过程行为校验、版本回归、CI/CD质量门禁的典型落地方案。核心特性兼容所有接入OTel埋点的Agent框架LangChain、OpenAI Agents SDK、Google ADK等支持Jaeger JSON、原生OTLP Trace格式内置工具轨迹、参数校验、输出合规等评估器支持自定义判分逻辑与LLM-as-Judge原生提供CLI、Web UI、MCP服务、K8s部署多种形态。权威来源PyPI官方包说明完整落地执行步骤共7步步骤1环境安装与前置依赖校验1. 框架安装# 安装官方CLI完整版pipinstallagentevals-cli# 验证安装成功agentevals--version2. 前置条件确认被测Agent已完成OpenTelemetry埋点可输出标准OTel链路数据自研Agent可通过OTel SDK手动上报执行节点。若使用LLM裁判评估器提前配置对应大模型的API密钥。离线回归场景提前导出Agent执行的Trace文件支持Jaeger JSON、原生OTLP两种格式。步骤2采集Agent全链路Trace数据AgentEvals的评测输入是Agent完整执行链路的结构化Trace包含每一步的规划、工具调用、输入输出、耗时、状态有两种采集模式模式A实时采集适配新任务评测启动AgentEvals内置接收器运行Agent时自动同步链路数据启动OTel接收服务agentevals receiver--port4317将Agent的OTel OTLP导出端点配置为[http://127.0.0.1:4317](http://127.0.0.1:4317)运行Agent执行测试任务全链路数据会自动同步到AgentEvals。模式B离线导入适配历史回归、多规则评测直接导入已导出的Trace文件无需重新运行Agent这是AgentEvals的核心优势适用场景同一份Trace反复评测不同规则、多版本评测集对比、历史BadCase回归验证成本收益一次Agent执行的Trace可无限次用于评测零额外Token消耗步骤3定义黄金评测集Eval Set评测集是「预期Agent行为」的结构化基准是判分的唯一依据对应每条测试用例的成功标准以JSON格式编写。标准评测集字段规范{eval_set_id:tool_call_baseline_v1.0,description:P0场景工具调用基线评测集,cases:[{case_id:helm_list_001,query:列出default命名空间下所有Helm发布版本,expected_behavior:{required_tools:[helm_list_releases],tool_order:strict,tool_params_rules:{helm_list_releases:{namespace:default}},output_rules:{must_contain:[发布名称,版本号,运行状态],format:markdown表格}}}]}设计原则每条用例对应明确、可校验的行为预期禁止“效果合理即可”这类模糊描述区分强制校验项工具选择、核心参数与弹性校验项输出格式、表述方式按业务优先级分级管理P0场景用于发布门禁P1/P2用于常规回归。步骤4选择评估器与评测指标AgentEvals内置多类规则化评估器可按需组合使用也支持自定义扩展与LLM裁判接入。内置核心评估器评估器名称核心能力适用场景tool_trajectory_avg_score校验工具调用的名称、数量、顺序与预期的匹配度输出0-1分工具型Agent过程行为基线校验tool_param_match_score校验工具入参的字段完整性、取值合规性参数填充准确性专项评测output_compliance_score校验最终输出的内容要素、格式规范是否符合要求结果交付质量评测step_count_score校验执行步数是否在合理区间识别冗余步骤或任务遗漏任务规划合理性评测扩展评测能力自定义评估器支持Python、JavaScript编写业务专属判分逻辑对接内部业务规则LLM-as-Judge对接大模型作为裁判针对语义合理性、任务完成度等主观维度打分二值门禁判定输出Pass/Fail硬判定直接用于CI/CD发布卡点。步骤5执行离线评测通过CLI一键执行支持单条验证、批量回归、多格式输出三种模式。1. 单条Trace快速验证agentevals run ./traces/helm_trace.json\--eval-set ./eval_sets/tool_baseline.json\-mtool_trajectory_avg_score output_compliance_score执行后直接输出结构化结果Trace: 3e289017fe03ffd7c4145316d2eb3d0d Invocations: 1 Metric Score Status ------ ------------------------- ------- [PASS] tool_trajectory_avg_score 1.0 PASSED [PASS] output_compliance_score 0.85 PASSED2. 批量全量回归评测# 批量执行目录下所有Trace输出JSON格式结果用于归档agentevals run ./traces/regression_batch/\--eval-set ./eval_sets/p0_full_eval.json\--outputjson\--output-path ./results/regression_v2.1.json3. Web可视化深度分析启动Web面板可视化查看链路匹配细节、精准定位失败点agentevals web--port8080访问[http://127.0.0.1:8080](http://127.0.0.1:8080)可查看全量用例通过率、各维度得分汇总单条Trace的Span级匹配明细逐步骤标注匹配/失败原因多版本评测结果对比指标升降幅自动统计步骤6错误分桶与根因归因基于评测结果与Trace链路数据按错误发生节点自动分桶定位根因错误类型判定依据对应能力短板轨迹匹配失败工具选错、调用顺序错误、遗漏必要工具任务规划能力、工具选择能力不足参数校验失败参数字段缺失、取值格式/范围错误工具语义理解、参数填充能力不足输出合规失败结果遗漏关键信息、格式不符合要求信息整合能力、指令遵循能力不足步骤异常步数过多冗余、步数不足遗漏子任务任务拆分合理性、目标对齐能力不足步骤7CI/CD集成与持续闭环AgentEvals原生适配流水线集成作为版本发布的强制质量门禁在CI配置中加入评测执行步骤指定P0基线评测集与得分阈值设置门禁规则核心场景通过率100%、综合得分≥0.95低于阈值自动阻断发布每次版本迭代复用同一套基线Trace与评测集自动对比指标升降幅评测结果自动归档支持历史版本追溯与质量趋势分析。GitHub Actions 集成示例-name:Agent P0 Baseline Evalrun:|agentevals run ./baseline_traces/ \ --eval-set ./eval_sets/p0_baseline.json \ --threshold 0.95 \ --output json落地关键注意事项Trace完整性前置校验必须覆盖Agent全执行链路规划→工具调用→结果解析→最终输出缺失节点会导致评测失真评测前需自动校验Trace完整性。评测集版本化管理评测集随业务迭代同步更新与Agent版本一一对应避免规则与实际业务需求脱节。评估器选型原则过程类校验优先用内置规则评估器效率高、结果稳定语义类、主观维度补充LLM裁判兼顾效率与准确性。防数据泄露Trace数据包含完整执行信息需按业务数据等级做权限管控禁止敏感数据明文存储。agentevals-cli PyPI官方文档https://pypi.org/project/agentevals-cli/AgentEvals工作流与快速入门https://pypi.org/project/agentevals-cli/0.6.2/