Agent Workflow Audit Log Setup：從零搭建可審計的 Agent 工作流程

當你開始在生產環境中運行 Agent 工作流程，最害怕遇到什麼？不是它回答錯了，而是你完全不知道它為什麼錯。沒有審計日誌，Agent 就像一個黑盒子：它調了哪個工具、傳了什麼參數、中間狀態如何、最終決策依據是什麼——全都不透明。

審計日誌（Audit Log）就是為了解決這個黑盒子問題。它記錄 Agent 工作流程中每一次關鍵動作：包括工具呼叫、LLM 輸入輸出、狀態躍遷、異常事件等。有了它，你才能事後複盤、調試異常、滿足合規審計要求。

審計日誌應該記錄什麼？

不是所有數據都值得記。核心記錄項分為五類：

1. 請求與回應：每次 LLM 呼叫的完整 prompt 和 completion，包括 temperature、max_tokens 等參數。丟失這個，你就無法復現任何一次推理。
2. 工具呼叫軌跡：Agent 呼叫的函數名稱、傳入參數、傳回結果、耗時。很多錯誤發生在工具回傳的資料格式不符預期時。
3. 狀態變更：工作流程中關鍵變數的值變化，例如使用者意圖、已收集資訊、中間決策結果。
4. 異常與重試：網路逾時、LLM 回傳格式錯誤、工具拋出異常——這些都是偵錯的重頭戲。
5. 元資料：請求 ID、時間戳記、版本號、Agent 實例 ID。用於關聯多次互動和橫向排查。

在實際專案中，我看過團隊只記錄 LLM 對話，完全忽略工具調用，結果一次 API 限流導致整個工作流程中斷，查了兩天才定位到——就是因為工具調用日誌缺失。

搭建步驟：從日誌結構到檢索

1. 定義日誌結構

採用扁平化的 JSON 格式，每個事件一筆記錄。關鍵欄位：event_id, trace_id（用於關聯相同工作流程）、agent_id, event_type（如 llm_call、tool_call、state_change、error）、[TRTS1]。

避免嵌套過深，否則查詢效能會急劇下降。建議使用列式儲存（如 ClickHouse）或結構化日誌服務（如 Seq、Loki）。

2. 埋點策略

不要試圖記錄所有變數——這會擊穿儲存成本，也難以分析。優先記錄：

• 每次 LLM 呼叫的輸入輸出（可開啟 truncation 限制大文本）
• 每次工具呼叫的參數和傳回結果
• 工作流程開始與結束（記錄最終輸出和耗時）
• 任何異常或重試事件

埋點代碼通常以裝飾器模式或 AOP 插入 Agent 框架。以 LangChain 為例，可在 CallbackHandler 中 on_llm_start、on_tool_start 等鉤子寫入日誌。

3. 儲存與保留策略

審計日誌不能只存在記憶體裡，停機就丟了。至少寫入本機磁碟（每天輪轉壓縮），可選同步到 S3 或 ES。保留期限依合規要求（一般 90-180 天），老舊資料歸檔至冷儲存。

4. 檢索與視覺化

日誌只有能查才有意義。建立一個簡單的查詢介面，支援按 trace_id、時間範圍、事件類型、agent_id 過濾。如果能用自然語言查詢（如「上週三工作流程 X 為什麼失敗」）就更好了。

最容易踩的坑

我見過最多的問題是 日誌阻塞工作流程。很多人同步寫入遠端資料庫，網路擁塞時 Agent 回應變慢甚至逾時。解決方法是異步寫入：本地先寫記憶體緩衝佇列，由後台執行緒批次 flush。如果佇列寫滿，寧可丟日誌也不要影響主流程－丟日誌至少還能跑，工作流程掛掉什麼都查不到。

第二個坑是 日誌過多導致儲存爆炸。特別是每個 LLM 呼叫都記錄完整對話，一天就能上 GB。解決方案：只保留最近 X 天的原始日誌，舊資料聚合摘要後丟棄。另外，只錄關鍵 payload，去掉冗長的系統​​ prompt。

第三個坑是 日誌沒有 trace_id。如果沒有關聯上下文，幾千條日誌散落在文件裡，你根本不知道哪些屬於同一次工作流程。 Trace ID 必須在工作流程啟動時生成，並貫穿所有子呼叫。

真實場景：一次失敗的 Tool 調用

假設有一個 Agent 負責查詢使用者訂單。它呼叫了 get_order(id) 工具，但服務端回傳了 500 錯誤。審計日誌應該記錄：

• 事件類型：tool_call_start，參數：{order_id: "123"}
• 事件類型：tool_call_error，回傳：{status: 500, error: "Internal Server Error"}
• 然後 Agent 進行重試（或換策略），再記錄 tool_call_retry 和 tool_call_end。

沒有審計日誌，這個 500 錯誤只會被 LLM 悄無聲息地吞掉，用戶看到的是“查詢失敗”，而你作為開發者完全不知道是 Agent 代碼問題還是後端接口問題。

備用方案：當標準方案失敗時

如果團隊資源有限，無法搭建獨立日誌系統，可以降級利用 LLM 本身來「審計」。具體做法是：在每一步 action 後，讓 Agent 自己以自然語言總結目前狀態，寫入一個臨時變數。工作流程結束時，請 Agent 輸出完整日誌。雖然不可靠（Agent 可能遺漏或編造），但聊勝於無。

另一個更成熟的降級方案是複用已有的業務日誌 + 請求 ID：將每次 Agent 互動的 trace_id 寫入業務資料庫的請求日誌表，由後端服務自行記錄呼叫連結。缺點是侵入性強，但不需要額外基建。

最後

審計日誌不是可選項。當你的 Agent 工作流程開始處理真實使用者請求時，它就是唯一的排障視窗。先搭好日誌再上線，否則遲早要花幾倍時間去返工。