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