選型：從LLM調(diào)用到Harness Runtime的落地指南)
1. 架構(gòu)分層從一次 LLM 調(diào)用到完整 Harness Runtime到底在選什么1.1 先把問題拆開你需要的不是“選框架”而是“選復雜度”很多人一上來就問“AI Agent 架構(gòu)到底用哪個框架好”我覺得這個問題本身就問偏了。真正要回答的不是“哪個好”而是“你現(xiàn)在需要多復雜”。一次 LLM 調(diào)用、一個 ReAct 循環(huán)、一套完整 Harness Runtime這三者之間的差距比想象中大得多。我見過不少團隊踩同一個坑剛跑通一個帶工具調(diào)用的 Demo就急著上全套 Agent 運行時結(jié)果被上下文管理、記憶持久化、沙箱執(zhí)行、可觀測性這些基礎設施拖垮。反過來也有團隊在業(yè)務已經(jīng)需要并行 Agent、長時任務、斷點恢復時還在手寫while True: llm.call()的死循環(huán)腳本導致任務一跑長就崩、一并發(fā)就亂。先把概念對齊。我這里說的“一次 LLM 調(diào)用”指的是單輪請求-響應模型根據(jù) System Prompt 直接產(chǎn)出結(jié)果不涉及工具、循環(huán)和狀態(tài)。這是最基礎的范式適合分類、抽取、簡單問答。“從一次調(diào)用到完整 Harness Runtime”中間其實隔了好幾層工具調(diào)用層模型輸出結(jié)構(gòu)化指令由程序解析并執(zhí)行外部函數(shù)循環(huán)控制層Agent 在“思考-行動-觀察”之間反復迭代直到任務完成狀態(tài)管理層維護會話上下文、任務進度、中間結(jié)果支持暫停和恢復運行時層負責沙箱、并發(fā)調(diào)度、安全策略、資源限制、可觀測性也就是題名里的 Harness Runtime所以“AI Agent 架構(gòu)怎么選”這個問題的實質(zhì)是你要在哪一層投入復雜度這決定了后續(xù)所有的技術(shù)選型。1.2 確定需求的三個關鍵判斷任務類型、交互模式、運行環(huán)境我一般會從三個維度判斷該落在哪一層比直接看框架榜單靠譜得多。第一個維度是任務類型。如果是短任務比如“從這段合同里抽取違約條款并結(jié)構(gòu)化輸出”一次調(diào)用加 JSON Mode 就夠了壓根不需要 Agent 架構(gòu)。如果是多步驟任務比如“調(diào)研一下某領域的競品寫一份對比報告”這就是典型的 ReAct 多輪工具調(diào)用場景。如果是長時任務比如“每天監(jiān)控數(shù)據(jù)異常異常時自動排查并生成處置建議”這需要完整 Runtime因為涉及定時觸發(fā)、持久化狀態(tài)、并發(fā)執(zhí)行和失敗重試。第二個維度是交互模式。單輪問答、多輪對話、任務式執(zhí)行、人機協(xié)同這四種模式的架構(gòu)要求完全不同。任務式執(zhí)行要求 Agent 能自主決策那么工具權(quán)限、操作審計、安全邊界就變成核心問題。人機協(xié)同要求 Agent 能在不確定時停下來問人那么運行時需要有“掛起-恢復”機制。第三個維度是運行環(huán)境。跑在本地腳本里、跑在服務端 API 里、跑在云端工作流里這決定了你要不要做沙箱、怎么做隔離、怎么處理網(wǎng)絡權(quán)限。這三個維度想清楚之后架構(gòu)選型基本就收斂了。接下來我按“輕-中-重”三檔詳細拆解每一檔的實現(xiàn)方案和適用邊界。2. 輕量方案單次 LLM 調(diào)用的工程化增強2.1 結(jié)構(gòu)化輸出的關鍵技巧JSON Mode、函數(shù)調(diào)用與輸出校驗先說最輕的一檔。你可能只需要一次 LLM 調(diào)用但生產(chǎn)環(huán)境里“一次調(diào)用”遠不是“把 Prompt 扔給模型”那么簡單。要做對結(jié)構(gòu)化輸出核心是三個技巧。JSON Mode 是基礎。現(xiàn)在的模型基本都支持約束輸出為合法 JSON這能省掉大量“從文本里提取結(jié)果”的臟活。但注意JSON Mode 只保證“是合法 JSON”不保證“是你想要的 JSON”。字段名可能漂移、枚舉值可能不在你定義的范圍內(nèi)所以一定要在請求里用response_format之類的參數(shù)顯式聲明而不是在 Prompt 里“期望”它輸出 JSON。函數(shù)調(diào)用Function Calling是更穩(wěn)的方式。對我來說與其讓模型自由發(fā)揮生成 JSON不如定義好函數(shù)簽名讓模型輸出“我要調(diào)用這個函數(shù)參數(shù)是這些”。這種方式本質(zhì)上是把“結(jié)構(gòu)化輸出”變成了“參數(shù)填充”模型的準確率會高很多。舉個例子定義一個extract_contract_clauses(text: str, clause_types: List[str]) - List[Clause]函數(shù)模型會嚴格按參數(shù)約束輸出。輸出校驗這步絕對不能省而且要在架構(gòu)上設成強制關卡。我見過太多人省了這步導致下游解析崩潰。我的做法是拿到模型輸出后先做 JSON Schema 校驗再做業(yè)務規(guī)則校驗比如枚舉值是否合法、日期格式是否正確。校驗失敗就自動重試重試時把校驗錯誤信息回傳給模型。這個“校驗-失敗-回傳-重試”的閉環(huán)是輕量方案里性價比最高的一環(huán)。2.2 輕量方案的工具調(diào)用落地沒有框架也能跑通 ReAct 雛形很多人以為工具調(diào)用必須上框架其實不然。最樸素的 ReAct 循環(huán)幾行代碼就能跑通關鍵是設計好“循環(huán)終止條件”和“工具注冊機制”。核心數(shù)據(jù)結(jié)構(gòu)是消息列表。每輪循環(huán)把系統(tǒng)提示、歷史消息、工具結(jié)果依次追加到消息列表里再把整個列表發(fā)給模型。模型要么返回最終答案要么返回“要調(diào)用某某工具參數(shù)是什么”。程序解析出工具調(diào)用意圖后在本地注冊表里查找對應函數(shù)執(zhí)行把結(jié)果轉(zhuǎn)成一條tool角色消息繼續(xù)下一輪循環(huán)。循環(huán)終止條件要設置三層防線。第一層是模型明確返回最終答案自然終止。第二層是達到最大迭代次數(shù)比如 10 輪強制終止并通知用戶“任務未完成可能超出模型能力邊界了”。第三層是超時保護整個循環(huán)設定一個時間上限防止某些工具調(diào)用卡死或模型陷入死循環(huán)。這三層防線缺一不可否則生產(chǎn)環(huán)境里你會被各種邊緣情況折磨。工具注冊機制上我推薦用裝飾器模式把“函數(shù)實現(xiàn)”和“函數(shù)描述”綁定在一起。一個工具函數(shù)配上它的名稱、描述、參數(shù) JSON Schema注冊進全局字典。模型看到的工具列表就是這份字典的推導結(jié)果實際執(zhí)行時也是從字典里查函數(shù)。這樣增刪工具只改一處不會出現(xiàn)“模型能調(diào)用但程序找不到函數(shù)”的尷尬情況。2.3 什么情況下該止步于“輕量方案”輕量方案的適用邊界我的判斷標準有三個任務步驟不超過 3-5 步、狀態(tài)變化不復雜、不需要長時間后臺運行。比如做一個“工單自動分類助手”輸入工單文本輸出類別、優(yōu)先級、處理建議這用輕量方案就非常合適。但如果你想做“工單自動處理助手”需要查知識庫、調(diào)內(nèi)部系統(tǒng)、依據(jù)結(jié)果做決策這就超出輕量方案的能力范圍了。還有一個容易被忽略的信號當你的工具數(shù)量超過 10 個、一輪任務中每個 Agent 平均要調(diào)用 3 次以上工具時手寫循環(huán)開始變得不可維護。不是說你寫不了而是錯誤處理、上下文管理、日志追蹤這些橫切邏輯會讓你疲于奔命。這時候應該考慮上框架或者自己搭一個更完整的運行時骨架。3. 中量方案框架選型與 ReAct 循環(huán)的完整落地3.1 主流開源框架的三條技術(shù)路線如果你需要更完整的 Agent 能力又不打算從零造輪子主流開源框架基本可以歸為三條技術(shù)路線。我這里不提具體品牌只講它們代表的架構(gòu)思想。第一條是聲明式工作流路線。你用配置文件或代碼聲明“先做 A再做 B如果 C 則跳到 D”每個節(jié)點可以是 LLM 調(diào)用、工具調(diào)用或條件分支。優(yōu)點是流程確定性強、可觀測性好、狀態(tài)管理簡單適合業(yè)務流程相對固定的場景比如客服工單處理、數(shù)據(jù)處理管線。缺點是靈活性受限遇到計劃外路徑時需要人工補寫邏輯。第二條是自主決策路線。Agent 自己決定下一步做什么框架只提供工具、記憶和循環(huán)機制。這是 ReAct 范式的工程化實現(xiàn)適合開放性強、步驟不確定的場景比如智能調(diào)研、代碼生成與執(zhí)行、復雜問題拆解。優(yōu)點是非常靈活缺點是流程不可預知需要更多安全護欄和評估手段。第三條是多智能體協(xié)作路線。多個 Agent 各司其職有的負責規(guī)劃、有的負責執(zhí)行、有的負責審查通過消息傳遞協(xié)作完成任務。適合任務復雜度高、需要角色分工的場景。但我要潑一盆冷水多智能體不是銀彈通信協(xié)議、任務分配、死鎖檢測都是新增的復雜度業(yè)務沒到那個體量的時候單 Agent 加好工具往往比多 Agent 更穩(wěn)定。3.2 撐起一個 ReAct 循環(huán)的最小運行時架構(gòu)不管用哪條路線一個完整的 ReAct 循環(huán)都需要六個基礎組件我把它們稱為“最小運行時架構(gòu)”。模型網(wǎng)關統(tǒng)一封裝不同模型提供方的調(diào)用接口支持超時、重試、限流上下文管理器負責維護消息上下文、截斷策略、核心信息注入工具注冊表與執(zhí)行器管理工具元數(shù)據(jù)執(zhí)行工具調(diào)用并返回結(jié)構(gòu)化結(jié)果循環(huán)控制器調(diào)度“思考-行動-觀察”的迭代執(zhí)行終止策略記憶模塊管理短期會話記憶和長期向量記憶事件總線與日志記錄每個環(huán)節(jié)的輸入輸出方便追蹤和評估這里我想重點展開上下文管理器因為它是在實操里頭號翻車點。ReAct 循環(huán)里每輪工具結(jié)果都要拼進消息列表幾輪之后 Token 數(shù)就上去了。如果不做管理輕則上下文超限重則模型注意力被舊消息稀釋表現(xiàn)斷崖式下降。我常用的策略是三段式固定不變的系統(tǒng)提示放最前面最近 N 輪對話和工具結(jié)果放中間當前正在處理的任務指令放最后。超長歷史做摘要壓縮摘要有損所以只壓縮“已經(jīng)完成”的輪次當前輪次永遠保留完整信息。3.3 框架選型的判斷清單不要因為“熱”就選我這些年幫人看過不少選型方案也自己經(jīng)歷過反復橫跳最后提煉出一張判斷清單照著打一遍分基本不會選錯。第一項是社區(qū)活躍度?？醋罱齻€月有沒有持續(xù)發(fā)版、Issue 響應速度如何、文檔是否有人維護。開源框架如果社區(qū)死了你就是在給自己埋坑。第二項是協(xié)議規(guī)范性。重點看它是否遵循標準的工具調(diào)用協(xié)議、消息格式標準?？蚣軆?nèi)部的抽象可以自定義但對外接模型、接工具的協(xié)議最好符合通用標準否則你將被綁定遷移成本極高。第三項是可觀測性?？催\行時是否暴露了完整的 trace 信息、每個節(jié)點的輸入輸出是否可導出。Agent 應用與普通后端應用不一樣模型輸出的不確定性導致 bug 難以復現(xiàn)沒有好的可觀測性線上問題你將無從下手。第四項是擴展成本。不要看 Demo 跑得多快要看“加一個自定義工具要改幾個文件”“換一個模型服務商要動哪些代碼”“流式輸出支持得怎么樣”。這些才是日常開發(fā)的真實成本。4. 重量方案完整 Harness Runtime 的設計與實現(xiàn)4.1 Harness Runtime 的核心職責安全、穩(wěn)定、可控當你的 Agent 要跑長時任務、并發(fā)執(zhí)行、調(diào)用外部系統(tǒng)時就需要一個完整的 Harness Runtime。它本質(zhì)上是一個“專為 Agent 設計的執(zhí)行環(huán)境”核心職責用六個字概括安全、穩(wěn)定、可控。先講安全。Agent 執(zhí)行工具時可能觸發(fā)外部命令、訪問文件系統(tǒng)、調(diào)內(nèi)部 API、甚至寫數(shù)據(jù)庫。每一條都是風險點。我的做法是分級純函數(shù)工具走白名單機制文件操作走沙箱目錄命令執(zhí)行走獨立容器或子進程網(wǎng)絡請求走受控代理。再講穩(wěn)定。長時任務意味著進程可能崩潰、網(wǎng)絡可能斷、模型可能超時所以運行時必須要有斷點持久化和自動重試。狀態(tài)快照每隔一段時間落一次盤重啟后從最近的快照恢復。然后是可控。運行時必須暴露完整的控制接口包括暫停、恢復、取消、注入人工消息。當 Agent 在不確定時應該停下問人運行時就要能掛起任務等人回復后繼續(xù)跑。這個“人機協(xié)同”能力是完整 Runtime 區(qū)別于普通循環(huán)腳本的最大標志。4.2 調(diào)度與執(zhí)行單元任務隊列、沙箱與資源限制完整 Runtime 里我建議拋棄“一次任務對應一個進程”的樸素模型改成“任務隊列加執(zhí)行槽”的設計。任務進隊列由調(diào)度器按優(yōu)先級和資源空閑度分發(fā)給執(zhí)行單元每個執(zhí)行單元對應一個獨立的 Agent 運行實例。執(zhí)行單元內(nèi)部有獨立的 Token 配額、時間配額、內(nèi)存配額。這樣設計的好處是多個任務可以并發(fā)而不互相干擾單個任務跑飛了不至于拖垮整個系統(tǒng)。沙箱這塊是執(zhí)行單元的基石我用三層隔離來搭。第一層是容器級隔離跑不可信代碼時用第二層是進程級隔離跑可信但可能有 bug 的代碼時用限制 CPU、內(nèi)存和運行時長第三層是環(huán)境級隔離給 Agent 一個專屬的臨時工作目錄。三層隔離的觸發(fā)邏輯是看工具的風險等級。只讀操作不需要沙箱寫文件操作進工作目錄執(zhí)行代碼進進程級隔離需要網(wǎng)絡操作的則進容器級隔離。資源限制不只在執(zhí)行側(cè)模型調(diào)用側(cè)也要限。我踩過一個大坑Agent 循環(huán)里某一步傳了太多內(nèi)容導致模型響應超時程序不對超時做任何處理整個任務卡死既不報錯也不退出。后來我在模型網(wǎng)關上加了響應時間監(jiān)控超時即中斷本輪把超時信息作為工具結(jié)果回傳讓模型自己決定是精簡輸入還是換一種處理方式。4.3 狀態(tài)持久化與斷點恢復快照設計狀態(tài)持久化是完整 Runtime 與腳本循環(huán)之間的一道分水嶺。腳本循環(huán)的問題在于狀態(tài)都存在內(nèi)存里進程一掛就什么都沒了。完整 Runtime 則必須把狀態(tài)外置。我設計的快照分三層。第一層是會話快照保存消息歷史、任務描述、上下文狀態(tài)。第二層是進度快照保存當前執(zhí)行到哪個環(huán)節(jié)、中間結(jié)果、依賴的工具調(diào)用記錄。第三層是數(shù)據(jù)快照保存 Agent 在沙箱里產(chǎn)生的文件變更。三層快照分開存恢復時按需加載?？煺疹l率不是越高越好。我試過每輪循環(huán)都落盤結(jié)果 IO 開銷大得驚人長任務的性能被拖垮了。后來改成“關鍵節(jié)點落盤”策略工具調(diào)用前后、生成最終答案前、收到人工指令時這三個節(jié)點必須落盤其他中間狀態(tài)只記內(nèi)存這樣既保證了崩潰恢復的最小損失又不會讓性能崩掉?；謴土鞒桃埠苡兄v究。原則上沒有銀彈我一般分兩級先恢復到最近的會話快照讓 Agent 重新加載上下文繼續(xù)跑如果進度快照顯示某步工具調(diào)用已經(jīng)執(zhí)行完但結(jié)果沒來得及保存就標記該步驟為“可重放”用冪等設計避免重復執(zhí)行產(chǎn)生副作用。4.4 人機協(xié)同與可觀測性Runtime 的“駕駛艙”最后一個關鍵模塊是“駕駛艙”。我認為一個成熟 Runtime 必須具備兩個駕駛艙能力人機協(xié)同接口和全鏈路可觀測面板。人機協(xié)同接口解決的是“Agent 不確定時怎么辦”的問題。我實現(xiàn)了一個ask_human工具Agent 在決策樹里遇到低置信度分支時調(diào)用它運行時收到后把任務狀態(tài)標記為waiting_human暫停繼續(xù)執(zhí)行同時把需要人決策的問題和可選方案推送給前端。用戶確認后選擇結(jié)果作為工具返回值繼續(xù)推進。這里有一個設計細節(jié)等待人工響應時任務要支持超時自動降級比如 24 小時無人響應則執(zhí)行默認策略避免任務無限期掛起?？捎^測面板則是給開發(fā)者和運維人員用的。我強烈建議運行時從第一行代碼就埋點而不是事后補。每條鏈路至少要記錄模型調(diào)用的輸入輸出 Token 數(shù)、單輪延遲、工具執(zhí)行耗時和結(jié)果摘要、循環(huán)輪次、狀態(tài)轉(zhuǎn)移事件。有了這些數(shù)據(jù)你才能回答“這個 Agent 為什么這么慢”“它為什么在這一步反復重試”“哪個工具調(diào)用最不可靠”。我見過不少團隊在 Agent 上線之后兩眼一抹黑出了問題只能“重新跑一遍試試”。在 Agent 這種充滿不確定性的系統(tǒng)里沒有可觀測性相當于盲飛。要我說可觀測性建設投入的精力至少應該占 Runtime 開發(fā)的四成。4.5 演進路線從輕到重的平滑遷移最后聊一個很現(xiàn)實的問題我已經(jīng)用輕量方案跑通了業(yè)務怎么平滑遷移到完整 Runtime而不是推倒重來我的建議是圍繞工具層做兼容圍繞調(diào)用層做抽象。也就是說工具函數(shù)本身不要動只把“工具注冊、工具調(diào)用、結(jié)果回傳”這層邏輯封裝成標準接口。這樣輕量方案里的工具代碼可以直接復用。遷移過程分三步走。第一步先把工具調(diào)用層抽成獨立的服務接口讓應用層和模型層都通過 HTTP 或內(nèi)部 RPC 調(diào)用它。第二步引入循環(huán)控制器把“手寫 while 循環(huán)”替換成框架或自研輪子原有消息結(jié)構(gòu)保持兼容。第三步你要逐步加上持久化、沙箱和可觀測性。這里說一個實操里的細節(jié)遷移時舊任務還在線上跑新老系統(tǒng)會有一段時間并行。我建議做一層“適配器”讓老代碼看起來像新運行時的一個執(zhí)行單元而不是要求所有任務立刻切換。這樣你能先用一小部分流量驗證新架構(gòu)的穩(wěn)定性再逐步放大流量風險會小得多。5. 典型場景案例拆解不同架構(gòu)方案的落地對照5.1 案例一客服工單自動分類系統(tǒng)輕量方案某電商公司的客服團隊每天收到上千個工單需要自動分類、打標、轉(zhuǎn)派。這個場景我用的是輕量方案加結(jié)構(gòu)化輸出。具體做法是定義好分類枚舉、優(yōu)先級枚舉、轉(zhuǎn)派部門枚舉后把這些枚舉和字段描述直接放進函數(shù)簽名里讓模型走 Function Calling 路徑輸出。接了一層 JSON Schema 校驗和失敗重試后準確率從最初的 92% 提到了 97% 左右。這個項目從頭到尾沒有引入任何 Agent 框架沒有 ReAct 循環(huán)上線后運維也很簡單。日志里只需要記錄“輸入工單、模型原始響應、校驗結(jié)果、最終輸出”四樣東西排查問題非常輕松。如果你也遇到類似需求我的建議就是別被“AI Agent”這個詞忽悠了能一次調(diào)用解決的事情就不要往復雜里做。5.2 案例二智能調(diào)研助手中量方案另一個做內(nèi)部運營的朋友要做“智能調(diào)研助手”輸入一個主題Agent 自動搜索、閱讀、整理、輸出調(diào)研報告。這就是典型的中量方案場景。我?guī)退ǖ氖且粋€ ReAct 循環(huán)加少量工具搜索引擎工具、網(wǎng)頁正文提取工具、要點歸納工具。循環(huán)控制設定最大 15 輪每輪做完一個子任務就更新“調(diào)研筆記”最終把筆記匯總成報告。上下文管理用了摘要壓縮策略把已完成的搜索結(jié)果壓縮成要點避免 Token 爆炸。實測下來的坑是搜索引擎返回的噪音信息太多Agent 容易被無關內(nèi)容帶偏。后面我加了一個“信息可信度評分”前置步驟讓模型先對搜索結(jié)果做一輪相關性過濾再進入正文提取。這個優(yōu)化之后報告質(zhì)量提升非常明顯。5.3 案例三后臺數(shù)據(jù)分析與自動監(jiān)控 Agent重量方案第三個案例是“后臺數(shù)據(jù)分析與自動監(jiān)控 Agent”需要定時觸發(fā)、數(shù)據(jù)異常檢測、自動排查歸因、生成處置建議還要支持人工干預。這個必須上完整 Harness Runtime。架構(gòu)上采用任務隊列加多執(zhí)行單元設計。監(jiān)控任務每五分鐘觸發(fā)一批每個異常事件生成一個子任務進入隊列由多個執(zhí)行單元并發(fā)處理。每個執(zhí)行單元里有獨立的模型 Token 配額和沙箱工作目錄。狀態(tài)快照在每個異常事件的關鍵分析節(jié)點落盤系統(tǒng)重啟后可以從中斷處繼續(xù)排查。人機協(xié)同這塊是這樣用的當 Agent 判斷異?？赡苁侵卮蠊收蠒r會調(diào)用ask_human工具把已經(jīng)收集到的證據(jù)鏈、推測原因、可選處置方案推給值班人員等待確認后再繼續(xù)執(zhí)行。值班人員在面板上點一下“按方案一處置”Agent 就繼續(xù)往下做。這個設計極大提升了運維團隊對 Agent 的信任度。6. 常見問題與排查技巧實錄6.1 工具調(diào)用死循環(huán)不是模型的問題是控制邏輯的問題Agent 在工具調(diào)用里陷入死循環(huán)是我被問得最多的問題。現(xiàn)象是 Agent 反復調(diào)用同一個工具每次都拿到相似結(jié)果然后繼續(xù)調(diào)用直到達到最大輪數(shù)。排查思路先別急著懷疑模型。我第一步是打開 trace 日志看每輪模型的思考內(nèi)容。如果思考內(nèi)容顯示“我要再調(diào)用一次確認結(jié)果”說明模型陷入了“確認偏誤”這時候應該做的是在 Prompts 里加一條規(guī)則“如果上一輪工具結(jié)果已經(jīng)足夠支持決策不要重復調(diào)用”。如果思考內(nèi)容顯示“調(diào)用結(jié)果不符合預期嘗試換一種方式”但工具列表里沒有更合適的工具說明工具覆蓋度不夠需要補工具。實操中最管用的防御是多設一道“重復調(diào)用檢測”同一工具連續(xù)調(diào)用超過三次且參數(shù)基本一致時循環(huán)控制器主動插入一條提醒消息告訴模型“您已經(jīng)調(diào)用過該工具且結(jié)果未變化請基于已有信息繼續(xù)推進”。實測效果立竿見影。6.2 上下文越權(quán)與 Token 爆炸三招控制長期運行內(nèi)存長時任務跑久了最后崩潰在 Token 超限上這是重量方案里最典型的翻車場景。我的經(jīng)驗是三個招配合用。第一招是分層摘要。系統(tǒng)提示和核心任務指令永遠完整保留工具執(zhí)行結(jié)果只保留最近兩輪的完整內(nèi)容再往前的統(tǒng)一壓縮成一句話摘要。第二招是上下文裁剪計劃。每五輪循環(huán)檢查一次 Token 總量超過閾值就觸發(fā)一次“歷史壓縮”壓縮過程本身也是一次模型調(diào)用因此要把壓縮結(jié)果標記為“已壓縮”避免下次再被壓縮。第三招是主動遺忘。與當前任務無關的歷史消息直接丟棄只保留摘要。這三招配合下來我最長跑過一個 40 輪的工具調(diào)用任務Token 消耗穩(wěn)定在可控區(qū)間。6.3 工具調(diào)用副作用與并發(fā)安全冪等設計和鎖工具調(diào)用的副作用問題在并發(fā)場景下會放大。比如一個 Agent 在寫數(shù)據(jù)庫另一個 Agent 在刪除數(shù)據(jù)兩個的決策依據(jù)可能互相沖突。我建議在兩個層面做防護。工具層面凡是寫操作統(tǒng)一要求冪等通過請求 ID 去重。運行時層面每個 Agent 的沙箱和外部資源訪問通道做隔離共享資源訪問必須走帶鎖的 API 網(wǎng)關。有一次我排查了半天最后發(fā)現(xiàn)是兩個并行 Agent 同時在處理同一個業(yè)務對象產(chǎn)生覆蓋寫加一把分布式鎖就好了。6.4 常見問題速查表問題現(xiàn)象排查方向推薦解法模型反復調(diào)用同一工具檢查思考內(nèi)容與工具覆蓋度重復調(diào)用檢測 提醒消息Token 超限崩潰檢查歷史消息累積量分層摘要 裁剪計劃任務中斷后無法恢復檢查快照落盤頻率與內(nèi)容關鍵節(jié)點落盤策略并行 Agent 互相干擾檢查共享資源訪問冪等設計 分布式鎖模型輸出不穩(wěn)定檢查校驗與重試鏈路校驗失敗回傳模型重試線上問題無法復現(xiàn)檢查鏈路追蹤完整性埋點從第一行代碼開始6.5 最后分享一個我的排障習慣排查 Agent 線上問題我從來不看應用日志里的 Error 堆棧而是先看 trace 鏈路里“最后一步成功的工具調(diào)用”是什么。Agent 問題的根因幾乎總在“某一步我們以為成功的操作實際產(chǎn)出了錯誤結(jié)果”而錯誤結(jié)果被當作正常輸入喂給了下一步。順著鏈路回放通常很快能定位到問題點。個人體會是Agent 架構(gòu)選型這件事最怕的不是選錯而是不知道自己為什么選。你把需求維度拆清楚把每一檔方案的邊界搞清楚把運行時該有的骨架搭起來剩下的無非是在實踐中持續(xù)調(diào)優(yōu)。我做的這三個案例從輕到重都跑通過生產(chǎn)環(huán)境過程中踩過的坑遠比寫出來的多但架構(gòu)上只要大方向?qū)α诵栴}都好修。希望這份從實踐里沉淀的方案能幫你少走一些我沒避開的彎路。 AI Agent架構(gòu)選型：從LLM調(diào)用到Harness Runtime的落地指南
1. 架構(gòu)分層從一次 LLM 調(diào)用到完整 Harness Runtime到底在選什么1.1 先把問題拆開你需要的不是“選框架”而是“選復雜度”很多人一上來就問“AI Agent 架構(gòu)到底用哪個框架好”我覺得這個問題本身就問偏了。真正要回答的不是“哪個好”而是“你現(xiàn)在需要多復雜”。一次 LLM 調(diào)用、一個 ReAct 循環(huán)、一套完整 Harness Runtime這三者之間的差距比想象中大得多。我見過不少團隊踩同一個坑剛跑通一個帶工具調(diào)用的 Demo就急著上全套 Agent 運行時結(jié)果被上下文管理、記憶持久化、沙箱執(zhí)行、可觀測性這些基礎設施拖垮。反過來也有團隊在業(yè)務已經(jīng)需要并行 Agent、長時任務、斷點恢復時還在手寫while True: llm.call()的死循環(huán)腳本導致任務一跑長就崩、一并發(fā)就亂。先把概念對齊。我這里說的“一次 LLM 調(diào)用”指的是單輪請求-響應模型根據(jù) System Prompt 直接產(chǎn)出結(jié)果不涉及工具、循環(huán)和狀態(tài)。這是最基礎的范式適合分類、抽取、簡單問答。“從一次調(diào)用到完整 Harness Runtime”中間其實隔了好幾層工具調(diào)用層模型輸出結(jié)構(gòu)化指令由程序解析并執(zhí)行外部函數(shù)循環(huán)控制層Agent 在“思考-行動-觀察”之間反復迭代直到任務完成狀態(tài)管理層維護會話上下文、任務進度、中間結(jié)果支持暫停和恢復運行時層負責沙箱、并發(fā)調(diào)度、安全策略、資源限制、可觀測性也就是題名里的 Harness Runtime所以“AI Agent 架構(gòu)怎么選”這個問題的實質(zhì)是你要在哪一層投入復雜度這決定了后續(xù)所有的技術(shù)選型。1.2 確定需求的三個關鍵判斷任務類型、交互模式、運行環(huán)境我一般會從三個維度判斷該落在哪一層比直接看框架榜單靠譜得多。第一個維度是任務類型。如果是短任務比如“從這段合同里抽取違約條款并結(jié)構(gòu)化輸出”一次調(diào)用加 JSON Mode 就夠了壓根不需要 Agent 架構(gòu)。如果是多步驟任務比如“調(diào)研一下某領域的競品寫一份對比報告”這就是典型的 ReAct 多輪工具調(diào)用場景。如果是長時任務比如“每天監(jiān)控數(shù)據(jù)異常異常時自動排查并生成處置建議”這需要完整 Runtime因為涉及定時觸發(fā)、持久化狀態(tài)、并發(fā)執(zhí)行和失敗重試。第二個維度是交互模式。單輪問答、多輪對話、任務式執(zhí)行、人機協(xié)同這四種模式的架構(gòu)要求完全不同。任務式執(zhí)行要求 Agent 能自主決策那么工具權(quán)限、操作審計、安全邊界就變成核心問題。人機協(xié)同要求 Agent 能在不確定時停下來問人那么運行時需要有“掛起-恢復”機制。第三個維度是運行環(huán)境。跑在本地腳本里、跑在服務端 API 里、跑在云端工作流里這決定了你要不要做沙箱、怎么做隔離、怎么處理網(wǎng)絡權(quán)限。這三個維度想清楚之后架構(gòu)選型基本就收斂了。接下來我按“輕-中-重”三檔詳細拆解每一檔的實現(xiàn)方案和適用邊界。2. 輕量方案單次 LLM 調(diào)用的工程化增強2.1 結(jié)構(gòu)化輸出的關鍵技巧JSON Mode、函數(shù)調(diào)用與輸出校驗先說最輕的一檔。你可能只需要一次 LLM 調(diào)用但生產(chǎn)環(huán)境里“一次調(diào)用”遠不是“把 Prompt 扔給模型”那么簡單。要做對結(jié)構(gòu)化輸出核心是三個技巧。JSON Mode 是基礎。現(xiàn)在的模型基本都支持約束輸出為合法 JSON這能省掉大量“從文本里提取結(jié)果”的臟活。但注意JSON Mode 只保證“是合法 JSON”不保證“是你想要的 JSON”。字段名可能漂移、枚舉值可能不在你定義的范圍內(nèi)所以一定要在請求里用response_format之類的參數(shù)顯式聲明而不是在 Prompt 里“期望”它輸出 JSON。函數(shù)調(diào)用Function Calling是更穩(wěn)的方式。對我來說與其讓模型自由發(fā)揮生成 JSON不如定義好函數(shù)簽名讓模型輸出“我要調(diào)用這個函數(shù)參數(shù)是這些”。這種方式本質(zhì)上是把“結(jié)構(gòu)化輸出”變成了“參數(shù)填充”模型的準確率會高很多。舉個例子定義一個extract_contract_clauses(text: str, clause_types: List[str]) - List[Clause]函數(shù)模型會嚴格按參數(shù)約束輸出。輸出校驗這步絕對不能省而且要在架構(gòu)上設成強制關卡。我見過太多人省了這步導致下游解析崩潰。我的做法是拿到模型輸出后先做 JSON Schema 校驗再做業(yè)務規(guī)則校驗比如枚舉值是否合法、日期格式是否正確。校驗失敗就自動重試重試時把校驗錯誤信息回傳給模型。這個“校驗-失敗-回傳-重試”的閉環(huán)是輕量方案里性價比最高的一環(huán)。2.2 輕量方案的工具調(diào)用落地沒有框架也能跑通 ReAct 雛形很多人以為工具調(diào)用必須上框架其實不然。最樸素的 ReAct 循環(huán)幾行代碼就能跑通關鍵是設計好“循環(huán)終止條件”和“工具注冊機制”。核心數(shù)據(jù)結(jié)構(gòu)是消息列表。每輪循環(huán)把系統(tǒng)提示、歷史消息、工具結(jié)果依次追加到消息列表里再把整個列表發(fā)給模型。模型要么返回最終答案要么返回“要調(diào)用某某工具參數(shù)是什么”。程序解析出工具調(diào)用意圖后在本地注冊表里查找對應函數(shù)執(zhí)行把結(jié)果轉(zhuǎn)成一條tool角色消息繼續(xù)下一輪循環(huán)。循環(huán)終止條件要設置三層防線。第一層是模型明確返回最終答案自然終止。第二層是達到最大迭代次數(shù)比如 10 輪強制終止并通知用戶“任務未完成可能超出模型能力邊界了”。第三層是超時保護整個循環(huán)設定一個時間上限防止某些工具調(diào)用卡死或模型陷入死循環(huán)。這三層防線缺一不可否則生產(chǎn)環(huán)境里你會被各種邊緣情況折磨。工具注冊機制上我推薦用裝飾器模式把“函數(shù)實現(xiàn)”和“函數(shù)描述”綁定在一起。一個工具函數(shù)配上它的名稱、描述、參數(shù) JSON Schema注冊進全局字典。模型看到的工具列表就是這份字典的推導結(jié)果實際執(zhí)行時也是從字典里查函數(shù)。這樣增刪工具只改一處不會出現(xiàn)“模型能調(diào)用但程序找不到函數(shù)”的尷尬情況。2.3 什么情況下該止步于“輕量方案”輕量方案的適用邊界我的判斷標準有三個任務步驟不超過 3-5 步、狀態(tài)變化不復雜、不需要長時間后臺運行。比如做一個“工單自動分類助手”輸入工單文本輸出類別、優(yōu)先級、處理建議這用輕量方案就非常合適。但如果你想做“工單自動處理助手”需要查知識庫、調(diào)內(nèi)部系統(tǒng)、依據(jù)結(jié)果做決策這就超出輕量方案的能力范圍了。還有一個容易被忽略的信號當你的工具數(shù)量超過 10 個、一輪任務中每個 Agent 平均要調(diào)用 3 次以上工具時手寫循環(huán)開始變得不可維護。不是說你寫不了而是錯誤處理、上下文管理、日志追蹤這些橫切邏輯會讓你疲于奔命。這時候應該考慮上框架或者自己搭一個更完整的運行時骨架。3. 中量方案框架選型與 ReAct 循環(huán)的完整落地3.1 主流開源框架的三條技術(shù)路線如果你需要更完整的 Agent 能力又不打算從零造輪子主流開源框架基本可以歸為三條技術(shù)路線。我這里不提具體品牌只講它們代表的架構(gòu)思想。第一條是聲明式工作流路線。你用配置文件或代碼聲明“先做 A再做 B如果 C 則跳到 D”每個節(jié)點可以是 LLM 調(diào)用、工具調(diào)用或條件分支。優(yōu)點是流程確定性強、可觀測性好、狀態(tài)管理簡單適合業(yè)務流程相對固定的場景比如客服工單處理、數(shù)據(jù)處理管線。缺點是靈活性受限遇到計劃外路徑時需要人工補寫邏輯。第二條是自主決策路線。Agent 自己決定下一步做什么框架只提供工具、記憶和循環(huán)機制。這是 ReAct 范式的工程化實現(xiàn)適合開放性強、步驟不確定的場景比如智能調(diào)研、代碼生成與執(zhí)行、復雜問題拆解。優(yōu)點是非常靈活缺點是流程不可預知需要更多安全護欄和評估手段。第三條是多智能體協(xié)作路線。多個 Agent 各司其職有的負責規(guī)劃、有的負責執(zhí)行、有的負責審查通過消息傳遞協(xié)作完成任務。適合任務復雜度高、需要角色分工的場景。但我要潑一盆冷水多智能體不是銀彈通信協(xié)議、任務分配、死鎖檢測都是新增的復雜度業(yè)務沒到那個體量的時候單 Agent 加好工具往往比多 Agent 更穩(wěn)定。3.2 撐起一個 ReAct 循環(huán)的最小運行時架構(gòu)不管用哪條路線一個完整的 ReAct 循環(huán)都需要六個基礎組件我把它們稱為“最小運行時架構(gòu)”。模型網(wǎng)關統(tǒng)一封裝不同模型提供方的調(diào)用接口支持超時、重試、限流上下文管理器負責維護消息上下文、截斷策略、核心信息注入工具注冊表與執(zhí)行器管理工具元數(shù)據(jù)執(zhí)行工具調(diào)用并返回結(jié)構(gòu)化結(jié)果循環(huán)控制器調(diào)度“思考-行動-觀察”的迭代執(zhí)行終止策略記憶模塊管理短期會話記憶和長期向量記憶事件總線與日志記錄每個環(huán)節(jié)的輸入輸出方便追蹤和評估這里我想重點展開上下文管理器因為它是在實操里頭號翻車點。ReAct 循環(huán)里每輪工具結(jié)果都要拼進消息列表幾輪之后 Token 數(shù)就上去了。如果不做管理輕則上下文超限重則模型注意力被舊消息稀釋表現(xiàn)斷崖式下降。我常用的策略是三段式固定不變的系統(tǒng)提示放最前面最近 N 輪對話和工具結(jié)果放中間當前正在處理的任務指令放最后。超長歷史做摘要壓縮摘要有損所以只壓縮“已經(jīng)完成”的輪次當前輪次永遠保留完整信息。3.3 框架選型的判斷清單不要因為“熱”就選我這些年幫人看過不少選型方案也自己經(jīng)歷過反復橫跳最后提煉出一張判斷清單照著打一遍分基本不會選錯。第一項是社區(qū)活躍度?？醋罱齻€月有沒有持續(xù)發(fā)版、Issue 響應速度如何、文檔是否有人維護。開源框架如果社區(qū)死了你就是在給自己埋坑。第二項是協(xié)議規(guī)范性。重點看它是否遵循標準的工具調(diào)用協(xié)議、消息格式標準?？蚣軆?nèi)部的抽象可以自定義但對外接模型、接工具的協(xié)議最好符合通用標準否則你將被綁定遷移成本極高。第三項是可觀測性?？催\行時是否暴露了完整的 trace 信息、每個節(jié)點的輸入輸出是否可導出。Agent 應用與普通后端應用不一樣模型輸出的不確定性導致 bug 難以復現(xiàn)沒有好的可觀測性線上問題你將無從下手。第四項是擴展成本。不要看 Demo 跑得多快要看“加一個自定義工具要改幾個文件”“換一個模型服務商要動哪些代碼”“流式輸出支持得怎么樣”。這些才是日常開發(fā)的真實成本。4. 重量方案完整 Harness Runtime 的設計與實現(xiàn)4.1 Harness Runtime 的核心職責安全、穩(wěn)定、可控當你的 Agent 要跑長時任務、并發(fā)執(zhí)行、調(diào)用外部系統(tǒng)時就需要一個完整的 Harness Runtime。它本質(zhì)上是一個“專為 Agent 設計的執(zhí)行環(huán)境”核心職責用六個字概括安全、穩(wěn)定、可控。先講安全。Agent 執(zhí)行工具時可能觸發(fā)外部命令、訪問文件系統(tǒng)、調(diào)內(nèi)部 API、甚至寫數(shù)據(jù)庫。每一條都是風險點。我的做法是分級純函數(shù)工具走白名單機制文件操作走沙箱目錄命令執(zhí)行走獨立容器或子進程網(wǎng)絡請求走受控代理。再講穩(wěn)定。長時任務意味著進程可能崩潰、網(wǎng)絡可能斷、模型可能超時所以運行時必須要有斷點持久化和自動重試。狀態(tài)快照每隔一段時間落一次盤重啟后從最近的快照恢復。然后是可控。運行時必須暴露完整的控制接口包括暫停、恢復、取消、注入人工消息。當 Agent 在不確定時應該停下問人運行時就要能掛起任務等人回復后繼續(xù)跑。這個“人機協(xié)同”能力是完整 Runtime 區(qū)別于普通循環(huán)腳本的最大標志。4.2 調(diào)度與執(zhí)行單元任務隊列、沙箱與資源限制完整 Runtime 里我建議拋棄“一次任務對應一個進程”的樸素模型改成“任務隊列加執(zhí)行槽”的設計。任務進隊列由調(diào)度器按優(yōu)先級和資源空閑度分發(fā)給執(zhí)行單元每個執(zhí)行單元對應一個獨立的 Agent 運行實例。執(zhí)行單元內(nèi)部有獨立的 Token 配額、時間配額、內(nèi)存配額。這樣設計的好處是多個任務可以并發(fā)而不互相干擾單個任務跑飛了不至于拖垮整個系統(tǒng)。沙箱這塊是執(zhí)行單元的基石我用三層隔離來搭。第一層是容器級隔離跑不可信代碼時用第二層是進程級隔離跑可信但可能有 bug 的代碼時用限制 CPU、內(nèi)存和運行時長第三層是環(huán)境級隔離給 Agent 一個專屬的臨時工作目錄。三層隔離的觸發(fā)邏輯是看工具的風險等級。只讀操作不需要沙箱寫文件操作進工作目錄執(zhí)行代碼進進程級隔離需要網(wǎng)絡操作的則進容器級隔離。資源限制不只在執(zhí)行側(cè)模型調(diào)用側(cè)也要限。我踩過一個大坑Agent 循環(huán)里某一步傳了太多內(nèi)容導致模型響應超時程序不對超時做任何處理整個任務卡死既不報錯也不退出。后來我在模型網(wǎng)關上加了響應時間監(jiān)控超時即中斷本輪把超時信息作為工具結(jié)果回傳讓模型自己決定是精簡輸入還是換一種處理方式。4.3 狀態(tài)持久化與斷點恢復快照設計狀態(tài)持久化是完整 Runtime 與腳本循環(huán)之間的一道分水嶺。腳本循環(huán)的問題在于狀態(tài)都存在內(nèi)存里進程一掛就什么都沒了。完整 Runtime 則必須把狀態(tài)外置。我設計的快照分三層。第一層是會話快照保存消息歷史、任務描述、上下文狀態(tài)。第二層是進度快照保存當前執(zhí)行到哪個環(huán)節(jié)、中間結(jié)果、依賴的工具調(diào)用記錄。第三層是數(shù)據(jù)快照保存 Agent 在沙箱里產(chǎn)生的文件變更。三層快照分開存恢復時按需加載?？煺疹l率不是越高越好。我試過每輪循環(huán)都落盤結(jié)果 IO 開銷大得驚人長任務的性能被拖垮了。后來改成“關鍵節(jié)點落盤”策略工具調(diào)用前后、生成最終答案前、收到人工指令時這三個節(jié)點必須落盤其他中間狀態(tài)只記內(nèi)存這樣既保證了崩潰恢復的最小損失又不會讓性能崩掉?；謴土鞒桃埠苡兄v究。原則上沒有銀彈我一般分兩級先恢復到最近的會話快照讓 Agent 重新加載上下文繼續(xù)跑如果進度快照顯示某步工具調(diào)用已經(jīng)執(zhí)行完但結(jié)果沒來得及保存就標記該步驟為“可重放”用冪等設計避免重復執(zhí)行產(chǎn)生副作用。4.4 人機協(xié)同與可觀測性Runtime 的“駕駛艙”最后一個關鍵模塊是“駕駛艙”。我認為一個成熟 Runtime 必須具備兩個駕駛艙能力人機協(xié)同接口和全鏈路可觀測面板。人機協(xié)同接口解決的是“Agent 不確定時怎么辦”的問題。我實現(xiàn)了一個ask_human工具Agent 在決策樹里遇到低置信度分支時調(diào)用它運行時收到后把任務狀態(tài)標記為waiting_human暫停繼續(xù)執(zhí)行同時把需要人決策的問題和可選方案推送給前端。用戶確認后選擇結(jié)果作為工具返回值繼續(xù)推進。這里有一個設計細節(jié)等待人工響應時任務要支持超時自動降級比如 24 小時無人響應則執(zhí)行默認策略避免任務無限期掛起?？捎^測面板則是給開發(fā)者和運維人員用的。我強烈建議運行時從第一行代碼就埋點而不是事后補。每條鏈路至少要記錄模型調(diào)用的輸入輸出 Token 數(shù)、單輪延遲、工具執(zhí)行耗時和結(jié)果摘要、循環(huán)輪次、狀態(tài)轉(zhuǎn)移事件。有了這些數(shù)據(jù)你才能回答“這個 Agent 為什么這么慢”“它為什么在這一步反復重試”“哪個工具調(diào)用最不可靠”。我見過不少團隊在 Agent 上線之后兩眼一抹黑出了問題只能“重新跑一遍試試”。在 Agent 這種充滿不確定性的系統(tǒng)里沒有可觀測性相當于盲飛。要我說可觀測性建設投入的精力至少應該占 Runtime 開發(fā)的四成。4.5 演進路線從輕到重的平滑遷移最后聊一個很現(xiàn)實的問題我已經(jīng)用輕量方案跑通了業(yè)務怎么平滑遷移到完整 Runtime而不是推倒重來我的建議是圍繞工具層做兼容圍繞調(diào)用層做抽象。也就是說工具函數(shù)本身不要動只把“工具注冊、工具調(diào)用、結(jié)果回傳”這層邏輯封裝成標準接口。這樣輕量方案里的工具代碼可以直接復用。遷移過程分三步走。第一步先把工具調(diào)用層抽成獨立的服務接口讓應用層和模型層都通過 HTTP 或內(nèi)部 RPC 調(diào)用它。第二步引入循環(huán)控制器把“手寫 while 循環(huán)”替換成框架或自研輪子原有消息結(jié)構(gòu)保持兼容。第三步你要逐步加上持久化、沙箱和可觀測性。這里說一個實操里的細節(jié)遷移時舊任務還在線上跑新老系統(tǒng)會有一段時間并行。我建議做一層“適配器”讓老代碼看起來像新運行時的一個執(zhí)行單元而不是要求所有任務立刻切換。這樣你能先用一小部分流量驗證新架構(gòu)的穩(wěn)定性再逐步放大流量風險會小得多。5. 典型場景案例拆解不同架構(gòu)方案的落地對照5.1 案例一客服工單自動分類系統(tǒng)輕量方案某電商公司的客服團隊每天收到上千個工單需要自動分類、打標、轉(zhuǎn)派。這個場景我用的是輕量方案加結(jié)構(gòu)化輸出。具體做法是定義好分類枚舉、優(yōu)先級枚舉、轉(zhuǎn)派部門枚舉后把這些枚舉和字段描述直接放進函數(shù)簽名里讓模型走 Function Calling 路徑輸出。接了一層 JSON Schema 校驗和失敗重試后準確率從最初的 92% 提到了 97% 左右。這個項目從頭到尾沒有引入任何 Agent 框架沒有 ReAct 循環(huán)上線后運維也很簡單。日志里只需要記錄“輸入工單、模型原始響應、校驗結(jié)果、最終輸出”四樣東西排查問題非常輕松。如果你也遇到類似需求我的建議就是別被“AI Agent”這個詞忽悠了能一次調(diào)用解決的事情就不要往復雜里做。5.2 案例二智能調(diào)研助手中量方案另一個做內(nèi)部運營的朋友要做“智能調(diào)研助手”輸入一個主題Agent 自動搜索、閱讀、整理、輸出調(diào)研報告。這就是典型的中量方案場景。我?guī)退ǖ氖且粋€ ReAct 循環(huán)加少量工具搜索引擎工具、網(wǎng)頁正文提取工具、要點歸納工具。循環(huán)控制設定最大 15 輪每輪做完一個子任務就更新“調(diào)研筆記”最終把筆記匯總成報告。上下文管理用了摘要壓縮策略把已完成的搜索結(jié)果壓縮成要點避免 Token 爆炸。實測下來的坑是搜索引擎返回的噪音信息太多Agent 容易被無關內(nèi)容帶偏。后面我加了一個“信息可信度評分”前置步驟讓模型先對搜索結(jié)果做一輪相關性過濾再進入正文提取。這個優(yōu)化之后報告質(zhì)量提升非常明顯。5.3 案例三后臺數(shù)據(jù)分析與自動監(jiān)控 Agent重量方案第三個案例是“后臺數(shù)據(jù)分析與自動監(jiān)控 Agent”需要定時觸發(fā)、數(shù)據(jù)異常檢測、自動排查歸因、生成處置建議還要支持人工干預。這個必須上完整 Harness Runtime。架構(gòu)上采用任務隊列加多執(zhí)行單元設計。監(jiān)控任務每五分鐘觸發(fā)一批每個異常事件生成一個子任務進入隊列由多個執(zhí)行單元并發(fā)處理。每個執(zhí)行單元里有獨立的模型 Token 配額和沙箱工作目錄。狀態(tài)快照在每個異常事件的關鍵分析節(jié)點落盤系統(tǒng)重啟后可以從中斷處繼續(xù)排查。人機協(xié)同這塊是這樣用的當 Agent 判斷異?？赡苁侵卮蠊收蠒r會調(diào)用ask_human工具把已經(jīng)收集到的證據(jù)鏈、推測原因、可選處置方案推給值班人員等待確認后再繼續(xù)執(zhí)行。值班人員在面板上點一下“按方案一處置”Agent 就繼續(xù)往下做。這個設計極大提升了運維團隊對 Agent 的信任度。6. 常見問題與排查技巧實錄6.1 工具調(diào)用死循環(huán)不是模型的問題是控制邏輯的問題Agent 在工具調(diào)用里陷入死循環(huán)是我被問得最多的問題。現(xiàn)象是 Agent 反復調(diào)用同一個工具每次都拿到相似結(jié)果然后繼續(xù)調(diào)用直到達到最大輪數(shù)。排查思路先別急著懷疑模型。我第一步是打開 trace 日志看每輪模型的思考內(nèi)容。如果思考內(nèi)容顯示“我要再調(diào)用一次確認結(jié)果”說明模型陷入了“確認偏誤”這時候應該做的是在 Prompts 里加一條規(guī)則“如果上一輪工具結(jié)果已經(jīng)足夠支持決策不要重復調(diào)用”。如果思考內(nèi)容顯示“調(diào)用結(jié)果不符合預期嘗試換一種方式”但工具列表里沒有更合適的工具說明工具覆蓋度不夠需要補工具。實操中最管用的防御是多設一道“重復調(diào)用檢測”同一工具連續(xù)調(diào)用超過三次且參數(shù)基本一致時循環(huán)控制器主動插入一條提醒消息告訴模型“您已經(jīng)調(diào)用過該工具且結(jié)果未變化請基于已有信息繼續(xù)推進”。實測效果立竿見影。6.2 上下文越權(quán)與 Token 爆炸三招控制長期運行內(nèi)存長時任務跑久了最后崩潰在 Token 超限上這是重量方案里最典型的翻車場景。我的經(jīng)驗是三個招配合用。第一招是分層摘要。系統(tǒng)提示和核心任務指令永遠完整保留工具執(zhí)行結(jié)果只保留最近兩輪的完整內(nèi)容再往前的統(tǒng)一壓縮成一句話摘要。第二招是上下文裁剪計劃。每五輪循環(huán)檢查一次 Token 總量超過閾值就觸發(fā)一次“歷史壓縮”壓縮過程本身也是一次模型調(diào)用因此要把壓縮結(jié)果標記為“已壓縮”避免下次再被壓縮。第三招是主動遺忘。與當前任務無關的歷史消息直接丟棄只保留摘要。這三招配合下來我最長跑過一個 40 輪的工具調(diào)用任務Token 消耗穩(wěn)定在可控區(qū)間。6.3 工具調(diào)用副作用與并發(fā)安全冪等設計和鎖工具調(diào)用的副作用問題在并發(fā)場景下會放大。比如一個 Agent 在寫數(shù)據(jù)庫另一個 Agent 在刪除數(shù)據(jù)兩個的決策依據(jù)可能互相沖突。我建議在兩個層面做防護。工具層面凡是寫操作統(tǒng)一要求冪等通過請求 ID 去重。運行時層面每個 Agent 的沙箱和外部資源訪問通道做隔離共享資源訪問必須走帶鎖的 API 網(wǎng)關。有一次我排查了半天最后發(fā)現(xiàn)是兩個并行 Agent 同時在處理同一個業(yè)務對象產(chǎn)生覆蓋寫加一把分布式鎖就好了。6.4 常見問題速查表問題現(xiàn)象排查方向推薦解法模型反復調(diào)用同一工具檢查思考內(nèi)容與工具覆蓋度重復調(diào)用檢測 提醒消息Token 超限崩潰檢查歷史消息累積量分層摘要 裁剪計劃任務中斷后無法恢復檢查快照落盤頻率與內(nèi)容關鍵節(jié)點落盤策略并行 Agent 互相干擾檢查共享資源訪問冪等設計 分布式鎖模型輸出不穩(wěn)定檢查校驗與重試鏈路校驗失敗回傳模型重試線上問題無法復現(xiàn)檢查鏈路追蹤完整性埋點從第一行代碼開始6.5 最后分享一個我的排障習慣排查 Agent 線上問題我從來不看應用日志里的 Error 堆棧而是先看 trace 鏈路里“最后一步成功的工具調(diào)用”是什么。Agent 問題的根因幾乎總在“某一步我們以為成功的操作實際產(chǎn)出了錯誤結(jié)果”而錯誤結(jié)果被當作正常輸入喂給了下一步。順著鏈路回放通常很快能定位到問題點。個人體會是Agent 架構(gòu)選型這件事最怕的不是選錯而是不知道自己為什么選。你把需求維度拆清楚把每一檔方案的邊界搞清楚把運行時該有的骨架搭起來剩下的無非是在實踐中持續(xù)調(diào)優(yōu)。我做的這三個案例從輕到重都跑通過生產(chǎn)環(huán)境過程中踩過的坑遠比寫出來的多但架構(gòu)上只要大方向?qū)α诵栴}都好修。希望這份從實踐里沉淀的方案能幫你少走一些我沒避開的彎路。