评估套件 - FailproofAI

AgentEye 通过向客户自有的评估服务发送 POST 请求，将完整的事件记录提交，以对已完成的 agent 会话进行评分。评估服务可直接返回评分结果，或返回一个 job_id 供 AgentEye 轮询。评分结果将被存储并展示在仪表盘中。本文档涵盖以下内容：

会话完成的检测方式。
评估服务必须实现的 HTTP 协议规范。
AgentEye 服务器的配置方法。
查看评估结果。
故障排查。

如需使用已实现上述协议规范的 Python 辅助库，请参阅 PyPI 上的 agenteye-evaluator 包。

工作原理

ingest /events  ──▶  AgentEye  ──── POST /evaluate ────▶  评估服务
   (agent_end)        server   ◀──── done | pending ────
                          │
                          │     GET /evaluate/{job_id} ─────▶
                          │     ◀──── done ──────────────
                          ▼
                     evaluations  (终态结果)

当 AgentEye SDK 为某个会话发出 agent_end 事件时，服务器会调度一次评估任务，并将完整的事件记录以 POST 请求发送至评估服务。评估服务可以：

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

对于从未发出 agent_end 事件的会话（例如 agent 进程崩溃），同样可以触发评估：评估服务的 GET /config 可返回 {"inactivity_timeout_secs": 1800}，AgentEye 将对闲置时间超过该值的会话发起评估。将该字段设为 null 或省略可禁用此兜底机制。若未设置 EVALUATOR_ENDPOINT，整个评估管道将完全空操作。一个会话可以随时间积累多个终态评估结果：每个 agent_end 事件（以及每次从仪表盘手动触发的重新评估）都会追加一条新的评估记录。这是评估已恢复对话的标准方式：用户结束 agent 后，稍后返回继续发送事件，再次结束 agent，第二次评估将针对更新后的完整记录运行。仪表盘将最新一次评估作为主要显示内容，历史评估以可折叠时间线的形式呈现。当某会话有评估正在运行时，该会话的后续 agent_end 事件将被忽略；等当前评估完成后，下一个 agent_end 事件才会正常入队新的评估任务。闲置兜底机制在已恢复的会话中同样生效：如果在已有终态评估的情况下又有新事件到来，且会话随后闲置超过 inactivity_timeout_secs，则会触发新的评估任务入队。瞬时错误（5xx、429、超时、网络错误）将以指数退避方式重试，最多重试 EVALUATOR_MAX_ATTEMPTS 次；4xx 响应为终态错误。AgentEye 支持多实例水平扩展，任务会分区处理，同一会话不会被并发派发两次。

HTTP 协议规范

所有需要认证的路由均使用 Bearer Token 认证，双方必须配置相同的令牌值：

AgentEye 服务器：环境变量 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": { ... } },
    ...
  ]
}

响应格式

同步（直接返回结果）：

{
  "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，对应的界面元素将不显示。 异步（延迟处理）：

{ "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 编写评估服务

agenteye-evaluator Python 包提供了一个带类型的 FastAPI 封装，已实现上述 HTTP 协议规范。从 PyPI 安装：

pip install agenteye-evaluator

最简评估服务示例：

import os
from agenteye_evaluator import Evaluator, EvalRequest, EvalResponse

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

@app.evaluator
def run(req: EvalRequest) -> EvalResponse:
    # 检查 req.events（完整的会话记录）并返回评分。
    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 处理函数；AgentEye 服务器将轮询 GET /evaluate/{job_id}，直至返回终态状态或达到 EVALUATOR_MAX_POLL_DURATION_SECS 上限（默认 1 小时）。完整 API 参考文档、异步模式说明及事件 schema 请参阅 agenteye-evaluator 的 README，该文件随每个发布包附带于 agenteye-enterprise releases 页面，也可在该包的 PyPI 页面查阅。

在 Kubernetes 上运行评估服务

评估服务是您自己的服务：AgentEye 不提供默认的评估服务容器。发布包中包含 deploy/examples/evaluator/ 目录下的 Kubernetes 参考清单，替换镜像地址和共享 Bearer Token 后即可直接应用。

1. 将评估服务容器化

评估服务的最简 Dockerfile：

FROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir agenteye-evaluator uvicorn
COPY my_evaluator.py .
RUN useradd --uid 10001 --create-home --shell /usr/sbin/nologin evaluator \
    && chown -R evaluator:evaluator /app
USER evaluator
EXPOSE 9000
CMD ["uvicorn", "my_evaluator:app", "--host", "0.0.0.0", "--port", "9000"]

设置 runAsNonRoot（UID 10001）可使容器兼容 Pod Security 受限配置文件。

2. 创建共享 Bearer Token

kubectl -n agenteye create secret generic evaluator-token \
  --from-literal=token="$(openssl rand -hex 32)"

该值需与 AgentEye 服务器上的 EVALUATOR_TOKEN 保持一致。服务器每次请求均会发送 Authorization: Bearer <token>；SDK 使用 hmac.compare_digest 进行常量时间校验，不匹配时返回 HTTP 401。

3. 应用示例清单

# 先编辑 deploy/examples/evaluator/deployment.yaml，
# 将 `image:` 指向您的镜像仓库，然后执行：
kubectl apply -k deploy/examples/evaluator/

示例清单包含：

2 副本的 Deployment，配置了 runAsNonRoot、只读根文件系统、删除所有 capabilities，以及基于 /health 的存活探针和就绪探针
端口 9000 的 ClusterIP Service
secret.example.yaml 模板（已从 Kustomization 中排除，请通过带外方式创建真实 Secret，避免令牌提交到 git）

4. 将 AgentEye 连接到评估服务

在 AgentEye 服务器上设置：

EVALUATOR_ENDPOINT=http://evaluator:9000
EVALUATOR_TOKEN=<上面生成的值>

服务器会向所有评估服务 Pod 并发发送 EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH 个请求（默认值：2 × 4 = 8）。请根据这些服务端参数同步调整 replicas 和每个 Pod 的资源限制。

验证

kubectl -n agenteye port-forward svc/evaluator 9000:9000
curl -s http://localhost:9000/health   # → {"status":"ok"}

在 agent 完整运行一次后，AgentEye 服务器上的 GET /evaluations 应返回一条 status: "done" 的记录，其中包含评估服务产生的评分。

配置 AgentEye 服务器

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

环境变量	说明
`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` 的情况。

若要为整个实例启用自动评分，请创建包含上述两个键的 agenteye-evaluator Secret。在附带的 Kubernetes 清单中，服务器从该可选 Secret 中读取 EVALUATOR_ENDPOINT 和 EVALUATOR_TOKEN。请通过组织的标准密钥管理流程创建该 Secret，然后重启服务器 Deployment 使配置生效。上述调优参数默认不在 Deployment 清单中配置；如需覆盖默认值，请在服务器容器的 Deployment 清单中显式添加对应的环境变量。完整环境变量列表请参阅 deployment.md。

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 分布、各评分键的统计指标（在任意 `scores` 键上计算 count/avg/min/max/p50）以及按时间分桶的趋势数据。接受与 `/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。

​工作原理

​HTTP 协议规范

​评估服务必须实现的路由

​服务器发送的 EvalRequest 请求体

​响应格式

​使用 SDK 编写评估服务

​在 Kubernetes 上运行评估服务

​1. 将评估服务容器化

​2. 创建共享 Bearer Token

​3. 应用示例清单

​4. 将 AgentEye 连接到评估服务

​验证

​配置 AgentEye 服务器

​API 参考

​按分数范围过滤：score_filters

​权限

​查看结果

​仪表盘

​故障排查