Agentry - 代理原生分析與日誌記錄
Agentry 是專為程式碼代理設計的原生分析與日誌記錄系統。它透過單一 HTTP API 涵蓋產品分析、錯誤日誌記錄與部署歸因，讓代理能夠回答使用者做了什麼、什麼出錯了、以及什麼改變了。
使用此技能進行 Agentry 安裝/設定、產品分析、日誌記錄、錯誤監控、部署追蹤、生產除錯以及日常 Agentry 查詢。請勿將此文件視為 API 參考文件；它是通往即時文件的精簡入口。
接下來要擷取什麼
- 安裝或設定 Agentry：擷取 https://agentry.sh/install.md。
- 設定後回答產品、可靠性、案例、分析或部署問題：擷取 https://agentry.sh/agentry.md。
- 探索 API 表面與 3 寫入 / 3 讀取模型：從 https://api.agentry.sh/ 開始。
- 檢查確切的請求/回應結構：擷取 https://api.agentry.sh/v1/openapi.json；使用
?flow=、?tag=、?path=&method=或?index=true進行篩選。 - 安裝或重新整理未來工作階段的適配器：擷取 https://api.agentry.sh/adapters 並寫入每一個與檢測到的代理環境相符的適配器。
對於非瀏覽器的直接 HTTP 呼叫，請使用自訂的 User-Agent 標頭；預設用戶端（如 Python-urllib）可能會被封鎖。瀏覽器 fetch 會使用瀏覽器自身的 User-Agent 且無法手動設定此標頭。
安裝工作流程
安裝 Agentry 時，請擷取 https://agentry.sh/install.md 並遵循該流程。從儲存庫的重要業務問題與管道/業務邏輯流程開始。讓 POST /v1/install/plan 從實際程式碼庫推導出事件、屬性、錯誤表面與部署證明。請勿手動撰寫通用的事件目錄。
在宣稱成功之前，請儲存訊號對應表與實作報告，然後驗證已核准的遙測資料正在流動。
心智模型
Agentry 有三個寫入路徑與三個讀取概念。
使用 AGENTRY_DSN 寫入應用程式執行時期資料：
POST /v1/logs/用於記錄錯誤、例外與營運失敗。POST /v1/analytics/用於記錄產品、使用者、管道與業務事件。
僅在成功的發布後，於 CI/提供者發布後自動化中使用相同的 AGENTRY_DSN 寫入部署歸因：
POST /v1/deploys/用於發布歸因。
使用 AGENTRY_API_KEY 讀取：
- 案例： 什麼出錯了。從
GET /v1/projects/:project_id/cases開始，然後GET /v1/cases/:case_id。 - 分析： 使用者做了什麼。從已儲存的訊號對應表、最新的驗證報告、答案合約、事件名稱與屬性鍵開始；然後針對常見讀取使用查詢藍圖，或針對自訂 HogQL 使用
POST /v1/projects/:project_id/analytics/query。 表格狀的 Agentry 查詢讀取會回傳物件形狀的rows；請勿從代理面向端點讀取 PostHog 風格的results。 - 部署： 什麼改變了。使用
GET /v1/projects/:project_id/deploys。
查詢藍圖、事件名稱、公開查詢、健康狀態與後續步驟是圍繞這三個讀取概念的輔助功能。公開查詢 URL 與儀表板是選用的輸出表面，並非證明基礎產品問題可被回答的證據。
對於日常問題，在選擇查詢藍圖或自訂 HogQL 之前，請先讀取已儲存的訊號對應表、最新的驗證報告、答案合約、事件名稱與屬性鍵。如果缺少所需的事件/屬性，請說明缺少什麼，並改為連接或觸發該產品流程，而不是自行發明一個指標。
認證
從環境變數或 ~/.agentry/credentials.json 讀取 AGENTRY_API_KEY；從 AGENTRY_PROJECT_ID 或已提交的 .agentry/config.json 讀取 project_id。如果沒有 API 金鑰，請使用 POST /v1/auth/device 啟動裝置授權流程。執行時期資料攝取使用 AGENTRY_DSN。
事實來源
請勿依賴此已安裝的文件來獲取端點詳細資訊。請擷取上述的即時文件；它們是權威來源，並且可以獨立於適配器進行更新。