最近聊 Agent 架構(gòu)的人越來越多從 LangChain 到 Claude Code 再到各家自研的 harness 框架名字一堆但真正落到生產(chǎn)環(huán)境里我發(fā)現(xiàn)絕大多數(shù)團隊踩的坑都一樣模型跑起來了但不知道它下一步要干嘛工具接上了但不知道誰在管權(quán)限多步驟任務(wù)一長直接變成失控的亂循環(huán)。網(wǎng)上那些 demo 看著挺唬人可真要扛住線上流量、要能排查、要能灰度缺的從來不是模型本事而是工程骨架。這半年我陸續(xù)做了幾套不同規(guī)模的 Agent 系統(tǒng)從最簡單的單機腳本到要走完整個發(fā)布流程的服務(wù)最后總結(jié)下來所有花里胡哨的框架本質(zhì)都是在解決同一件事把模型的自由發(fā)揮裝進一套受控的管道里。這套管道拆開看就是 Harness、Loop、Graph 三層。不夸張地說這三層概念一旦理清楚市面上任何 Agent 框架你拿過來都能在三分鐘內(nèi)定位它在哪個層級做文章自己設(shè)計系統(tǒng)的時候也知道該在哪兒使勁。這篇文章我打算把這套三層架構(gòu)掰開揉碎從原理講到參數(shù)從選型聊到踩坑給正在做或者準(zhǔn)備做生產(chǎn)級 Agent 的同學(xué)一份可以直接抄作業(yè)的參考。1. 為什么 Agent 工程要拆成三層1.1 一次事故暴露的三個問題先說個我親眼見過的案例。有個團隊做了一個多步驟調(diào)研 Agent輸入一個商業(yè)問題讓模型自己搜索資料、總結(jié)觀點、生成報告。最開始 demo 階段一切完美因為測試問題就那么三五個模型路徑也固定。上線第一天就出了事模型在一個網(wǎng)頁搜索任務(wù)里連續(xù)調(diào)了二十多次搜索工具每次返回結(jié)果都“感覺信息不夠”然后換關(guān)鍵詞繼續(xù)搜把單月搜索 API 預(yù)算燒掉了百分之六十。用戶看到的不是報告而是一張無限轉(zhuǎn)圈的加載頁。這個事故表面看是“模型太笨”但往深了挖是三個工程問題疊加在一起。第一沒有邊界控制——模型想調(diào)多少次工具就能調(diào)多少次沒有任何外層機制對它說“停下”。第二沒有循環(huán)約束——搜索、思考、再搜索這個循環(huán)沒有最大輪數(shù)也沒有質(zhì)量標(biāo)準(zhǔn)來判定“什么時候信息夠了”。第三沒有路徑編排——這個任務(wù)本來應(yīng)該是“調(diào)研分支、評估分支、寫作分支”三個子流程結(jié)果全被塞進一個線性循環(huán)里模型在調(diào)研分支里鉆牛角尖時其他兩個分支完全沒有介入的機會。這三個問題恰好就對應(yīng)了 Harness、Loop、Graph 三層各自的職責(zé)。1.2 三層架構(gòu)各管一段用一句話概括Harness 管環(huán)境、Loop 管思考、Graph 管流程。更準(zhǔn)確一點說Harness 解決的是“Agent 能碰什么、不能碰什么”的問題它負責(zé)任務(wù)啟動、工具注冊、權(quán)限校驗、狀態(tài)讀寫、日志審計這些圍繞模型的外圍能力。Loop 解決的是“模型如何一步步逼近答案”的問題它把“思考、行動、觀察”這個循環(huán)體變成可重復(fù)執(zhí)行的機制并控制循環(huán)什么時候開始、什么時候結(jié)束。Graph 解決的是“多個循環(huán)和多個模型之間怎么配合”的問題它用節(jié)點和邊把復(fù)雜的任務(wù)組織成有向圖讓分支、合并、并行、人工介入都變成顯式設(shè)計。這三個詞在英文里其實都來自日常詞匯但在這個語境下有明確的工程含義。Harness 原意是“馬具、挽具”就是套在馬身上的那一整套皮帶用來控制方向、傳遞力量。Graph 最直觀就是圖點線相連。Loop 就是循環(huán)一個 while 語句。連起來看你給模型套上馬具Harness讓它在一個循環(huán)里干活Loop再把多個循環(huán)用圖組織起來應(yīng)對復(fù)雜任務(wù)Graph。這個比喻雖然簡單但非常貼近實際分工。1.3 這套架構(gòu)不是發(fā)明是逼出來的很多同學(xué)看到三層架構(gòu)第一反應(yīng)是“是不是又一套理論框架”。我可以負責(zé)任地說這是從無數(shù)的坑里倒推出來的產(chǎn)物。早期 Agent 框架只有一層一個 system prompt 加一個 while 循環(huán)模型自己決定一切。這種“一層流”在小任務(wù)上很好用但一旦工具超過五個、任務(wù)步驟超過十步、并發(fā)用戶超過幾十個立刻崩盤。模型會在工具之間來回跳會把同樣的錯誤重復(fù)犯三次會因為在上下文里找不到關(guān)鍵信息而開始編造結(jié)果。于是大家開始給這個循環(huán)“加護欄”這些護欄長成了 Harness 層開始給循環(huán)加“剎車和油門”變成了我們說的 Loop 工程最后發(fā)現(xiàn)一個循環(huán)解決不了一個需要多角色協(xié)作、多分支決策的任務(wù)于是把多個循環(huán)連接成圖Graph 層自然就出現(xiàn)了。這套演化路線和軟件工程里的分層思想完全一致不是誰發(fā)明了一個漂亮的理論而是復(fù)雜度到了那個程度不分層根本活不下去。理解了這一點再看任何框架都會有一種“原來你在這個層做文章”的洞察力。2. Harness 層給 Agent 套上能干活的“操作間”2.1 Harness 管的不是模型是邊界先搞清楚一個概念問題Harness 和 Agent 是什么關(guān)系。很多人以為 Harness 就是 Agent這是最常見的誤解。Agent 指的是那個有自主決策能力的智能體它核心的表現(xiàn)是“想”和“做”。Harness 不是思考的主體而是承載 Agent 的外殼它管的是思考之外的一切事情這個 Agent 能調(diào)用哪些工具、調(diào)用工具需要什么授權(quán)、每一步的輸入輸出怎么記錄、中途出現(xiàn)異常怎么恢復(fù)、用戶怎么打斷它。說得更直白一點Agent 是靈魂Harness 是身體身體不決定靈魂想什么但決定了靈魂能做什么。實際操作中Harness 最關(guān)鍵的是四個子模塊。第一個是上下文管理模塊負責(zé)把系統(tǒng)提示、歷史記錄、工具返回結(jié)果組裝成模型需要的輸入并且控制上下文的長度別讓 token 無限膨脹。第二個是工具調(diào)度模塊它維護一份工具清單把模型輸出的結(jié)構(gòu)化指令比如 JSON 參數(shù)轉(zhuǎn)成真實的函數(shù)調(diào)用然后把調(diào)用結(jié)果再塞回上下文。第三個是權(quán)限與審計模塊它決定某個工具在當(dāng)前狀態(tài)下能不能被調(diào)用同時把每次調(diào)用的請求、響應(yīng)、耗時全部落到日志里。第四個是會話與狀態(tài)模塊它管理多輪對話的狀態(tài)用戶切換對話、任務(wù)中斷恢復(fù)都要靠它。這四個模塊聽起來平平無奇但缺任何一個都會出大事。沒有上下文管理長任務(wù)跑一半就報“超出上下文限制”沒有工具調(diào)度模型輸出的參數(shù)和函數(shù)簽名對不上報錯率居高不下沒有權(quán)限審計模型誤刪數(shù)據(jù)你都不知道是誰刪的沒有狀態(tài)管理用戶刷新一下頁面整個任務(wù)就得從頭來過。2.2 工具注冊、權(quán)限和審計Harness 設(shè)計得好不好一半看工具注冊的規(guī)范性。我見過的失敗案例里最常見的就是工具接入方式太隨意有人直接給模型塞了一堆 Python 函數(shù)文檔讓模型“自己看著辦生成參數(shù)”。結(jié)果模型生成 json 參數(shù)經(jīng)常類型不對、字段拼錯。后來我把所有工具都改成嚴(yán)格定義的 JSON Schema每個參數(shù)都有類型、取值范圍、示例值模型調(diào)用成功率立刻從七成漲到九成五以上。工具 Schema 是 Harness 層最重要的“接口契約”它就像是給模型的一份工具使用說明書。定義 Schema 的時候有幾條原則值得記住參數(shù)名要跟真實業(yè)務(wù)名詞保持一致別搞“a1、b2”這種縮寫每個參數(shù)都要寫清楚默認(rèn)值和邊界條件比如“日期范圍默認(rèn)最近 30 天最大不超過 365 天”有依賴關(guān)系的參數(shù)要明確說明比如“調(diào)用轉(zhuǎn)賬接口之前必須先調(diào)用身份驗證接口”。這些話模型都會認(rèn)真讀你寫得不清楚它就會犯錯。權(quán)限控制我建議走“默認(rèn)拒絕按需開放”的策略。比如一個 Agent 同時有搜索工具、數(shù)據(jù)庫查詢工具和文件刪除工具那在初始狀態(tài)下應(yīng)該只開放只讀類工具寫操作和刪除操作必須在用戶明確授權(quán)之后才動態(tài)加入工具列表。這個策略聽起來簡單但是很多團隊圖省事把所有工具一股腦全塞給模型然后出問題再怪模型不聽話。實際上模型就是“給什么工具就會用什么工具”你不給它刪除工具的把手它想刪也沒轍。審計日志是另一個容易被忽略的模塊。我個人的習(xí)慣是Agent 的每一次工具調(diào)用都記錄這樣一條結(jié)構(gòu)化日志任務(wù) ID、當(dāng)前動作、工具名稱、入?yún)⒄?、出參摘要、耗時、Token 消耗、是否成功。這些日志不用多花哨但要能支撐兩件事一是出問題時能快速回放整個任務(wù)軌跡二是在調(diào)參時能統(tǒng)計工具調(diào)用成功率、單步耗時和平均循環(huán)輪數(shù)。沒有審計日志的 Agent 就像是沒裝行車記錄儀的車出事全憑嘴說。2.3 從裸調(diào) API 到 Harness 框架很多早期開發(fā)者做 Agent 就是直接調(diào)用大模型 API寫個循環(huán)丟一個 system prompt 就完事了。這種裸調(diào)方式在實驗階段完全沒問題但生產(chǎn)環(huán)境里你會發(fā)現(xiàn)大量工作其實是在重復(fù)造輪子你要寫 token 計數(shù)和截斷、要寫參數(shù)解析和異常重試、要寫并發(fā)控制和隊列、要寫慢日志和告警。這些代碼跟業(yè)務(wù)邏輯一點關(guān)系都沒有但每一項都影響系統(tǒng)能不能穩(wěn)定跑下去。于是出現(xiàn)了各種 Harness 框架把我上面說的四個子模塊打包成可復(fù)用的產(chǎn)品。最近很火的 DeepSeek Harness、Claude Code 里的 Agent Skills、社區(qū)里的各類 skill 插件本質(zhì)上都是在 Harness 層做文章。它們把工具注冊、技能加載、權(quán)限配置、會話恢復(fù)這些能力做成了一套標(biāo)準(zhǔn)化流程讓開發(fā)者不用從零開始寫外圍設(shè)施。我自己的體會是做原型可以裸調(diào) API但決定長期維護的話盡早遷到一個 Harness 框架上省下的不是開發(fā)時間而是后期跟基礎(chǔ)設(shè)施搏斗的精力。但框架不是上了就萬事大吉。很多 Harness 框架自帶默認(rèn)配置非常適合 demo但到了生產(chǎn)環(huán)境你需要改的地方非常多內(nèi)置的 prompt 模板可能和你的業(yè)務(wù)場景沖突、默認(rèn)超時時間可能太短、日志格式可能不滿足你的監(jiān)控系統(tǒng)要求。所以我建議把這層看作“可替換的底座”在上面做一層薄薄的封裝把你們公司的工具接入規(guī)范、權(quán)限模型、審計標(biāo)準(zhǔn)確定下來這樣就算底層框架換了上面的業(yè)務(wù)代碼不用動。2.4 自己寫一個極簡 Harness 的要點如果你不想一開始就依賴重量級框架直接手寫一個最小 Harness 也能跑大概需要四五十行代碼。核心結(jié)構(gòu)就三部分工具字典、循環(huán)器、觀察者。工具字典存放工具名到實際函數(shù)的映射循環(huán)器負責(zé)跑模型和調(diào)度工具觀察者負責(zé)記錄日志和校驗權(quán)限。我建議新手可以先寫一個這樣的最小實現(xiàn)把“模型調(diào)用、工具執(zhí)行、結(jié)果回填”這個鏈路親手跑通再考慮引入框架。這樣你對后面遇到的每一個抽象概念都會有一個實體感知。這里有一個技術(shù)選型問題用 Python 還是用 Rust。如果是團隊已有 Python 技術(shù)棧、工具生態(tài)依賴 Pandas 這些庫那閉眼選 Python開發(fā)效率優(yōu)先。但如果你要做一個高并發(fā)、低延遲的 Agent 網(wǎng)關(guān)Rust 的優(yōu)勢就體現(xiàn)出來了內(nèi)存安全、無 GC 停頓、異步并發(fā)能力極強。我見過有人用 Rust 把 Agent 的單次循環(huán)開銷壓到了幾毫秒級別而同樣的邏輯在 Python 里光解釋器開銷就幾十毫秒。但 Rust 的代價是開發(fā)效率低尤其是和 AI 相關(guān)的生態(tài)還有不少坑。我的建議是你如果是做業(yè)務(wù)集成用 Python如果是做中間件和網(wǎng)關(guān)用 Rust兩者之間用消息隊列或者 gRPC 通信各取所長。3. Loop 層循環(huán)才是 Agent 的思考引擎3.1 ReAct 循環(huán)到底在循環(huán)什么Agent 的核心思考模式其實就是 ReActThought思考、Action行動、Observation觀察三者不斷循環(huán)。模型先看當(dāng)前上下文產(chǎn)生一個思考說明“我現(xiàn)在需要獲取什么信息”然后把這個思考轉(zhuǎn)成一個動作——通常是調(diào)用某個工具工具返回結(jié)果作為觀察模型再基于觀察產(chǎn)生下一步思考。這個循環(huán)不斷重復(fù)直到模型認(rèn)為任務(wù)完成。這個循環(huán)的本質(zhì)可以理解成“模型在外部世界做試驗”它不確定某個假設(shè)對不對就調(diào)一次工具驗證一下拿到結(jié)果再調(diào)整下一步。它跟人類解決問題的模式很像我們查資料寫報告也是“先想、再搜、再看結(jié)果、再寫”。但有個關(guān)鍵區(qū)別人的記憶容量幾乎是無限的而模型的上下文窗口是有限的錢包每多一次循環(huán)就多吃一筆 token循環(huán)越長成本越高出錯的概率也越大。所以 Loop 層真正的工程量其實就三個字控得住。控得住長度、控得住次數(shù)、控得住方向。長度用上下文管理來控制超過閾值就做摘要壓縮次數(shù)用最大迭代上限來控制超過就強制終止方向用路由判斷來控制一旦識別出當(dāng)前循環(huán)陷入重復(fù)動作就觸發(fā)放棄、換路徑或者求助人工。這三個控制點就是 Loop Engineering 的核心內(nèi)容。3.2 終止條件防止循環(huán)變成死循環(huán)循環(huán)最怕的是退不出來。你給模型一個開放式任務(wù)比如“改進這段文案”它會覺得永遠有改進空間一直在原地打轉(zhuǎn)。所以我設(shè)計 Loop 的時候第一個要定死的參數(shù)就是最大迭代次數(shù)max_iterations。大部分工具調(diào)研性任務(wù)10 到 15 輪足夠完成如果是復(fù)雜報告生成類任務(wù)30 輪左右也到頭了。我一般會設(shè)置成 15 作為默認(rèn)值線上任務(wù)再根據(jù)歷史統(tǒng)計調(diào)整到覆蓋 99% 的完成區(qū)間剩下 1% 的特例就直接終止并轉(zhuǎn)入人工處理通道。除了硬性次數(shù)還要有“軟性終止條件”。我常用的做法是讓模型在思考里輸出一個“任務(wù)完成置信度”字段0 到 1 之間。當(dāng)置信度超過閾值比如 0.9而且最近兩輪都沒有調(diào)用新工具就判定可以結(jié)束。這個“兩輪無新工具調(diào)用”的規(guī)則很實用可以防止模型嘴上說著“快完成了”手里卻還在一遍遍調(diào)用同一類工具。本質(zhì)上這是一個加權(quán)判斷完成置信度高、動作頻率低就收尾置信度低但動作還在變就繼續(xù)置信度低且動作開始重復(fù)就趕緊中斷。終止之后還有一個容易被忽略的操作寫結(jié)論。讓模型在循環(huán)結(jié)束前把當(dāng)前所有觀察結(jié)果壓縮成一段結(jié)論性摘要而不是直接把原始工具結(jié)果一股腦塞給下游。這樣既方便人工審查也能讓下游模塊拿到高質(zhì)量輸入。我管這一步叫“循環(huán)收口”它直接決定了后續(xù) Graph 層各節(jié)點之間的信息傳遞質(zhì)量。3.3 Loop Engineering把單循環(huán)升級為多窗口并行理解了單循環(huán)之后繼續(xù)看 Loop Engineering 這個詞。它不只是“調(diào)教一個循環(huán)”而是“工程化地管理多個循環(huán)”。典型場景是一個 Agent 在主循環(huán)里拆出了三個子問題跑了一輪搜索發(fā)現(xiàn)三個方向彼此獨立于是它可以并行開三個子循環(huán)讓三個模型實例同時去調(diào)研最后把結(jié)果匯總回主循環(huán)。這種多窗口并行能大幅縮短響應(yīng)時間但也引入了新問題三個子循環(huán)分別消耗多少 token如果其中一個子循環(huán)死掉了其他兩個是要等它還是要取消匯總沖突的結(jié)論以誰為準(zhǔn)我的實踐方案是這樣的用一張共享任務(wù)表管理所有子循環(huán)。每個子循環(huán)在表里注冊自己的狀態(tài)pending、running、done、failed主循環(huán)定期輪詢這張表一旦發(fā)現(xiàn)某個子循環(huán)失敗就決定是重試還是帶部分結(jié)果繼續(xù)。并行數(shù)量一開始不要貪建議控制在 3 到 5 路太多會讓總體 token 消耗呈線性爆炸也會給下游工具 API 造成壓力。先串行跑通再并行優(yōu)化這是一個穩(wěn)妥的路子。還有一個小技巧叫“觀察共享”如果兩個子循環(huán)要查詢的數(shù)據(jù)是同一類就讓 Harness 層做一層緩存第二個子循環(huán)直接讀緩存結(jié)果不再重復(fù)調(diào)用工具。很多團隊把這個職責(zé)放在 Graph 層做全局緩存我試下來放在 Loop 層做更輕量因為它不需要感知整個圖的結(jié)構(gòu)只需要在同一個循環(huán)家族內(nèi)做結(jié)果復(fù)用實現(xiàn)成本低收益卻很直觀。4. Graph 層把循環(huán)升級成可編排的有向圖4.1 循環(huán)的局限與圖的出現(xiàn)單循環(huán)和并行循環(huán)能覆蓋不少場景但有一個硬傷它們用代碼寫死了流程。比如我要做一個客服 Agent流程是“用戶提問 - 判斷意圖 - 查詢訂單 - 查詢物流 - 生成回復(fù)”。用循環(huán)寫所有分支都藏在 if-else 里改一次流程就要改代碼、發(fā)版本而且流程內(nèi)部的每一步都難以監(jiān)控和單獨測試。更麻煩的是當(dāng)流程里需要出現(xiàn)“人工介入”節(jié)點時純循環(huán)很難表達“在這里停下等人工答復(fù)后繼續(xù)”。Graph 層的核心思路就是把流程從代碼里抽出來變成一張顯式的有向圖。每個節(jié)點是一個獨立執(zhí)行單元——可能是模型推理、工具調(diào)用、條件判斷或者人工任務(wù)每條邊則定義了從哪個節(jié)點到哪個節(jié)點的流轉(zhuǎn)條件。這樣做的好處是流程可讀、可分析、可單獨編排你可以把整張圖畫出來給非技術(shù)同事看他們也能看懂任務(wù)走到哪一步了。這就是 Graph 在 Agent 工程里的價值它不是為了炫技而是為了讓復(fù)雜流程變得可管理。從我實際使用的經(jīng)驗看Graph 層帶來的最大收益不是執(zhí)行效率而是可觀測性和可維護性。節(jié)點之間不互相依賴全局變量每個節(jié)點只消費上游傳入的數(shù)據(jù)結(jié)構(gòu)輸出也統(tǒng)一為同一個數(shù)據(jù)結(jié)構(gòu)。這樣每個節(jié)點都能單獨寫單測、單獨灰度、單獨回滾。哪怕某一個節(jié)點換了模型只要輸入輸出協(xié)議不變整條鏈路都不用動。4.2 節(jié)點、邊與條件路由Graph 的基本組成是節(jié)點和邊。節(jié)點按職能可以分成五類Start 節(jié)點負責(zé)接收輸入并初始化上下文模型節(jié)點負責(zé)某一段推理或生成任務(wù)工具節(jié)點負責(zé)調(diào)用外部 API 或數(shù)據(jù)庫路由節(jié)點負責(zé)做條件判斷根據(jù)輸入數(shù)據(jù)決定下一步走哪條邊人工節(jié)點負責(zé)暫停流程等待人工審核確認(rèn)。一套完整的 Agent 圖至少會組合使用這五類中的多數(shù)很多場景甚至五類都要用。邊不是簡單的“從 A 到 B”它要攜帶轉(zhuǎn)移條件。我剛用 Graph 時犯過一個錯誤把所有邊都設(shè)成無條件轉(zhuǎn)移結(jié)果流程像鐵軌一樣直來直去圖和數(shù)據(jù)毫無差別。后來我意識到每條邊都應(yīng)該有一個判斷函數(shù)輸入是當(dāng)前節(jié)點產(chǎn)出的結(jié)果對象輸出是布爾值或路由標(biāo)簽。比如訂單查詢節(jié)點返回“訂單存在”則走向查詢物流節(jié)點返回“訂單不存在”則走向客服回復(fù)節(jié)點。路由節(jié)點本質(zhì)上是把多個條件邊集中到一個節(jié)點上執(zhí)行讓圖看起來更整潔。給一個非常小的圖示例。用字典結(jié)構(gòu)描述節(jié)點和邊的關(guān)系這是我最常用的表達方式簡潔直觀graph { start: {next: intent_classify}, intent_classify: { use_model: gpt-4o-mini, routes: [ {condition: 意向為查訂單, next: query_order}, {condition: 意向為找人工, next: human_handoff}, {default: True, next: chat_fallback} ] }, query_order: {tool: order_api}, human_handoff: {type: human_review}, chat_fallback: {tool: general_reply}, }這個示例看著簡單但它說明了一個關(guān)鍵點Graph 節(jié)點需要聲明自己要什么資源模型、工具、人工邊的條件決定流程走向整張圖以數(shù)據(jù)驅(qū)動的方式運行。生產(chǎn)級的 Graph 還會給每個節(jié)點配 retry 策略、超時時間和獨立的日志 tag比如query_order節(jié)點配 3 次重試、30 秒超時日志 tag 是order_service。這樣每次出問題你直接從日志里按 tag 過濾定位非常快。4.3 圖構(gòu)建工具與商圖的落地思路Graph 這么有用自然有配套工具。最典型的是 LangGraph 這類編程式的編排框架它把圖構(gòu)建的過程變成“添加節(jié)點、添加邊、編譯執(zhí)行”。也有一些可視化平臺走拖拽建圖路線類似 Snap 的 Graph Builder 那類產(chǎn)品——雖然它本身是內(nèi)容創(chuàng)作工具但它把“節(jié)點-連線-條件”的交互做得極其順暢我一度從它的交互設(shè)計里借鑒了不少靈感?？梢暬▓D的好處是業(yè)務(wù)人員也能參與流程圖設(shè)計但難度在于生產(chǎn)環(huán)境里的圖不可能只靠拖拽完成復(fù)雜的條件邏輯還是得回到代碼里寫。再聊一個 Graph 層面比較進階的概念商圖quotient graph圖論里它指把圖中的節(jié)點按某種等價關(guān)系聚合后形成的簡化圖。這個概念在 Agent 編排里非常實用。舉個例子一張客服流程圖有二十個節(jié)點其中三個節(jié)點都在做“校驗用戶身份”這件事只是針對不同入口。你可以把這三個節(jié)點聚合成一個“身份校驗”抽象節(jié)點整張圖瞬間從二十個節(jié)點縮到十五個結(jié)構(gòu)清晰很多。商圖思維的本質(zhì)是“找重復(fù)、提公共”它讓大圖不至于失控。實際操作商圖時我會先從日志里統(tǒng)計節(jié)點調(diào)用頻率和相鄰關(guān)系把那些“同進同出”的節(jié)點挑出來判斷它們是不是同一類職責(zé)如果是就直接合并成一個公共節(jié)點然后在公共節(jié)點上做統(tǒng)一的緩存和監(jiān)控。這樣既減少了圖的復(fù)雜度也把重復(fù)的 token 成本砍掉了。4.4 什么場景必須上 GraphGraph 不是銀彈有些任務(wù)用單循環(huán)就能干得很好上了 Graph 反而增加復(fù)雜度。我總結(jié)了一下以下三個信號出現(xiàn)時你就該考慮從 Loop 升級到 Graph。第一個信號是流程分支超過三個。諸如“根據(jù)用戶身份走不同流程”“根據(jù)故障類型走不同修復(fù)路徑”這種多分支邏輯用 if-else 寫會非常難維護而 Graph 能把每個分支都畫成顯式的路徑一眼看穿。第二個信號是需要人工介入閉環(huán)?？头徍恕?nèi)容合規(guī)、高危操作確認(rèn)這些場景要求流程能在某個節(jié)點停下來等人工沒有 Graph 節(jié)點抽象你只能用一個全局 interrupt 標(biāo)志手動控制特別容易出錯。第三個信號是同一個 Agent 需要復(fù)用能力。比如你在做一個資料助理搜索能力同時被“查新聞”“查競品”“查內(nèi)部 wiki”三個流程復(fù)用Graph 能把“搜索”做成一個公共節(jié)點三個流程各自引用它改搜索邏輯時只需改一處。順便提一個容易混淆的概念QT Quick 的 Scene Graph。它也是“圖”但它管理的是渲染場景里的繪制元素節(jié)點之間是空間關(guān)系、層級關(guān)系而在 Agent 工程里 Graph 管理的是執(zhí)行流轉(zhuǎn)關(guān)系、控制流關(guān)系。兩者形態(tài)相似、目的完全不同。如果面試時被問到能一句話說清這個區(qū)別基本就能證明你對 Graph 的理解不是停留在名字層面。5. 三層架構(gòu)的生產(chǎn)實踐選型、參數(shù)與代碼骨架5.1 用幾層才合適三層架構(gòu)是一個完整參考模型但不代表每個項目一開始就要上滿三層。我個人的選型決策是這樣如果任務(wù)是“單次問答 最多一次工具調(diào)用”比如天氣查詢、計算器那就只上 Harness 層甚至 Harness 都可以簡化到只做工具注冊如果任務(wù)是“多步推理 多次工具調(diào)用”比如查資料寫摘要、做數(shù)據(jù)分析報告就上 Harness Loop 兩層如果任務(wù)是“多角色協(xié)作 多分支流程 人工介入”比如客服工單全流程處理那就三層全上。這里要特別說一句上 Graph 的前提是你的流程已經(jīng)穩(wěn)定絕不是開發(fā)初期就畫一張大圖。我見過不少團隊一開始就搭了十幾節(jié)點的圖結(jié)果需求一變圖天天改開發(fā)全耗在連線上了。更務(wù)實的做法是先用 Loop 層把單個 Agent 的循環(huán)調(diào)通、調(diào)出穩(wěn)定的執(zhí)行效果再從日志里發(fā)現(xiàn)哪些步驟出現(xiàn)了分支、出現(xiàn)了重復(fù)把這些真實出現(xiàn)的結(jié)構(gòu)性問題抽象成 Graph 節(jié)點。換句話說Graph 是從 Loop 里長出來的不是拍腦袋畫出來的。5.2 關(guān)鍵參數(shù)設(shè)計與成本估算Agent 生產(chǎn)化的核心參數(shù)其實就那幾個max_iterations最大循環(huán)輪數(shù)、timeout單輪超時、max_tokens單次生成上限、temperature溫度、retry_limit工具重試次數(shù)。我給一套默認(rèn)值供參考參數(shù)默認(rèn)值說明max_iterations15調(diào)研型任務(wù)默認(rèn) 15 輪復(fù)雜任務(wù) 30 輪封頂timeout30s單輪模型調(diào)用或工具調(diào)用的超時時間max_tokens2048單次模型生成上限推薦任務(wù)可設(shè) 4096temperature0.2生產(chǎn)環(huán)境偏低工具調(diào)用類任務(wù)甚至可設(shè) 0retry_limit3工具調(diào)用失敗重試次數(shù)指數(shù)退避間隔context_window32k上下文窗口上限超過則觸發(fā)摘要壓縮這些參數(shù)不能拍腦袋要從真實數(shù)據(jù)統(tǒng)計里來。一個簡單的估算方法假設(shè)你觀察了 100 個成功案例平均每個任務(wù)跑 8 輪循環(huán)每輪消耗輸入 token 約 12000上下文逐步累積、輸出 token 約 500那么單個任務(wù)平均消耗約8 * (12000 500) 100000 token。再乘以用戶訪問量和模型單價你就能算出單日成本上限。這套計算我建議每個團隊都做一遍很多人在 Agent 上花了冤枉錢就是因為從沒算過“一次完整任務(wù)到底燒多少 token”。還有一個細節(jié)上下文增長策略。如果不做控制第 8 輪的輸入 token 會是第 1 輪的數(shù)倍。我常用的做法是“前 6 輪保留完整歷史之后的舊輪次做摘要壓縮”這樣長任務(wù)的 token 消耗不會線性爆炸。壓縮摘要的動作本身也要消耗一次生成 token但通常比保留完整原文便宜得多回退風(fēng)險也更小。5.3 一個最小三層架構(gòu)的代碼骨架給一個能跑通的最小骨架用 Python 寫重點看結(jié)構(gòu)不用糾結(jié)細節(jié)。Harness 管工具和權(quán)限Loop 管循環(huán)Graph 管流程# harness.py - 外殼層 class Harness: def __init__(self, tools: dict, max_iterations: int 15): self.tools tools self.max_iterations max_iterations self.audit_log [] def execute_tool(self, name: str, args: dict): if name not in self.tools: raise ValueError(f工具 {name} 未注冊) self.audit_log.append({tool: name, args: args}) return self.tools[name](**args) # loop.py - 循環(huán)層 class LoopEngine: def __init__(self, model, harness: Harness): self.model model self.harness harness def run(self, task: str, memory: list, max_stepsNone): max_steps max_steps or self.harness.max_iterations for step in range(max_steps): response self.model.plan(task, memory) if response[action] finish: return {status: done, answer: response[output]} try: tool_result self.harness.execute_tool( response[action], response[args]) except Exception as e: tool_result {error: str(e)} memory.append({step: step, **response, result: tool_result}) return {status: timeout, partial: memory} # graph.py - 圖編排層 class GraphRunner: def __init__(self, nodes: dict, edges: list): self.nodes nodes self.edges edges def run(self, start_input: dict): current start payload start_input while current ! end: node self.nodes[current] payload node.execute(payload) for edge in self.edges: if edge[from] current and edge[condition](payload): current edge[to] break return payload這個骨架非常簡略但它體現(xiàn)的職責(zé)邊界是準(zhǔn)確的Harness 不關(guān)心任務(wù)是什么只負責(zé)工具調(diào)用的安全與記錄Loop 不關(guān)心流程圖長什么樣只負責(zé)循環(huán)的啟動和終止Graph 不關(guān)心模型用什么 prompt只負責(zé)節(jié)點間數(shù)據(jù)怎么流轉(zhuǎn)。三層各自干好一件事組合起來就能承載復(fù)雜的業(yè)務(wù)邏輯。生產(chǎn)環(huán)境在這個骨架上加緩存、加觀測、加失敗重試就好核心邊界不用動。6. 生產(chǎn)踩坑實錄與排查技巧6.1 循環(huán)引用報錯與狀態(tài)序列化先說一個離 Graph 最近的坑。你做一個帶狀態(tài)的 Agent希望把整個執(zhí)行狀態(tài)緩存起來比如把圖節(jié)點的 payload 寫進 Redis 或存成 JSON 文件結(jié)果一序列化就報錯self referencing loop detected for property mem_memberinfo with type system...。這類報錯我在 .NET 環(huán)境遇到過最典型的版本本質(zhì)是對象存在循環(huán)引用序列化器無法打破這個環(huán)。這個問題的根源通常是你把模型的 response、工具函數(shù)的引用或者某個 manager 對象直接塞進了 payload而這些東西又反向持有 GraphRunner 的引用。解決方案有兩個。第一個方案是在定義節(jié)點數(shù)據(jù)結(jié)構(gòu)時只保留純數(shù)據(jù)字段絕不塞函數(shù)引用和模型句柄工具和模型都通過 Harness 層按名稱索引不直接放進 payload。第二個方案是序列化時配置循環(huán)引用處理JSON.NET 里設(shè)ReferenceLoopHandling.IgnorePython 里用自定義編碼器跳過不可序列化字段。但我要提醒一句處理掉報錯只是治標(biāo)治本還是設(shè)計數(shù)據(jù)結(jié)構(gòu)時保持“payload 即純數(shù)據(jù)”。6.2 死循環(huán)與 token 爆炸死循環(huán)是 Loop 層最常見的線上事故。表現(xiàn)是任務(wù)一直不結(jié)束、工具調(diào)用次數(shù)持續(xù)增長、用戶側(cè)看到無限轉(zhuǎn)圈。排查的第一步不是看代碼而是看審計日志里的“重復(fù)動作”統(tǒng)計如果模型連續(xù)三輪以上調(diào)用同一工具且參數(shù)幾乎一樣基本可以判定它陷入了“原地打轉(zhuǎn)”。這通常是因為上下文里缺少一個“你已經(jīng)試過這個方案結(jié)果無效”的信號模型把前一步的結(jié)果忘掉了或者沒理解。我的兩個保險做法一是在每輪工具結(jié)果前面加一個狀態(tài)提示字段格式是“第 N 次嘗試此前結(jié)果摘要xxx如果本次結(jié)果與之前相同請不要再重復(fù)此動作”給模型一個顯式的記憶錨點。二是在代碼層面實現(xiàn)“動作去重”——檢測到同一工具同參數(shù)已調(diào)用過一次就在本輪直接攔截并在返回結(jié)果里注明“該調(diào)用已執(zhí)行過結(jié)果同上”。后者更硬核不依賴模型自覺。Token 爆炸通常和上下文壓縮策略失配有直接關(guān)系。明明設(shè)置了摘要壓縮為什么還是爆大概率是你只在代碼里寫了壓縮函數(shù)但沒有在模型 prompt 里告訴它“舊記憶已被壓縮細節(jié)可能丟失”。模型不理解壓縮語義一旦需要細節(jié)又會去重新調(diào)用工具查詢反而多燒一輪。解決辦法是壓縮時保留結(jié)構(gòu)化摘要包含關(guān)鍵結(jié)論、數(shù)字、引用來源而不是壓縮成自然語言散文這樣模型再需要細節(jié)時可以直接用摘要里的數(shù)據(jù)不必重新查詢。6.3 框架安裝、內(nèi)網(wǎng)部署與權(quán)限失控Harness 框架本身也會坑人。很多社區(qū)框架倚靠在線倉庫安裝依賴到了內(nèi)網(wǎng)環(huán)境就裝不上。DeepSeek Harness 這類項目我見過最多的求助就是“安裝失敗”“依賴沖突”“沒法離線部署”。我的經(jīng)驗是生產(chǎn)環(huán)境部署這類框架之前一定要做三件事第一在隔離環(huán)境里生成完整的依賴鎖文件第二把所有依賴包預(yù)先下載到本地離線倉庫內(nèi)網(wǎng)安裝時直接用本地源不要現(xiàn)場拉取第三鎖定框架版本不要追新因為你不知道上游哪次提交會改掉默認(rèn)行為。權(quán)限失控是 Harness 層最恐怖的事故。模型拿到了數(shù)據(jù)庫寫權(quán)限一次 prompt 注入就可能導(dǎo)致數(shù)據(jù)被清空。雖然聽起來像安全競賽題但我見過真實案例一個 Agent 被用戶輸入誘導(dǎo)調(diào)用了管理接口關(guān)閉了某租戶的服務(wù)。從那之后我定了一條鐵律凡是寫操作、刪除操作、管理操作一律要走人工節(jié)點確認(rèn)Graph 層必須在這些節(jié)點的輸出上掛“人工審批”邊。模型可以高度自主地做只讀分析但要動“真金白銀”的狀態(tài)必須有人按下確認(rèn)鍵。6.4 測試與灰度策略Agent 的測試和傳統(tǒng)接口測試完全是兩回事同一個輸入模型可能給出不同的輸出路徑。所以我不追求“斷言輸出一致”而是斷言“路徑合理、結(jié)果結(jié)構(gòu)正確、關(guān)鍵詞覆蓋”。具體做法是錄制回放把線上真實的工具調(diào)用序列錄下來回放時用 Mock 替代真實工具讓模型跑出它的動作序列然后用規(guī)則判斷動作序列是否落在預(yù)期區(qū)間。比如“用戶咨詢訂單過期”這個場景預(yù)期動作序列應(yīng)該包含“查詢訂單”“判斷狀態(tài)”不能直接跳到“生成道歉話術(shù)”?；叶劝l(fā)布時我用的是“影子模式”。新模型或者新流程上線前把真實的線上流量復(fù)制一份到影子環(huán)境跑同一批請求但影子環(huán)境的結(jié)果只記賬不執(zhí)行真實動作比如不真發(fā)短信、不真改配置。對比影子結(jié)果和線上結(jié)果看新邏輯有沒有引入錯誤動作。這個模式尤其適合 Graph 層改動因為你改的可能只是某一個節(jié)點影子跑一周就能看出整條鏈路的穩(wěn)定性變化比直接全量發(fā)布穩(wěn)妥得多。另外一個很實用的小技巧給每個 Agent 任務(wù)加一個“trace_id”貫穿 Harness、Loop、Graph 三層日志。這樣任何一層出了問題都能從 trace_id 拉出全鏈路的動作軌跡。沒有這個 ID排查問題就是大海撈針有了它問題定位基本按分鐘計。7. 做了三個生產(chǎn)級 Agent 后的三點體悟第一點體會是功能的邊界比模型的能力重要得多。模型再聰明如果沒有 Harness 管住工具和權(quán)限它在線上就是在裸奔。先把“不能讓模型做的事”寫清楚產(chǎn)出比調(diào) prompt 高得多。第二點體會是先讓 Loop 穩(wěn)定再談 Graph。每次看到有人一上來就搭一張二十個節(jié)點的流程圖我都替他捏把汗。Graph 應(yīng)該是從真實的循環(huán)日志里長出來的是結(jié)構(gòu)提煉的結(jié)果不是設(shè)計稿的抄寫。沒有穩(wěn)定的單循環(huán)再漂亮的圖也跑不起來。第三點體會是不管哪一層都要給“人工介入”留一個口子。自動化的盡頭永遠需要人來看一眼哪怕只是在高風(fēng)險節(jié)點上點一個確認(rèn)按鈕。這個口子不是流程的退步它是系統(tǒng)真正敢上線的前提。我做的任何一個 Agent上線前都會先檢查一件事如果這個 Agent 徹底失控需要幾步能把它停下來如果答案超過兩步我就知道這系統(tǒng)還不到發(fā)布的時候。