前一阵子在做一个 Java 后端团队的技术调研报告生成助手需求很朴素用户丢一个技术主题它负责查资料、抽数据、写报告。试了两周单智能体方案终态效果总是不稳定——不是资料查全了但报告结构乱就是报告漂亮但数据算错。后来我把架构切到 LangGraph4j 的 Multi-Agent Supervisor 模式用 supervisor 调度三个专职 worker问题才算系统性解决。这篇博客就把这次从调研到落地的过程讲清楚。内容覆盖为什么多智能体拓扑里 Supervisor 是最容易先落地的形态LangGraph4j 环境搭建和最小 StateGraph 怎么写worker 节点、supervisor 路由、checkpointer 的完整实现思路我在实测中踩过的三个典型坑以及团队里反复纠结的 Spring AI 还是 LangGraph4j我会给出一个实操向的选型结论。不管你是在评估多智能体方案还是已经在写 LangGraph4j 代码这篇都值得花十分钟看完。1. 单智能体撞墙之后我才开始认真研究 Multi-Agent 拓扑1.1 一个 Prompt 塞下所有能力的代价最开始的方案非常朴素一个ChatLanguageModel挂 12 个工具系统 Prompt 里写你是全能的科技情报分析师你可以搜索资料、计算指标、生成报告。demo 数据还不错但很快就出现三类问题。第一指令遵循率下降。工具一多模型经常选错工具。我一开始以为是工具描述写得不够好后来发现根本原因是工具间的边界在模型眼里是模糊的尤其是搜索资料和计算指标这种需要明确上下文的动作。第二上下文相互污染。搜索返回的资料和生成报告的指令在同一个 dialog 上下文里报告很容易被原始资料里的噪声带偏出现资料里有什么就写什么的复读机行为。第三单次请求耗时长。一次调用要完成搜索、读取、分析、撰写四件事执行时间完全不可控用户等十秒才看到第一句话的情况都有。我不否认更精细的 Prompt 更少的工具可以把单智能体调到可用水平。但我的判断是这个方向的天花板太低。业务场景一旦把任务拆细比如先查某开源监控系统的可用性数据再对比三家厂商的指标最后按财报格式输出单智能体维护成本就是指数级上升而多智能体把每个子任务封装成独立节点天然可扩展、可观测、可单独调优。这里有一个朴素但重要的认知转变多智能体不是为了看起来高级而是为了把一个模型干所有事变成每个模型只干一件事。一旦接受了这个设定后面的拓扑选择和实现逻辑就顺了。1.2 Supervisor 拓扑与通信机制为什么不是每个智能体都互相喊话我在调研多智能体拓扑时最常见的是三类形态拓扑形态通信方式优点缺点Peer-to-peer智能体之间直接传消息灵活、去中心化难收敛、监控困难Supervisor中心化所有消息汇聚到 supervisor 再分发可控、可观测supervisor 是单点Hierarchical子 supervisor 分级管理适合复杂任务树实现成本高我最终选了 Supervisor理由很直接第一通信机制最简单。worker 之间不需要知道对方的存在所有消息先汇到 supervisor再由 supervisor 决定下一步。第二状态可观测。每个节点产出什么supervisor 都能看见排查问题的时候相当于有一个总览视角。第三实现成本可控。LangGraph4j 的 StateGraph 天然支持这种单入口 条件边 多节点的模型不需要额外引入消息队列或事件总线。这里需要强调一个认知很多人以为多智能体的通信就是让智能体互相发消息其实图编排框架里的通信本质上是通过共享状态 节点读写完成的。每个节点读当前状态经处理之后写回新的状态边决定状态加工的路径。也就是说消息不是点对点投递的而是沉淀在一个可被所有节点读取的状态空间里。这个概念理解透了LangGraph4j 用起来才会顺手。2. LangGraph4j 环境与最小图先把编排跑起来2.1 选择 LangGraph4j 的理由和依赖引入团队原本考虑过两个方向一个是纯手写状态机 CompletableFuture另一个是引入 Spring AI 的 Agent 基础能力。手写状态机的问题在于多智能体调度里的重试、Checkpoint、条件路由都要自己造轮子写出来的代码注定只有维护者敢碰。Spring AI 很好但对图编排、状态持久化、interrupt 这些多智能体的核心设施当时还比较少文档和 API 支持硬上会变成Spring AI 自己的状态机。LangGraph4j 是 LangGraph 的 Java 移植版本核心能力和 Python 版对齐StateGraph、节点、边、条件边、CheckpointSaver、interrupt 都有。因为团队全是 Java 技术栈不需要额外部署 Python 服务直接嵌进 Spring Boot 线程池里跑就行。Maven 依赖3.x 系列大致这样dependency groupIdorg.bsc.langgraph4j/groupId artifactIdlanggraph4j-core/artifactId version3.1.1/version /dependency dependency groupIdorg.bsc.langgraph4j/groupId artifactIdlanggraph4j-langchain4j/artifactId version3.1.1/version /dependency注意LangGraph4j 早期版本的坐标是org.bsc.langgraph4j后来社区有往com.langgraph4j迁移的趋势。如果你在 Maven Central 上看到不同 groupId说明版本分支不同建议直接以官方 README 里给出的坐标为准不要照抄网上的老配置。我用的 3.1.1 在 JDK 17 和 Spring Boot 3 下跑得很稳没有遇到引入冲突。2.2 状态、节点、边的三要素在写 supervisor 之前我先用最小图跑通 LangGraph4j 的三要素。状态State一个可读写的对象保存 messages、当前路由目标等。节点Node一个函数读状态、处理、返回要更新的字段。边Edge决定调用顺序条件边根据状态里的某个字段决定走向。一个最简单的入口节点 结束示例逻辑和你熟悉的先 A 后 B完全一样// 伪代码级示意不同版本 API 命名有差异重点看节点和边的结构 StateGraphAgentState graph new StateGraph(AgentState.SCHEMA) .addNode(greet, state - Map.of(messages, hello from greeter)) .addEdge(START, greet) .addEdge(greet, END) .compile();这里AgentState的核心数据结构大致是public class AgentState { public static final StateKeyListObject MESSAGES StateKey.of(messages); public static final StateKeyString NEXT StateKey.of(next); public static final StateKey[] SCHEMA new StateKey[] { MESSAGES, NEXT }; }节点返回的Map.of(messages, ...)会覆盖或追加到状态里条件边读取NEXT来决定下一步。我把这个最小图拿给组里两个原先坚持手写状态机的同事看他们很快意识到LangGraph4j 把状态机里最容易出 bug 的部分状态跟踪、转移触发、终止条件变成了声明式配置业务需求变化时改节点的连接关系就行不用删改一坨命令式逻辑。这是选型层面的最大收益。3. Worker 节点让每个智能体只干一件事3.1 岗位说明书的制作系统 Prompt 的分工要点把任务拆成三个 workerresearcher搜索资料、analyst计算指标、writer撰写报告。每个 worker 都是一个独立节点只负责完成自己的子任务。每个 worker 有自己的系统 Prompt我称之为岗位说明书。例如 researcher 的 prompt 是你是一个研究助理只做信息检索与事实整理。你从用户输入和对话上下文中提取检索词调用工具进行搜索输出结构化的研究笔记。你不负责撰写报告也不负责数值分析。关键点不要在 worker 的 prompt 里写入如果...也可以...这样的柔性授权。兼职思维会让模型自行跨边界导致 supervisor 看到的产出变得不统一。worker 的职责范围越窄模型选工具越准prompt 也越好维护。3.2 工具注册与节点返回值约定worker 的工具通过 LangChain4j 的Tool注解方式注册。比如 researcher 的搜索工具public class SearchDocsTool { Tool(根据关键词搜索内部知识库返回相关文档摘要) public String search(String keyword) { // 调用搜索服务 return searchService.search(keyword, 5); } }绑定模型时我用了 LangChain4j 的AiServices组装然后在 LangGraph4j 节点里调用。核心的 execute 方法大致长这样public MapString, Object execute(State state) { String task state.value(messages).toString(); // 调用带 tool 的 LLM得到回答 var response aiServices.chat(task); return Map.of(research_notes, response); }这段代码我简化了工具调用组装细节。核心要理解的是worker 节点返回的不是一段面向用户的话而是一个给 supervisor 看的中间产物例如research_notes、analysis_result、report_draft。中间产物以结构化字段的形式写回状态而不是和用户消息混在一个 messages 列表里。这样 supervisor 在下一轮路由时能准确知道每个 worker 干了什么。我在实际测试中发现节点返回的字段命名最好带业务含义不要用result1、result2这种序号。因为图的状态会越来越大字段名就是业务语义的一部分命名混乱会让后续调试 cost 变得极高。4. Supervisor 的路由机制LLM 调度员如何干活4.1 核心代码路由指令的生产supervisor 节点同样是一个 LLM 调用只不过它不执行具体工具而是输出一个下一个节点决策。最直接的做法是把决策建模成一个结构化输出recordpublic record SupervisorDecision(String next, String reason) {} var decision model.generate(List.of( SystemMessage.from(supervisorSystemPrompt), UserMessage.from(currentConcentratedContext) ), SupervisorDecision.class);next只有四种取值researcher、analyst、writer、FINISH。是的没有第五种这是为了保证能收敛。我在上一版里加过next 也可以等于 human结果模型经常在需要深度分析时把任务推回给人体验很糟。supervisor 系统 Prompt 里我明确写了调度原则你需要判断当前用户的意图是查资料、算数据还是最终要一份成文报告。如果还需要补充事实路由给 researcher如果已经拿到事实但需要计算指标路由给 analyst如果事实和指标齐备路由给 writer。只有当所有子任务都完成、产出达到交付标准时才输出 FINISH。不要反复路由给同一个 worker除非该 worker 明确报告前一步失败。4.2 条件边如何把决策变成图路径得到SupervisorDecision后怎么驱动图走下去LangGraph4j 的条件边写法类似这样graph.addConditionalEdges( supervisor, state - { String next state.value(next).orElse(FINISH); return next; }, Map.of( researcher, researcher, analyst, analyst, writer, writer, FINISH, END ) );每次任意 worker 节点执行完毕后我会把一条带谁产出的中间消息追加到状态同时让图回到 supervisor 入口形成supervisor 决策 - worker 执行 - supervisor 复核的循环。有些人会担心这样很慢每次路由都调用一次 LLM。实测下来对大多数任务来说这个开销是值得的——因为决策模型只做路由一次只生成少数 token 的决策比让一个大模型长时间思考再输出最终答案要快也更可控。4.3 通信机制在 Supervisor 拓扑里的实际载体再回到通信机制。supervisor 能做出好决策前提是它需要看到用户的最新问题上一个 worker 的中间产物可能是research_notes也可能是analysis_result最近几轮的路由历史避免重复调度。这些数据全部存在一个共享状态对象里。supervisor 节点的实现里我通常会拼一个 compact 的 contextString currentConcentratedContext Stream.of( latestUserMessage(state), state.value(research_notes).orElse(), state.value(analysis_result).orElse(), state.value(report_draft).orElse(), routingHistory(state) ).filter(s - !s.isBlank()) .collect(Collectors.joining(\n---\n));这就是多智能体之间的通信本质不通过消息总线点对点传而是统一读写状态。好处是异常发生时有完整的状态快照出问题可以直接 dump 出来看。对于 Java 团队来说这比在业务代码里到处传引用要清爽得多。5. 会话记忆与隔离没有 Checkpointer 的 supervisor 等于失忆调度员5.1 为什么多轮对话必须有会话状态如果只是单轮问答无状态调用也能跑。但真实场景里用户会追问第二家公司的数据给我再看一眼或者刚才那份报告里把图表改成三年对比。如果 supervisor 每次都是白纸一张它既不知道第二家公司是哪家也不知道刚才那份报告是谁写的。LangGraph 系列框架给出的标准解法是 Checkpointer每次节点执行后把状态快照持久化下来并关联一个threadId。下一次调用时传入同一个threadId图会从快照中恢复上下文。5.2 内存版 Checkpointer 的接入LangGraph4j 里提供了CheckpointSaver接口实测中我用内存版就够CheckpointSaver saver new MemorySaver(); StateGraphAgentState graph workflow.compile(saver); // 调用端 var config Map.of(configurable, Map.of(thread_id, thread-001)); var result graph.invoke(input, config);这里有两个细节值得注意。第一threadId最好由业务侧生成并持久化比如存在用户会话表里。否则重启服务后线程 ID 没了用户上下文就丢了。第二内存版MemorySaver不能用多实例部署。如果你有两个服务实例轮询转发用户的请求一定得换成 Redis/DB 的 checkpoint 实现否则不同实例各自维护一份状态用户会感觉到上下文随机失忆。我用一个真实测试场景验证过同一个 threadId 连续问了三个问题第三个问题要求基于前两个问题的结论做总结答案准确切到新 threadId 再问同样的问题模型明确说我看不到之前的对话。这说明 checkpoint 在 LangGraph4j 中是真实生效的。6. 实测翻车记录三个必须提前防范的坑6.1 坑一supervisor 在两个 worker 之间反复横跳第一次联调时我输入搜索某厂商的基站功耗数据并和上一季度对比。结果 supervisor 在 researcher 和 analyst 之间循环了整整七次。翻查日志发现researcher 每次产出一份新的研究笔记analyst 每次产出新的指标supervisor 看到有新增产出就又认为是新信息需要再次路由永远不会输出 FINISH。修复动作有三个系统 Prompt 里加强约束只有新增产出是实质性的回答进展才继续路由如果产出没有导致信息增量直接 FINISH。在 State 里记录路由历史当出现同一个 worker 被推荐超过两次时条件边直接强制走 FINISH。给图执行加上最大步数限制超过则中断并返回当前中间产物。这样即使模型抽风也不会烧掉大量 token。这三步叠加后循环基本消失。需要注意Prompt 约束是软性的代码兜底才是硬性的。我建议每个生产环境的 Supervisor 项目都要有最大步数兜底否则一个循环可能让一次请求耗费几十次 LLM 调用。6.2 坑二上下文爆炸与决策质量下降上线前几天supervisor 的决策突然变得很敷衍经常直接 FINISH或者给错 worker。查看日志后发现每次调用我都把完整 messages 列表传给 supervisor几轮对话后 token 数轻松过万模型在长上下文里反而抓不住重点。我给 supervisor 的输入做了两层裁剪窗口化只保留最近 3 轮用户消息 最近一轮 worker 产出。摘要化新增一个summarize节点当消息条数超过阈值时把旧历史压成一段 summary保存在状态里。实际操作中summarize 节点比较耗时我不会每次都跑只是超过 12 条才触发。这个阈值我调过几轮太早触发会丢失细节太晚触发又会把上下文撑爆。12 条在 OpenAI 和本地化模型上都有不错表现。6.3 坑三worker 工具调用失败导致整图中断某次演示时researcher 调搜索工具超时整个图直接抛异常中断supervisor 没有机会做 fallback。这暴露了我对节点异常处理的疏忽。LangGraph4j 不会替你做业务级容错节点内部必须自己 catch。我在每个 worker 节点外层包了一个safeExecute方法try { return agent.execute(state); } catch (Exception e) { return Map.of(error, e.getMessage(), next, FINISH); }同时工具的 LLM 调用层我还加了两次重试第一次超时后等待 500ms 再试。对内部知识库这样的低延迟服务重试的成功率很高。值得强调的是worker 失败时不要把错误直接抛到图外面最好是转成一个结构化错误信息写回状态让 supervisor 在下一次决策时看到这个工人刚才失败了需要换策略这样整个系统才有自愈能力。7. 团队选型纠结Spring AI 和 LangGraph4j 到底怎么选7.1 两者的舒适区完全不同我理解很多人纠结这个问题因为我们团队也纠结了挺久。先说结论这不是一个简单的替代关系Spring AI 的舒适区是Spring Boot 应用里快速接入 LLM 能力并做好工具抽象LangGraph4j 的舒适区是以图编排的方式管理复杂智能体生命周期。维度Spring AILangGraph4j上手成本低依赖 Spring 生态中需要理解图/状态/节点概念典型场景单 Agent 工具固定顺序链多 Agent 协作、动态路由、跨会话恢复状态持久化有简单的 ChatMemoryCheckpointSaver支持快照/回放条件路由需要手写逻辑原生条件边节点即路由Human-in-the-loop支持有限原生 interrupt 机制与 Spring Boot 集成无缝可作为独立库嵌入Spring AI 适合的场景只需要一个 ChatClient接上模型挂三五个工具开箱即用想用 Spring 家族的 AutoConfiguration 管理各种 model provider需要对话记忆和简单的 advisor 链不需要复杂条件路由。LangGraph4j 适合的场景多个智能体分工协作且需要动态路由supervisor需要跨会话恢复状态、human-in-the-loop、节点级可重放节点之间的流转逻辑经常变动希望以图配置代替命令式代码。最常见的误用是用 Spring AI 硬写多智能体最后自己维护一个巨大的 if-else 状态切换器或者反过来只为了一个简单问答就引入 LangGraph4j成本明显不划算。7.2 我的实操建议能用编排绝不用手写状态机给团队的建议是按复杂度分层如果调用链是固定顺序A 完了 BB 完了 C且分支不超过两个直接用 Spring AI 代码顺序调用最简单。如果任务需要根据内容动态分配到不同 worker或者需要跨会话状态直接上 LangGraph4j不要自己去写状态机。如果项目已经用了 Spring AI 做基础设施也不冲突LangGraph4j 可以单独作为一条支线运行在 Spring Boot 里两者各管一段把 LLM 调用层统一用 LangChain4j 抽象即可。我个人的体会是对于 Multi-Agent Supervisor 这类架构选 LangGraph4j 的收益是长期的。前期多花的一个下午会在后期排查路由问题、加新 worker、做断点恢复时成倍赚回来。最后再分享一个当时帮了大忙的小技巧把每次 LLM 调用的输入输出都落到日志里特别是 supervisor 的决策理由。多智能体系统的黑盒感很强有了决策理由日志用户质问为什么让研究员重做一遍的时候你能立刻给出答案这比任何监控面板都管用。