Failproof AI 可观测性评估器 Agent Skill

​

难点在于决定要评分什么

​

它与其他评估组件的关系

​

与 CLI Skill 的区别：构建 vs 读取

• agenteye-evaluator（本文档）构建产生分数的东西。它的任务在分数首次落地时就完成了。
• agenteye-cli 读取已经存在的分数（agenteye evals）。「这周质量有没有下降？」是它回答的问题，不是本 Skill 的。

​

前提条件

1. 已安装并登录 agenteye CLI（pipx install agenteye，然后 agenteye login）。该 Skill 在两个环节依赖它：拉取用于设计的真实会话，以及最后确认分数是否成功落地。你的登录账号需要 events:read 权限，最终检查还需要 evaluations:read。与 CLI Skill 一样，它无法替你完成邮件一次性验证码的登录流程。
2. 评估器的宿主环境。 它会被构建成镜像并作为长期运行的服务运行，因此需要一个真实的代码仓库，而非临时文件。评估器通常有自己独立的仓库，与被评分的 Agent 分开——该 Skill 会查找现有仓库，并在创建新仓库前向你确认。
3. agenteye-evaluator SDK wheel——在让 Agent 开始输入 pip 命令之前，请先阅读下一节。

​

获取方式

​

安装 Skill

# Claude Code，仅限本项目
npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code

# 所有项目（安装到 ~/.claude/skills/）
npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g --copy

# 使用 Codex 的情况
npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex

npx skills list -a claude-code           # 查看已安装的内容
npx skills update agenteye-evaluator     # 拉取最新版本
npx skills remove agenteye-evaluator     # 移除

• Claude Code：将 agenteye-evaluator/ 文件夹放入 ~/.claude/skills/（所有项目）或 <你的仓库>/.claude/skills/（仅限该仓库）。Claude Code 会自动发现它——通过 /skills 列表验证，或者直接要求做评估即可。
• Codex（OpenAI）：Codex 读取同一个 SKILL.md。内置的 agents/openai.yaml 设置了 allow_implicit_invocation: true，因此当任务匹配时 Codex 会自动选择该 Skill；否则可以通过 $agenteye-evaluator 显式调用。

​

SDK 不在公开的 PyPI 上

警告： 在让 Agent 安装 SDK 之前，请先阅读本节。

​

你可以向它提出什么请求

你    ▸ 我想为我们的支持机器人做评估。我觉得它有时候表现很差。

Agent ▸ 在我写任何东西之前：请描述一次进展顺利的运行，
        以及一次出问题的运行。

你    ▸ 好的情况：它从文档中给出答案。差的情况：它编造内容，
        或者放弃并说「请联系支持团队」。

Agent ▸ 正在执行：agenteye --json sessions --status error --since 7d
        读取 5 个会话，包括两个你认为有问题的。

        你的描述提到了事实准确性和转移问题。转录记录
        与转移问题吻合（5 个中有 2 个以转接支持结束，
        在 model_response.content 中清晰可见），但事实准确性
        需要一个你的事件中不存在的标准答案。

        因此我会评估以下三项：
          - deflection      基于规则，低成本，能区分你的两种运行
          - tool_efficiency 基于规则，能捕捉 run-004 中的重试循环
          - groundedness    LLM 裁判：每个声明是否都来自它检索到的文档？

        「事实准确性」需要我们没有的标准答案；groundedness
        是你的转录记录实际上能支撑的最接近的替代方案。
        这三个名称可以吗？之后重命名会导致历史记录断裂。

你    ▸ 可以

Agent ▸ 这个仓库中没有评估器。要在这里创建一个，还是
        你在别处有现成的？

​

需要注意的事项

• 维度名称几乎是永久性的。 分数键是任意字符串，平台会对你发送的任何内容进行趋势分析，这意味着下游没有任何机制能纠正一个错误的选择。之后重命名会导致历史记录断裂：旧会话保留旧键，趋势就此中断。这就是为什么 Skill 在编写代码之前要求明确签字确认——请认真对待这个提示。
• 测试夹具是真实的生产转录记录。 针对真实会话进行设计意味着要将它们拉取到磁盘上，而其中可能包含客户数据。Skill 在将它们提交到 git 之前会询问你；如有疑虑，请将 fixtures/ 排除在仓库之外，让每位开发者自行拉取。
• Agent 编写并部署一个读取所有转录记录的服务。 它以你的身份行事，受你的 CLI 登录权限约束，但请像对待任何接触生产数据的代码一样审查评估器。

​

后续步骤

• 评估套件（Evaluation suite）：HTTP 契约、SDK 以及 Skill 所配置的服务器环境变量。
• 评估（Evaluations）：分数落地后的呈现位置。
• CLI Skill：姊妹 Skill，用于读取结果而非构建评分器。
• CLI：Skill 设计所依赖的会话数据背后的命令参考。