現(xiàn)Multi-Agent Supervisor模式)
最近在搞一個(gè) Java 服務(wù)里的多智能體協(xié)作需求需要在同一個(gè)進(jìn)程里跑幾個(gè)職責(zé)不同的 Agent再由一個(gè) Supervisor 統(tǒng)一調(diào)度、分配任務(wù)。最早我用 Python 版的 LangGraph 搭原型邏輯很快跑通但到了交付階段團(tuán)隊(duì)不想為一個(gè)小功能額外引一套 Python 運(yùn)行時(shí)于是轉(zhuǎn)向 LangGraph4j。折騰了兩周我把 Multi-Agent Supervisor 模式完整落地在 Spring Boot 服務(wù)里這里記錄一下完整的設(shè)計(jì)思路、關(guān)鍵代碼、踩過(guò)的坑以及很多人糾結(jié)的“現(xiàn)在到底用 Spring AI 還是 LangGraph4j”這個(gè)問(wèn)題。1. 為什么在 JVM 團(tuán)隊(duì)里做 Multi-Agent我最終選了 LangGraph4j1.1 我的場(chǎng)景需要一個(gè)“老板”來(lái)分活的 Agent 系統(tǒng)我做的業(yè)務(wù)是一個(gè)工單助手用戶提交一個(gè)問(wèn)題系統(tǒng)要決定是去查知識(shí)庫(kù)、還是生成一段代碼、還是讓用戶補(bǔ)充信息最后匯總成答案。最初我用一個(gè)大 prompt 把“理解意圖、檢索、生成、總結(jié)”全塞給一個(gè) Agent看起來(lái)簡(jiǎn)單實(shí)際用起來(lái)問(wèn)題很多。prompt 越長(zhǎng)模型越容易忽略關(guān)鍵指令檢索和寫(xiě)代碼的邏輯互相干擾出了錯(cuò)也很難定位到底是哪一步的問(wèn)題。后來(lái)我改成 Multi-Agent 架構(gòu)核心就是 Supervisor 模式一個(gè) Supervisor Agent 負(fù)責(zé)讀用戶請(qǐng)求判斷該叫哪個(gè)子 Agent 干活所有子 Agent 干完活都把結(jié)果交回給 SupervisorSupervisor 再?zèng)Q定下一步是繼續(xù)派活還是收尾。就像一個(gè)小團(tuán)隊(duì)主管不親自寫(xiě)代碼但是負(fù)責(zé)分配任務(wù)和驗(yàn)收結(jié)果。這種模式下每個(gè)子 Agent 的職責(zé)很單一prompt 可以寫(xiě)得很聚焦Supervisor 只做決策不淹沒(méi)在具體操作細(xì)節(jié)里。問(wèn)題是Java 生態(tài)里一直沒(méi)有特別順手的編排框架直到我注意到 LangGraph4j。1.2 LangGraph4j 與 Python 版 LangGraph 的關(guān)系LangGraph4j 是社區(qū)把 LangGraph 的設(shè)計(jì)思想移植到 JVM 上的實(shí)現(xiàn)核心概念和 Python 版一致StateGraph、Node、Edge、Conditional Edge、Checkpoint甚至執(zhí)行方式都盡量對(duì)齊。我最早擔(dān)心它只是“照著畫(huà)了個(gè)葫蘆”實(shí)際用下來(lái)基礎(chǔ)的狀態(tài)流轉(zhuǎn)、條件路由、流式輸出都是可用的。對(duì)我來(lái)說(shuō)最大的價(jià)值不是 API 完全一致而是思想一致。我在 Python 版里驗(yàn)證過(guò)的 Supervisor 循環(huán)可以在 Java 里幾乎一比一復(fù)刻。團(tuán)隊(duì)不用重新學(xué)一套“多 Agent 設(shè)計(jì)哲學(xué)”只需要補(bǔ) Java 語(yǔ)法和庫(kù) API 就行。另外LangGraph4j 天然適合 Java 技術(shù)棧狀態(tài)能定義成強(qiáng)類型對(duì)象節(jié)點(diǎn)能復(fù)用 Spring Service日志鏈路可以用現(xiàn)成的 Java 日志框架測(cè)試也更順手。對(duì)我們這種長(zhǎng)期維護(hù) Spring Boot 項(xiàng)目的團(tuán)隊(duì)來(lái)說(shuō)Hybrid 架構(gòu)比引入異構(gòu)運(yùn)行時(shí)穩(wěn)妥得多。1.3 和 Spring AI 的對(duì)比它不是替代品而是編排層最近?？吹接腥嗽趩?wèn)“用 Spring AI 還是 LangGraph4j”我的結(jié)論很直接它倆不是同層的東西別做成二選一。Spring AI 解決的是“怎么跟模型說(shuō)話”它幫你封裝了 ChatClient、Prompt、結(jié)構(gòu)化輸出、工具調(diào)用、Embedding 等能力讓 Java 代碼可以聲明式地調(diào)用大模型。但 Spring AI 本身不關(guān)心你編排幾個(gè) Agent、誰(shuí)先誰(shuí)后、條件路由怎么走。LangGraph4j 解決的是“多個(gè) Agent 怎么協(xié)作”它負(fù)責(zé)把整個(gè)工作流描述成一張有向圖定義哪個(gè)節(jié)點(diǎn)運(yùn)行完走哪條邊也支持暫停、恢復(fù)、保存狀態(tài)。節(jié)點(diǎn)內(nèi)部具體怎么調(diào)模型它不關(guān)心。所以最舒服的組合是LangGraph4j 充當(dāng) Multi-Agent 的“骨架”Spring AI 充當(dāng)每個(gè) Agent 的“大腦連接器”。在后面代碼里你會(huì)看到我在 LangGraph4j 的節(jié)點(diǎn)里面直接調(diào)用 Spring AI 的 ChatClient二者完全可以共存。維度Spring AILangGraph4j核心價(jià)值模型訪問(wèn)、Prompt、工具調(diào)用封裝多 Agent 流程編排、狀態(tài)管理、循環(huán)與恢復(fù)適合場(chǎng)景單個(gè) Agent、簡(jiǎn)單多輪對(duì)話、RAGSupervisor、多專家協(xié)作、人工審批、條件分支和 LangFlow 類工具的關(guān)系不沖突可以互相配合不沖突可以互相配合學(xué)習(xí)成本較低中等需要理解圖執(zhí)行模型如果你只是希望“給 Spring Boot 項(xiàng)目接一個(gè)會(huì)調(diào)用工具的聊天助手”Spring AI 完全夠不需要引入 LangGraph4j。但當(dāng)你發(fā)現(xiàn)一個(gè) Agent 里塞了太多職責(zé)、代碼越來(lái)越亂、開(kāi)始出現(xiàn)“根據(jù)上一步結(jié)果決定下一步要誰(shuí)來(lái)干”的復(fù)雜流程時(shí)就是該上 LangGraph4j 的時(shí)候了。2. Supervisor 模式到底是什么用狀態(tài)機(jī)的思路理解多 Agent 調(diào)度2.1 三種常見(jiàn)的多 Agent 模式社區(qū)里常見(jiàn)的設(shè)計(jì)模式有三種搞清楚它們的區(qū)別才知道自己到底需要什么并行扇出一個(gè)任務(wù)拆成多個(gè)子任務(wù)多個(gè) Agent 同時(shí)執(zhí)行最后匯總。適合“多路搜索、對(duì)比分析”這類場(chǎng)景。流水線Agent 按順序執(zhí)行上一個(gè)的輸出是下一個(gè)的輸入。適合“生成大綱-擴(kuò)寫(xiě)-校對(duì)”這種嚴(yán)格串行流程。Supervisor主管中央控制器根據(jù)當(dāng)前狀態(tài)動(dòng)態(tài)決定下一步執(zhí)行哪個(gè)子 Agent子 Agent 完成后把控制權(quán)交還給主管形成循環(huán)直到主管判定任務(wù)完成。Supervisor 模式最大的優(yōu)點(diǎn)是靈活它不是一個(gè)固定流程而是一個(gè)帶“決策節(jié)點(diǎn)”的循環(huán)流程。每一步都可能不一樣更像是真正的團(tuán)隊(duì)協(xié)作。缺點(diǎn)是決策本身有開(kāi)銷因?yàn)槊枯喲h(huán)都要調(diào)一次模型做路由判斷而且如果路由不穩(wěn)定可能陷入來(lái)回切換的循環(huán)。2.2 Supervisor 循環(huán)的關(guān)鍵條件邊和控制權(quán)交接理解了 Supervisor 模式再看 LangGraph4j 實(shí)現(xiàn)關(guān)鍵就是兩個(gè)條件邊和控制權(quán)回傳。條件邊是指從一個(gè)節(jié)點(diǎn)出發(fā)時(shí)根據(jù)當(dāng)前狀態(tài)的不同走不同的目標(biāo)節(jié)點(diǎn)。在 Supervisor 里就是 Supervisor 節(jié)點(diǎn)看完請(qǐng)求后決定下一步是去 researcher 還是 reporter 還是直接結(jié)束?？刂茩?quán)回傳的意思是子 Agent 干完活之后不能直接走到 END而是必須回到 Supervisor。這樣 Supervisor 才能根據(jù)子 Agent 的產(chǎn)出判斷“任務(wù)是否完成”或者“要不要換一個(gè) Agent 再來(lái)一次”。如果子節(jié)點(diǎn)直接連 ENDSupervisor 就失去了最后一次決策機(jī)會(huì)。這個(gè)模型特別像狀態(tài)機(jī)狀態(tài)是當(dāng)前用戶的請(qǐng)求、對(duì)話歷史、各子 Agent 的產(chǎn)出事件是節(jié)點(diǎn)執(zhí)行完畢轉(zhuǎn)移規(guī)則由條件邊描述。把 Multi-Agent 當(dāng)成狀態(tài)機(jī)來(lái)設(shè)計(jì)比靠感覺(jué)拼 prompt 要可靠得多。2.3 最少可用的執(zhí)行流一個(gè)最精簡(jiǎn)的 Supervisor 執(zhí)行流是這樣的開(kāi)始用戶請(qǐng)求進(jìn)入 START。Supervisor 節(jié)點(diǎn)運(yùn)行調(diào)用模型輸出下一跳。條件路由如果模型輸出 “research”走 researcher 節(jié)點(diǎn)輸出 “report”走 reporter 節(jié)點(diǎn)輸出 “finish”走 END。子 Agent 節(jié)點(diǎn)運(yùn)行researcher 或 reporter 干活把結(jié)果寫(xiě)回狀態(tài)。控制權(quán)返回子 Agent 的邊指向 Supervisor再次進(jìn)入 Supervisor 節(jié)點(diǎn)。循環(huán)直到路由結(jié)果為 “finish”。在這個(gè)流程里子 Agent 的數(shù)量可以任意擴(kuò)展只要在路由表里注冊(cè)一個(gè) key 和對(duì)應(yīng)節(jié)點(diǎn)即可。Supervisor 不關(guān)心某個(gè) Agent 內(nèi)部怎么實(shí)現(xiàn)只關(guān)心它返回的結(jié)果是否已經(jīng)寫(xiě)入了共享狀態(tài)。3. 用 LangGraph4j 實(shí)現(xiàn) Supervisor狀態(tài)、節(jié)點(diǎn)、條件路由3.1 狀態(tài) State所有子 Agent 共享的“共享白板”LangGraph4j 里最重要的概念是 State。它會(huì)在整個(gè)圖執(zhí)行過(guò)程中傳遞每個(gè)節(jié)點(diǎn)都能讀、能改。我把 State 理解為一張放在會(huì)議桌上的白板誰(shuí)拿到筆都能寫(xiě)但必須按照約定寫(xiě)不能隨意覆蓋別人的內(nèi)容。我用的 State 是HashMap的子類好處是擴(kuò)展字段方便。LangGraph4j 官方示例里有不少是直接用HashMap的但對(duì)于復(fù)雜工程我建議還是定義一個(gè)語(yǔ)義明確的類型public class AgentState extends HashMapString, Object { public AgentState() { super(); } public String getRequest() { return (String) this.get(request); } SuppressWarnings(unchecked) public ListMapString, String getMessages() { return (ListMapString, String) this.get(messages); } public String getNext() { return (String) this.get(next); } public void setNext(String next) { this.put(next, next); } }我這個(gè) project 里常用的字段包括request用戶原始請(qǐng)求、messages所有 Agent 產(chǎn)生的消息歷史、next路由決策、instruction給子 Agent 的額外指令、steps循環(huán)次數(shù)、finalAnswer最終答案。狀態(tài)字段越清晰節(jié)點(diǎn)邏輯就越容易寫(xiě)。有一點(diǎn)要注意State 是可變對(duì)象節(jié)點(diǎn)返回值會(huì)合并更新。別在節(jié)點(diǎn)里偷偷把 State 換成新對(duì)象否則可能導(dǎo)致后續(xù)節(jié)點(diǎn)讀不到之前寫(xiě)的數(shù)據(jù)。3.2 Supervisor 節(jié)點(diǎn)讓 LLM 決定下一步該找誰(shuí)Supervisor 節(jié)點(diǎn)其實(shí)是整個(gè)系統(tǒng)里最簡(jiǎn)單也最關(guān)鍵的節(jié)點(diǎn)它做的事情只有一件調(diào)用模型讓模型從預(yù)定義的 Agent 集合里選一個(gè)并輸出給對(duì)應(yīng) Agent 的指令。我讓模型輸出嚴(yán)格 JSON這樣解析方便public AgentState supervisorNode(AgentState state) { String request state.getRequest(); ListMapString, String history state.getMessages(); String prompt 你是 Multi-Agent 系統(tǒng)的 Supervisor。 根據(jù)用戶請(qǐng)求和當(dāng)前歷史從下面三個(gè)動(dòng)作中選一個(gè) - research需要深入調(diào)研交給 researcher 節(jié)點(diǎn) - report需要整理報(bào)告交給 reporter 節(jié)點(diǎn) - finish任務(wù)已經(jīng)完成可以給出最終答案 只輸出 JSON不要其他解釋格式如下 {next:research,instruction:給子 Agent 的指令} ; String response chatClient.prompt() .system(prompt) .user(request) .call() .content(); try { JsonNode node objectMapper.readTree(response); state.setNext(node.get(next).asText()); state.put(instruction, node.get(instruction).asText()); state.put(steps, ((Integer) state.getOrDefault(steps, 0)) 1); } catch (JsonProcessingException e) { state.setNext(finish); } return state; }這里有幾個(gè)實(shí)踐要點(diǎn)。一是必須限制輸出格式不然路由沒(méi)法做。二是我加了steps自增后面會(huì)用來(lái)做循環(huán)上限保護(hù)。三是如果 JSON 解析失敗我寧可讓它走finish也不要隨便走一個(gè)子節(jié)點(diǎn)因?yàn)樵谏a(chǎn)環(huán)境里不確定的決策落到某個(gè) Agent 上比直接收尾危險(xiǎn)得多。3.3 子 Agent 節(jié)點(diǎn)干完活把結(jié)果寫(xiě)回狀態(tài)子 Agent 節(jié)點(diǎn)和普通節(jié)點(diǎn)沒(méi)有本質(zhì)區(qū)別只是職責(zé)更純粹。比如 researcher 節(jié)點(diǎn)它的任務(wù)就是根據(jù) Supervisor 給的instruction去檢索數(shù)據(jù)并把結(jié)果寫(xiě)回 Statepublic AgentState researcherNode(AgentState state) { String instruction (String) state.getOrDefault(instruction, ); String request state.getRequest(); // 這里可以調(diào)用知識(shí)庫(kù)檢索、外部 API 或工具函數(shù) String knowledge knowledgeBaseService.search(request); String result chatClient.prompt() .system(你是一名研究員請(qǐng)基于檢索內(nèi)容給出客觀回答。) .user(instruction \n檢索內(nèi)容 knowledge) .call() .content(); state.put(researchResult, result); ListMapString, String messages state.getMessages(); messages.add(Map.of(role, researcher, content, result)); state.put(messages, messages); return state; }reporter 節(jié)點(diǎn)類似它不關(guān)注怎么調(diào)研只關(guān)注怎么把已有的researchResult和request組合成一份結(jié)構(gòu)化報(bào)告段落、要點(diǎn)、結(jié)論。兩個(gè)節(jié)點(diǎn)干完活之后都不會(huì)自己決定結(jié)束而是通過(guò)圖定義中的邊回到 supervisor這就保證了“誰(shuí)決定的開(kāi)始誰(shuí)負(fù)責(zé)結(jié)束”。3.4 主流程裝配與編譯運(yùn)行現(xiàn)在到了最核心的部分把上面這些節(jié)點(diǎn)用 LangGraph4j 裝配成一張可執(zhí)行的圖。我以我項(xiàng)目里鎖定的 API 版本為例整體結(jié)構(gòu)如下StateGraphAgentState graph new StateGraph(AgentState::new) .addNode(supervisor, this::supervisorNode) .addNode(researcher, this::researcherNode) .addNode(reporter, this::reporterNode) .addEdge(START, supervisor) .addConditionalEdges(supervisor, this::routeFromSupervisor, Map.of( research, researcher, report, reporter, finish, END )) .addEdge(researcher, supervisor) .addEdge(reporter, supervisor); CompiledGraphAgentState compiledGraph graph.compile();注意最后兩條固定邊researcher - supervisor和reporter - supervisor。它們實(shí)現(xiàn)了我前面說(shuō)的“控制權(quán)回傳”。沒(méi)有它們子 Agent 執(zhí)行完就結(jié)束Supervisor 就沒(méi)有機(jī)會(huì)驗(yàn)收結(jié)果。路由函數(shù)里我做了歸一化處理避免模型輸出不一致導(dǎo)致路由失敗public String routeFromSupervisor(AgentState state) { String next state.getNext(); if (next null) { return finish; } String normalized next.trim().toLowerCase(); if (normalized.contains(research)) { return research; } else if (normalized.contains(report)) { return report; } return finish; }執(zhí)行的時(shí)候也很簡(jiǎn)單MapString, Object input new HashMap(); input.put(request, 幫我查一下最近日志里的錯(cuò)誤原因); input.put(messages, new ArrayList()); input.put(steps, 0); MapString, Object output compiledGraph.invoke(Input.of(input)); System.out.println(output.get(finalAnswer));更推薦在調(diào)試階段用 stream 方式逐步觀察compiledGraph.stream(Input.of(input)) .stream() .forEach(System.out::println);這樣你能看到每個(gè)節(jié)點(diǎn)的進(jìn)入和退出排查問(wèn)題時(shí)不用瞎猜。4. 讓 Supervisor 更可靠Checkpoint、人工審批、超時(shí)與重試4.1 Checkpoint 保存現(xiàn)場(chǎng)Agent 中途掛了可以從頭恢復(fù)LangGraph4j 支持 Checkpoint核心作用是保存每一步 State 的快照。一旦某個(gè)子 Agent 調(diào)用失敗我們可以從最近一個(gè)正確的快照恢復(fù)而不是整個(gè)流程重新跑。我的做法是為每個(gè)用戶請(qǐng)求分配一個(gè)獨(dú)立的threadId把 threadId 和用戶請(qǐng)求綁定。執(zhí)行前經(jīng)過(guò) Checkpoint 保存執(zhí)行失敗后用同一個(gè) threadId 再次發(fā)起調(diào)用框架會(huì)把狀態(tài)恢復(fù)到最近完成的節(jié)點(diǎn)然后繼續(xù)往下走。MapString, Object input new HashMap(); input.put(threadId, order_10086); input.put(request, 分析訂單 10086 的交付延遲原因); input.put(messages, new ArrayList()); input.put(steps, 0); compiledGraph.stream(Input.of(input, order_10086));Checkpoint 在生產(chǎn)環(huán)境里特別重要因?yàn)槎?Agent 流程通常比單 Agent 長(zhǎng)中途失敗的概率也更高。如果沒(méi)有持久化狀態(tài)用戶一個(gè)問(wèn)題可能要重新跑好幾分鐘體驗(yàn)極差。4.2 人工審批把控制權(quán)交給“人”來(lái)確認(rèn)很多業(yè)務(wù)場(chǎng)景里Agent 不能完全自主行動(dòng)。比如“自動(dòng)生成一封發(fā)給客戶的道歉信”Supervisor 可以寫(xiě)草稿但發(fā)送前必須由人工確認(rèn)。這種需求不適合硬編碼成子 Agent更適合設(shè)計(jì)成“掛起流程”。我的通用做法是在 State 里放一個(gè)approvalRequired字段當(dāng) Supervisor 判斷需要人工審批時(shí)把狀態(tài)設(shè)置成掛起然后讓流程自然結(jié)束。真正的人工審批接口不在 LangGraph4j 內(nèi)部而是通過(guò)外部 REST API 觸發(fā)PostMapping(/orders/{orderId}/approve) public void approve(PathVariable String orderId) { MapString, Object input new HashMap(); input.put(threadId, order_ orderId); input.put(approvalResult, approved); compiledGraph.invoke(Input.of(input)); }關(guān)鍵思路是一個(gè)threadId對(duì)應(yīng)一份完整的 State人工審批只是“重新喚醒”這個(gè) threadId讓 Supervisor 讀到最新的approvalResult再?zèng)Q定下一步走向。這樣既實(shí)現(xiàn)了人工介入又保持了圖的統(tǒng)一性。別試圖把審批按鈕塞進(jìn)圖里的某個(gè)節(jié)點(diǎn)那會(huì)把流程編排和業(yè)務(wù)接口耦合在一起維護(hù)起來(lái)很痛苦。4.3 超時(shí)、重試與預(yù)算控制Multi-Agent 系統(tǒng)最容易被忽略的問(wèn)題是“失控”。因?yàn)槊總€(gè)子 Agent 都在調(diào)用大模型每一步都有成本和時(shí)間開(kāi)銷。Supervisor 又是一個(gè)循環(huán)如果模型判斷失誤可能一直在幾個(gè)子 Agent 之間來(lái)回切換十幾輪都結(jié)束不了。我做了三層保護(hù)第一層循環(huán)次數(shù)上限。每次 Supervisor 執(zhí)行steps加一超過(guò) 5 次強(qiáng)制finish。第二層每個(gè)子 Agent 調(diào)用模型時(shí)在 Spring AI 的 ChatClient 上設(shè)置最大 token 數(shù)和超時(shí)時(shí)間。第三層整個(gè)圖執(zhí)行外面包一層CompletableFuture超時(shí)超過(guò) 120 秒直接終止。public AgentState supervisorNode(AgentState state) { int steps (Integer) state.getOrDefault(steps, 0); if (steps 5) { state.setNext(finish); state.put(finalAnswer, 已經(jīng)多次嘗試為避免循環(huán)直接給出當(dāng)前已有結(jié)論 state.getOrDefault(researchResult, 暫無(wú)結(jié)果)); return state; } // 正常調(diào)用模型做決策 return state; }這套保護(hù)在測(cè)試階段救過(guò)我很多次。有一回我在 prompt 里寫(xiě)“如果信息不足繼續(xù)調(diào)查”模型真的就一直在 research 和 supervisor 之間循環(huán)了七八輪直到我加上步驟上限才停下來(lái)。5. 實(shí)測(cè)中的坑和調(diào)試技巧5.1 條件路由的返回值不穩(wěn)定正則兜底我最早天真地認(rèn)為模型會(huì)穩(wěn)定輸出{next:research}結(jié)果實(shí)際返回五花八門(mén)有時(shí)候是“research”有時(shí)候是“Research”有時(shí)候是“next”: “researcher”甚至帶一些前后綴解釋。如果你直接拿它去 Map 里查隨時(shí)會(huì)命中不了預(yù)設(shè)路由。后來(lái)我在路由函數(shù)里做了三步歸一化先 trim再轉(zhuǎn)小寫(xiě)再 contain 判斷。這樣 “researcher” 也能命中 “research”“report” 和 “reporting” 都能命中 “report”。如果歸一化后仍匹配不到默認(rèn)走finish絕不讓圖執(zhí)行在中途斷裂。5.2 節(jié)點(diǎn)間數(shù)據(jù)復(fù)用與并發(fā)問(wèn)題LangGraph4j 的圖本身是支持多實(shí)例并發(fā)執(zhí)行的但如果你在節(jié)點(diǎn)里偷懶把中間結(jié)果存在類字段里就會(huì)出現(xiàn)嚴(yán)重串?dāng)?shù)據(jù)問(wèn)題。比如我一開(kāi)始為了省事在 Service 類里寫(xiě)了一個(gè)currentState字段結(jié)果兩個(gè)用戶同時(shí)發(fā)任務(wù)時(shí)后一個(gè)用戶直接覆蓋前一個(gè)導(dǎo)致 A 的請(qǐng)求跑到一半拿到 B 的數(shù)據(jù)。排查了很久才意識(shí)到State 必須通過(guò)方法的入?yún)鬟f不能塞進(jìn) Bean 的成員變量。正確做法是節(jié)點(diǎn)方法參數(shù)里接收 State返回值也是 State所有的臨時(shí)變量都放在 State 或方法局部變量里。團(tuán)隊(duì)里所有人都要遵守這個(gè)約定否則并發(fā)一上來(lái)就出事故。5.3 如何觀察圖執(zhí)行過(guò)程逐步輸出排查 Multi-Agent 問(wèn)題最痛苦的是“你只知道結(jié)果不對(duì)不知道卡在哪一步”。我用stream方式輸出后明顯效率提升。每個(gè)節(jié)點(diǎn)進(jìn)入、退出、路由方向都能看到compiledGraph.stream(Input.of(input)) .stream() .forEach(event - System.out.println(event));LangGraph4j 的輸出里包含事件類型和狀態(tài)比如ON_NODE_START、ON_NODE_END、路由結(jié)果等。配合日志文件的 traceId基本能還原一條完整的“用戶請(qǐng)求 - Supervisor 決策 - 子 Agent 執(zhí)行 - 回到 Supervisor”的鏈路。還有一個(gè)很土但很有用的技巧在節(jié)點(diǎn)代碼里加一個(gè)短日志打印當(dāng)前 State 里幾個(gè)關(guān)鍵字段的摘要。實(shí)測(cè)不需要打印整個(gè) State因?yàn)橄v史可能很長(zhǎng)刷屏刷到?jīng)]法看。打印steps、next、instruction就夠了。5.4 關(guān)于“Spring AI 還是 LangGraph4j”的最終判斷回到開(kāi)頭那個(gè)問(wèn)題我認(rèn)為真正的判斷標(biāo)準(zhǔn)不是看誰(shuí)更火而是看你的流程復(fù)雜度。如果只是單一 Agent 工具函數(shù) 對(duì)話補(bǔ)全用 Spring AI 是最省事的。它和 Spring Boot 融合得很好寫(xiě)個(gè) ChatClient 就能干活。這時(shí)候引入 LangGraph4j純屬給自己增加概念負(fù)擔(dān)。但如果你的業(yè)務(wù)里已經(jīng)出現(xiàn)了“多個(gè)角色協(xié)作”、需要條件分支、需要人工確認(rèn)、需要從失敗現(xiàn)場(chǎng)恢復(fù)那就應(yīng)該選 LangGraph4j。你可以在它的節(jié)點(diǎn)里繼續(xù)用 Spring AI 調(diào)模型兩者配合起來(lái)才是完整方案。還有一點(diǎn)LangGraph4j 的官方文檔更新速度相當(dāng)快不同版本的 API 可能略有差異。我在項(xiàng)目里直接把依賴版本鎖死并且維護(hù)了一套從最小圖到完整圖自動(dòng)跑通的集成測(cè)試。每次升級(jí)依賴先跑一遍測(cè)試確認(rèn)行為沒(méi)變?cè)俸先胫鞲赡苁〉粢淮蟀肽涿畹木€上故障。最后分享一個(gè)很土但實(shí)用的建議如果你也是第一次接觸 LangGraph4j不要一上來(lái)就設(shè)計(jì)十幾個(gè)節(jié)點(diǎn)的復(fù)雜圖。先把 Supervisor 兩個(gè)子 Agent 的最小循環(huán)跑通確認(rèn)路由和狀態(tài)流轉(zhuǎn)符合預(yù)期再逐步加 Checkpoint、人工審批、超時(shí)控制。多 Agent 系統(tǒng)最怕的不是模型不行而是編排邏輯自己先亂成一鍋粥。 用LangGraph4j在Spring Boot中實(shí)現(xiàn)Multi-Agent Supervisor模式
最近在搞一個(gè) Java 服務(wù)里的多智能體協(xié)作需求需要在同一個(gè)進(jìn)程里跑幾個(gè)職責(zé)不同的 Agent再由一個(gè) Supervisor 統(tǒng)一調(diào)度、分配任務(wù)。最早我用 Python 版的 LangGraph 搭原型邏輯很快跑通但到了交付階段團(tuán)隊(duì)不想為一個(gè)小功能額外引一套 Python 運(yùn)行時(shí)于是轉(zhuǎn)向 LangGraph4j。折騰了兩周我把 Multi-Agent Supervisor 模式完整落地在 Spring Boot 服務(wù)里這里記錄一下完整的設(shè)計(jì)思路、關(guān)鍵代碼、踩過(guò)的坑以及很多人糾結(jié)的“現(xiàn)在到底用 Spring AI 還是 LangGraph4j”這個(gè)問(wèn)題。1. 為什么在 JVM 團(tuán)隊(duì)里做 Multi-Agent我最終選了 LangGraph4j1.1 我的場(chǎng)景需要一個(gè)“老板”來(lái)分活的 Agent 系統(tǒng)我做的業(yè)務(wù)是一個(gè)工單助手用戶提交一個(gè)問(wèn)題系統(tǒng)要決定是去查知識(shí)庫(kù)、還是生成一段代碼、還是讓用戶補(bǔ)充信息最后匯總成答案。最初我用一個(gè)大 prompt 把“理解意圖、檢索、生成、總結(jié)”全塞給一個(gè) Agent看起來(lái)簡(jiǎn)單實(shí)際用起來(lái)問(wèn)題很多。prompt 越長(zhǎng)模型越容易忽略關(guān)鍵指令檢索和寫(xiě)代碼的邏輯互相干擾出了錯(cuò)也很難定位到底是哪一步的問(wèn)題。后來(lái)我改成 Multi-Agent 架構(gòu)核心就是 Supervisor 模式一個(gè) Supervisor Agent 負(fù)責(zé)讀用戶請(qǐng)求判斷該叫哪個(gè)子 Agent 干活所有子 Agent 干完活都把結(jié)果交回給 SupervisorSupervisor 再?zèng)Q定下一步是繼續(xù)派活還是收尾。就像一個(gè)小團(tuán)隊(duì)主管不親自寫(xiě)代碼但是負(fù)責(zé)分配任務(wù)和驗(yàn)收結(jié)果。這種模式下每個(gè)子 Agent 的職責(zé)很單一prompt 可以寫(xiě)得很聚焦Supervisor 只做決策不淹沒(méi)在具體操作細(xì)節(jié)里。問(wèn)題是Java 生態(tài)里一直沒(méi)有特別順手的編排框架直到我注意到 LangGraph4j。1.2 LangGraph4j 與 Python 版 LangGraph 的關(guān)系LangGraph4j 是社區(qū)把 LangGraph 的設(shè)計(jì)思想移植到 JVM 上的實(shí)現(xiàn)核心概念和 Python 版一致StateGraph、Node、Edge、Conditional Edge、Checkpoint甚至執(zhí)行方式都盡量對(duì)齊。我最早擔(dān)心它只是“照著畫(huà)了個(gè)葫蘆”實(shí)際用下來(lái)基礎(chǔ)的狀態(tài)流轉(zhuǎn)、條件路由、流式輸出都是可用的。對(duì)我來(lái)說(shuō)最大的價(jià)值不是 API 完全一致而是思想一致。我在 Python 版里驗(yàn)證過(guò)的 Supervisor 循環(huán)可以在 Java 里幾乎一比一復(fù)刻。團(tuán)隊(duì)不用重新學(xué)一套“多 Agent 設(shè)計(jì)哲學(xué)”只需要補(bǔ) Java 語(yǔ)法和庫(kù) API 就行。另外LangGraph4j 天然適合 Java 技術(shù)棧狀態(tài)能定義成強(qiáng)類型對(duì)象節(jié)點(diǎn)能復(fù)用 Spring Service日志鏈路可以用現(xiàn)成的 Java 日志框架測(cè)試也更順手。對(duì)我們這種長(zhǎng)期維護(hù) Spring Boot 項(xiàng)目的團(tuán)隊(duì)來(lái)說(shuō)Hybrid 架構(gòu)比引入異構(gòu)運(yùn)行時(shí)穩(wěn)妥得多。1.3 和 Spring AI 的對(duì)比它不是替代品而是編排層最近?？吹接腥嗽趩?wèn)“用 Spring AI 還是 LangGraph4j”我的結(jié)論很直接它倆不是同層的東西別做成二選一。Spring AI 解決的是“怎么跟模型說(shuō)話”它幫你封裝了 ChatClient、Prompt、結(jié)構(gòu)化輸出、工具調(diào)用、Embedding 等能力讓 Java 代碼可以聲明式地調(diào)用大模型。但 Spring AI 本身不關(guān)心你編排幾個(gè) Agent、誰(shuí)先誰(shuí)后、條件路由怎么走。LangGraph4j 解決的是“多個(gè) Agent 怎么協(xié)作”它負(fù)責(zé)把整個(gè)工作流描述成一張有向圖定義哪個(gè)節(jié)點(diǎn)運(yùn)行完走哪條邊也支持暫停、恢復(fù)、保存狀態(tài)。節(jié)點(diǎn)內(nèi)部具體怎么調(diào)模型它不關(guān)心。所以最舒服的組合是LangGraph4j 充當(dāng) Multi-Agent 的“骨架”Spring AI 充當(dāng)每個(gè) Agent 的“大腦連接器”。在后面代碼里你會(huì)看到我在 LangGraph4j 的節(jié)點(diǎn)里面直接調(diào)用 Spring AI 的 ChatClient二者完全可以共存。維度Spring AILangGraph4j核心價(jià)值模型訪問(wèn)、Prompt、工具調(diào)用封裝多 Agent 流程編排、狀態(tài)管理、循環(huán)與恢復(fù)適合場(chǎng)景單個(gè) Agent、簡(jiǎn)單多輪對(duì)話、RAGSupervisor、多專家協(xié)作、人工審批、條件分支和 LangFlow 類工具的關(guān)系不沖突可以互相配合不沖突可以互相配合學(xué)習(xí)成本較低中等需要理解圖執(zhí)行模型如果你只是希望“給 Spring Boot 項(xiàng)目接一個(gè)會(huì)調(diào)用工具的聊天助手”Spring AI 完全夠不需要引入 LangGraph4j。但當(dāng)你發(fā)現(xiàn)一個(gè) Agent 里塞了太多職責(zé)、代碼越來(lái)越亂、開(kāi)始出現(xiàn)“根據(jù)上一步結(jié)果決定下一步要誰(shuí)來(lái)干”的復(fù)雜流程時(shí)就是該上 LangGraph4j 的時(shí)候了。2. Supervisor 模式到底是什么用狀態(tài)機(jī)的思路理解多 Agent 調(diào)度2.1 三種常見(jiàn)的多 Agent 模式社區(qū)里常見(jiàn)的設(shè)計(jì)模式有三種搞清楚它們的區(qū)別才知道自己到底需要什么并行扇出一個(gè)任務(wù)拆成多個(gè)子任務(wù)多個(gè) Agent 同時(shí)執(zhí)行最后匯總。適合“多路搜索、對(duì)比分析”這類場(chǎng)景。流水線Agent 按順序執(zhí)行上一個(gè)的輸出是下一個(gè)的輸入。適合“生成大綱-擴(kuò)寫(xiě)-校對(duì)”這種嚴(yán)格串行流程。Supervisor主管中央控制器根據(jù)當(dāng)前狀態(tài)動(dòng)態(tài)決定下一步執(zhí)行哪個(gè)子 Agent子 Agent 完成后把控制權(quán)交還給主管形成循環(huán)直到主管判定任務(wù)完成。Supervisor 模式最大的優(yōu)點(diǎn)是靈活它不是一個(gè)固定流程而是一個(gè)帶“決策節(jié)點(diǎn)”的循環(huán)流程。每一步都可能不一樣更像是真正的團(tuán)隊(duì)協(xié)作。缺點(diǎn)是決策本身有開(kāi)銷因?yàn)槊枯喲h(huán)都要調(diào)一次模型做路由判斷而且如果路由不穩(wěn)定可能陷入來(lái)回切換的循環(huán)。2.2 Supervisor 循環(huán)的關(guān)鍵條件邊和控制權(quán)交接理解了 Supervisor 模式再看 LangGraph4j 實(shí)現(xiàn)關(guān)鍵就是兩個(gè)條件邊和控制權(quán)回傳。條件邊是指從一個(gè)節(jié)點(diǎn)出發(fā)時(shí)根據(jù)當(dāng)前狀態(tài)的不同走不同的目標(biāo)節(jié)點(diǎn)。在 Supervisor 里就是 Supervisor 節(jié)點(diǎn)看完請(qǐng)求后決定下一步是去 researcher 還是 reporter 還是直接結(jié)束?？刂茩?quán)回傳的意思是子 Agent 干完活之后不能直接走到 END而是必須回到 Supervisor。這樣 Supervisor 才能根據(jù)子 Agent 的產(chǎn)出判斷“任務(wù)是否完成”或者“要不要換一個(gè) Agent 再來(lái)一次”。如果子節(jié)點(diǎn)直接連 ENDSupervisor 就失去了最后一次決策機(jī)會(huì)。這個(gè)模型特別像狀態(tài)機(jī)狀態(tài)是當(dāng)前用戶的請(qǐng)求、對(duì)話歷史、各子 Agent 的產(chǎn)出事件是節(jié)點(diǎn)執(zhí)行完畢轉(zhuǎn)移規(guī)則由條件邊描述。把 Multi-Agent 當(dāng)成狀態(tài)機(jī)來(lái)設(shè)計(jì)比靠感覺(jué)拼 prompt 要可靠得多。2.3 最少可用的執(zhí)行流一個(gè)最精簡(jiǎn)的 Supervisor 執(zhí)行流是這樣的開(kāi)始用戶請(qǐng)求進(jìn)入 START。Supervisor 節(jié)點(diǎn)運(yùn)行調(diào)用模型輸出下一跳。條件路由如果模型輸出 “research”走 researcher 節(jié)點(diǎn)輸出 “report”走 reporter 節(jié)點(diǎn)輸出 “finish”走 END。子 Agent 節(jié)點(diǎn)運(yùn)行researcher 或 reporter 干活把結(jié)果寫(xiě)回狀態(tài)。控制權(quán)返回子 Agent 的邊指向 Supervisor再次進(jìn)入 Supervisor 節(jié)點(diǎn)。循環(huán)直到路由結(jié)果為 “finish”。在這個(gè)流程里子 Agent 的數(shù)量可以任意擴(kuò)展只要在路由表里注冊(cè)一個(gè) key 和對(duì)應(yīng)節(jié)點(diǎn)即可。Supervisor 不關(guān)心某個(gè) Agent 內(nèi)部怎么實(shí)現(xiàn)只關(guān)心它返回的結(jié)果是否已經(jīng)寫(xiě)入了共享狀態(tài)。3. 用 LangGraph4j 實(shí)現(xiàn) Supervisor狀態(tài)、節(jié)點(diǎn)、條件路由3.1 狀態(tài) State所有子 Agent 共享的“共享白板”LangGraph4j 里最重要的概念是 State。它會(huì)在整個(gè)圖執(zhí)行過(guò)程中傳遞每個(gè)節(jié)點(diǎn)都能讀、能改。我把 State 理解為一張放在會(huì)議桌上的白板誰(shuí)拿到筆都能寫(xiě)但必須按照約定寫(xiě)不能隨意覆蓋別人的內(nèi)容。我用的 State 是HashMap的子類好處是擴(kuò)展字段方便。LangGraph4j 官方示例里有不少是直接用HashMap的但對(duì)于復(fù)雜工程我建議還是定義一個(gè)語(yǔ)義明確的類型public class AgentState extends HashMapString, Object { public AgentState() { super(); } public String getRequest() { return (String) this.get(request); } SuppressWarnings(unchecked) public ListMapString, String getMessages() { return (ListMapString, String) this.get(messages); } public String getNext() { return (String) this.get(next); } public void setNext(String next) { this.put(next, next); } }我這個(gè) project 里常用的字段包括request用戶原始請(qǐng)求、messages所有 Agent 產(chǎn)生的消息歷史、next路由決策、instruction給子 Agent 的額外指令、steps循環(huán)次數(shù)、finalAnswer最終答案。狀態(tài)字段越清晰節(jié)點(diǎn)邏輯就越容易寫(xiě)。有一點(diǎn)要注意State 是可變對(duì)象節(jié)點(diǎn)返回值會(huì)合并更新。別在節(jié)點(diǎn)里偷偷把 State 換成新對(duì)象否則可能導(dǎo)致后續(xù)節(jié)點(diǎn)讀不到之前寫(xiě)的數(shù)據(jù)。3.2 Supervisor 節(jié)點(diǎn)讓 LLM 決定下一步該找誰(shuí)Supervisor 節(jié)點(diǎn)其實(shí)是整個(gè)系統(tǒng)里最簡(jiǎn)單也最關(guān)鍵的節(jié)點(diǎn)它做的事情只有一件調(diào)用模型讓模型從預(yù)定義的 Agent 集合里選一個(gè)并輸出給對(duì)應(yīng) Agent 的指令。我讓模型輸出嚴(yán)格 JSON這樣解析方便public AgentState supervisorNode(AgentState state) { String request state.getRequest(); ListMapString, String history state.getMessages(); String prompt 你是 Multi-Agent 系統(tǒng)的 Supervisor。 根據(jù)用戶請(qǐng)求和當(dāng)前歷史從下面三個(gè)動(dòng)作中選一個(gè) - research需要深入調(diào)研交給 researcher 節(jié)點(diǎn) - report需要整理報(bào)告交給 reporter 節(jié)點(diǎn) - finish任務(wù)已經(jīng)完成可以給出最終答案 只輸出 JSON不要其他解釋格式如下 {next:research,instruction:給子 Agent 的指令} ; String response chatClient.prompt() .system(prompt) .user(request) .call() .content(); try { JsonNode node objectMapper.readTree(response); state.setNext(node.get(next).asText()); state.put(instruction, node.get(instruction).asText()); state.put(steps, ((Integer) state.getOrDefault(steps, 0)) 1); } catch (JsonProcessingException e) { state.setNext(finish); } return state; }這里有幾個(gè)實(shí)踐要點(diǎn)。一是必須限制輸出格式不然路由沒(méi)法做。二是我加了steps自增后面會(huì)用來(lái)做循環(huán)上限保護(hù)。三是如果 JSON 解析失敗我寧可讓它走finish也不要隨便走一個(gè)子節(jié)點(diǎn)因?yàn)樵谏a(chǎn)環(huán)境里不確定的決策落到某個(gè) Agent 上比直接收尾危險(xiǎn)得多。3.3 子 Agent 節(jié)點(diǎn)干完活把結(jié)果寫(xiě)回狀態(tài)子 Agent 節(jié)點(diǎn)和普通節(jié)點(diǎn)沒(méi)有本質(zhì)區(qū)別只是職責(zé)更純粹。比如 researcher 節(jié)點(diǎn)它的任務(wù)就是根據(jù) Supervisor 給的instruction去檢索數(shù)據(jù)并把結(jié)果寫(xiě)回 Statepublic AgentState researcherNode(AgentState state) { String instruction (String) state.getOrDefault(instruction, ); String request state.getRequest(); // 這里可以調(diào)用知識(shí)庫(kù)檢索、外部 API 或工具函數(shù) String knowledge knowledgeBaseService.search(request); String result chatClient.prompt() .system(你是一名研究員請(qǐng)基于檢索內(nèi)容給出客觀回答。) .user(instruction \n檢索內(nèi)容 knowledge) .call() .content(); state.put(researchResult, result); ListMapString, String messages state.getMessages(); messages.add(Map.of(role, researcher, content, result)); state.put(messages, messages); return state; }reporter 節(jié)點(diǎn)類似它不關(guān)注怎么調(diào)研只關(guān)注怎么把已有的researchResult和request組合成一份結(jié)構(gòu)化報(bào)告段落、要點(diǎn)、結(jié)論。兩個(gè)節(jié)點(diǎn)干完活之后都不會(huì)自己決定結(jié)束而是通過(guò)圖定義中的邊回到 supervisor這就保證了“誰(shuí)決定的開(kāi)始誰(shuí)負(fù)責(zé)結(jié)束”。3.4 主流程裝配與編譯運(yùn)行現(xiàn)在到了最核心的部分把上面這些節(jié)點(diǎn)用 LangGraph4j 裝配成一張可執(zhí)行的圖。我以我項(xiàng)目里鎖定的 API 版本為例整體結(jié)構(gòu)如下StateGraphAgentState graph new StateGraph(AgentState::new) .addNode(supervisor, this::supervisorNode) .addNode(researcher, this::researcherNode) .addNode(reporter, this::reporterNode) .addEdge(START, supervisor) .addConditionalEdges(supervisor, this::routeFromSupervisor, Map.of( research, researcher, report, reporter, finish, END )) .addEdge(researcher, supervisor) .addEdge(reporter, supervisor); CompiledGraphAgentState compiledGraph graph.compile();注意最后兩條固定邊researcher - supervisor和reporter - supervisor。它們實(shí)現(xiàn)了我前面說(shuō)的“控制權(quán)回傳”。沒(méi)有它們子 Agent 執(zhí)行完就結(jié)束Supervisor 就沒(méi)有機(jī)會(huì)驗(yàn)收結(jié)果。路由函數(shù)里我做了歸一化處理避免模型輸出不一致導(dǎo)致路由失敗public String routeFromSupervisor(AgentState state) { String next state.getNext(); if (next null) { return finish; } String normalized next.trim().toLowerCase(); if (normalized.contains(research)) { return research; } else if (normalized.contains(report)) { return report; } return finish; }執(zhí)行的時(shí)候也很簡(jiǎn)單MapString, Object input new HashMap(); input.put(request, 幫我查一下最近日志里的錯(cuò)誤原因); input.put(messages, new ArrayList()); input.put(steps, 0); MapString, Object output compiledGraph.invoke(Input.of(input)); System.out.println(output.get(finalAnswer));更推薦在調(diào)試階段用 stream 方式逐步觀察compiledGraph.stream(Input.of(input)) .stream() .forEach(System.out::println);這樣你能看到每個(gè)節(jié)點(diǎn)的進(jìn)入和退出排查問(wèn)題時(shí)不用瞎猜。4. 讓 Supervisor 更可靠Checkpoint、人工審批、超時(shí)與重試4.1 Checkpoint 保存現(xiàn)場(chǎng)Agent 中途掛了可以從頭恢復(fù)LangGraph4j 支持 Checkpoint核心作用是保存每一步 State 的快照。一旦某個(gè)子 Agent 調(diào)用失敗我們可以從最近一個(gè)正確的快照恢復(fù)而不是整個(gè)流程重新跑。我的做法是為每個(gè)用戶請(qǐng)求分配一個(gè)獨(dú)立的threadId把 threadId 和用戶請(qǐng)求綁定。執(zhí)行前經(jīng)過(guò) Checkpoint 保存執(zhí)行失敗后用同一個(gè) threadId 再次發(fā)起調(diào)用框架會(huì)把狀態(tài)恢復(fù)到最近完成的節(jié)點(diǎn)然后繼續(xù)往下走。MapString, Object input new HashMap(); input.put(threadId, order_10086); input.put(request, 分析訂單 10086 的交付延遲原因); input.put(messages, new ArrayList()); input.put(steps, 0); compiledGraph.stream(Input.of(input, order_10086));Checkpoint 在生產(chǎn)環(huán)境里特別重要因?yàn)槎?Agent 流程通常比單 Agent 長(zhǎng)中途失敗的概率也更高。如果沒(méi)有持久化狀態(tài)用戶一個(gè)問(wèn)題可能要重新跑好幾分鐘體驗(yàn)極差。4.2 人工審批把控制權(quán)交給“人”來(lái)確認(rèn)很多業(yè)務(wù)場(chǎng)景里Agent 不能完全自主行動(dòng)。比如“自動(dòng)生成一封發(fā)給客戶的道歉信”Supervisor 可以寫(xiě)草稿但發(fā)送前必須由人工確認(rèn)。這種需求不適合硬編碼成子 Agent更適合設(shè)計(jì)成“掛起流程”。我的通用做法是在 State 里放一個(gè)approvalRequired字段當(dāng) Supervisor 判斷需要人工審批時(shí)把狀態(tài)設(shè)置成掛起然后讓流程自然結(jié)束。真正的人工審批接口不在 LangGraph4j 內(nèi)部而是通過(guò)外部 REST API 觸發(fā)PostMapping(/orders/{orderId}/approve) public void approve(PathVariable String orderId) { MapString, Object input new HashMap(); input.put(threadId, order_ orderId); input.put(approvalResult, approved); compiledGraph.invoke(Input.of(input)); }關(guān)鍵思路是一個(gè)threadId對(duì)應(yīng)一份完整的 State人工審批只是“重新喚醒”這個(gè) threadId讓 Supervisor 讀到最新的approvalResult再?zèng)Q定下一步走向。這樣既實(shí)現(xiàn)了人工介入又保持了圖的統(tǒng)一性。別試圖把審批按鈕塞進(jìn)圖里的某個(gè)節(jié)點(diǎn)那會(huì)把流程編排和業(yè)務(wù)接口耦合在一起維護(hù)起來(lái)很痛苦。4.3 超時(shí)、重試與預(yù)算控制Multi-Agent 系統(tǒng)最容易被忽略的問(wèn)題是“失控”。因?yàn)槊總€(gè)子 Agent 都在調(diào)用大模型每一步都有成本和時(shí)間開(kāi)銷。Supervisor 又是一個(gè)循環(huán)如果模型判斷失誤可能一直在幾個(gè)子 Agent 之間來(lái)回切換十幾輪都結(jié)束不了。我做了三層保護(hù)第一層循環(huán)次數(shù)上限。每次 Supervisor 執(zhí)行steps加一超過(guò) 5 次強(qiáng)制finish。第二層每個(gè)子 Agent 調(diào)用模型時(shí)在 Spring AI 的 ChatClient 上設(shè)置最大 token 數(shù)和超時(shí)時(shí)間。第三層整個(gè)圖執(zhí)行外面包一層CompletableFuture超時(shí)超過(guò) 120 秒直接終止。public AgentState supervisorNode(AgentState state) { int steps (Integer) state.getOrDefault(steps, 0); if (steps 5) { state.setNext(finish); state.put(finalAnswer, 已經(jīng)多次嘗試為避免循環(huán)直接給出當(dāng)前已有結(jié)論 state.getOrDefault(researchResult, 暫無(wú)結(jié)果)); return state; } // 正常調(diào)用模型做決策 return state; }這套保護(hù)在測(cè)試階段救過(guò)我很多次。有一回我在 prompt 里寫(xiě)“如果信息不足繼續(xù)調(diào)查”模型真的就一直在 research 和 supervisor 之間循環(huán)了七八輪直到我加上步驟上限才停下來(lái)。5. 實(shí)測(cè)中的坑和調(diào)試技巧5.1 條件路由的返回值不穩(wěn)定正則兜底我最早天真地認(rèn)為模型會(huì)穩(wěn)定輸出{next:research}結(jié)果實(shí)際返回五花八門(mén)有時(shí)候是“research”有時(shí)候是“Research”有時(shí)候是“next”: “researcher”甚至帶一些前后綴解釋。如果你直接拿它去 Map 里查隨時(shí)會(huì)命中不了預(yù)設(shè)路由。后來(lái)我在路由函數(shù)里做了三步歸一化先 trim再轉(zhuǎn)小寫(xiě)再 contain 判斷。這樣 “researcher” 也能命中 “research”“report” 和 “reporting” 都能命中 “report”。如果歸一化后仍匹配不到默認(rèn)走finish絕不讓圖執(zhí)行在中途斷裂。5.2 節(jié)點(diǎn)間數(shù)據(jù)復(fù)用與并發(fā)問(wèn)題LangGraph4j 的圖本身是支持多實(shí)例并發(fā)執(zhí)行的但如果你在節(jié)點(diǎn)里偷懶把中間結(jié)果存在類字段里就會(huì)出現(xiàn)嚴(yán)重串?dāng)?shù)據(jù)問(wèn)題。比如我一開(kāi)始為了省事在 Service 類里寫(xiě)了一個(gè)currentState字段結(jié)果兩個(gè)用戶同時(shí)發(fā)任務(wù)時(shí)后一個(gè)用戶直接覆蓋前一個(gè)導(dǎo)致 A 的請(qǐng)求跑到一半拿到 B 的數(shù)據(jù)。排查了很久才意識(shí)到State 必須通過(guò)方法的入?yún)鬟f不能塞進(jìn) Bean 的成員變量。正確做法是節(jié)點(diǎn)方法參數(shù)里接收 State返回值也是 State所有的臨時(shí)變量都放在 State 或方法局部變量里。團(tuán)隊(duì)里所有人都要遵守這個(gè)約定否則并發(fā)一上來(lái)就出事故。5.3 如何觀察圖執(zhí)行過(guò)程逐步輸出排查 Multi-Agent 問(wèn)題最痛苦的是“你只知道結(jié)果不對(duì)不知道卡在哪一步”。我用stream方式輸出后明顯效率提升。每個(gè)節(jié)點(diǎn)進(jìn)入、退出、路由方向都能看到compiledGraph.stream(Input.of(input)) .stream() .forEach(event - System.out.println(event));LangGraph4j 的輸出里包含事件類型和狀態(tài)比如ON_NODE_START、ON_NODE_END、路由結(jié)果等。配合日志文件的 traceId基本能還原一條完整的“用戶請(qǐng)求 - Supervisor 決策 - 子 Agent 執(zhí)行 - 回到 Supervisor”的鏈路。還有一個(gè)很土但很有用的技巧在節(jié)點(diǎn)代碼里加一個(gè)短日志打印當(dāng)前 State 里幾個(gè)關(guān)鍵字段的摘要。實(shí)測(cè)不需要打印整個(gè) State因?yàn)橄v史可能很長(zhǎng)刷屏刷到?jīng)]法看。打印steps、next、instruction就夠了。5.4 關(guān)于“Spring AI 還是 LangGraph4j”的最終判斷回到開(kāi)頭那個(gè)問(wèn)題我認(rèn)為真正的判斷標(biāo)準(zhǔn)不是看誰(shuí)更火而是看你的流程復(fù)雜度。如果只是單一 Agent 工具函數(shù) 對(duì)話補(bǔ)全用 Spring AI 是最省事的。它和 Spring Boot 融合得很好寫(xiě)個(gè) ChatClient 就能干活。這時(shí)候引入 LangGraph4j純屬給自己增加概念負(fù)擔(dān)。但如果你的業(yè)務(wù)里已經(jīng)出現(xiàn)了“多個(gè)角色協(xié)作”、需要條件分支、需要人工確認(rèn)、需要從失敗現(xiàn)場(chǎng)恢復(fù)那就應(yīng)該選 LangGraph4j。你可以在它的節(jié)點(diǎn)里繼續(xù)用 Spring AI 調(diào)模型兩者配合起來(lái)才是完整方案。還有一點(diǎn)LangGraph4j 的官方文檔更新速度相當(dāng)快不同版本的 API 可能略有差異。我在項(xiàng)目里直接把依賴版本鎖死并且維護(hù)了一套從最小圖到完整圖自動(dòng)跑通的集成測(cè)試。每次升級(jí)依賴先跑一遍測(cè)試確認(rèn)行為沒(méi)變?cè)俸先胫鞲赡苁〉粢淮蟀肽涿畹木€上故障。最后分享一個(gè)很土但實(shí)用的建議如果你也是第一次接觸 LangGraph4j不要一上來(lái)就設(shè)計(jì)十幾個(gè)節(jié)點(diǎn)的復(fù)雜圖。先把 Supervisor 兩個(gè)子 Agent 的最小循環(huán)跑通確認(rèn)路由和狀態(tài)流轉(zhuǎn)符合預(yù)期再逐步加 Checkpoint、人工審批、超時(shí)控制。多 Agent 系統(tǒng)最怕的不是模型不行而是編排邏輯自己先亂成一鍋粥。