去年做第二個 Agent 項目時我差點被自己的代碼堆埋掉。當時的架構(gòu)很簡單一條鏈模型跑完接工具工具結(jié)果再喂給模型循環(huán)往復(fù)。前五十個流程內(nèi)一切正常等業(yè)務(wù)要求變成模型需要根據(jù)上游判斷決定是繼續(xù)追問還是直接收尾鏈式編排開始失控我在一個函數(shù)里塞了七八層 if-else改一處崩三處最后連自己都說不清某個分支到底在什么條件下觸發(fā)。后來我把這套東西整個推翻換成基于 Graph 架構(gòu)的 Agent Harness——把執(zhí)行流程建模成一張有向圖節(jié)點是工作單元邊是流轉(zhuǎn)條件運行時負責調(diào)度、狀態(tài)恢復(fù)和檢查點。改完以后復(fù)雜流程的改動變成了改幾條邊、加一個節(jié)點的事而不是在調(diào)用鏈里大海撈針。這篇就圍繞 Graph 架構(gòu)的 Agent Harness 展開講講它到底解決了什么問題、核心抽象怎么設(shè)計、真實需求怎么拆成一張圖以及我在落地過程中踩過的幾個比較深的坑。適合已經(jīng)做過 Agent 原型、想往可維護、可觀測、可恢復(fù)方向走的開發(fā)者也適合正在評估編排架構(gòu)、糾結(jié)要不要從鏈式切到圖式的人。1. 為什么非用 Graph 不可鏈式編排的邊界與 Graph 的解圍方式1.1 鏈式編排的最初便利與失控現(xiàn)場鏈式編排在項目起步階段非常舒服。代碼寫出來就是流程本身調(diào)用模型得到結(jié)果把結(jié)果傳給工具工具返回后再次調(diào)用模型拼接最終輸出。每一步的輸入輸出清晰測試也直觀只要把函數(shù)按順序排好一個能跑的 Agent 五分鐘就能立起來。這是我一開始選鏈式的原因也是絕大多數(shù)人從 demo 走向真實業(yè)務(wù)時的起點。但真實業(yè)務(wù)從來不是直線。比如一個客服質(zhì)檢 Agent它要先判斷用戶情緒再決定走安撫話術(shù)還是業(yè)務(wù)流程說明業(yè)務(wù)說明又分售前咨詢和售后問題售后里再分退款、換貨、投訴升級。如果用鏈式實現(xiàn)每個分支判斷都要寫在調(diào)用鏈里流程一旦超過三四層代碼里會同時出現(xiàn)根據(jù)上一輪結(jié)果決定下一步和根據(jù)工具返回決定是否繼續(xù)兩種邏輯二者交織在一起狀態(tài)散落在各個函數(shù)返回值里想追一個數(shù)據(jù)從哪兒來、被誰改過幾乎只能靠肉眼追代碼。更麻煩的是并行和回退。鏈式架構(gòu)天然只表達順序多個 Agent 并行處理同一批任務(wù)時要么加線程池維護狀態(tài)要么把并行結(jié)果手動合并而某個分支失敗后回退到上一個節(jié)點重新走這種高頻需求在鏈式里實現(xiàn)起來等于手工維護一個棧。流程稍微一變整個調(diào)用鏈重寫一遍測試用例全部失效。我在某次復(fù)盤時數(shù)過當時一個信息收集 → 分類 → 生成回復(fù) → 人工復(fù)核 → 發(fā)送的流程光狀態(tài)字段就有十幾個函數(shù)之間互相傳參有一半?yún)?shù)其實只是透傳沒人知道哪一步真正消費它。那已經(jīng)不是寫得快不快的問題了是根本不敢改。1.2 把流程當圖而不是當代碼鏈式編排的本質(zhì)是用函數(shù)調(diào)用來表達控制流而控制流一旦復(fù)雜函數(shù)調(diào)用這種表達方式就不夠用了。Graph 架構(gòu)換了一個視角流程不是下一步調(diào)用誰的代碼而是誰能從哪兒流向哪兒的結(jié)構(gòu)。在這個模型里每個節(jié)點是一個獨立工作單元處理一件事輸入輸出都是被定義好的。邊描述節(jié)點之間的依賴關(guān)系和流轉(zhuǎn)條件。分支是條件邊并行是多個節(jié)點指向同一個收束點循環(huán)是從某個節(jié)點回退到之前的節(jié)點回退就是一條反向邊。也就是說分支、并行、循環(huán)、回退這些在代碼里很難維護的控制邏輯在圖里都變成了可聲明的結(jié)構(gòu)而不是散落在 if-else 里的邏輯。我常用一個地鐵換乘的類比鏈式編排像一條只跑一輛車的單線公交乘客只能按固定站點順序走中途不能換乘、不能并線、不能折返。Graph 是地鐵網(wǎng)絡(luò)每個站點是一個節(jié)點你可以從 A 到 B、從 B 到 C也可能從 C 發(fā)現(xiàn)前面封站了回頭走 B2 線再繞到 D。修網(wǎng)絡(luò)的一條線不用把所有列車都改一遍。Graph 還帶來兩個鏈式難以匹敵的收益。一是可重放因為每個節(jié)點輸入輸出都是顯式的跑完一次可以回看數(shù)據(jù)流定位問題出在哪個節(jié)點。二是可恢復(fù)節(jié)點之間通過共享狀態(tài)傳遞數(shù)據(jù)某個節(jié)點失敗后可以從檢查點恢復(fù)而不是整條鏈從頭跑。這兩點直接決定了復(fù)雜 Agent 能不能穩(wěn)定落在生產(chǎn)環(huán)境。我見過不少團隊最初覺得 Graph 是過度設(shè)計等流程復(fù)雜到第三個月就默默切回去了——不是切回鏈式把代碼堆得更厚而是換了一套圖編排框架來用。反過來看與其等代碼失控再重構(gòu)不如在架構(gòu)選型時就把流程會變復(fù)雜這個預(yù)期提前放進設(shè)計里。2. Harness 到底是什么Graph Agent 的執(zhí)行外殼與關(guān)鍵抽象2.1 Harness 的職責邊界Graph 解決的是流程怎么表達的問題但光有 Graph 還不夠你還需要一層?xùn)|西來讓它真正跑起來并且跑得穩(wěn)、停得住、能恢復(fù)。這層?xùn)|西就是 Harness。Harness 這個詞直譯是挽具放在 AI Agent 場景里我把它理解為執(zhí)行外殼。它不負責寫提示詞不負責訓(xùn)練模型也不負責實現(xiàn)具體工具它負責的是把這些部件組裝起來之后的一切工程問題節(jié)點如何啟動、狀態(tài)如何流轉(zhuǎn)、失敗如何重試、中斷如何恢復(fù)、日志如何記錄、權(quán)限如何控制。如果沒有 HarnessGraph 只是一張描述性的圖畫得再清楚也不能自動執(zhí)行。有了 Harness圖才會變成一臺可以被調(diào)度、被監(jiān)控、被中斷、被恢復(fù)的機器。我見過一些剛好相反的做法把 Harness 當成業(yè)務(wù)框架往里塞各種業(yè)務(wù)邏輯最后圖和業(yè)務(wù)糾纏在一起改業(yè)務(wù)等于改框架。這里的原則很簡單Harness 只處理流程如何執(zhí)行不處理每個節(jié)點里到底做什么。節(jié)點自己是黑盒Harness 只需要知道節(jié)點有輸入、有輸出、可能失敗、可能超時。2.2 節(jié)點、邊、運行時三要素設(shè)計Graph Harness 的核心抽象我總結(jié)了三個節(jié)點Node、邊Edge、運行時Runtime。聽起來簡單但每部分都有需要認真設(shè)計的地方。節(jié)點的類型劃分直接影響圖的表達能力。我把節(jié)點分成幾類節(jié)點類型職責典型場景LLM 節(jié)點調(diào)用大模型處理自然語言任務(wù)意圖識別、內(nèi)容生成、總結(jié)歸納工具節(jié)點調(diào)用外部能力如數(shù)據(jù)庫、API、文件系統(tǒng)查庫存、發(fā)消息、寫文件路由節(jié)點根據(jù)輸入決定走哪條邊不產(chǎn)生業(yè)務(wù)輸出判斷繼續(xù)追問還是直接結(jié)束并行節(jié)點同時觸發(fā)多個子節(jié)點并等待全部完成多源信息收集收束節(jié)點匯總并行節(jié)點的結(jié)果合并數(shù)據(jù)把多個渠道的結(jié)構(gòu)化信息拼成一份人工確認節(jié)點暫停流程等待人類審批或輸入高危操作確認、方案審核循環(huán)邊界節(jié)點控制某個子流程的循環(huán)次數(shù)和退出條件反復(fù)優(yōu)化方案直到滿足指標邊的設(shè)計同樣重要不只是誰流向誰還分不同類型。我常用的邊有三種順序邊無條件的 A 到 B條件邊根據(jù)節(jié)點輸出判斷走 A 還是走 B數(shù)據(jù)流邊描述的是數(shù)據(jù)依賴而不是執(zhí)行依賴這類邊不觸發(fā)節(jié)點執(zhí)行只是告訴運行時B 節(jié)點的輸入依賴 A 節(jié)點的輸出主要用于狀態(tài)可見性和校驗。運行時是 Harness 的大腦。它維護一個可執(zhí)行隊列從起始節(jié)點拿到所有出邊按邊類型決定是直接入隊還是等條件滿足節(jié)點執(zhí)行完把結(jié)果寫回共享狀態(tài)再觸發(fā)新一輪出邊調(diào)度。它還要處理并行節(jié)點的并發(fā)控制、超時熔斷、重試策略、檢查點保存?？梢哉f圖只負責長得好看運行時負責跑得可靠。2.3 狀態(tài)設(shè)計集中式共享內(nèi)存與局部隔離Graph 里最容易忽略的是狀態(tài)。鏈式架構(gòu)狀態(tài)散落在變量里Graph 則適合采用集中式共享狀態(tài)整個流程共享一個頂層狀態(tài)對象每個節(jié)點從里面讀輸入、往里面寫輸出。這樣數(shù)據(jù)流變的顯式排查問題時打開狀態(tài)對象就能看清每一步產(chǎn)生了什么。但集中并不意味著所有節(jié)點共享一棵大樹。我的做法是給狀態(tài)劃分命名空間每個節(jié)點只允許讀寫自己的命名空間跨節(jié)點讀取必須走數(shù)據(jù)流邊聲明。比如多源聚合案例里信息源 A 節(jié)點的輸出放在sources.a信息源 B 放在sources.b收束節(jié)點讀取整個sources命名空間做合并。這樣既滿足集中共享又不會發(fā)生兩個節(jié)點寫同一個字段互相覆蓋。狀態(tài)還要做版本化。每次節(jié)點寫入狀態(tài)時生成一個單調(diào)遞增的版本號結(jié)合檢查點機制可以把整個流程恢復(fù)到任意節(jié)點執(zhí)行完后的狀態(tài)。這在調(diào)式、回放、異?；謴?fù)中非常有用。我經(jīng)常跑完一輪流程直接把狀態(tài)快照拉出來看每個節(jié)點寫入了什么很多時候 bug 當場就定位了。如果你發(fā)現(xiàn)自己頻繁需要手動讀寫狀態(tài)的中間層說明狀態(tài)設(shè)計有問題。應(yīng)該讓節(jié)點輸入輸出盡可能自包含中間的組裝交給收束類節(jié)點。3. 把真實需求拆成一張有向圖多源聚合 Agent 的完整案例3.1 業(yè)務(wù)需求與拆分思路用前面說的抽象來做一個具體的虛構(gòu)項目多源信息聚合與行動建議 Agent。它的任務(wù)是接收來自不同渠道的結(jié)構(gòu)化或非結(jié)構(gòu)化信息統(tǒng)一格式后檢測沖突生成一份帶優(yōu)先級的行為建議提交人工確認后再落地到下游系統(tǒng)。這個場景選它是因為它有并行多個信息源同時處理、有分支是否有沖突走不同流程、有回退人工駁回后重新生成方案、有收束多源結(jié)果合并幾乎涵蓋了 Graph 的典型能力。第一步是拆節(jié)點collect_sources并行觸發(fā)多個信息源采集節(jié)點每個節(jié)點負責一個渠道輸出原始內(nèi)容。normalize_format把原始內(nèi)容統(tǒng)一成結(jié)構(gòu)化的標準字段如時間、主體、類型、原始文本。detect_conflict檢查各來源之間是否存在沖突比如時間對不上、主體不一致。generate_plan根據(jù)標準化的信息生成行為建議方案輸出候選計劃和理由。human_review暫停流程等待人工確認或駁回意見。apply_plan方案通過后把計劃落地到下游系統(tǒng)輸出執(zhí)行結(jié)果。圖本身看起來像一段話先并行收集歸一化檢查沖突有沖突走生成方案 → 人工確認 → 落地沒沖突直接生成方案 → 人工確認 → 落地人工駁回就回到生成方案再來一次。3.2 節(jié)點、邊與狀態(tài)的具體定義圖中的節(jié)點定義需要明確輸入輸出。以normalize_format為例輸入是collect_sources輸出的原始內(nèi)容集合輸出是標準化記錄集合。這里的輸入輸出都必須走圖狀態(tài)中的命名空間不能在節(jié)點內(nèi)部偷偷引用外部變量。邊規(guī)則可以定義為條件邊detect_conflict的輸出是有沖突還是無沖突。運行時拿到這個輸出后自動決定走哪條邊——有沖突的話進入一輪沖突分析子流程或多走一次generate_plan無沖突則直接進入generate_plan生成常規(guī)方案。這個結(jié)構(gòu)最關(guān)鍵的改動是新增一個分支邏輯時我只加一條邊不用改節(jié)點內(nèi)部代碼。狀態(tài)對象長這樣偽代碼表達意圖state { sources: { source_a: None, source_b: None, source_c: None }, normalized_items: [], conflict_flag: False, conflict_details: [], draft_plan: None, review_status: pending, # pending / approved / rejected review_comment: , final_output: None }人工確認節(jié)點比較特別它不是一個常規(guī)的函數(shù)調(diào)用而是把流程掛起寫一條待辦等外部用戶通過接口提交確認結(jié)果后恢復(fù)執(zhí)行。運行時需要支持這種外部中斷后恢復(fù)的能力這也是 Harness 比普通代碼庫多出來的關(guān)鍵機制。沒做暫?；謴?fù)機制之前人工節(jié)點只能靠輪詢后來我加了基于檢查點的掛起機制簡單高效而且能記錄完整上下文。3.3 圖構(gòu)建與運行時的核心代碼形態(tài)graph 的構(gòu)建在代碼里其實很直觀。我不強調(diào)具體語言和框架用接近 Python 的偽代碼表達意圖graph Graph() graph.add_node(collect_sources, is_parallelTrue) # 并行子節(jié)點 graph.add_node(normalize_format) graph.add_node(detect_conflict) graph.add_node(generate_plan) graph.add_node(human_review, is_humanTrue) # 人工節(jié)點 graph.add_node(apply_plan) graph.add_edge(START, collect_sources) graph.add_edge(collect_sources, normalize_format) graph.add_edge(normalize_format, detect_conflict) # 條件邊detect_conflict 決定走哪條路 graph.add_conditional_edge(detect_conflict, if_is_conflict, targetgenerate_plan) graph.add_edge(generate_plan, human_review) # 人工駁回則回退到 generate_plan graph.add_conditional_edge(human_review, if_is_approved, targetapply_plan, if_elsegenerate_plan) graph.add_edge(apply_plan, END)運行時執(zhí)行時大概長這樣runtime Runtime(graph, state) runtime.run()關(guān)鍵是run()內(nèi)部不是線性調(diào)用它會維護一個待執(zhí)行隊列初始放入START節(jié)點的所有出邊節(jié)點執(zhí)行節(jié)點后根據(jù)邊規(guī)則動態(tài)出入隊。并行節(jié)點則把多個子節(jié)點同時放入隊列等全部完成后觸發(fā)收束。任何節(jié)點拋異常都會落到統(tǒng)一的重試邏輯超過閾值則暫停整圖并保存檢查點。我不在這里展開框架細節(jié)因為凡是能表達節(jié)點回調(diào) 條件邊 共享狀態(tài)能力的實現(xiàn)都可以承載這套設(shè)計。核心是思路具體選型看團隊熟悉度。3.4 為什么這樣切內(nèi)聚、可測、可恢復(fù)拆節(jié)點看著簡單真正值得講的是為什么這樣拆。首先是內(nèi)聚性。每個節(jié)點只做一件事因此每個節(jié)點可以單獨測試只給它構(gòu)造一份固定輸入看輸出是否符合預(yù)期。比如detect_conflict輸入一份標準化記錄輸出一個布爾值測試用例就是各種沖突組合不依賴任何外部模型。其次是可恢復(fù)性。假設(shè)在apply_plan這步調(diào)用下游系統(tǒng)時超時整條流程不會從頭再來檢查點機制可以把狀態(tài)恢復(fù)到review_status approved那一刻重新嘗試落地。這在真實生產(chǎn)里直接決定用戶的體感——從頭重跑幾十分鐘流程和從失敗點恢復(fù)幾秒鐘體驗差別巨大。最后是節(jié)點可復(fù)用。多個不同 Agent 可以共用normalize_format、detect_conflict這類通用節(jié)點因為節(jié)點對輸入輸出有明確約定跨項目遷移成本很低。這是我切換到 Graph 架構(gòu)后感受到的最大紅利不同業(yè)務(wù)里的大量基礎(chǔ)設(shè)施能力沉淀成了圖里的標準積木。4. 落地期間最常踩的五個 Graph Agent 坑Graph 架構(gòu)理論上是清爽的但實際用起來我踩了不少坑。挑了最典型的五個展開講每一個都是教訓(xùn)換來的。4.1 重試導(dǎo)致重復(fù)副作用工具調(diào)用不是天然冪等的有一次落地apply_plan節(jié)點向外部的任務(wù)系統(tǒng)發(fā)創(chuàng)建指令第一次請求超時運行時自動重試結(jié)果外部系統(tǒng)同時收到兩次請求產(chǎn)生了兩條重復(fù)任務(wù)。問題根源在于我把重試邏輯放在了節(jié)點外層而節(jié)點自己的調(diào)用不保證冪等。排查過程很典型我先看日志發(fā)現(xiàn)重試只發(fā)生了一次然后去外部系統(tǒng)查請求時間戳發(fā)現(xiàn)兩條記錄相差不到一分鐘再對比請求 ID確認是同一次圖執(zhí)行的兩次調(diào)用。解決方案分兩層。第一層給外部調(diào)用加冪等鍵把圖執(zhí)行的run_id和節(jié)點名組合成一個全局唯一的task_id外部系統(tǒng)靠它去重。第二層在狀態(tài)里記錄每個工具節(jié)點的執(zhí)行結(jié)果重試前先查這個節(jié)點是不是已經(jīng)成功執(zhí)行過成功了就直接復(fù)用結(jié)果不重復(fù)調(diào)用。后來我把這個邏輯抽象成冪等執(zhí)行器節(jié)點在本地狀態(tài)維護一個executed_flag執(zhí)行前檢查執(zhí)行成功立即寫入帶重試和超時。這次踩坑之后我所有的工具節(jié)點都默認帶冪等保護。4.2 循環(huán)路由沒設(shè)收斂條件Agent 自己把自己繞暈在我設(shè)計的human_review駁回回退到generate_plan的場景里原本預(yù)期最多駁回兩次就穩(wěn)定結(jié)果有一次用戶連續(xù)駁回了五次Agent 每次重新生成方案都會產(chǎn)生一組新的候選計劃狀態(tài)里的draft_plan被反復(fù)覆蓋整個流程像進入了死循環(huán)。排查時我先用日志打印了每次駁回的理由和時間發(fā)現(xiàn)每次駁回理由都不一樣也就是說不是上游數(shù)據(jù)問題而是方案本身每次都差一點塔的死循環(huán)源自于沒有對循環(huán)次數(shù)做限制。解決方案是給循環(huán)邊界加收斂控制。我在狀態(tài)里新增了迭代計數(shù)每次進入generate_plan時attempt_count 1節(jié)點內(nèi)部如果發(fā)現(xiàn)attempt_count 3就不再重新生成而是把當前方案標記為推薦但待人工強制確認走另一條邊到人工節(jié)點。同時運行時增加整體熔斷一個節(jié)點在同一個 run 里最多執(zhí)行 N 次超過 N 次直接暫停整個圖等待人工介入。循環(huán)收斂條件必須在設(shè)計階段就定好。沒有限制的循環(huán)在鏈式里最多是代碼寫得臭在 Graph 里會直接表現(xiàn)為圖跑不完對生產(chǎn)系統(tǒng)是致命的。4.3 并行節(jié)點共享狀態(tài)競爭最后一個寫入者贏并行處理多個信息源時我曾經(jīng)讓三個子節(jié)點并行寫同一個頂層字段sources.current_content結(jié)果發(fā)現(xiàn)只有最后一個完成寫入的數(shù)據(jù)保留了下來前面兩個源的信息全部丟失。我把日志打開挨個看三個節(jié)點的完成時間發(fā)現(xiàn)三個節(jié)點幾乎同時結(jié)束但狀態(tài)里只有一個值。原因很明確三個節(jié)點讀到的共享狀態(tài)是同一個對象各自往里賦值后寫的覆蓋先寫的串行的狀態(tài)模型根本無法感知并發(fā)寫入。根子上的問題是狀態(tài)設(shè)計沒有給并行節(jié)點做隔離。修復(fù)方案是改狀態(tài)結(jié)構(gòu)并行子節(jié)點只能寫自己命名空間下的字段用源 ID 做鍵比如sources.source_a、sources.source_b收束節(jié)點再去合并。這樣各寫各的不存在競爭。如果確實需要多個節(jié)點寫同一個聚合字段就得給運行時加合并策略常見做法是鎖、版本號或者寫入隊列。但說實話最省心的還是讓寫入目標分散合并交給收束節(jié)點統(tǒng)一處理。4.4 checkpoint 恢復(fù)時把外部工具也回放了一遍檢查點機制有一個隱藏陷阱狀態(tài)快照回滾沒問題但如果恢復(fù)時把已經(jīng)執(zhí)行過的節(jié)點再跑一遍外部工具會被重復(fù)調(diào)用產(chǎn)生和 4.1 類似的副作用而且更難察覺因為本地狀態(tài)里一切看起來都是正常的。有一次我主動觸發(fā)一次檢查點恢復(fù)想復(fù)現(xiàn)一個模型輸出問題結(jié)果下游發(fā)貨通知真的又發(fā)了一遍。排查花了很長時間因為不是超時重試而是我在恢復(fù)機制上只做了整個流程回到某個狀態(tài)的實現(xiàn)沒有區(qū)分狀態(tài)回滾和動作重放的區(qū)別。正確做法是檢查點只恢復(fù)狀態(tài)不重放已經(jīng)成功執(zhí)行的外部副作用節(jié)點。運行時需要在狀態(tài)里維護一個已執(zhí)行節(jié)點表記錄哪些節(jié)點已經(jīng)成功跑完、輸出是什么?；謴?fù)時從這張表里讀出歷史輸出而不是重新執(zhí)行。模型節(jié)點如果不涉及外部副作用可以安全重放但工具節(jié)點必須走執(zhí)行結(jié)果緩存 冪等的路徑。說白了檢查點機制必須搭配執(zhí)行歷史表否則你恢復(fù)的是狀態(tài)、重復(fù)的是副作用看起來日志正常、效果全錯。4.5 圖變大之后看不到圖了可視化與調(diào)試斷層圖到了十幾個節(jié)點以后我發(fā)現(xiàn)自己越來越難定位問題。以前鏈式代碼可以看調(diào)用棧Graph 架構(gòu)下節(jié)點之間不是函數(shù)調(diào)用而是狀態(tài)流轉(zhuǎn)你根本沒法用傳統(tǒng)堆棧來Debug。這個坑是最隱蔽的因為它是慢性病最開始節(jié)點少出問題很快能看出來等到節(jié)點多了每個節(jié)點內(nèi)部都有復(fù)雜邏輯狀態(tài)數(shù)據(jù)在命名空間間流動你在日志里看到一堆輸出但說不清從哪個節(jié)點流過來的。我的解法有四個方向。第一運行時必須記錄流轉(zhuǎn)軌跡每次節(jié)點執(zhí)行時都往 trace 里寫一行當前節(jié)點名、輸入狀態(tài)版本、輸出狀態(tài)版本、耗時。第二把 trace 可視化我在調(diào)試面板里看一張圖節(jié)點高亮顯示已執(zhí)行、失敗、卡住的狀態(tài)。第三支持單節(jié)點重放給定輸入狀態(tài)單獨跑一個節(jié)點看輸出不需要整個圖全部跑完。這是我最常用的調(diào)試方式幾乎取代了以前打日志的方式。第四狀態(tài) diff 功能對比兩個版本狀態(tài)之間的差異一眼看出誰改了哪個字段。沒有可視化和 trace 的圖編排節(jié)點少時無害節(jié)點一多就會讓你陷入改一個節(jié)點、跑一遍全圖、又找不到問題在哪的循環(huán)。我強烈建議在引入 Graph 架構(gòu)的第一天就把 trace 機制做上別等出了問題再補。5. 讓 Harness 真正可用可觀測、可治理以及該用和不該用 Graph 的判斷5.1 可觀測性設(shè)計從圖到軌跡前面提到 trace 和可視化這里展開說?？捎^測性對 Graph Agent 來說不是選配是標配。我從項目中期開始給運行時加了三類 trace 數(shù)據(jù)。第一類是執(zhí)行軌跡也就是哪個節(jié)點在什么時間被執(zhí)行、依賴哪些狀態(tài)、輸出是什么。第二類是耗時與 token 消耗每個 LLM 節(jié)點的調(diào)用耗時、token 數(shù)、重試次數(shù)都要記錄這樣你能清楚知道整個流程錢花在哪、時間耗在哪。第三類是狀態(tài)變更日志每個節(jié)點執(zhí)行前后的狀態(tài)版本差能自動輸出一個 JSON diff。這套數(shù)據(jù)除了方便調(diào)試還有一個更實用的用途回歸測試。我把每次 Graph 運行產(chǎn)生的 trace 保存下來作為一組行為基線下一次改完代碼再跑一遍相同輸入對比 trace 是否仍然符合預(yù)期。模型輸出可能有隨機性但流程結(jié)構(gòu)、節(jié)點順序、狀態(tài)變更應(yīng)該穩(wěn)定否則說明圖邏輯被意外改動了。對于生產(chǎn)環(huán)境我建議把 trace 和業(yè)務(wù)日志分兩個通道輸出trace 走管道業(yè)務(wù)日志進日志平臺。trace 保留最近一段時間用于回放不需要長期留全量按需歸檔即可。5.2 治理權(quán)限邊界與資源預(yù)算Graph 架構(gòu)跑起來之后我很快意識到一個問題圖里有多少個 LLM 節(jié)點就有多少個不受控的資源消耗點。如果流程里有三個模型節(jié)點每個節(jié)點內(nèi)部還悄悄調(diào)了好幾次模型最終費用會非常可觀。資源預(yù)算需要從運行時層面控制。我給每個節(jié)點設(shè)置了執(zhí)行時間上限和 token 上限超了就終止節(jié)點并返回錯誤。整張圖設(shè)一個總執(zhí)行預(yù)算當累計耗時長或 token 數(shù)達到閾值運行時自動暫停并在狀態(tài)中標記原因等待人工處理。除此之外還要看住并發(fā)數(shù)量并行節(jié)點最多同時跑幾個子節(jié)點防止一次性拉起幾十個請求把下游打掛。權(quán)限治理也同樣重要。圖中的工具節(jié)點往往有不同權(quán)限級別比如讀庫、寫庫、調(diào)用外部服務(wù)。我的做法是給每個節(jié)點聲明一個最小權(quán)限范圍運行時統(tǒng)一做鑒權(quán)節(jié)點要訪問某個資源必須本身帶對應(yīng)權(quán)限否則直接拒絕執(zhí)行。這樣即使某個 Agent 被提示詞誤導(dǎo)它所在節(jié)點的權(quán)限邊界也能限制危害面。5.3 什么時候別用 Graph不要為畫圖而畫圖Graph 架構(gòu)不是銀彈。我見過有人把三步流程硬拆成五個節(jié)點加三條邊跑起來代碼反而比鏈式更繁瑣調(diào)試也更繞。我的判斷標準很簡單如果流程是固定的、簡單的、沒有分支和循環(huán)的直接用鏈式代碼如果流程只需要一層判斷、最多兩三種分支鏈式加簡單的條件語句也能駕馭如果流程涉及分支嵌套、多源并行、循環(huán)回退、人工介入、狀態(tài)恢復(fù)或者你強烈需要把流程可視化納入治理體系Graph 才有明顯優(yōu)勢。Graph 還有一個不值得被低估的隱性成本它要求一開始就把狀態(tài)設(shè)計和節(jié)點劃分理清楚這對團隊的設(shè)計能力有要求。鏈式代碼寫錯了改一處就行圖的結(jié)構(gòu)錯了可能要重新連線甚至拆節(jié)點。所以我的建議是先在項目里用一個小流程跑通這套抽象驗證團隊熟悉度再決定要不要全面鋪開。不要因為標題看起來高級就強迫自己上 Graph——等需求復(fù)雜到鏈式真的撐不住時你自然會知道該切換了。開發(fā) Agent 一段時間后我最大的體會是真正難的地方往往不在模型調(diào)用而在于把一個復(fù)雜目標拆成一段可以驗證、可以恢復(fù)、可以收斂的執(zhí)行過程。Graph 架構(gòu)恰好逼著你這么做——每個節(jié)點有邊界每條邊有理由整個流程可以被觀察、被中斷、被恢復(fù)、被審計。我現(xiàn)在把所有新的 Agent 項目都默認按這套思路來設(shè)計哪怕一開始只有五六個節(jié)點。等流程真的復(fù)雜起來時你會發(fā)現(xiàn)已經(jīng)把地基打好了。