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