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