總翻車？Harness工程給大模型應用裝上“駕駛艙”護欄)
這幾年AI Agent很火但真正敢讓Agent自動干活的團隊不多不管是內(nèi)部工具還是對外服務我見過太多項目在Demo階段驚艷全場一上生產(chǎn)就翻車。原因幾乎都是同一個Agent的執(zhí)行過程是概率性的而生產(chǎn)環(huán)境要求的是確定性。你可能遇到過這種情況同一個問題讓Agent跑兩次第一次一路順暢拿到結果第二次它繞了半天還在原地打轉甚至把不該調(diào)的接口都調(diào)了一遍。這不是模型不夠強而是缺少一層控制與承載體系——也就是今天要聊的Harness工程。Harness這個詞直譯過來是安全帶線束用在AI Agent領域我更喜歡把它理解為一套駕駛艙系統(tǒng)。Agent是發(fā)動機Harness是方向盤、儀表盤、剎車和導航的總和。發(fā)動機馬力再大沒有這些輔助系統(tǒng)你也不敢讓它在真實道路上自己跑。這篇文章會從穩(wěn)定性問題拆起把Harness工程的核心機制講透再給出一套可以直接落地的架構和代碼骨架。適合那些正在從跑通Demo走向上生產(chǎn)的工程師、技術Leader和獨立開發(fā)者。1. 先說清楚Agent不穩(wěn)定到底卡在哪1.1 概率性執(zhí)行同一個問題兩次答案可能不一樣大模型本身是概率模型同樣的輸入溫度不為0時輸出會有隨機性。很多團隊在搭建Agent的第一天就想用Prompt強行約束模型必須輸出JSON必須調(diào)用某個工具結果發(fā)現(xiàn)模型偶爾就是不聽。這不是模型不聰明而是你設計系統(tǒng)時還在用函數(shù)調(diào)用的心智模型但Agent本質(zhì)上是對話生成動作序列的心智模型。生產(chǎn)系統(tǒng)最怕的不是出錯而是不可復現(xiàn)。普通代碼同樣的輸入必然得到同樣的輸出但Agent不是。你需要先接受這個前提再設計一套機制來收窄不確定性。比如把溫度調(diào)到0、強制結構化輸出、增加校驗層讓模型即使胡思亂想也被攔在門外。1.2 多步任務的累積誤差一步錯步步錯真正復雜的Agent不是一個Prompt就能搞定的它通常要拆解成理解意圖→拆分任務→調(diào)用工具→匯總結果→生成回答多個步驟。每一步都有成功率假設單步成功率是90%五步之后整體成功率就只剩59%。也就是說十個請求里有四個會失敗。這就是為什么很多Demo工具跑單步很漂亮但一旦涉及多步操作比如查一下這個月所有項目的支出并生成報表就頻繁出錯。問題往往不是最后一步處理報表錯了而是在前面的查詢項目列表選擇字段調(diào)用統(tǒng)計接口這些環(huán)節(jié)中某一個走了彎路。Harness工程的一個重要任務就是做累積誤差控制——每一步都要加校驗、加補償、加糾錯機制而不是把所有希望寄托在模型一次想明白。1.3 外部工具是不可控的黑盒Agent的價值在于能使用工具但工具也是最大的不穩(wěn)定源。API會超時、會限流、會返回異常結構、會突然改字段。有時甚至不是你代碼的問題而是第三方服務在給你返回200但JSON里全是錯誤信息。我在一個項目里踩過很經(jīng)典的坑Agent調(diào)用一個訂單查詢接口接口返回200但業(yè)務碼是50012表示訂單不存在或無權訪問。Agent沒有檢查業(yè)務碼直接把里面的錯誤描述當成正常數(shù)據(jù)寫進了最終報告。單看日志沒有任何異常但結果一塌糊涂。工具治理的核心就是不能盲目相信HTTP狀態(tài)碼為200就代表成功必須在工具層統(tǒng)一做防御性校驗。1.4 穩(wěn)定不是不報錯而是可控地失敗理解穩(wěn)定性前先厘清一個誤區(qū)我們要的不是Agent永遠不出錯而是出錯時我們能快速發(fā)現(xiàn)、快速限定影響范圍、快速恢復。就像飛機不是永遠不會出故障而是有冗余系統(tǒng)和應急預案讓故障不會導致機毀人亡。所以Harness工程的目標可以用三句話概括失敗能被發(fā)現(xiàn)、失敗能被隔離、失敗后能從容恢復。這需要我們在Agent外面包一層完整的控制邏輯而不是把希望全押在Prompt上。這也是為什么單純寫Prompt技巧解決不了生產(chǎn)穩(wěn)定性問題需要從工程架構層面下手。2. Harness工程到底解決什么問題2.1 先分清Agent和Harness不少人有困惑Harness和Agent的區(qū)別是什么我經(jīng)常用一個類比Agent是你的員工Harness是公司的規(guī)章制度和辦公系統(tǒng)。員工可以有自己的能力但如果沒有考勤、預算審批、操作日志、質(zhì)量檢查你根本不敢讓他獨立處理客戶事務。放在AI場景里Agent負責做什么理解任務、規(guī)劃步驟、決定調(diào)用哪個工具。Harness負責怎么做才安全控制流程、記錄軌跡、校驗輸出、限制權限、處理異常。兩者是配合關系不是替代關系。單純有Agent很靈活但不受控單純有Harness很安全但沒有智能。2.2 Harness是駕駛艙而不是引擎引擎是Agent的核心智能駕駛艙負責讓駕駛員安全到達目的地。駕駛艙里有油門也有剎車有儀表盤也有導航甚至還有限速器。對應到AI系統(tǒng)里油門是Agent的自主決策能力剎車是限流和熔斷儀表盤是可觀測性導航是任務路由限速是權限和資源配額。我見過一些團隊把大量精力放在調(diào)Prompt讓模型更智能上卻不投入精力建設駕駛艙。結果模型智能上去了亂闖紅綠燈的能力也跟著上去了。真正要上生產(chǎn)反而應該先在Harness上下功夫因為智能能力的差距可以靠模型版本迭代補上但失控會造成不可逆的信任崩塌。2.3 穩(wěn)定性的四個支柱控制、可觀測、容錯、恢復這四件事是Harness工程的核心抓手缺一不可。第一控制。Agent的決策邊界、工具權限、資源消耗都要有明確上限。比如單個任務最多調(diào)用10次工具、最多跑30秒、最多消耗50萬token一旦觸頂就必須停下不能讓它無限跑下去。第二可觀測。每個Agent從誕生到消亡的完整軌跡都要能回放它看到了什么、想了什么、調(diào)用了什么、結果是什么、在哪個環(huán)節(jié)花了最多時間。沒有這些數(shù)據(jù)排查問題就是大海撈針。第三容錯。請求超時了重試一次參數(shù)不對就重新生成工具返回異常就換個方案。Harness要把這些兜底邏輯固化下來而不是每次出問題都靠寫死分支。第四恢復。某個Agent實例掛了任務要能轉移到另一個實例繼續(xù)跑上下文丟了要有Checkpoint可以回滾到最近一個安全節(jié)點。2.4 為什么叫Engineering而不叫Framework叫Framework容易讓人以為裝個依賴就能解決所有問題但真實世界的穩(wěn)定性問題往往來自業(yè)務語義和系統(tǒng)集成不是某個庫能完全覆蓋的。叫Engineering是把它當作一項持續(xù)投入的工程需要架構設計、監(jiān)控告警、故障演練、持續(xù)優(yōu)化。比如我曾經(jīng)花了兩周時間優(yōu)化一個Agent的重試策略。最早是失敗就重試結果下游接口是冪等的還好說碰到非冪等的扣費接口就釀成事故。后來改成只有特定錯誤碼才重試重試次數(shù)超過3次就進入人工確認隊列。這個過程沒有現(xiàn)成框架能幫我決定必須基于業(yè)務理解去設計。所以Harness Engineering本質(zhì)上是一種工程思維而不是一個安裝包。3. 核心機制拆解給Agent裝上約束與護欄3.1 狀態(tài)管理讓Agent有工作記憶而不是臨時腦Agent執(zhí)行多步任務時最怕失憶。它前面已經(jīng)查到了用戶所在城市的編碼下一步要用這個編碼查天氣結果它忘了又去問用戶你在哪個城市。這不是模型能力問題而是狀態(tài)管理缺失。我建議把Agent運行時的狀態(tài)分成三類短期對話狀態(tài)、任務執(zhí)行狀態(tài)、長期記憶。短期對話狀態(tài)就是本輪請求的上下文可以直接放在內(nèi)存或請求對象里任務執(zhí)行狀態(tài)要放進可持久化的存儲比如Redis或數(shù)據(jù)庫保存到哪一步了、中間結果是什么長期記憶存在向量庫里供跨會話復用。有個實戰(zhàn)經(jīng)驗把中間結果顯式寫成一個結構化工作區(qū)而不是全塞在自然語言上下文里。工作區(qū)里直接維護當前用戶ID訂單號查詢結果這類字段。Agent在每一步都先讀工作區(qū)再決定下一步動作。這樣確實能顯著減少模型忘記前面信息的毛病也讓狀態(tài)可檢查可調(diào)。3.2 工具治理注冊制、Schema校驗、超時熔斷工具才是Agent落地時的真正風險敞口所以要像治理微服務一樣治理工具。第一步是注冊制所有Agent能調(diào)用的工具都要先在Harness里聲明比如工具名稱、用途、入?yún)⒏袷健⒊鰠⒏袷?、權限等級。Agent只能調(diào)用已注冊的工具它的自由組合能力被約束在可控范圍內(nèi)。第二步是Schema校驗。模型輸出的工具調(diào)用參數(shù)有時候會丟字段、類型錯誤或者缺必填項Harness要像API網(wǎng)關一樣做參數(shù)校驗不通過就拒絕調(diào)用并反饋給Agent重新修正。我一般用JSON Schema做校驗出錯信息盡量具體比如參數(shù)customer_id是string類型你傳的是object。第三步是超時、重試和熔斷。每個工具調(diào)用都要有超時時間默認10秒超時后返回給Agent一個明確的錯誤。重試只對可重試的錯誤生效比如網(wǎng)絡異常、限流而對參數(shù)被拒業(yè)務異常這類錯誤直接終止。熔斷的意思是如果某個工具連續(xù)失敗率超過閾值比如5分鐘內(nèi)有50%請求失敗Harness要主動停用這個工具一段時間防止鏈路雪崩。3.3 決策約束結構化輸出與策略路由大部分Agent任務其實不需要模型完全自由發(fā)揮我們需要的是在給定的選項里做選擇。與其讓模型自由生成整個JSON不如讓它生成結構化字段然后在Harness里做二次校驗。舉個例子客服Agent接到用戶投訴后Harness希望它輸出一個意圖分類候選值是退款換貨物流查詢其他。這時候不應該讓模型自由發(fā)揮寫一句話而是讓它從四個選項里選一個再生成補充參數(shù)。這個選擇策略可以放在代碼里硬校驗模型輸出退款就匹配中文釋義輸出退貨也要映射到退款分類。策略路由則是把不太需要智能的流程交給確定的代碼。很多Agent編排其實可以拆成先判斷是否命中固定規(guī)則命中就走決策樹沒命中再交給LLM。這樣大部分流量走穩(wěn)定路徑只有小部分復雜場景才走模型推理穩(wěn)定性和成本都能兼顧。3.4 上下文治理窗口管理、壓縮、長期記憶分層LLM的上下文窗口是有限資源也是最貴的資源。有一次我統(tǒng)計項目成本發(fā)現(xiàn)光是不斷把對話歷史全部發(fā)給模型一個月就燒掉了不少錢。后來我們做了上下文治理分三層處理。第一層是窗口管理設定最大消息長度超過之后做截斷或剔除低價值消息。有些歷史消息比如你好謝謝這種根本不重要可以直接丟掉。第二層是摘要壓縮當輪次很多時讓模型定期把早期對話壓縮成一個摘要放到當前上下文的頭部既保留了關鍵信息又壓縮了token。第三層是長期記憶把用戶偏好、歷史結論存到向量庫按需檢索而不是把所有歷史都塞進每次請求。這三層做下來平均每個請求的token消耗能降40%以上。上下文不再是做菜時堆得滿滿的案板而是像圖書館一樣有索引、有摘要、有書庫需要哪本取哪本。4. 實操搭建一套生產(chǎn)可用的Harness4.1 分層架構接入層、控制層、能力層、存儲層我通常把一個生產(chǎn)級Harness分成四層。接入層負責接收用戶請求、鑒權、會話管理這是所有流量進入的第一道閘門?？刂茖邮呛诵陌瑺顟B(tài)機、路由、工具調(diào)用編排、校驗、限流、重試、熔斷等邏輯。能力層是Agent真正使用的外部資源比如大模型API、內(nèi)部服務、數(shù)據(jù)庫、第三方系統(tǒng)。存儲層保存會話狀態(tài)、工具調(diào)用日志、工作區(qū)數(shù)據(jù)、長期記憶等。這套分層的好處是職責清晰控制邏輯不散落在業(yè)務代碼里。比如你要在某個環(huán)節(jié)增加新的校驗只需要改控制層不需要動Agent的提示詞和工具代碼。每一層都能獨立測試、獨立擴容不像一個巨大的Agent類那樣把所有邏輯揉在一起。4.2 最小可運行代碼骨架Python FastAPI LangGraph我用Python生態(tài)比較順手下面給個能跑的骨架。核心思路是用LangGraph來管理狀態(tài)機和Agent的流程用FastAPI做HTTP入口外部再掛上校驗和重試邏輯。from typing import TypedDict, Literal from langgraph.graph import StateGraph, END from pydantic import BaseModel, validator # 定義工作區(qū)狀態(tài)這是Harness的關鍵 # 所有步驟共享的結構化狀態(tài)而不是純自然語言 class AgentState(TypedDict): user_id: str query: str order_id: str | None intent: str | None tool_result: dict | None retry_count: int trace_id: str # 工具調(diào)用前用Pydantic做參數(shù)校驗 class QueryOrderInput(BaseModel): order_id: str user_id: str validator(order_id) def order_id_not_empty(cls, v): if not v.strip(): raise ValueError(order_id cannot be empty) return v # 第一步解析意圖但這里我們采用策略路由 # 先嘗試規(guī)則匹配匹配不到才交給LLM def route_intent(state: AgentState) - AgentState: query state[query] if 退 in query or 退款 in query: state[intent] refund elif 訂單 in query: state[intent] query_order else: # 調(diào)用LLM做意圖識別示例省略具體實現(xiàn) state[intent] unknown return state # 第二步調(diào)用工具這里展示超時和重試骨架 def call_query_order(state: AgentState) - AgentState: if state[intent] ! query_order: return state # 入?yún)⑿ｒ?try: params QueryOrderInput(order_idstate[order_id], user_idstate[user_id]) except ValueError as e: state[tool_result] {error: f參數(shù)校驗失敗: {e}} state[retry_count] 1 return state # 調(diào)用內(nèi)部訂單服務帶超時邏輯 try: result query_order_api(params.order_id, params.user_id, timeout10) if result[business_code] ! 0: # 業(yè)務錯誤不重試直接返回到可觀測日志 state[tool_result] {error: f業(yè)務失敗: {result[msg]}} else: state[tool_result] result[data] except TimeoutError: state[tool_result] {error: timeout} state[retry_count] 1 return state # 用StateGraph把這些步驟串起來 graph StateGraph(AgentState) graph.add_node(route, route_intent) graph.add_node(query_order, call_query_order) graph.add_edge(route, query_order) graph.add_edge(query_order, END) app graph.compile() # FastAPI暴露HTTP接口 from fastapi import FastAPI, HTTPException server FastAPI() server.post(/agent) async def run_agent(user_id: str, query: str, order_id: str | None None): if not query: raise HTTPException(status_code400, detailquery不能為空) state AgentState( user_iduser_id, queryquery, order_idorder_id, intentNone, tool_resultNone, retry_count0, trace_idgenerate_trace_id(), ) # 每個請求都會淺拷貝state并發(fā)安全由LangGraph保證 final_state await app.ainvoke(state) return final_state這個骨架看起來很簡略但核心思想值得注意所有決策和調(diào)用都圍繞結構化狀態(tài)AgentState展開工具的輸入和輸出都有校驗讓模型自由發(fā)揮的空間被壓縮到只有意圖識別這一個環(huán)節(jié)。生產(chǎn)環(huán)境里你還可以在route_intent后用一次LLM調(diào)用做多輪對話但固定流程的部分盡量不要完全交給LLM。4.3 并發(fā)與韌性限流、隊列、重試和信號量很多朋友問AI Agent怎么扛并發(fā)。Agent本身不是高并發(fā)的好手它慢、貴、占用上下文。Harness要做的是把并發(fā)沖擊擋在系統(tǒng)外把計算資源按配額分配。我的做法是三個層次。入口層做限流比如單用戶單會話的QPS限制、全局并發(fā)上限。控制層引入信號量限制同時運行的最大Agent任務數(shù)假設你的下游API只能承受50個并發(fā)那Harness的并發(fā)數(shù)就控制在40留出緩沖。任務層如果流量突然飆高就把超出的請求放入隊列排隊返回用戶系統(tǒng)繁忙或顯示排隊進度條而不是無腦并發(fā)把所有下游接口打死。還有一個容易忽略的點重試要加退避抖動。如果100個請求同時超時它們同時重試會給下游造成二次峰值。我一般用指數(shù)退避第一次等1秒第二次等2秒第三次等4秒再加上一個0到1秒的隨機抖動。這樣重試的流量會分散開來有效避免驚群效應。4.4 可觀測性Trace、Log、Metric三件套生產(chǎn)環(huán)境沒有可觀測性等于蒙著眼睛開飛機。我在Harness里會做三件事。第一全鏈路Trace。每次Agent請求生成一個TraceID從入口到每次工具調(diào)用都打上這個ID。最好把模型調(diào)用的輸入輸出也塞進低頻存儲里。排查問題的時候把TraceID一搜就能看到它每一步的輸入輸出比只盯著最終結果要強太多。第二結構化日志。日志不是給人看的散文而是給檢索用的結構化事件。每個事件至少包含時間戳、TraceID、AgentID、步驟名、耗時、狀態(tài)、錯誤信息。后期任何指標統(tǒng)計都能直接基于這些字段聚合。第三核心指標。我最關注的四個指標請求成功率、平均/中位數(shù)耗時、Token消耗、工具調(diào)用失敗率。這四個指標可以畫在同一張Dashboard上。一旦某個版本的Prompt或新工具上線的同時成功率掉下來馬上就能發(fā)現(xiàn)。我還習慣加一個行為漂移檢測定期隨機抽取一部分請求比對Agent的軌跡分布。如果發(fā)現(xiàn)某個工具的調(diào)用頻率出現(xiàn)異常波動大概率是模型行為變了。這種事用戶感知不到但會在后期體現(xiàn)成成功率下降。5. 高頻問題與排查實錄5.1 Agent陷入死循環(huán)怎么辦最常見的問題是Agent反復調(diào)用同一個工具比如它查了三遍天氣接口、又把昨天的錯誤信息當成新輸入去問模型。我一般用三個手段防死循環(huán)最大步數(shù)限制、循環(huán)檢測、中斷人機確認。最大步數(shù)限制很簡單比如一個任務最多20步達到后強制終止并給用戶一個進入人工客服的鏈接。循環(huán)檢測稍微復雜一點把每次工具調(diào)用的參數(shù)和結果摘要做成hash如果發(fā)現(xiàn)同一個hash出現(xiàn)三次就判定為循環(huán)這時把Agent的思考重置一下清掉一些歷史再讓它重新規(guī)劃。如果重置了兩次還是循環(huán)那就不再硬撐讓運營介入。還有一個成本很低的方案給Agent設置允許的出格動作上限比如最多調(diào)用5次風險接口超過5次就必須征求用戶確認我這邊發(fā)現(xiàn)重復執(zhí)行了某操作確認繼續(xù)嗎這個交互句話雖然簡單但能截住很多異常。5.2 上下文越寫越長成本和響應都失控這在長會話場景特別常見。用戶連續(xù)聊了二三十輪上下文里塞滿了原始消息模型每次推理開銷越來越大響應也變慢。解決思路上面提過就是分層治理。我踩過的一個坑是手動寫了個截斷舊消息的邏輯結果截斷太激進把上上輪用戶明確要求的下午3點的鬧鐘給丟了鬧鐘設錯了。后來我改成抽取關鍵信息到結構化slot比如用戶明確表達過的日期、時間、地點、偏好都存到slot里而不是依賴自然語言歷史。上下文里可以丟自然語言但slot必須保留這樣就算歷史被壓縮關鍵約束也不會丟。另一個小技巧如果上下文已經(jīng)很長讓模型優(yōu)先基于slot和最近兩輪來回復而不是每次都看全部歷史。你會發(fā)現(xiàn)很多場景根本不需要全程上下文。5.3 工具調(diào)用各種Timeout/參數(shù)錯亂工具調(diào)用的Timeout是最穩(wěn)定的報錯來源。我整理了三個排查方向。第一看你的HTTP客戶端是不是設置了默認的無窮超時。有些代碼庫請求庫默認超時非常長一旦下游掛住Harness也一起掛住。務必給每個請求顯式設置超時。第二看錯誤類型。是連接超時還是讀超時后者說明下游已經(jīng)接收請求但處理太慢這時冪等請求可以重試非冪等請求要降級。第三校驗Agent生成的參數(shù)是不是真的符合工具要求。我遇到過模型把1990-01-01這個字符串轉換成1990/01/01傳給一個只接受YYYY-MM-DD的接口結果接口解析失敗。Harness里應該有一份參數(shù)規(guī)范表并在工具調(diào)用前做自動轉換或校驗。一些必須強調(diào)的規(guī)矩重試只適用于冪等接口。如果是扣費、發(fā)短信、下單這類操作重試就是災難。所以工具注冊時要聲明冪等性不聲明默認不重試。5.4 版本升級后行為變異用黃金數(shù)據(jù)集守住回歸大模型上線和升級跟傳統(tǒng)代碼發(fā)版不一樣。模型價值升級了但行為可能會有你不知道的偏移。我見過某個Agent在GPT-4升級到新版本后突然把所有日期格式從12月25日改成了12/25內(nèi)部解析直接崩了。要攔截這類問題我會維護一個黃金數(shù)據(jù)集里面是100到200條真實且有代表性的任務每條都有期望輸出和允許的偏差范圍。每次模型版本升級、Prompt改動、工具Schema調(diào)整都用這個數(shù)據(jù)集跑一遍回歸看通過率掉沒掉。通過率低于95%就不能上線。另外一個良心建議Agent上線前要準備人工兜底開關。萬一生產(chǎn)環(huán)境出現(xiàn)大面積異常至少能一鍵切換到人工模式不讓異常繼續(xù)擴大。這個開關就像消防系統(tǒng)的手動閥門寧可平時不用不能沒有。6. 我的實操體會最近這個項目讓我印象最深的一件事是我們把大量的Prompt工程時間抽出來做Harness之后Agent反而變笨了但整體成功率從70%左右一路穩(wěn)定到97%以上。用戶的感受不是這AI很聰明而是這AI做事靠譜。對生產(chǎn)系統(tǒng)來說靠譜比聰明值錢得多。還有一個體會是Harness工程并不需要一步到位。你可以先做最輕量的版本在Agent外面加一層最大步數(shù)限制、工具結果校驗和全鏈路日志這三件事三天內(nèi)就能做完但效果立竿見影。再往后逐步追加狀態(tài)管理、上下文治理、熔斷機制。不要一開始就想用最重度的方案小步快跑反而更容易沉淀出真正貼合你業(yè)務的Harness。另外建議備一個故障演練日。每個月找一個流量低峰期故意把下一個工具接口調(diào)成超時看Agent的表現(xiàn)是否正常。這個做法讓我理解了一點Harness不是寫出來的是不斷被事故錘煉出來的。現(xiàn)在每次上線新工具我們都會先人為制造幾次異常場景確認兜底邏輯可靠之后才會放量。如果這篇文章能給到你的團隊一個明確的抓手pick三個最容易出問題的環(huán)節(jié)狀態(tài)管理、工具校驗、異常兜底。把這三件套做到位你的Agent就算不能吊打GPT-5也能在業(yè)務線上穩(wěn)穩(wěn)當當下地干活。 AI Agent上生產(chǎn)總翻車？Harness工程給大模型應用裝上“駕駛艙”護欄
這幾年AI Agent很火但真正敢讓Agent自動干活的團隊不多不管是內(nèi)部工具還是對外服務我見過太多項目在Demo階段驚艷全場一上生產(chǎn)就翻車。原因幾乎都是同一個Agent的執(zhí)行過程是概率性的而生產(chǎn)環(huán)境要求的是確定性。你可能遇到過這種情況同一個問題讓Agent跑兩次第一次一路順暢拿到結果第二次它繞了半天還在原地打轉甚至把不該調(diào)的接口都調(diào)了一遍。這不是模型不夠強而是缺少一層控制與承載體系——也就是今天要聊的Harness工程。Harness這個詞直譯過來是安全帶線束用在AI Agent領域我更喜歡把它理解為一套駕駛艙系統(tǒng)。Agent是發(fā)動機Harness是方向盤、儀表盤、剎車和導航的總和。發(fā)動機馬力再大沒有這些輔助系統(tǒng)你也不敢讓它在真實道路上自己跑。這篇文章會從穩(wěn)定性問題拆起把Harness工程的核心機制講透再給出一套可以直接落地的架構和代碼骨架。適合那些正在從跑通Demo走向上生產(chǎn)的工程師、技術Leader和獨立開發(fā)者。1. 先說清楚Agent不穩(wěn)定到底卡在哪1.1 概率性執(zhí)行同一個問題兩次答案可能不一樣大模型本身是概率模型同樣的輸入溫度不為0時輸出會有隨機性。很多團隊在搭建Agent的第一天就想用Prompt強行約束模型必須輸出JSON必須調(diào)用某個工具結果發(fā)現(xiàn)模型偶爾就是不聽。這不是模型不聰明而是你設計系統(tǒng)時還在用函數(shù)調(diào)用的心智模型但Agent本質(zhì)上是對話生成動作序列的心智模型。生產(chǎn)系統(tǒng)最怕的不是出錯而是不可復現(xiàn)。普通代碼同樣的輸入必然得到同樣的輸出但Agent不是。你需要先接受這個前提再設計一套機制來收窄不確定性。比如把溫度調(diào)到0、強制結構化輸出、增加校驗層讓模型即使胡思亂想也被攔在門外。1.2 多步任務的累積誤差一步錯步步錯真正復雜的Agent不是一個Prompt就能搞定的它通常要拆解成理解意圖→拆分任務→調(diào)用工具→匯總結果→生成回答多個步驟。每一步都有成功率假設單步成功率是90%五步之后整體成功率就只剩59%。也就是說十個請求里有四個會失敗。這就是為什么很多Demo工具跑單步很漂亮但一旦涉及多步操作比如查一下這個月所有項目的支出并生成報表就頻繁出錯。問題往往不是最后一步處理報表錯了而是在前面的查詢項目列表選擇字段調(diào)用統(tǒng)計接口這些環(huán)節(jié)中某一個走了彎路。Harness工程的一個重要任務就是做累積誤差控制——每一步都要加校驗、加補償、加糾錯機制而不是把所有希望寄托在模型一次想明白。1.3 外部工具是不可控的黑盒Agent的價值在于能使用工具但工具也是最大的不穩(wěn)定源。API會超時、會限流、會返回異常結構、會突然改字段。有時甚至不是你代碼的問題而是第三方服務在給你返回200但JSON里全是錯誤信息。我在一個項目里踩過很經(jīng)典的坑Agent調(diào)用一個訂單查詢接口接口返回200但業(yè)務碼是50012表示訂單不存在或無權訪問。Agent沒有檢查業(yè)務碼直接把里面的錯誤描述當成正常數(shù)據(jù)寫進了最終報告。單看日志沒有任何異常但結果一塌糊涂。工具治理的核心就是不能盲目相信HTTP狀態(tài)碼為200就代表成功必須在工具層統(tǒng)一做防御性校驗。1.4 穩(wěn)定不是不報錯而是可控地失敗理解穩(wěn)定性前先厘清一個誤區(qū)我們要的不是Agent永遠不出錯而是出錯時我們能快速發(fā)現(xiàn)、快速限定影響范圍、快速恢復。就像飛機不是永遠不會出故障而是有冗余系統(tǒng)和應急預案讓故障不會導致機毀人亡。所以Harness工程的目標可以用三句話概括失敗能被發(fā)現(xiàn)、失敗能被隔離、失敗后能從容恢復。這需要我們在Agent外面包一層完整的控制邏輯而不是把希望全押在Prompt上。這也是為什么單純寫Prompt技巧解決不了生產(chǎn)穩(wěn)定性問題需要從工程架構層面下手。2. Harness工程到底解決什么問題2.1 先分清Agent和Harness不少人有困惑Harness和Agent的區(qū)別是什么我經(jīng)常用一個類比Agent是你的員工Harness是公司的規(guī)章制度和辦公系統(tǒng)。員工可以有自己的能力但如果沒有考勤、預算審批、操作日志、質(zhì)量檢查你根本不敢讓他獨立處理客戶事務。放在AI場景里Agent負責做什么理解任務、規(guī)劃步驟、決定調(diào)用哪個工具。Harness負責怎么做才安全控制流程、記錄軌跡、校驗輸出、限制權限、處理異常。兩者是配合關系不是替代關系。單純有Agent很靈活但不受控單純有Harness很安全但沒有智能。2.2 Harness是駕駛艙而不是引擎引擎是Agent的核心智能駕駛艙負責讓駕駛員安全到達目的地。駕駛艙里有油門也有剎車有儀表盤也有導航甚至還有限速器。對應到AI系統(tǒng)里油門是Agent的自主決策能力剎車是限流和熔斷儀表盤是可觀測性導航是任務路由限速是權限和資源配額。我見過一些團隊把大量精力放在調(diào)Prompt讓模型更智能上卻不投入精力建設駕駛艙。結果模型智能上去了亂闖紅綠燈的能力也跟著上去了。真正要上生產(chǎn)反而應該先在Harness上下功夫因為智能能力的差距可以靠模型版本迭代補上但失控會造成不可逆的信任崩塌。2.3 穩(wěn)定性的四個支柱控制、可觀測、容錯、恢復這四件事是Harness工程的核心抓手缺一不可。第一控制。Agent的決策邊界、工具權限、資源消耗都要有明確上限。比如單個任務最多調(diào)用10次工具、最多跑30秒、最多消耗50萬token一旦觸頂就必須停下不能讓它無限跑下去。第二可觀測。每個Agent從誕生到消亡的完整軌跡都要能回放它看到了什么、想了什么、調(diào)用了什么、結果是什么、在哪個環(huán)節(jié)花了最多時間。沒有這些數(shù)據(jù)排查問題就是大海撈針。第三容錯。請求超時了重試一次參數(shù)不對就重新生成工具返回異常就換個方案。Harness要把這些兜底邏輯固化下來而不是每次出問題都靠寫死分支。第四恢復。某個Agent實例掛了任務要能轉移到另一個實例繼續(xù)跑上下文丟了要有Checkpoint可以回滾到最近一個安全節(jié)點。2.4 為什么叫Engineering而不叫Framework叫Framework容易讓人以為裝個依賴就能解決所有問題但真實世界的穩(wěn)定性問題往往來自業(yè)務語義和系統(tǒng)集成不是某個庫能完全覆蓋的。叫Engineering是把它當作一項持續(xù)投入的工程需要架構設計、監(jiān)控告警、故障演練、持續(xù)優(yōu)化。比如我曾經(jīng)花了兩周時間優(yōu)化一個Agent的重試策略。最早是失敗就重試結果下游接口是冪等的還好說碰到非冪等的扣費接口就釀成事故。后來改成只有特定錯誤碼才重試重試次數(shù)超過3次就進入人工確認隊列。這個過程沒有現(xiàn)成框架能幫我決定必須基于業(yè)務理解去設計。所以Harness Engineering本質(zhì)上是一種工程思維而不是一個安裝包。3. 核心機制拆解給Agent裝上約束與護欄3.1 狀態(tài)管理讓Agent有工作記憶而不是臨時腦Agent執(zhí)行多步任務時最怕失憶。它前面已經(jīng)查到了用戶所在城市的編碼下一步要用這個編碼查天氣結果它忘了又去問用戶你在哪個城市。這不是模型能力問題而是狀態(tài)管理缺失。我建議把Agent運行時的狀態(tài)分成三類短期對話狀態(tài)、任務執(zhí)行狀態(tài)、長期記憶。短期對話狀態(tài)就是本輪請求的上下文可以直接放在內(nèi)存或請求對象里任務執(zhí)行狀態(tài)要放進可持久化的存儲比如Redis或數(shù)據(jù)庫保存到哪一步了、中間結果是什么長期記憶存在向量庫里供跨會話復用。有個實戰(zhàn)經(jīng)驗把中間結果顯式寫成一個結構化工作區(qū)而不是全塞在自然語言上下文里。工作區(qū)里直接維護當前用戶ID訂單號查詢結果這類字段。Agent在每一步都先讀工作區(qū)再決定下一步動作。這樣確實能顯著減少模型忘記前面信息的毛病也讓狀態(tài)可檢查可調(diào)。3.2 工具治理注冊制、Schema校驗、超時熔斷工具才是Agent落地時的真正風險敞口所以要像治理微服務一樣治理工具。第一步是注冊制所有Agent能調(diào)用的工具都要先在Harness里聲明比如工具名稱、用途、入?yún)⒏袷健⒊鰠⒏袷?、權限等級。Agent只能調(diào)用已注冊的工具它的自由組合能力被約束在可控范圍內(nèi)。第二步是Schema校驗。模型輸出的工具調(diào)用參數(shù)有時候會丟字段、類型錯誤或者缺必填項Harness要像API網(wǎng)關一樣做參數(shù)校驗不通過就拒絕調(diào)用并反饋給Agent重新修正。我一般用JSON Schema做校驗出錯信息盡量具體比如參數(shù)customer_id是string類型你傳的是object。第三步是超時、重試和熔斷。每個工具調(diào)用都要有超時時間默認10秒超時后返回給Agent一個明確的錯誤。重試只對可重試的錯誤生效比如網(wǎng)絡異常、限流而對參數(shù)被拒業(yè)務異常這類錯誤直接終止。熔斷的意思是如果某個工具連續(xù)失敗率超過閾值比如5分鐘內(nèi)有50%請求失敗Harness要主動停用這個工具一段時間防止鏈路雪崩。3.3 決策約束結構化輸出與策略路由大部分Agent任務其實不需要模型完全自由發(fā)揮我們需要的是在給定的選項里做選擇。與其讓模型自由生成整個JSON不如讓它生成結構化字段然后在Harness里做二次校驗。舉個例子客服Agent接到用戶投訴后Harness希望它輸出一個意圖分類候選值是退款換貨物流查詢其他。這時候不應該讓模型自由發(fā)揮寫一句話而是讓它從四個選項里選一個再生成補充參數(shù)。這個選擇策略可以放在代碼里硬校驗模型輸出退款就匹配中文釋義輸出退貨也要映射到退款分類。策略路由則是把不太需要智能的流程交給確定的代碼。很多Agent編排其實可以拆成先判斷是否命中固定規(guī)則命中就走決策樹沒命中再交給LLM。這樣大部分流量走穩(wěn)定路徑只有小部分復雜場景才走模型推理穩(wěn)定性和成本都能兼顧。3.4 上下文治理窗口管理、壓縮、長期記憶分層LLM的上下文窗口是有限資源也是最貴的資源。有一次我統(tǒng)計項目成本發(fā)現(xiàn)光是不斷把對話歷史全部發(fā)給模型一個月就燒掉了不少錢。后來我們做了上下文治理分三層處理。第一層是窗口管理設定最大消息長度超過之后做截斷或剔除低價值消息。有些歷史消息比如你好謝謝這種根本不重要可以直接丟掉。第二層是摘要壓縮當輪次很多時讓模型定期把早期對話壓縮成一個摘要放到當前上下文的頭部既保留了關鍵信息又壓縮了token。第三層是長期記憶把用戶偏好、歷史結論存到向量庫按需檢索而不是把所有歷史都塞進每次請求。這三層做下來平均每個請求的token消耗能降40%以上。上下文不再是做菜時堆得滿滿的案板而是像圖書館一樣有索引、有摘要、有書庫需要哪本取哪本。4. 實操搭建一套生產(chǎn)可用的Harness4.1 分層架構接入層、控制層、能力層、存儲層我通常把一個生產(chǎn)級Harness分成四層。接入層負責接收用戶請求、鑒權、會話管理這是所有流量進入的第一道閘門?？刂茖邮呛诵陌瑺顟B(tài)機、路由、工具調(diào)用編排、校驗、限流、重試、熔斷等邏輯。能力層是Agent真正使用的外部資源比如大模型API、內(nèi)部服務、數(shù)據(jù)庫、第三方系統(tǒng)。存儲層保存會話狀態(tài)、工具調(diào)用日志、工作區(qū)數(shù)據(jù)、長期記憶等。這套分層的好處是職責清晰控制邏輯不散落在業(yè)務代碼里。比如你要在某個環(huán)節(jié)增加新的校驗只需要改控制層不需要動Agent的提示詞和工具代碼。每一層都能獨立測試、獨立擴容不像一個巨大的Agent類那樣把所有邏輯揉在一起。4.2 最小可運行代碼骨架Python FastAPI LangGraph我用Python生態(tài)比較順手下面給個能跑的骨架。核心思路是用LangGraph來管理狀態(tài)機和Agent的流程用FastAPI做HTTP入口外部再掛上校驗和重試邏輯。from typing import TypedDict, Literal from langgraph.graph import StateGraph, END from pydantic import BaseModel, validator # 定義工作區(qū)狀態(tài)這是Harness的關鍵 # 所有步驟共享的結構化狀態(tài)而不是純自然語言 class AgentState(TypedDict): user_id: str query: str order_id: str | None intent: str | None tool_result: dict | None retry_count: int trace_id: str # 工具調(diào)用前用Pydantic做參數(shù)校驗 class QueryOrderInput(BaseModel): order_id: str user_id: str validator(order_id) def order_id_not_empty(cls, v): if not v.strip(): raise ValueError(order_id cannot be empty) return v # 第一步解析意圖但這里我們采用策略路由 # 先嘗試規(guī)則匹配匹配不到才交給LLM def route_intent(state: AgentState) - AgentState: query state[query] if 退 in query or 退款 in query: state[intent] refund elif 訂單 in query: state[intent] query_order else: # 調(diào)用LLM做意圖識別示例省略具體實現(xiàn) state[intent] unknown return state # 第二步調(diào)用工具這里展示超時和重試骨架 def call_query_order(state: AgentState) - AgentState: if state[intent] ! query_order: return state # 入?yún)⑿ｒ?try: params QueryOrderInput(order_idstate[order_id], user_idstate[user_id]) except ValueError as e: state[tool_result] {error: f參數(shù)校驗失敗: {e}} state[retry_count] 1 return state # 調(diào)用內(nèi)部訂單服務帶超時邏輯 try: result query_order_api(params.order_id, params.user_id, timeout10) if result[business_code] ! 0: # 業(yè)務錯誤不重試直接返回到可觀測日志 state[tool_result] {error: f業(yè)務失敗: {result[msg]}} else: state[tool_result] result[data] except TimeoutError: state[tool_result] {error: timeout} state[retry_count] 1 return state # 用StateGraph把這些步驟串起來 graph StateGraph(AgentState) graph.add_node(route, route_intent) graph.add_node(query_order, call_query_order) graph.add_edge(route, query_order) graph.add_edge(query_order, END) app graph.compile() # FastAPI暴露HTTP接口 from fastapi import FastAPI, HTTPException server FastAPI() server.post(/agent) async def run_agent(user_id: str, query: str, order_id: str | None None): if not query: raise HTTPException(status_code400, detailquery不能為空) state AgentState( user_iduser_id, queryquery, order_idorder_id, intentNone, tool_resultNone, retry_count0, trace_idgenerate_trace_id(), ) # 每個請求都會淺拷貝state并發(fā)安全由LangGraph保證 final_state await app.ainvoke(state) return final_state這個骨架看起來很簡略但核心思想值得注意所有決策和調(diào)用都圍繞結構化狀態(tài)AgentState展開工具的輸入和輸出都有校驗讓模型自由發(fā)揮的空間被壓縮到只有意圖識別這一個環(huán)節(jié)。生產(chǎn)環(huán)境里你還可以在route_intent后用一次LLM調(diào)用做多輪對話但固定流程的部分盡量不要完全交給LLM。4.3 并發(fā)與韌性限流、隊列、重試和信號量很多朋友問AI Agent怎么扛并發(fā)。Agent本身不是高并發(fā)的好手它慢、貴、占用上下文。Harness要做的是把并發(fā)沖擊擋在系統(tǒng)外把計算資源按配額分配。我的做法是三個層次。入口層做限流比如單用戶單會話的QPS限制、全局并發(fā)上限。控制層引入信號量限制同時運行的最大Agent任務數(shù)假設你的下游API只能承受50個并發(fā)那Harness的并發(fā)數(shù)就控制在40留出緩沖。任務層如果流量突然飆高就把超出的請求放入隊列排隊返回用戶系統(tǒng)繁忙或顯示排隊進度條而不是無腦并發(fā)把所有下游接口打死。還有一個容易忽略的點重試要加退避抖動。如果100個請求同時超時它們同時重試會給下游造成二次峰值。我一般用指數(shù)退避第一次等1秒第二次等2秒第三次等4秒再加上一個0到1秒的隨機抖動。這樣重試的流量會分散開來有效避免驚群效應。4.4 可觀測性Trace、Log、Metric三件套生產(chǎn)環(huán)境沒有可觀測性等于蒙著眼睛開飛機。我在Harness里會做三件事。第一全鏈路Trace。每次Agent請求生成一個TraceID從入口到每次工具調(diào)用都打上這個ID。最好把模型調(diào)用的輸入輸出也塞進低頻存儲里。排查問題的時候把TraceID一搜就能看到它每一步的輸入輸出比只盯著最終結果要強太多。第二結構化日志。日志不是給人看的散文而是給檢索用的結構化事件。每個事件至少包含時間戳、TraceID、AgentID、步驟名、耗時、狀態(tài)、錯誤信息。后期任何指標統(tǒng)計都能直接基于這些字段聚合。第三核心指標。我最關注的四個指標請求成功率、平均/中位數(shù)耗時、Token消耗、工具調(diào)用失敗率。這四個指標可以畫在同一張Dashboard上。一旦某個版本的Prompt或新工具上線的同時成功率掉下來馬上就能發(fā)現(xiàn)。我還習慣加一個行為漂移檢測定期隨機抽取一部分請求比對Agent的軌跡分布。如果發(fā)現(xiàn)某個工具的調(diào)用頻率出現(xiàn)異常波動大概率是模型行為變了。這種事用戶感知不到但會在后期體現(xiàn)成成功率下降。5. 高頻問題與排查實錄5.1 Agent陷入死循環(huán)怎么辦最常見的問題是Agent反復調(diào)用同一個工具比如它查了三遍天氣接口、又把昨天的錯誤信息當成新輸入去問模型。我一般用三個手段防死循環(huán)最大步數(shù)限制、循環(huán)檢測、中斷人機確認。最大步數(shù)限制很簡單比如一個任務最多20步達到后強制終止并給用戶一個進入人工客服的鏈接。循環(huán)檢測稍微復雜一點把每次工具調(diào)用的參數(shù)和結果摘要做成hash如果發(fā)現(xiàn)同一個hash出現(xiàn)三次就判定為循環(huán)這時把Agent的思考重置一下清掉一些歷史再讓它重新規(guī)劃。如果重置了兩次還是循環(huán)那就不再硬撐讓運營介入。還有一個成本很低的方案給Agent設置允許的出格動作上限比如最多調(diào)用5次風險接口超過5次就必須征求用戶確認我這邊發(fā)現(xiàn)重復執(zhí)行了某操作確認繼續(xù)嗎這個交互句話雖然簡單但能截住很多異常。5.2 上下文越寫越長成本和響應都失控這在長會話場景特別常見。用戶連續(xù)聊了二三十輪上下文里塞滿了原始消息模型每次推理開銷越來越大響應也變慢。解決思路上面提過就是分層治理。我踩過的一個坑是手動寫了個截斷舊消息的邏輯結果截斷太激進把上上輪用戶明確要求的下午3點的鬧鐘給丟了鬧鐘設錯了。后來我改成抽取關鍵信息到結構化slot比如用戶明確表達過的日期、時間、地點、偏好都存到slot里而不是依賴自然語言歷史。上下文里可以丟自然語言但slot必須保留這樣就算歷史被壓縮關鍵約束也不會丟。另一個小技巧如果上下文已經(jīng)很長讓模型優(yōu)先基于slot和最近兩輪來回復而不是每次都看全部歷史。你會發(fā)現(xiàn)很多場景根本不需要全程上下文。5.3 工具調(diào)用各種Timeout/參數(shù)錯亂工具調(diào)用的Timeout是最穩(wěn)定的報錯來源。我整理了三個排查方向。第一看你的HTTP客戶端是不是設置了默認的無窮超時。有些代碼庫請求庫默認超時非常長一旦下游掛住Harness也一起掛住。務必給每個請求顯式設置超時。第二看錯誤類型。是連接超時還是讀超時后者說明下游已經(jīng)接收請求但處理太慢這時冪等請求可以重試非冪等請求要降級。第三校驗Agent生成的參數(shù)是不是真的符合工具要求。我遇到過模型把1990-01-01這個字符串轉換成1990/01/01傳給一個只接受YYYY-MM-DD的接口結果接口解析失敗。Harness里應該有一份參數(shù)規(guī)范表并在工具調(diào)用前做自動轉換或校驗。一些必須強調(diào)的規(guī)矩重試只適用于冪等接口。如果是扣費、發(fā)短信、下單這類操作重試就是災難。所以工具注冊時要聲明冪等性不聲明默認不重試。5.4 版本升級后行為變異用黃金數(shù)據(jù)集守住回歸大模型上線和升級跟傳統(tǒng)代碼發(fā)版不一樣。模型價值升級了但行為可能會有你不知道的偏移。我見過某個Agent在GPT-4升級到新版本后突然把所有日期格式從12月25日改成了12/25內(nèi)部解析直接崩了。要攔截這類問題我會維護一個黃金數(shù)據(jù)集里面是100到200條真實且有代表性的任務每條都有期望輸出和允許的偏差范圍。每次模型版本升級、Prompt改動、工具Schema調(diào)整都用這個數(shù)據(jù)集跑一遍回歸看通過率掉沒掉。通過率低于95%就不能上線。另外一個良心建議Agent上線前要準備人工兜底開關。萬一生產(chǎn)環(huán)境出現(xiàn)大面積異常至少能一鍵切換到人工模式不讓異常繼續(xù)擴大。這個開關就像消防系統(tǒng)的手動閥門寧可平時不用不能沒有。6. 我的實操體會最近這個項目讓我印象最深的一件事是我們把大量的Prompt工程時間抽出來做Harness之后Agent反而變笨了但整體成功率從70%左右一路穩(wěn)定到97%以上。用戶的感受不是這AI很聰明而是這AI做事靠譜。對生產(chǎn)系統(tǒng)來說靠譜比聰明值錢得多。還有一個體會是Harness工程并不需要一步到位。你可以先做最輕量的版本在Agent外面加一層最大步數(shù)限制、工具結果校驗和全鏈路日志這三件事三天內(nèi)就能做完但效果立竿見影。再往后逐步追加狀態(tài)管理、上下文治理、熔斷機制。不要一開始就想用最重度的方案小步快跑反而更容易沉淀出真正貼合你業(yè)務的Harness。另外建議備一個故障演練日。每個月找一個流量低峰期故意把下一個工具接口調(diào)成超時看Agent的表現(xiàn)是否正常。這個做法讓我理解了一點Harness不是寫出來的是不斷被事故錘煉出來的。現(xiàn)在每次上線新工具我們都會先人為制造幾次異常場景確認兜底邏輯可靠之后才會放量。如果這篇文章能給到你的團隊一個明確的抓手pick三個最容易出問題的環(huán)節(jié)狀態(tài)管理、工具校驗、異常兜底。把這三件套做到位你的Agent就算不能吊打GPT-5也能在業(yè)務線上穩(wěn)穩(wěn)當當下地干活。