企业官网建设流程全解析

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

框架定位与核心原理

业内常说的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--version

2. 前置条件确认

• 被测Agent已完成OpenTelemetry埋点，可输出标准OTel链路数据；自研Agent可通过OTel SDK手动上报执行节点。
• 若使用LLM裁判评估器，提前配置对应大模型的API密钥。
• 离线回归场景：提前导出Agent执行的Trace文件（支持Jaeger JSON、原生OTLP两种格式）。

步骤2：采集Agent全链路Trace数据

AgentEvals的评测输入是Agent完整执行链路的结构化Trace（包含每一步的规划、工具调用、输入输出、耗时、状态），有两种采集模式：

模式A：实时采集（适配新任务评测）

启动AgentEvals内置接收器，运行Agent时自动同步链路数据：

1. 启动OTel接收服务

agentevals receiver--port4317

2. 将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裁判接入。

内置核心评估器

扩展评测能力

• 自定义评估器：支持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 PASSED

2. 批量全量回归评测

# 批量执行目录下所有Trace，输出JSON格式结果用于归档agentevals run ./traces/regression_batch/\--eval-set ./eval_sets/p0_full_eval.json\--outputjson\--output-path ./results/regression_v2.1.json

3. Web可视化深度分析

启动Web面板，可视化查看链路匹配细节、精准定位失败点：

agentevals web--port8080

访问[http://127.0.0.1:8080](http://127.0.0.1:8080)可查看：

• 全量用例通过率、各维度得分汇总
• 单条Trace的Span级匹配明细，逐步骤标注匹配/失败原因
• 多版本评测结果对比，指标升降幅自动统计

步骤6：错误分桶与根因归因

基于评测结果与Trace链路数据，按错误发生节点自动分桶定位根因：

步骤7：CI/CD集成与持续闭环

AgentEvals原生适配流水线集成，作为版本发布的强制质量门禁：

1. 在CI配置中加入评测执行步骤，指定P0基线评测集与得分阈值；
2. 设置门禁规则：核心场景通过率100%、综合得分≥0.95，低于阈值自动阻断发布；
3. 每次版本迭代复用同一套基线Trace与评测集，自动对比指标升降幅；
4. 评测结果自动归档，支持历史版本追溯与质量趋势分析。

GitHub Actions 集成示例

-name:Agent P0 Baseline Evalrun:|agentevals run ./baseline_traces/ \ --eval-set ./eval_sets/p0_baseline.json \ --threshold 0.95 \ --output json

落地关键注意事项

1. Trace完整性前置校验：必须覆盖Agent全执行链路（规划→工具调用→结果解析→最终输出），缺失节点会导致评测失真，评测前需自动校验Trace完整性。
2. 评测集版本化管理：评测集随业务迭代同步更新，与Agent版本一一对应，避免规则与实际业务需求脱节。
3. 评估器选型原则：过程类校验优先用内置规则评估器，效率高、结果稳定；语义类、主观维度补充LLM裁判，兼顾效率与准确性。
4. 防数据泄露：Trace数据包含完整执行信息，需按业务数据等级做权限管控，禁止敏感数据明文存储。

1. agentevals-cli PyPI官方文档：https://pypi.org/project/agentevals-cli/
2. AgentEvals工作流与快速入门：https://pypi.org/project/agentevals-cli/0.6.2/