AgentEvals 轨迹评测
从已有 OpenTelemetry 轨迹评估 AI Agent，无需重跑 Agent。
- Star 数
- ★ 166
- 最近更新
- 5 天前
- License
- Apache-2.0
- 主语言
- Python
- FA 评分
- 68/100 · 存在缺口
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code（部分支持）
- 费用
- 免费，无需付费服务
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 为使用 OpenTelemetry 的 Agent 团队在 CI 中对记录的轨迹运行确定性工具轨迹检查，并用退出码阻止不合格部署。
- 不适合
- 需要端到端评估长时间编码会话的团队
- 要求项目已稳定且避免破坏性变更的团队
- 源码审查
- 68/100 · 存在缺口
这个 Agent 能做什么，适合哪些场景？
AgentEvals 接收 Agent 已生成的 OpenTelemetry 数据，并将 GenAI span 和日志事件转换为对话轮次、工具调用、令牌与回答。它通过 CLI、Web UI、REST API、gRPC API 或 MCP 服务器运行评估，也可接收 OTLP HTTP 和 gRPC 数据。内置指标涵盖工具轨迹、回答匹配和基于 LLM 的评分，用户也能添加自定义评估器和评分规则。评估结果可作为 gen_ai.evaluation.result 日志事件导出，并关联到被评估的 span。它可本地运行、以 Docker 部署或通过 Helm 部署到 Kubernetes；运行历史可选用 Postgres 持久化。
AgentEvals 从 OTLP HTTP 或 gRPC 接收实时遥测，也可读取 OTLP JSON、Jaeger JSON 或 Collector file exporter 文件。它从 invoke_agent、execute_tool 和模型调用 span，以及 GenAI 消息属性、span 事件或日志事件中提取轮次、工具调用、令牌、模型和消息，再与 golden eval set 比较。用户可运行 agentevals run，选择内置指标、LLM judge 或自定义评估器；也可在 Web UI 检查 span 树和实时会话，或通过 MCP 工具和 API 评估会话。结果可输出为 CLI 文本或 JSON，并通过 --emit-otel 以 gen_ai.evaluation.result 事件送回遥测管线。
- 为使用 OpenTelemetry 的 Agent 团队在 CI 中对记录的轨迹运行确定性工具轨迹检查，并用退出码阻止不合格部署。
- 使用 Google ADK、Strands、LangChain、OpenAI Agents SDK 或 Pydantic AI 的开发者，想从现有 OTLP 数据评估 Agent，而不重跑调用。
- 需要人工检查实时 Agent 会话、工具输入输出和 span 树的工程师，可运行服务器并使用内置 Web UI。
- 维护 OpenTelemetry Collector 管线的团队，想将评估结果作为
gen_ai.evaluation.result事件回传并供后端查询或告警。 - 需要将领域规则接入评估的团队，可用任意语言编写通过 stdin/stdout 传递 JSON 分数的自定义评估器。
- 在 Kubernetes 部署 Agent 评估服务的运维团队，可使用 Helm chart，并在需要运行历史记录时配置 Postgres。
如何安装或部署这个 Agent？
安装 CLI；若需要 MCP 服务器，使用 live extra。运行 AgentEvals 不要求付费服务或 API 密钥。若从源码安装，仓库说明使用 uv sync，随后可通过 uv run agentevals 启动命令。
如何使用这个 Agent？
对已记录的轨迹运行工具轨迹指标，并可选择 JSON 输出或将结果发回 OTLP 管线：
agentevals run samples/helm.json \
--eval-set samples/eval_set_helm.json \
-m tool_trajectory_avg_score启动服务以接收实时 Agent 遥测；将 Agent 的 OTLP exporter 指向默认 HTTP 端点。service.instance.id 可区分重跑，agentevals.session_name 可命名会话：
agentevals serve --devexport OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_RESOURCE_ATTRIBUTES="agentevals.session_name=my-agent,service.instance.id=$(uuidgen)"
python your_agent.py可选 Python SDK 用 AgentEvals 会话设置 eval set：
from agentevals import AgentEvals
app = AgentEvals()
with app.session(eval_set_id="my-eval"):
agent.invoke("Roll a 20-sided die for me")这个 Agent 有哪些优点和局限？
- 直接评估已有遥测，不需重跑 Agent，因此同一运行可重复评分而不消耗额外 Agent 令牌。
- 接受标准 OTLP HTTP 和 gRPC，并支持多种框架及 Collector 管线。
- 支持确定性匹配、LLM judge、rubrics 和任意语言的自定义评估器。
- 可输出与被评估 span 关联的标准
gen_ai.evaluation.result事件，便于接入现有遥测后端。
- 项目处于积极开发阶段，文档提示可能发生破坏性变更。
- 评估取决于输入遥测包含可识别的 GenAI span 或消息；未包装成相应 span 的编码会话可能无法形成评估轮次。
- 长时间编码会话的端到端成功评估不在其目标范围内。
- 持久化运行历史需要配置 Postgres；该存储层为预览，schema 可能在小版本间变化。
这个 Agent 与同类方案有什么区别？
README 将 AgentEvals 与 LangSmith、Langfuse、Opik 和 Bedrock AgentCore evaluation 对比：这些方案被描述为需要重跑 Agent，或先依赖自己的 SDK 和存储；AgentEvals 则评估已有 OpenTelemetry 数据。README 也指出，ADK eval 会在一个步骤中运行并评分 Agent，而 AgentEvals 只从遥测评分，并采用 ADK 的指标和 eval set 格式。
与相关度最高的同类 agent 并排比较关键指标。
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示 CI 权限限于 contents: read，SDK 不读取其他后端的 OTEL_EXPORTER_OTLP_* 凭据，并说明会处理的遥测字段和 OTLP 输出；依赖配置还列出若干安全版本下限。扣分原因：服务接收消息内容，但材料未说明敏感字段过滤、访问控制或保留策略；执行评估、发送遥测及持久化均未要求确认，远程评估器和 MCP 有外部影响，且未见回滚说明。ADK 指标与格式有致谢，但发布者身份及维护负责人未获验证。
README 的离线文件评估、在线服务、可选 Postgres 和可选 SDK 描述大体一致，CI 检查锁文件并覆盖多个 Python 版本；示例也展示了轨迹不匹配的失败说明。扣分原因：材料未证明依赖源持续可用或所有故障路径都有清晰错误处理；CI 配置不能替代本次执行验证。
材料列出多种框架、CI、CLI、UI、MCP、Docker 和 Kubernetes 用例，并明确 Claude Code 等场景仅部分支持，长编码会话端到端评分不在适用范围内。扣分原因：触发入口虽有说明，但权限、部署边界及不同环境的安全配置未完整界定。
README 的目录式导航、安装命令、快速开始、框架示例、FAQ 和限制说明较完整；仓库含 Apache-2.0 许可证。扣分原因：项目明确处于活跃开发且预期会有破坏性变更，材料没有具体版本迁移约定或变更日志；虽有贡献指南和 CI，未明确维护责任人。
结果可输出为 JSON 或 OpenTelemetry 评估事件，示例展示了可读的通过与失败原因；基于已有轨迹评估可避免重跑 Agent，体现了清楚的增量价值。扣分原因：LLM judge、服务部署及可选持久化会带来额外成本，材料没有量化其与收益的权衡。
README 对输入、输出、支持格式、限制和安装方式给出具体说明，且 pyproject、CI 与部分测试能交叉印证依赖、安全下限、版本范围和持久化行为。扣分原因：不少能力描述仍是 README 声明，材料没有逐项对应的实现证据；本评估仅据静态材料，未执行或独立验证。
- 接收的遥测可能包含消息内容；部署前应核对采集范围、访问控制和保留设置。
- 项目声明仍在活跃开发并可能出现破坏性变更；升级前应检查兼容性。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
What's Changed * feat: v1alpha1 protobuf contract + native gRPC by @krisztianfekete in https://github.com/agentevals-dev/agentevals/pull/251 * Give rubric_based_* metrics a public rubric path (#132) by @erauner12 in https://github.com/agentevals-dev/agentevals/pull/229 * fix: resolve the package version from v* tags only by @krisztianfekete in https://github.com/agentevals-dev/agentevals/pull/254 * chore(ui): bump dev dependencies by @krisztianfekete in https://github.com/agentevals-dev/agentevals/pull/255 …在 GitHub 查看 ↗ -
发布说明摘录
agentevals v0.10.0 agentevals now reads, stores and evaluates agent telemetry as plain OpenTelemetry. Send OTLP from any GenAI instrumentation, evaluate turns against a golden run, and get the scores back into your observability pipeline as OTel events. Highlights - OpenTelemetry native ingestion. OTLP over HTTP (:4318, now spec compliant with gzip, proper 400 errors and protobuf responses) and gRPC (:4317). Files can be OTLP JSON or protobuf, Jaeger, JSONL, or Collector file exporter output. See [Sending telemetry to agentevals](https://github.com/agentevals-dev/agentevals/blob/v0.10. …在 GitHub 查看 ↗ -
发布说明摘录
What's Changed * chore(deps): bump the npm group in /ui with 10 updates by @dependabot[bot] in https://github.com/agentevals-dev/agentevals/pull/217 * ci: hold mcp at 1.x in the dependabot python group by @krisztianfekete in https://github.com/agentevals-dev/agentevals/pull/219 * chore(deps): bump astral-sh/setup-uv from 10.0.1 to 10.1.0 in the github-actions group by @dependabot[bot] in https://github.com/agentevals-dev/agentevals/pull/221 …在 GitHub 查看 ↗
常见问题
评估会额外消耗 Agent 的模型令牌吗？
必须部署服务器或数据库吗？
能评估 Claude Code 或 Codex 的完整编码过程吗？
Agent 必须使用哪种框架或遥测传输？
如何在 CI 中判断评估是否通过？
agentevals run 提供轨迹、eval set、指标和阈值；CLI 可用退出码作为部署门禁，并可通过 --output json 输出机器可读结果。