Promptetheus – 追踪、检测并自动修复AI代理故障

Promptetheus 是一款专为 AI 代理设计的调试基础设施，旨在帮助开发者追踪、检测并自动修复代理运行中的故障。该项目以 Python SDK 为核心，结合本地回放工具、托管追踪交付以及 MCP 证据访问，为 AI 代理提供全面的可观测性。

核心功能包括：一个代理任务对应一个追踪，通过装饰器（如 @pt.observe 和 @pt.tool）轻松集成到现有代码中。这些装饰器能够记录用户消息、代理消息、工具调用、浏览器操作、DOM 快照、屏幕截图、LLM 调用、检索、指标、错误、评分以及最终目标检查等事件。SDK 采用持久化交付机制，即使在 HTTP 交付失败或未配置的情况下，事件也会本地存储，并可在后续进行回放。

对于本地开发，Promptetheus 提供了丰富的 CLI 工具。开发者可以使用 promptetheus sessions 列出本地会话，使用 promptetheus replay 查看完整时间线或树状结构，使用 promptetheus fingerprint 生成失败指纹以快速定位问题，以及使用 promptetheus spool 管理本地事件缓存。此外，还支持通过 promptetheus import 导入导出的会话。

Promptetheus 支持异步代理和浏览器代理。对于异步代理，提供了 AsyncSession 类。对于浏览器代理，建议记录用户目标、关键浏览器操作、最终 DOM 状态以及明确的目标检查。这些数据可以帮助 Promptetheus 回放失败过程并生成修复证据。

框架适配器是可选的，可通过 pip install "promptetheus[openai]" 等方式安装。支持的适配器包括 AnthropicAdapter、OpenAIAdapter、LangGraphAdapter 等。当框架已提供结构化回调时，使用适配器可避免重复的手动埋点。

AgentRuntime 是用于实时、服务端协调的客户端，与持久化追踪存储分离。它提供 remember、before_tool_call、after_tool_call 和 heartbeat 等方法，帮助代理在运行时获取提示信息。

对于需要 MCP 证据访问的场景，Promptetheus 可以生成托管 MCP 客户端配置，支持 Codex、Claude 和 Cursor 等客户端。生成的配置以只读方式访问工作区和 Supabase 项目范围内的证据。

总之，Promptetheus 为 AI 代理提供了从开发到生产的完整调试方案，帮助开发者快速定位和修复代理运行中的问题。