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