這篇是整個系列最核心的一篇

Day 4 提過三層次框架，其中最難、也最容易被忽略的是決策邏輯層——因為沒有現成模板，需要團隊自己設計。這篇要處理的正是這件事：怎麼設計一份真正能回答「Agent 為什麼這樣做」的結構化日誌。

先看反例：只記動作的日誌

多數團隊初期的 Agent 日誌長這樣：

[INFO] Agent invoked tool: search_knowledge_base
[INFO] Tool returned 3 results
[INFO] Agent invoked tool: escalate_to_human

這份日誌能告訴你「發生了什麼」，但完全無法回答「為什麼從搜尋知識庫變成轉接人工」——是搜尋結果品質不好？是 Agent 判斷問題超出範圍？還是有其他觸發條件？沒有這層資訊，事後除錯只能靠猜。

結構化日誌的基本設計

改成結構化 JSON 之後，同一段流程可以承載多得多的資訊：

{
  "severity": "INFO",
  "trace_id": "abc123...",
  "session_id": "sess_789",
  "agent_id": "customer_support_agent",
  "step": 3,
  "event_type": "tool_selection",
  "selected_tool": "escalate_to_human",
  "considered_tools": ["search_knowledge_base", "create_ticket", "escalate_to_human"],
  "decision_summary": "知識庫搜尋結果相關性低於門檻，且問題涉及帳務調整權限",
  "confidence_signal": "low_retrieval_relevance",
  "latency_ms": 240
}

關鍵欄位的設計思路：

trace_id / session_id：讓這筆日誌能跟 Week 3 的 Trace 關聯，也能把同一次對話的所有日誌串起來（Day 9 會深入）。

event_type：把日誌分類，讓查詢時可以只看某一類事件（例如只看所有 tool_selection 事件，分析工具選擇的分布）。

considered_tools 與 selected_tool：這組欄位是「從動作到決策」的關鍵——不只記錄選了什麼，還記錄當時考慮過哪些選項。

decision_summary：一段簡短的自然語言摘要，說明為什麼做這個決定。這個欄位需要應用層主動產生，是最需要自己設計的部分。

設計原則：可查詢優先

結構化日誌的價值在於能被查詢與聚合，所以欄位設計要考慮「未來會想問什麼問題」。例如：

• 想分析「哪類問題最常導致轉接」→ 需要 event_type 與問題分類欄位
• 想找出「哪個工具最常呼叫失敗」→ 需要工具名稱與執行結果欄位
• 想追蹤「決策延遲的分布」→ 需要 latency_ms

一個實用的做法是：在設計欄位前，先列出十個你未來想回答的問題，再反推需要哪些欄位——而不是先設計欄位，事後才發現查不到想要的答案。

別把所有東西都塞進去

跟 Day 5 提到的 Span 屬性反模式同理：完整的 Prompt 與模型回應不建議直接塞進日誌欄位——體積大、可能含個資、也讓日誌成本失控。Day 11 會專門處理這個取捨。

這篇的檢查清單

• [ ] 目前的 Agent 日誌是否只記錄動作，而沒有記錄決策理由？
• [ ] 是否已先列出「未來想回答的問題」，再反推需要的欄位？
• [ ] 每筆日誌是否都帶有 trace_id / session_id 以便關聯？