跳转到主要内容
告诉你的编码智能体 “为这个智能体添加 Failproof AI Observability”,让它读取你的循环逻辑,判断插桩位置,编写代码,并在宣告任务完成之前验证事件。 Python SDK skillagenteye-python-sdk)是一个 Agent Skill:一个包含指令的文件夹,供 Claude Code 或 Codex 等编码智能体在任务匹配时按需加载。它教会智能体如何使用 Python SDK——它不是一个库,也不会改变 SDK 的任何工作方式。

插桩容易写,也容易悄悄出错

SDK 很小:十三个事件方法,全部仅支持关键字参数。编码智能体可以读取 Python SDK 参考文档,在一分钟内写出看起来合理的插桩代码。 问题在于,这个 SDK 在出错时不会抛出异常,而错误的插桩看起来和正确的插桩完全一样——直到有人打开仪表盘发现一片空白。那些真正耗费时间的错误,全都是沉默: 这些错误都不会抛出异常,也不会在测试中暴露。每一条都在 skill 中有明确说明,并附有捕获它的检查契约。

它的工作流程

该 skill 执行的是一位细心工程师会做的同样三个步骤:
  1. 规划。 它读取你的智能体循环,并提出只有你才能回答的两个问题:什么算作一次运行(你的 session_id),以及可区分的参与者是谁(你的 agent_id)。它在写任何代码之前先就这些问题达成一致,因为之后再修改会分裂你的历史数据并破坏趋势分析。
  2. 编写。 它在每次运行时只绑定一次身份,而不是在每个调用点都传递,并选择并发安全的写法——这个细节很重要,因为看似简单的捷径会悄悄地将两个并发运行混入同一个会话。
  3. 验证。 它运行你的智能体并读取生成的事件文件,检查 agent_start 是否存在、环境是否正确、一次运行是否只产生一个会话。
第三步正是人们通常会跳过的。SDK 将事件写入本地文件,因此完整的集成可以在笔记本电脑上完成验证,无需服务器、无需 API 密钥、无需网络——这正是该 skill 坚持执行这一步的原因。

它与其他 skill 的关系

三个 skill,职责清晰划分: 它们按顺序交接:这个 skill 让事件流动起来,evaluator 对其评分,CLI 读取结果。在你的智能体发出会话之前,没有任何内容可评估,也没有任何内容可读取——所以如果你从零开始,就从这里开始。

前置条件

  1. Python 3.10+ 以及你想要插桩的智能体代码库。
  2. SDK。 它以私有 wheel 包的形式分发给客户,而非公开索引——你的入门流程会介绍如何获取和安装它。该 skill 知道安装路径,如果找不到会询问你而不是自行猜测。
  3. 不需要其他任何东西。 无需登录仪表盘、无需 API 密钥、无需网络。该 skill 通过 SDK 写入的事件文件进行验证,因此可以在离线状态下完成并证明其工作成果。

获取方式

该 skill 位于公开的 FailproofAI/skills 集合中:
添加 -g 可为所有项目安装,而不仅限于当前项目;如果你的环境不支持符号链接,请添加 --copy。对于 Codex,传入 -a codex

手动安装

Agent Skills 是包含 SKILL.md 及相关引用的文件夹。如果你不想使用安装程序:
  • Claude Code:将 agenteye-python-sdk/ 文件夹复制到 ~/.claude/skills/(所有项目)或 <你的代码库>/.claude/skills/(仅该代码库)。Claude Code 会自动发现它——查看 /skills 列表,或直接提问匹配的问题即可。
  • Codex:Codex 读取相同的 SKILL.md。捆绑的 agents/openai.yaml 设置了 allow_implicit_invocation: true,因此当任务匹配时会自动选择;否则使用 $agenteye-python-sdk 调用它。
在包含你要插桩代码的代码库中运行你的智能体——该 skill 会在提出任何建议之前读取你的智能体循环。

一次对话示例

值得注意的模式:它在提出建议之前先读取了代码,只问你才能回答的问题,复用了你已有的 ID,因为看到了线程池而选择了并发安全的写法,并且通过读取实际事件来验证而不是直接宣告成功——然后标记出它知道会静默失败的那一处。

你可以问它的问题

  • “为什么我的智能体没有出现在仪表盘上?” → 逐层排查:事件是否被写入,agent_start 是否存在,环境是否正确,采集器是否读取了正确的位置。
  • “所有内容都落在 dev 下。” → 环境变量从未设置,或被后续调用重置了。
  • “添加 token 追踪。” → 找到你的 LLM wrapper,记录模型、停止原因和用量。
  • “也为子智能体插桩。” → 一个会话,不同的智能体标签,嵌套在各自的父级下。
  • “为插桩代码编写测试。” → 将 SDK 指向临时目录,并对写入的事件进行断言。

注意事项

让它验证。 让这个 skill 物有所值的步骤是最后一步——运行你的智能体并读回事件。一个只写插桩代码就停止的智能体只完成了容易的那一半,而静默失败的恰恰是另一半。 在写代码之前先商定命名。 session_idagent_id 是每个展示面按其分组的坐标轴。之后重命名会分裂历史数据:旧运行保留旧标签,你的趋势就会中断。该 skill 会询问;答案值得花一分钟认真思考。 如果你的智能体提议从公开索引安装 SDK,说明该 skill 没有加载。 SDK 是私有分发的。这个提议是一个可靠的信号,说明你的编码智能体在猜测而不是遵循 skill——在那里停下来,检查 skill 是否已安装。 除此之外,它的影响范围很小:它在你的工作目录中写代码,在你指定的位置写事件文件。它不读取你的部署中的任何内容,也不对其做任何修改。

后续步骤

  • Python SDK:完整的事件参考——该 skill 所自动化内容背后的每种事件类型和字段。
  • Sessions:事件落地后你的插桩所产生的会话数据。
  • Evaluator Agent Skill:运行数据落地后的下一步——对其评分。
  • CLI Agent Skill:读取你的遥测数据。