评估套件

Failproof AI Observability 可以自动对每次已完成的 Agent 运行进行质量评分：您提供一个小型评分服务，Observability 负责其余一切。使用它来追踪您关心的维度（有用性、工具效率、事实准确性、安全性；由您决定），及早发现回归问题，并一眼比较不同 Agent 或环境的表现。评分功能为可选项：在服务器上设置 EVALUATOR_ENDPOINT 之前，该流水线不会执行任何操作。

注意： 评分维度由您自行定义。您的评估器可以返回任意数值键；Observability 会存储、趋势分析并展示您返回的所有内容。

概览

编写评分器。 搭建一个小型 HTTP 服务，读取会话转录并返回评分。Observability 附带一个可直接复制使用的参考实现。请参阅使用 SDK 编写评估器。
将 Observability 指向该服务。 在服务器进程上设置 EVALUATOR_ENDPOINT（以及共享的 EVALUATOR_TOKEN）。
查看评分结果。 每个已完成的会话都会被自动评分；结果显示在会话详情页、会话列表和已保存的仪表盘上。

配置评估器后，每次已完成的运行都会被评分，结果出现在会话的右侧边栏：顶部为摘要，其下为带推理说明的各维度评分条。

工作原理

当 Observability SDK 为某个会话发出 agent_end 事件时，服务器会调度一次评估。随后它将完整的事件转录以 POST 方式发送到您的评估器服务，评估器可以：

内联返回结果，格式为 {"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}。结果将追加到该会话的评估时间线中。reasoning 和 summary 为可选字段。
延迟处理，返回 {"status":"pending", "job_id":"abc-123"}。Observability 随后会轮询 GET {EVALUATOR_ENDPOINT}/evaluate/abc-123，直到评估器返回 {"status":"done", ...} 或 {"status":"error", "error":"..."}。轮询频率按任务设置：pending 响应中可包含 next_poll_secs 来覆盖默认值；否则 Observability 使用 GET /config 返回的 default_poll_interval_secs；若未设置则回退到服务器的 EVALUATOR_POLLING_INTERVAL_SECS（默认 10 秒）。所有值均被限制在 [1s, 1h] 范围内。

从未发出 agent_end 的会话（例如 Agent 进程崩溃）也可以被处理：评估器的 GET /config 可返回 {"inactivity_timeout_secs": 1800}，Observability 将对闲置超过该时长的会话进行评估。将该字段设为 null 或省略可禁用此回退机制。当 EVALUATOR_ENDPOINT 未设置时，该流水线完全为空操作。一个会话可以随时间累积多条终态评估记录：每个 agent_end 事件（以及从仪表盘手动触发的重新评估）都会追加一条新的评估行。这是评估已恢复对话的支持方式：用户结束一个 Agent，稍后返回，发送更多事件，再次结束 Agent，第二次评估将针对完整的更新后转录执行。仪表盘将最新评估显示为主要结果，将之前的评估显示为可折叠的时间线。当某个会话有一次评估正在进行时，该会话后续的 agent_end 事件将被忽略；等运行中的评估完成后，下一个 agent_end 事件将照常触发新的评估入队。闲置回退机制在已恢复的会话中同样生效：如果在上一次终态评估之后有新事件到达，且会话随后再次闲置超过 inactivity_timeout_secs，则会入队一次新的评估。暂时性失败（5xx、429、超时、网络错误）将以指数退避方式重试，最多重试 EVALUATOR_MAX_ATTEMPTS 次；4xx 响应为终态错误。Observability 支持多实例水平扩展运行，工作会被分区处理，确保同一会话不会被同时分发两次。

HTTP 协议规范

所有需要认证的路由均使用Bearer Token 认证。两端必须配置相同的值：

Observability 服务器：环境变量 EVALUATOR_TOKEN
评估器服务：以相同方式配置（agenteye-evaluator SDK 按惯例读取 EVALUATOR_TOKEN）

如果 EVALUATOR_TOKEN 未设置，服务器将不发送 Authorization 请求头；评估器可以接受匿名请求，这在纯内部网络中是可以接受的，但不建议在公共互联网上使用。

评估器必须提供的路由

路由	请求体/参数	响应
`GET /health`	无	`{"status":"ok"}`（公开，无需认证）
`GET /config`	无	`{"inactivity_timeout_secs": <int> \| null, "default_poll_interval_secs": <int> \| omitted}`
`POST /evaluate`	`EvalRequest` JSON	`{"status":"done", ...}` 或 `{"status":"pending", "job_id":"..."}`
`GET /evaluate/{id}`	无	与 `/evaluate` 相同的响应格式

服务器发送的 `EvalRequest` 请求体

{
  "schema_version": "1",
  "session_id":     "session-abc123",
  "agent_id":       "planner",
  "environment":    "production",
  "started_at":     "2026-05-10T12:00:00Z",
  "ended_at":       "2026-05-10T12:05:00Z",
  "events": [
    { "id": 1234, "ts": "...", "event_type": "agent_start", "payload": { ... } },
    ...
  ]
}

响应格式

同步（done）：

{
  "status": "done",
  "scores": { "helpfulness": 0.85, "tool_efficiency": 0.6 },
  "reasoning": {
    "helpfulness": "answered the question directly with citations",
    "tool_efficiency": "called list_files three times when one would have done"
  },
  "summary": "strong answer quality, weak tool selection"
}

reasoning（每个评分的理由映射）和 summary（整体一段式叙述）均为可选字段。reasoning 中的键应与 scores 中的键对应；仪表盘会在每个评分条下方内联渲染对应条目。只返回 scores 的旧版评估器无需修改即可继续使用；reasoning 和 summary 将显示为 null，对应的 UI 元素将被省略。 异步（延迟处理）：

{ "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 }

next_poll_secs 为可选字段；若省略，服务器将回退到评估器 /config 中的 default_poll_interval_secs，再回退到自身的 EVALUATOR_POLLING_INTERVAL_SECS 环境变量。 评估器侧终态错误：

{ "status": "error", "error": "model service unavailable" }

服务器将任何其他 2xx 响应体视为协议错误，并为该会话记录一条终态 error。

使用 SDK 编写评估器

您不必手动实现 HTTP 协议规范。agenteye-evaluator Python 包提供了一个带类型的 FastAPI 封装，帮您处理认证、路由以及请求/响应格式。 Failproof AI Observability 还附带了一个可直接使用的参考评估器，它根据转录的结构为 helpfulness、tool_efficiency 和 factuality 进行评分。您可以将其作为起点，替换为自己的逻辑：LLM 裁判、规则引擎，或任何适合您质量标准的方法。最小可用评估器示例：

import os
from agenteye_evaluator import Evaluator, EvalRequest, EvalResponse

app = Evaluator(token=os.environ["EVALUATOR_TOKEN"])

@app.evaluator
def run(req: EvalRequest) -> EvalResponse:
    # Inspect req.events (the full session transcript) and return scores.
    tool_calls = sum(1 for e in req.events if e.event_type == "tool_use")
    return EvalResponse(
        scores={"tool_calls": float(tool_calls)},
        reasoning={"tool_calls": f"{tool_calls} tool invocations in the transcript"},
        summary="tight tool loop" if tool_calls < 5 else "agent looped on tools",
    )

app 实例可在任何 ASGI 服务器下运行，使用 uvicorn module:app 即可启动。对于需要延迟执行高开销任务的评估器，可返回 JobPending 并注册一个 @app.job_lookup 处理器；Observability 服务器会轮询 GET /evaluate/{job_id}，直到您返回终态状态或达到 EVALUATOR_MAX_POLL_DURATION_SECS 上限（默认 1 小时）。完整的 API 参考、异步模式和事件模式请参阅 agenteye-evaluator SDK 的 README。

运行您的评估器

评估器是您自己的服务 —— Failproof AI Observability 不提供默认评估器，因此您需要在自己的服务基础设施中构建并运行它。它可在任何 ASGI 服务器下运行（例如 uvicorn my_evaluator:app）；按照 HTTP 协议规范提供 /health、/config 和 /evaluate 路由，然后将服务器指向该地址（参见配置服务器）。评估器可访问后，GET /health 将返回 {"status":"ok"}。Agent 完整运行结束后，在服务器上执行 GET /evaluations 将返回一条 status: "done" 的记录及您的评估器产生的评分。

配置服务器

在服务器进程上设置以下环境变量：

环境变量	说明
`EVALUATOR_ENDPOINT`	评估器的基础 URL（如 `http://evaluator:9000`）。未设置 = 流水线禁用。
`EVALUATOR_TOKEN`	Bearer Token。必须与评估器服务配置的值相同。
`EVALUATOR_WORKERS`	每个服务器实例的工作任务数（默认 2）。
`EVALUATOR_CLAIM_BATCH`	每次工作任务轮询时领取的行数（默认 4）。批次并发处理；评估器端点的实际并发量为 `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`。
`EVALUATOR_POLL_IDLE_SECS`	当没有待处理评估时，工作任务在两次分发尝试之间的休眠时长（默认 2 秒）。
`EVALUATOR_POLLING_INTERVAL_SECS`	当响应中的 `next_poll_secs` 和评估器的 `default_poll_interval_secs` 均未设置时，`GET /evaluate/{id}` 轮询频率的最终回退值（默认 10 秒）。
`EVALUATOR_REQUEST_TIMEOUT_MS`	单次请求超时时间（默认 30000）。
`EVALUATOR_MAX_ATTEMPTS`	达到此次数的暂时性失败后，结果将记录为终态 `error`（默认 5）。
`EVALUATOR_CONFIG_REFRESH_SECS`	`GET /config` 刷新频率（默认 300）。
`EVALUATOR_MAX_POLL_DURATION_SECS`	会话在轮询队列中保留的最长实际时间，超出后记录为 `timeout`（默认 3600 秒）。防止评估器持续返回 `pending` 的情况。

要开启自动评分，在服务器上同时设置 EVALUATOR_ENDPOINT 和 EVALUATOR_TOKEN，然后重启服务器使配置生效。未设置 EVALUATOR_ENDPOINT 时，流水线保持空操作状态。上述调优参数均为可选项；仅在需要覆盖默认值时才在服务器上设置对应的环境变量。

API 参考

方法	路径	所需权限	用途
`GET`	`/evaluations`	`evaluations:read`	查询终态结果。支持 `session_id`、`agent_id`、`environment`、`status`（`done`/`error`/`timeout`）、`ts_from`、`ts_to`、`cursor`、`limit`、`score_filters`、`latest_per_session` 参数。`limit` 默认为 50，上限为 200（注意与 `/events` 不同，后者上限为 1000）。`environment` 接受逗号分隔的列表（如 `environment=prod,staging`）；单个值同样有效。`latest_per_session=true` 时，响应中每个 `session_id` 最多返回一条记录（按 `completed_at` 最新的一条），供会话列表页将会话评估时间线折叠为当前主要结果使用。默认为 false（返回完整历史记录）。
`GET`	`/evaluations/aggregate`	`evaluations:read`	对过滤后的数据片段进行评估健康状况汇总：总数量、done/error/timeout 分类统计、各评分键的统计数据（count/avg/min/max/p50，针对任意 `scores` 键），以及按时间分桶的趋势时间线。接受与 `/evaluations` 相同的过滤参数，额外支持 `featured_keys`（要趋势展示的评分键 CSV）和 `latest_per_session`。为仪表盘功能提供数据；指标对整个匹配集进行精确计算，不进行采样。
`GET`	`/evaluations/environments`	`evaluations:read`	从 `evaluations` 表中获取不重复的 environment 值。用于填充评估数据范围内的过滤下拉菜单。
`GET`	`/evaluation-jobs`	`evaluations:read`	查看进行中的评估。支持按 `status`（`pending`/`polling`）过滤。
`GET`	`/events`	`events:read`	流式获取会话的原始事件。支持 `session_id`、`agent_id`、`event_type`（CSV）、`environment`（CSV）、`ts_from`、`ts_to`、`cursor`、`limit` 和 `order` 参数。`order` 为 `desc`（最新优先，默认值）或 `asc`（最旧优先）；无法识别的值将回退为 `desc`。通过响应中的 `next_cursor`（事件 id）进行游标分页：将其作为 `cursor` 传回以获取下一页；`asc` 模式下下一页为该 id 之后的事件，`desc` 模式下为该 id 之前的事件。`limit` 默认为 50，上限为 1000。
`GET`	`/sessions/:session_id/export`	`events:read`	返回评估器将接收到的该会话的精确 JSON 请求体，以可下载附件形式提供，文件名为 `session-<id>.json`。适用于将生产会话通过 `agenteye-evaluator` 进行离线测试回放。字节内容与评估流水线实际发送的完全一致。
`POST`	`/sessions/:session_id/re-evaluate`	`evaluations:trigger`	为会话入队一次新的评估；无论是否存在之前的评估均可执行。新结果将追加到会话的评估时间线，而不是覆盖之前的结果，因此历史评分仍然可见。入队成功返回 `202`，会话不存在返回 `404`，已有评估正在进行中返回 `409`。适用于部署新评估器后，或对从未发出 `agent_end` 的会话重新评估。

按评分范围过滤：`score_filters`

GET /evaluations 接受可选的 score_filters 参数，用于按 scores 对象中的数值缩小结果范围。该参数为逗号分隔的 key:min..max 条目列表；上下界均可省略。多个条目以逻辑 AND 组合。指定键不存在或非数值的行将被排除。单次请求最多可包含 20 条过滤条目；超出后返回 HTTP 400。示例：

# helpfulness 在 [0.5, 0.8] 范围内
GET /evaluations?score_filters=helpfulness:0.5..0.8

# tool_efficiency 最高为 0.3（无下限）
GET /evaluations?score_filters=tool_efficiency:..0.3

# helpfulness >= 0.5 且 factuality >= 0.9
GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9..

每条 /evaluations 响应对象包含以下字段：

字段	类型	说明
`evaluation_id`	string (UUID)	此终态评估的规范标识符。每次终态评估都会获得一个新的 UUID；单个会话可包含多条评估。
`id`	string (UUID)	向后兼容别名，与 `evaluation_id` 值相同。
`session_id`	string	此评估所针对的会话。一个会话在时间线中可包含多条评估。
`agent_id`	string	标识产生该会话的 Agent。
`environment`	string	从会话中复制的环境标签。
`status`	enum	`"done"`、`"error"` 或 `"timeout"` 之一。
`scores`	object \| null	评估器返回的评分。
`reasoning`	object \| null	评估器返回的可选逐评分理由映射。键通常与 `scores` 中的键对应。仪表盘在每个评分条下方渲染各条目。
`summary`	string \| null	评估器返回的可选整体一段式叙述。仪表盘在各评分详情上方将其渲染为评估的主要标题。
`error`	string \| null	仅在 `"error"` / `"timeout"` 时填充。
`attempt_count`	integer	分发尝试次数（≥ 1）。
`duration_ms`	integer \| null	最后一次尝试的耗时。
`completed_at`	string (ISO 8601 UTC)	终态结果的记录时间。结果按 `completed_at` 排序（最新优先）。
`created_at`	string (ISO 8601 UTC)	与 `completed_at` 时间戳相同（写入后不可修改）。

权限

权限	授予能力
`evaluations:read`	列出评估结果、在仪表盘中查看评分，以及加载仪表盘健康指标。
`evaluations:trigger`	通过 `POST /sessions/:session_id/re-evaluate` 或仪表盘的重新评估按钮手动为会话入队评估。
`dashboards:read`	查看已保存的仪表盘（同时需要 `evaluations:read` 以加载指标）。
`dashboards:write`	创建和编辑仪表盘。
`dashboards:delete`	删除仪表盘。

引导管理员（ADMIN_KEY、ADMIN_EMAIL）会自动获得上述所有权限。

查看结果

/sessions/<id>：事件时间线 + 右侧边栏，显示会话的评分及分发尝试中的任何错误。如果您的密钥具有 evaluations:trigger 权限，导出按钮旁会出现重新评估按钮，适用于从未发出 agent_end 的会话，或部署新评估器后刷新评分。仪表盘会轮询新结果，并在结果就绪时更新右侧边栏。
/sessions：可过滤的会话列表；评分列一眼显示每个会话的评估状态和评分。
/dashboards：已保存的评估健康视图（参见下方仪表盘）。

会话列表，显示每个会话的评估状态标签和颜色编码的评分徽章（helpfulness、factuality、tool_efficiency、safety、coherence）

会话列表一眼显示每次运行的评估状态和评分；红/黄/绿徽章让低评分一目了然。

仪表盘

仪表盘页面（/dashboards）允许您将一组评估过滤条件保存为命名的可复用视图，并一眼了解该数据片段的评估状况。仪表盘在整个组织内共享；所有具有 dashboards:read 权限的人都能看到相同的仪表盘集合。每个仪表盘固定以下配置：

过滤条件：与会话页面相同的控件：环境、状态、Agent、滚动时间窗口和评分范围过滤器（key:min..max）。
显示配置：要重点展示的评分键、绿/黄/红健康阈值、要显示的面板，以及是否折叠为每个会话的最新评估。

每张卡片显示匹配会话数量、done/error/timeout 分类统计、每个重点评分的平均值，以及小型趋势迷你图。打开仪表盘可查看全尺寸面板；**“在会话中打开”**可跳转至预先过滤到该数据片段的会话页面。指标通过 GET /evaluations/aggregate 在服务端对整个匹配集进行精确计算，结果为精确值而非采样值。

评估健康仪表盘，显示每个评估维度的平均评分条、工具正常/错误分类统计、热门工具及每小时事件趋势

权限： 查看需要同时具备 dashboards:read 和 evaluations:read；创建和编辑需要 dashboards:write；删除需要 dashboards:delete。引导管理员会自动获得所有这些权限。

故障排查

会话存在但未创建任何评估。 确认服务器进程上已设置 EVALUATOR_ENDPOINT，服务器和评估器使用相同的 EVALUATOR_TOKEN 值，且评估器的 /health 端点可从服务器访问。未设置 EVALUATOR_ENDPOINT 时，流水线为空操作。 进行中的评估积压。 查询 GET /evaluation-jobs 查看进行中的队列。检查每条记录的 attempt_count、next_attempt_at 和 last_error。常见原因：评估器服务不可达或返回 5xx（以退避方式重试）、EVALUATOR_TOKEN 错误（401 为终态错误），或异步评估器无限期返回 pending（参见下文）。 会话已完成但无终态评估。 查询 GET /evaluation-jobs?status=polling；结果可能仍在进行中。如果某个任务卡在 pending 状态，说明服务器无法访问评估器；检查评估器是否正常运行且 EVALUATOR_TOKEN 是否匹配。 HTTP 401 from evaluator: invalid bearer token。 服务器上的 EVALUATOR_TOKEN 与评估器服务配置的值不匹配。两者必须完全相同。 异步评估器持续返回 pending。 服务器会轮询 GET /evaluate/{job_id}，直到评估器返回 done 或 error，或达到 EVALUATOR_MAX_POLL_DURATION_SECS 上限（默认 1 小时）。超出上限后，评估将被记录为 timeout 并从进行中的队列中移除。如果您的评估器合理地需要超过默认时长，请适当增大 EVALUATOR_MAX_POLL_DURATION_SECS。

后续步骤

评估器 Agent 技能：让编码 Agent 针对真实会话设计您的评估维度并为您构建该服务。
Python SDK：发出触发评分的 agent_end 事件。
API 密钥：evaluations:read 和 evaluations:trigger 权限。
审计：Observability 的另一个自动化质量功能，用于基于策略的审查。

Overview

Features

SDK and CLI

Administration

概览

工作原理

HTTP 协议规范

评估器必须提供的路由

服务器发送的 `EvalRequest` 请求体

响应格式

使用 SDK 编写评估器

运行您的评估器

配置服务器

API 参考

按评分范围过滤：`score_filters`

权限

查看结果

仪表盘

故障排查

后续步骤

​概览

​工作原理

​HTTP 协议规范

​评估器必须提供的路由

​服务器发送的 EvalRequest 请求体

​响应格式

​使用 SDK 编写评估器

​运行您的评估器

​配置服务器

​API 参考

​按评分范围过滤：score_filters

​权限

​查看结果

​仪表盘

​故障排查

​后续步骤

概览

工作原理

HTTP 协议规范

评估器必须提供的路由

服务器发送的 `EvalRequest` 请求体

响应格式

使用 SDK 编写评估器

运行您的评估器

配置服务器

API 参考

按评分范围过滤：`score_filters`

权限

查看结果

仪表盘

故障排查

后续步骤