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 代理提供了從開發到生產的完整調試方案，幫助開發者快速定位和修復代理運行中的問題。