AI 代理可觀察性應能重建一次執行中的使用者請求、模型呼叫、工具選擇、政策決策、工具執行、下游副作用、重試及最終回應。日誌、指標、追蹤與評估各自回答不同問題，因此只收集模型文字並不夠。
先選一項失敗或成本高的工作流程，再確認是否有一個識別碼能一路追蹤到權威後端結果。
追蹤完整的決策與執行路徑
sequenceDiagram
participant U as User
participant A as Agent
participant M as Model
participant P as Policy
participant T as Tool
participant B as Backend
U->>A: Request
A->>M: Model call
M-->>A: Tool selection
A->>P: Authorize identity and action
P-->>A: Decision
A->>T: Tool call with operation ID
T->>B: Downstream request
B-->>T: Authoritative result
T-->>A: Structured result
A-->>U: Response
使用 trace 表示一次執行、span 表示模型及工具工作，可能比 trace 活得更久的副作用則使用 operation ID。可行時，將 tool-call ID 帶進伺服器。資料庫資料列應能連回操作與 trace，但不必儲存完整追蹤本身。
OpenTelemetry 發布模型、代理及工具 span 的 GenAI 語意慣例。這些慣例仍在演進，因此要固定版本，並保留一個小型內部結構描述層，避免把實驗性屬性名稱散落在應用程式各處。
擷取能解釋執行的事實
模型 span
記錄供應商、模型、回應識別碼、延遲、token 用量、結束原因、重試次數及提示詞範本版本。只有政策允許時才儲存完整提示詞；一般追蹤使用雜湊、遮蔽後的樣本或受保護參照可能就足夠。
工具 span
記錄可見工具名稱與版本、tool-call ID、遮蔽後的引數、選擇來源、執行時間、結果類別、重試次數及下游 operation ID。明確分開「模型選擇工具」、「政策允許工具」與「後端完成動作」。
政策與核准 span
記錄所代表的身分、租戶、資源、動作、政策版本、決策、原因碼及核准參照。絕不能記錄存取權杖或原始密鑰。遭拒的請求是預期的政策結果，不一定是應用程式錯誤。
復原 span
將恢復的工作連回原始工作流程及操作。記錄系統是重試、對應未知結果、補償已完成動作，還是停止等待人類審查。失敗復原指南會說明這些分支。
用指標找出模式，而不是解釋事件
彙總指標應包含：
- 成功、失敗、遭拒及取消的執行；
- 工作完成率與人類升級率；
- 依百分位呈現的模型及工具延遲；
- 每項工作及每個租戶的 token 與供應商成本；
- 工具選擇、驗證、授權及後端錯誤率；
- 重試、重複呼叫、迴圈停止及未知結果；
- 佇列延遲、作用中執行及檢查點時間。
不要在 label 中放入提示詞文字、使用者 ID、工具引數或 trace ID 等無限種類的值。這些資訊應放在受保護的日誌或追蹤中，指標維度則保持有界限。
將日誌保存成個別且遮蔽的事件
日誌適合記錄部署變更、政策決策、操作轉換、供應商錯誤及清理。使用穩定事件名稱與結構化欄位，不要在每一層都重複記錄完整模型承載資料。
資料離開程序前就要完成遮蔽。密鑰、授權標頭、個人資料、擷取文件及工具輸出都可能出現在提示詞與錯誤中；匯出後再取樣無法消除已經發生的暴露。
使用評估衡量品質
遙測會告訴你發生了什麼，但如果沒有預期行為，它無法判斷回應是否有幫助、工具選擇是否正確。將正式環境失敗及抽樣追蹤加入有版本的評估集合，再於變更模型、提示詞或工具合約前執行。
AI 代理評估指南會區分確定性斷言、模型裁判、重複試驗及發布門檻。
針對人類能採取的動作設定警示
對有明確應變方式的情況發出警示，例如部署後大量授權失敗、破壞性工具呼叫突增、追蹤中斷、反覆出現未知結果、佇列等待過久、支出限制，以及執行超過呼叫或時間預算。
不要為每個模型錯誤發出即時通知。先依供應商、模型、工具、發布版本及結果類別分組。儀表板可以呈現雜訊較多的品質變化；即時通知則應指向具體的限制或回復動作。
加入儀表板前先稽核一條追蹤
選擇一次真實執行並手動追蹤。你能否找出提示詞版本、工具清單、政策決策、下游請求、業務結果、成本及每次重試？能否從 trace 找到受影響的操作，也從操作找到 trace？
下方提示詞會在不傳送資料的情況下，對儲存庫執行這項稽核。第一個缺少的連結，比另一張彙總圖表更適合作為 instrumentation 工作。