傳統(tǒng)軟件出了問題我們會看日志。但對 Agent 系統(tǒng)來說傳統(tǒng)日志經(jīng)常不夠。因為 Agent 的失敗不一定表現(xiàn)為異常。它可能是選錯了上下文。 調(diào)用了錯誤工具。 相信了過期信息。 重復(fù)執(zhí)行同一步。 省略了驗證。 在錯誤目標(biāo)上努力很久。 成本一路升高但沒有明顯報錯。這些問題不是普通 error log 能解釋的你需要看見 Agent 的循環(huán)。它看到了什么 它為什么這么判斷 它調(diào)用了什么工具 工具返回了什么 它如何更新狀態(tài) 它怎么驗證 它為什么繼續(xù)或停止這就是 Agent Observability。一、為什么傳統(tǒng)日志不夠傳統(tǒng)服務(wù)日志主要記錄系統(tǒng)行為。比如request_id endpoint status_code latency error_message stack_trace這些對 Agent 仍然有用但它們看不到最關(guān)鍵的部分模型輸入了哪些上下文 為什么選擇這個工具 為什么相信這個工具輸出 為什么沒有繼續(xù)驗證 為什么把用戶目標(biāo)理解成另一個目標(biāo)Agent 的核心行為發(fā)生在推理和工具循環(huán)里。如果 trace 只記錄最終輸出你只能看到結(jié)果?？床坏竭^程?？床坏竭^程就無法定位問題。你只能猜是不是 prompt 不好 是不是模型不行 是不是工具有問題 是不是上下文沒給夠這不是調(diào)試這是占卜。二、Agent trace 應(yīng)該記錄什么一個實用的 Agent trace至少要記錄八類信息。第一目標(biāo)。user_goal task_id success_criteria risk_level第二上下文選擇。system instructions project rules retrieved documents memory entries previous state excluded context注意不只記錄放進去了什么。也要記錄為什么排除某些上下文。第三模型調(diào)用。model input token count output token count latency cost temperature / reasoning settings第四工具調(diào)用。tool_name tool_input tool_output_summary artifact_ref error_type retry_count第五中間決策。selected_plan reason_for_tool_choice assumptions open_questions stop_reason第六狀態(tài)更新。progress update decisions update open issues verification state第七驗證結(jié)果。tests run test result review result unverified items human approval第八最終結(jié)果。output files changed side effects remaining risks next action這些信息不一定都要原樣暴露給最終用戶但系統(tǒng)內(nèi)部必須能追。三、三種常見盲區(qū)Agent 可觀測性最容易漏三類東西。1. 上下文盲區(qū)很多系統(tǒng)只記錄 prompt但不記錄上下文來源。結(jié)果出錯時你不知道模型到底看到了哪份文檔、哪段記憶、哪次工具輸出。比如模型引用了舊政策。你需要知道舊政策是從哪里來的 為什么新政策沒有被檢索到 檢索排序為什么錯了 壓縮摘要有沒有丟掉關(guān)鍵條件沒有上下文 trace就只能猜。2. 工具盲區(qū)很多系統(tǒng)記錄“調(diào)用了工具”但不記錄工具輸入、輸出摘要和錯誤恢復(fù)。結(jié)果你不知道模型是用什么參數(shù)查的 工具返回的是空結(jié)果還是錯誤 Agent 有沒有重試 有沒有換查詢條件 有沒有誤讀狀態(tài)碼工具調(diào)用是 Agent 行動的核心這里不能只有一行日志。3. 驗證盲區(qū)最常見的是Agent 說完成了。但系統(tǒng)沒有記錄它跑了哪些測試 哪些沒跑 為什么沒跑 reviewer agent 有沒有發(fā)現(xiàn)問題 人類有沒有審批沒有驗證 trace完成聲明就沒有工程含義。四、調(diào)試手冊可觀測性不是為了好看是為了調(diào)試。下面是幾個常見故障和排查路徑。4.1 Context miss表現(xiàn)Agent 回答漏掉關(guān)鍵事實。 引用了舊文檔。 重復(fù)問已經(jīng)給過的信息。看這些 traceretrieval query retrieved documents selected context memory entries compaction summary excluded context常見修復(fù)改檢索 query 調(diào)整 rerank 補上下文選擇規(guī)則 更新 memory 修改壓縮模板4.2 Wrong tool表現(xiàn)Agent 調(diào)了不該調(diào)的工具。 用讀工具代替寫工具。 用通用 API 工具繞過業(yè)務(wù)工具?？催@些 traceavailable tools tool descriptions tool choice reason tool inputs permission prompts常見修復(fù)改工具名 改工具描述 拆分讀寫工具 增加 when_not_to_use 增加權(quán)限門4.3 Invalid plan表現(xiàn)Agent 從一開始就走錯方向。 拆任務(wù)不合理。 忽略用戶約束?？催@些 traceinitial plan success criteria user constraints assumptions human feedback常見修復(fù)增加計劃確認 讓 Agent 輸出假設(shè) 加入任務(wù)模板 高風(fēng)險任務(wù)先人工審 plan4.4 Repeated loop表現(xiàn)反復(fù)查同一個文件。 反復(fù)跑同一個失敗命令。 修復(fù)同一個錯誤多次?？催@些 traceloop iteration count same tool repeated state update failure reason retry count stop condition常見修復(fù)設(shè)置最大重試 記錄已嘗試方案 失敗后換策略 觸發(fā)人工介入4.5 Cost explosion表現(xiàn)一次任務(wù) token 急劇增加。 工具輸出越來越長。 多 Agent 互相傳大上下文?？催@些 tracetoken per turn tool output size context size cache hit rate model calls subagent count常見修復(fù)工具輸出 offload 壓縮歷史 緩存穩(wěn)定前綴 限制循環(huán)輪數(shù) 降低模型調(diào)用層級五、指標(biāo)不是 trace 的替代品指標(biāo)很重要。比如success rate tool error rate average turns cost per task latency per turn approval rate rollback rate human escalation rate這些能告訴你系統(tǒng)整體健康狀況但指標(biāo)只能告訴你“哪里異常”。trace才能告訴你“為什么異?！薄Ｋ訟gent可觀測性要同時有兩層Metrics看趨勢和報警 Trace看單次任務(wù)路徑只有指標(biāo)沒有 trace定位不了具體原因。只有 trace沒有指標(biāo)看不到系統(tǒng)性退化。六、從單次調(diào)試到系統(tǒng)改進可觀測性的最終目的不是把某一次失敗查清楚而是把失敗轉(zhuǎn)成系統(tǒng)改進。每一次失敗都應(yīng)該歸類prompt issue context issue tool issue permission issue verification issue loop issue human process issue然后進入對應(yīng)改進改 prompt 模板 改檢索策略 改工具描述 加權(quán)限門 加測試 加停止條件 改人工審批流程如果每次事故只靠人類手動修結(jié)果Agent 系統(tǒng)不會變好。真正成熟的團隊會把人類從“修每個輸出”遷移到“修產(chǎn)生輸出的系統(tǒng)”。這也是Harness Engineering的核心精神。七、實戰(zhàn) Checklist上線 Agent 前先檢查這十項。1. 每個任務(wù)是否有 trace_id 2. 是否記錄用戶目標(biāo)和成功標(biāo)準 3. 是否記錄選入上下文和來源 4. 是否記錄工具輸入、輸出摘要和 artifact 5. 是否記錄中間決策和假設(shè) 6. 是否記錄狀態(tài)文件更新 7. 是否記錄驗證命令和結(jié)果 8. 是否記錄人工審批 9. 是否記錄 token、成本和延遲 10. 是否能按失敗類型聚合分析如果這些都沒有Agent 可以先在低風(fēng)險環(huán)境試用但不建議直接進入生產(chǎn)閉環(huán)。八、最后第七篇到第十一篇我們把 Harness Engineering 的主要層拆完了。工具讓 Agent 能行動。驗證讓 Agent 能自證。權(quán)限讓 Agent 有邊界。觀測讓團隊能調(diào)試和改進。到這里一個生產(chǎn)級 Agent 已經(jīng)不再只是模型 prompt而是一套可運行、可驗證、可審計、可恢復(fù)的系統(tǒng)。下一篇我們進入最后一個階段Loop Engineering。因為當(dāng) Agent 不只是執(zhí)行一次而是圍繞目標(biāo)持續(xù)運行時新的問題會出現(xiàn)它什么時候繼續(xù) 什么時候停止 狀態(tài)怎么保存 失敗怎么恢復(fù) 目標(biāo)漂移怎么發(fā)現(xiàn)這就是 Agent Loop 的問題。參考資料? OpenAI Agents SDK: Tracing and Observability? OpenTelemetry Documentation? Claude Agent SDK / Claude Code Observability Documentation? Langfuse / Opik / SigNoz Agent Observability Integrations? Martin Fowler: Harness Engineering for Coding Agent Users參考文獻第十一篇可觀測性看不見 Agent 的循環(huán)就無法調(diào)試 Agent