agenteye-python-sdk)是一个 Agent Skill:一个包含指令的文件夹,供 Claude Code 或 Codex 等编码智能体在任务匹配时按需加载。它教会智能体如何使用 Python SDK——它不是一个库,也不会改变 SDK 的任何工作方式。
插桩容易写,也容易悄悄出错
SDK 很小:十三个事件方法,全部仅支持关键字参数。编码智能体可以读取 Python SDK 参考文档,在一分钟内写出看起来合理的插桩代码。 问题在于,这个 SDK 在出错时不会抛出异常,而错误的插桩看起来和正确的插桩完全一样——直到有人打开仪表盘发现一片空白。那些真正耗费时间的错误,全都是沉默:
这些错误都不会抛出异常,也不会在测试中暴露。每一条都在 skill 中有明确说明,并附有捕获它的检查契约。
它的工作流程
该 skill 执行的是一位细心工程师会做的同样三个步骤:- 规划。 它读取你的智能体循环,并提出只有你才能回答的两个问题:什么算作一次运行(你的
session_id),以及可区分的参与者是谁(你的agent_id)。它在写任何代码之前先就这些问题达成一致,因为之后再修改会分裂你的历史数据并破坏趋势分析。 - 编写。 它在每次运行时只绑定一次身份,而不是在每个调用点都传递,并选择并发安全的写法——这个细节很重要,因为看似简单的捷径会悄悄地将两个并发运行混入同一个会话。
- 验证。 它运行你的智能体并读取生成的事件文件,检查
agent_start是否存在、环境是否正确、一次运行是否只产生一个会话。
它与其他 skill 的关系
三个 skill,职责清晰划分:
它们按顺序交接:这个 skill 让事件流动起来,evaluator 对其评分,CLI 读取结果。在你的智能体发出会话之前,没有任何内容可评估,也没有任何内容可读取——所以如果你从零开始,就从这里开始。
前置条件
- Python 3.10+ 以及你想要插桩的智能体代码库。
- SDK。 它以私有 wheel 包的形式分发给客户,而非公开索引——你的入门流程会介绍如何获取和安装它。该 skill 知道安装路径,如果找不到会询问你而不是自行猜测。
- 不需要其他任何东西。 无需登录仪表盘、无需 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调用它。
一次对话示例
你可以问它的问题
- “为什么我的智能体没有出现在仪表盘上?” → 逐层排查:事件是否被写入,
agent_start是否存在,环境是否正确,采集器是否读取了正确的位置。 - “所有内容都落在 dev 下。” → 环境变量从未设置,或被后续调用重置了。
- “添加 token 追踪。” → 找到你的 LLM wrapper,记录模型、停止原因和用量。
- “也为子智能体插桩。” → 一个会话,不同的智能体标签,嵌套在各自的父级下。
- “为插桩代码编写测试。” → 将 SDK 指向临时目录,并对写入的事件进行断言。
注意事项
让它验证。 让这个 skill 物有所值的步骤是最后一步——运行你的智能体并读回事件。一个只写插桩代码就停止的智能体只完成了容易的那一半,而静默失败的恰恰是另一半。 在写代码之前先商定命名。session_id 和 agent_id 是每个展示面按其分组的坐标轴。之后重命名会分裂历史数据:旧运行保留旧标签,你的趋势就会中断。该 skill 会询问;答案值得花一分钟认真思考。
如果你的智能体提议从公开索引安装 SDK,说明该 skill 没有加载。 SDK 是私有分发的。这个提议是一个可靠的信号,说明你的编码智能体在猜测而不是遵循 skill——在那里停下来,检查 skill 是否已安装。
除此之外,它的影响范围很小:它在你的工作目录中写代码,在你指定的位置写事件文件。它不读取你的部署中的任何内容,也不对其做任何修改。
后续步骤
- Python SDK:完整的事件参考——该 skill 所自动化内容背后的每种事件类型和字段。
- Sessions:事件落地后你的插桩所产生的会话数据。
- Evaluator Agent Skill:运行数据落地后的下一步——对其评分。
- CLI Agent Skill:读取你的遥测数据。

