LangGraph4j 实战：用状态图编排 Java AI Agent 流程

写这篇 LangGraph4j 入门的时候我已经在 Java 里跑过不下二十个 AI Agent 的练手项目。最开始我跟很多人一样在一个 Service 里疯狂堆 if-else如果是意图 A 就调这个工具如果是意图 B 就先调模型再查库后来代码膨胀到看三行就想重构。直到我把其中一个售后工单助手重写成状态图才真正理解“AI Agent 什么时候该上状态图”这个问题的分量。这篇文章不打算只讲 LangGraph4j 的 API我尽量把判断逻辑、设计思路和实际踩过的坑一起说清楚适合那些已经跑通过 Spring AI 或类似模型调用、但对 Agent 流程编排还处于“一把梭”阶段的 Java 工程师。1. 先想清楚你的 Agent 到底需不需要状态图1.1 Agent 的“流程感”来自哪里很多人对 AI Agent 的理解就是“模型能调工具”。这话没错但只对了一半。一个真正能干活儿的 Agent本质上是“感知-决策-行动-观察”的循环。模型每次输出都不只是一个答案而是一个动作可能是调用函数、可能是查数据库、可能是生成一段文本。而这个循环往往不止跑一次它要带着上一轮的结果继续走。问题就出在这里你用代码怎么写这个循环我见过最简单的做法是把整个循环写在一个方法里用一个大 JSON 存 messages然后for循环调模型。项目刚起步时这确实是效率最高的方案因为没有任何多余抽象。但一旦出现下面几种情况这种写法就开始失控你需要根据当前上下文决定“下一步调用哪个工具”你需要让 Agent 在某个环节停下来等人工确认你需要把运行到一半的状态持久化下来下次接着跑你需要同时跑多个 Agent它们之间还要互相传结果。只要命中两三条硬编码的循环基本就撑不住了。这时引入状态图不是为了显得技术很酷而是为了让“流程”变成显式的一等公民。每个节点是清晰的一步每条边是明确的转移条件Agent 运行到哪儿、为什么这么走全都能看清楚、能审计、能恢复。1.2 三个判断维度复杂度、循环、人工介入我个人的经验是把问题拆成三个维度来判断比拍脑袋准得多。第一个维度是分支复杂度。状态的下一跳是不是只由模型回答决定是不是有多个候选节点如果整个 Agent 只有“先调用模型再根据结果选择工具 A 或 B”这种两层分支用策略模式就够了。可一旦候选路径超过四五个而且后续路径还会继续分叉你手写 if-else 的时候就已经在画一张隐式的图了不如直接把它画出来。第二个维度是循环和回溯。真实 Agent 经常需要“重试”“退回上一步”“让子 Agent 重新查一次”。硬编码循环最怕的就是回溯因为你要维护一个复杂的调用栈。状态图天然支持环节点 A 走到节点 CC 判断结果不合格又指回 A这在图模型里只是一个有向环执行引擎天然支持不会写出一堆递归调用来。第三个维度是人工介入。凡是涉及审核、确认、敏感操作流程就一定要能够“挂起”。比如 Agent 帮你生成了一段面向客户的营销文案在发送之前必须人工确认。状态图可以专门开一个await_human_confirm节点走到这里就停住等外部事件触发再继续。这个能力用普通循环实现非常痛苦因为你得把整个执行上下文挂到某个队列或者表里循环本身很难“暂停”。1.3 状态图不是越多越好我知道很多人看完上面这段会有点焦虑觉得自己的项目是不是也该上状态图。冷静一下判断标尺反过来同样重要。如果你的 Agent 其实就是一次模型调用加上一个固定的工具调用顺序比如“先总结简历再提取技能标签再打分”这是流水线不是图没有条件跳转就不要上状态图。给固定流水线强行套状态图只会多出一堆节点定义和模板代码。又或者你的“状态”只有一个变量根本没有多个需要互斥的路径那用普通代码更直接。我自己喜欢用一个“同事能看懂吗”的检验法把流程讲给旁边工位的同事如果一句话就能说清楚直接写代码如果说三句话还说不清中途还要分情况那就画图。状态图解决的是“复杂度的可视化”不是代码量的精简。过度设计是真实存在的问题我见过有人为了三步流程引入了完整的图引擎结果连他自己都绕晕了。1.4 状态图给你带来的四个具体好处第一是确定性。状态图把“什么条件下走哪条路”变成了可检查的静态结构模型可以乱说但图的边界不会因为模型幻觉而崩塌。第二是可恢复性。节点和边一旦明确State 就可以持久化服务重启、网络抖动后都能接着跑。第三是可测试性。你可以针对每个节点单独喂数据做单测不需要一直让模型“随缘输出”。第四是可审计性。用户问“为什么我的工单被转人工了”你可以明确回答因为在intent_classify节点判定为投诉倾向。这四条对个人练手项目可能没那么重要但对企业级 Java AI Agent 应用平台来说每一条都是硬性要求。2. LangGraph4j 核心概念拆开说2.1 为什么是 Java 生态里的 LangGraph4j如果用过 Python 的 LangGraph再看 LangGraph4j 会有一股很强的亲切感。它把“状态机 图执行引擎”搬到了 JVM 上。但我要提醒一句LangGraph4j 不是 Python 库的逐行翻译它更贴合 Java 的使用习惯强调类型约束和 Spring Boot 集成。在 Java 后端落地 Agent绕不开几个现实问题生产环境基本是 Spring Boot团队背靠 Java 技术栈模型调用不算核心竞争力流程的稳定性才是。LangGraph4j 的高层抽象正好卡在这个位置它不管你是接 OpenAI 还是通义千问还是某个私有化模型它只负责把“节点的流转、状态的读写、条件的判断”这一层做好。模型接入那层你完全可以继续用 Spring AI这俩是在不同层协作。2.2 State 是唯一的事实来源状态图里的每个节点都读同一个 State然后返回自己那部分更新再由引擎合并回全局 State。这个设计初看很简单但它是整个图正确性的命根子。设计 State 的时候最容易犯的错是把所有东西塞进去。模型消息、工具返回、用户ID、临时变量、大段 HTML 全部堆在一个大 Map 里最后你根本不知道哪个节点改了哪个字段。我现在的习惯是先列出“项目必须跨节点传递的数据”至少保证三层。第一层是会话上下文比如messages这是模型多轮对话的基础。第二层是业务数据比如工单号、客户等级、预算金额、审核状态。第三层是执行痕迹比如每个节点写入latest_step方便排查。临时中间变量比如“当前模型返回的原始 JSON”“上一次工具调用的耗时”就不要放进 State 了放在节点内部的局部变量里就行。State 越大合并冲突的概率越高序列化和持久化成本也越高。LangGraph4j 的 State 更新逻辑也值得留意节点返回的不是完整 State而是部分更新引擎负责合并。这意味着每个节点要尽量只写属于自己的字段别动别人的。如果发现两个节点在抢同一个字段说明状态划分设计有问题。2.3 Node一个节点只做一件小事我在代码里看到最多的毛病是有人把两三个职责塞进同一个 Node理由是“反正都是处理同一类业务”。这会让状态图失去意义。Node 的粒度应该是“能独立命名、独立测试、独立失败重试”的粒度。比如一个售后工单 Agent 可以拆成classify_intent、search_orders、generate_reply、send_to_human四个节点。其中classify_intent只负责调用模型做意图分类返回一个枚举字符串search_orders只负责查订单系统把结果写进 Stategenerate_reply只负责生成回复文案。每个节点内部都足够短即使模型调用失败了你也知道该重试哪个节点而不是整个 Agent 从头再来。节点内部还需要做防御式处理模型返回格式不符合预期时是自己修正还是走异常边工具超时了是重试还是直接转人工这些在节点实现里想清楚比放到图外面做全局 try-catch 有效得多。2.4 Edge 和 ConditionalEdge把“如果”写进图里固定边很简单A 节点结束后一定去 B 节点。复杂的是条件边。LangGraph4j 的addConditionalEdges允许你提供一个路由函数函数的输入是当前 State返回值是“下一步节点名”。这个设计的好处是路由逻辑集中在一个地方可单测、可替换。我在路由函数里一般只写纯逻辑不做模型调用不做 IO。比如根据intent字段判断走answer_node还是human_node就把映射表写好搞清楚置信度边界。如果你在路由函数里又去调一次模型等于埋了一颗雷路由结果本身不可控而且每次执行图的成本翻倍。条件边多了以后建议在路由函数里加一个兜底分支。模型总会出现“我判断不出来这是哪类意图”的情况这时候应该默认走人工或安全回复而不是让图抛异常。这个兜底逻辑是 Agent 稳定性的关键设计很多线上故障都出在“模型返回了意料之外的值路由函数没接住”。3. 从 0 到 1 搭一个可运行的 LangGraph4j Agent3.1 场景定义一个带人工兜底的售后工单助手为了不空谈我挑一个典型但不过于复杂的场景用户提交售后工单Agent 先做意图识别再决定是直接检索订单信息并生成回复还是转人工处理。这个场景具备分支、节点流转、状态写入和人工介入非常适合用来理解状态图。我用到的 State 字段大致是这样字段类型说明sessionIdString会话标识用于并发隔离messagesList多轮对话消息userInputString当前用户输入intentString意图分类结果如SHIP_QUERY、REFUND、HUMANorderInfoString订单查询结果draftReplyString生成的回复草稿needHumanboolean是否需要人工介入图结构就三跳入口节点做意图识别然后条件路由普通咨询直接答复复杂问题转人工答复节点最后生成文案。一旦needHuman为 true流程走到human_handle节点后就挂起等待人工处理完成再结束。3.2 代码骨架与关键实现下面代码是 LangGraph4j 常见的写法版本相关的 API 建议以官方文档为准但核心思想不变。依赖坐标大致长这样dependency groupIdorg.bsc.langgraph4j/groupId artifactIdlanggraph4j-core/artifactId version1.0.0/version /dependency dependency groupIdorg.bsc.langgraph4j/groupId artifactIdlanggraph4j-spring-ai/artifactId version1.0.0/version /dependency定义状态对象核心是提供一个初始 State 构建方式以及把部分更新合并回 State 的逻辑。为节省篇幅我直接用简单的 Map 风格做演示public class AfterSaleAgent { private final ChatClient chatClient; public AfterSaleAgent(ChatClient chatClient) { this.chatClient chatClient; } // 节点1意图识别。只用轻量提示词不调用任何外部工具。 MapString, Object classifyIntent(MapString, Object state) { String userInput state.get(userInput).toString(); String prompt 你是售后工单意图识别器。根据用户输入判断意图只能输出以下之一 SHIP_QUERY、REFUND、HUMAN。 用户输入%s .formatted(userInput); String intent chatClient.call(prompt).trim(); if (!Set.of(SHIP_QUERY, REFUND, HUMAN).contains(intent)) { intent HUMAN; } return Map.of(intent, intent); } // 节点2根据意图查询订单信息。 MapString, Object searchOrder(MapString, Object state) { String sessionId state.get(sessionId).toString(); String orderInfo queryOrderSystem(sessionId); return Map.of(orderInfo, orderInfo); } // 节点3生成回复文案。 MapString, Object generateReply(MapString, Object state) { String orderInfo state.get(orderInfo).toString(); String prompt 根据订单信息生成简短客服回复%s.formatted(orderInfo); String reply chatClient.call(prompt); return Map.of(draftReply, reply); } // 条件路由决定下一步走自动回复还是人工。 String route(MapString, Object state) { String intent state.get(intent).toString(); boolean needHuman REFUND.equals(intent) || HUMAN.equals(intent); state.put(needHuman, needHuman); return needHuman ? human_handle : answer_node; } MapString, Object humanHandle(MapString, Object state) { // 实际项目中这里会发送通知并等待人工处理。 // 处理完成后将结果写回 state。 state.put(draftReply, 工单已转人工处理进度稍后会通过消息通知您。); return state; } }这是节点层。接着把它们组装成图StateGraphMapString, Object graph new StateGraph(); graph.addNode(classify_node, this::classifyIntent); graph.addNode(search_node, this::searchOrder); graph.addNode(answer_node, this::generateReply); graph.addNode(human_handle, this::humanHandle); graph.addEdge(start, classify_node); graph.addConditionalEdges(classify_node, this::route); graph.addEdge(search_node, answer_node); graph.addEdge(answer_node, end); graph.addEdge(human_handle, end); graph.compile();跑的时候每次调用都要传入独立的 sessionId并把初始状态放进一个新的 State 对象。线上并发场景下尤其要注意同一个图定义可以被所有请求共用但 State 实例绝不能被共用。否则 A 请求的意向会把 B 请求的订单信息带回 B 的回复里那种 bug 极其隐蔽。3.3 条件路由函数不能有副作用我写路由函数有个硬性要求除了读 State 并返回下一节点名绝不写库、绝不调模型、绝不改外部系统。如果你在路由里调用了一次耗时 500ms 的模型接口整个图的执行时间就被拖了 500ms而且条件判断不稳定的风险直接传导给了图本身。类似于state.put(needHuman, needHuman)这种写法也需要克制。虽然它看起来只是给路由结果留个标记但如果多个节点都会写同一个字段最终合并顺序就很难判断。更稳妥的做法是让每个节点只负责自己的输出字段路由判断依赖的字段尽量由上游节点统一写入。比如needHuman这个字段应该在classify_intent里根据意图一次算好而不是在路由函数里临时 put 进去。3.4 人工介入和挂起机制的实际落地思路如果只是想展示 demo把human_handle当普通节点直接执行完就行。但真实的人工介入需要“挂起”。“挂起”意味着图执行到某个节点时暂停整体 State 被持久化线程释放直到外部系统确认人工处理完成后再恢复执行。LangGraph4j 这类图引擎通常会对这种场景提供 checkpoint 或中断机制。作为工程落地方案我一般会在human_handle节点里把 State 存储到后端数据库或 Redis同时给消息队列发一条待办通知。运营人员在工单系统里处理后回写handled_by、handled_note等字段再通过一个/resume接口把新的 State 提交回去图引擎继续往下走。这里有个重要细节挂起期间 State 里的消息列表不能无限增长。人工处理可能耗时几个小时如果你把用户所有原始消息、中间过程全堆在内存里既不安全也不经济。我的做法是只保留必要字段用户 ID、工单号、待确认信息摘要、下一步路由提示。至于大段的 RAG 检索结果处理完就已经没用了及时丢。3.5 持久化与恢复从“能跑”到“能生产”状态图最大的红利之一是天然支持持久化。你不需要自己设计一个“任务队列”来管理 Agent 进度只要把 State 序列化保存下次反序列化就能接着跑。我用过的方案是存 JSON 到 PostgreSQL结构大概是这样的表create table agent_state ( session_id varchar(64) primary key, graph_name varchar(64), state_json jsonb, current_node varchar(64), updated_at timestamp default now() );每次节点执行完把当前节点名和 state_json 一起更新。恢复的时候反序列化出 State再根据 current_node 决定从哪个节点继续。注意序列化只挑可 JSON 化的字段如果你在 State 里塞了一个无法序列化的 SDK 对象服务重启后直接炸。这是我早期踩过的坑解决方案是所有外部 SDK 客户端在节点内部创建State 里只存 ID、token、必要参数不存连接对象。4. Spring AI 还是 LangGraph4j不是一道选择题4.1 这俩本来就不在一个层次最近总有人问“现在到底用 Spring AI 还是 LangGraph4j”我每次都要先纠正一个误区。Spring AI 解决的是“Java 如何接入大模型”它给你统一的ChatClient屏蔽了不同厂商 SDK 的差异也提供了简单的工具调用支持。LangGraph4j 解决的是“多个模型调用和工具调用如何编排成有状态流程”。一个是模型访问层一个是流程引擎层。把这两个对立起来就像问“用 Spring MVC 还是 MySQL”一样不成立。实际项目里我可以先用 Spring AI 的ChatClient接通模型厂商再在 LangGraph4j 的节点里调用这个 ChatClient。模型调用怎么试都行但图结构保持稳定节点和边不会因为换模型而重写。如果非要说选择标准我会这样看项目复杂度在“一个模型 少量工具”级别LangGraph4j 是锦上添花项目涉及多轮循环、条件路由、人工审核、状态持久化LangGraph4j 才是必需品。核心不是“选框架”而是“你的流程撑不撑得住硬编码”。4.2 Spring AI 的工具调用和 LangGraph4j 的节点怎么配合Spring AI 的工具调用已经在“模型发起函数调用”这个层面解决得很好了你注册一个Tool注解方法模型觉得需要时就会调用它。但在复杂场景下工具调用只是一棵树上的叶子节点。谁来决定调哪个工具工具结果如何影响下一步多次调用结果如何累计这些编排逻辑才是 LangGraph4j 的用武之地。我的推荐架构是外层用 LangGraph4j 画流程在每个节点内部用 Spring AI 做模型交互。比如classify_intent节点内部直接用轻量模型做分类search_order节点内部调用 Spring AI 的 Tool 或者直接写 Java 查询逻辑generate_reply节点再用模型生成文案。这样模型厂商、提示词、工具函数都在节点内部图结构保持稳定排查起来非常舒服。4.3 2026 年 Java Agent 落地的两个关键词合规与闭环看最近的各种 AI Agent 产品盘点我会明显感觉到风向已经不是“能对话”而是“能把事儿办完且不出错”。对 Java 后端来说这意味着两件事第一流程必须可审计第二高风险操作必须有人工兜底。状态图天然适合这两个要求。每个节点都有名字每条路由都有依据每个状态变更都能被记录。你可以很方便地给图增加一个“操作日志”节点把所有用户请求、模型输出、工具调用、路由决策写进审计表。这在金融、医疗、电商等场景几乎是硬需求也是很多企业级 Java AI Agent 应用平台选状态图作为核心的原因。5. 常见问题排查与避坑实录5.1 三个最常见的运行期问题第一个问题是状态更新不生效。你发现节点明明返回了Map.of(intent, REFUND)但路由函数看到的还是空值。多数原因是 LangGraph4j 要求节点返回值经过 State 合并器做处理如果你直接对整个 Map 做了全量替换而不是部分更新合并逻辑可能被覆盖掉。排查思路很简单在路由前面加一行日志把完整 State 打出来看intent到底有没有进去。第二个问题是条件边路由字符串写错。你定义一个节点名叫human_handle路由函数返回了human_handler引擎找不到就直接报错。这类错误我用一个笨办法避免把节点名统统抽成常量类不让路由函数里出现裸字符串。这活儿听起来无聊但省下的排障时间很可观。第三个问题是无限循环。条件边设计不严时节点 A 走到 BB 又无条件回到 AAgent 就会自己跑成一个死循环。我在状态图里会给循环节点加一个最大跳数放在 State 里做计数器超过阈值强制走兜底分支。这个阈值可以根据业务设置普通咨询流程一般 10 跳以内跑完超过 20 跳基本就是图设计出了问题。5.2 调试状态图的三板斧第一板斧是写“跳转日志”。我会在 State 里放一个trace_steps列表记录每次进入节点的原因、离开节点的去向、路由函数的返回值。这个列表既能用于排查也能用于后续做流程审计。线上某个工单被莫名其妙转人工了打开 trace 一看就明白是最后一条模型回复触发了投诉倾向。第二板斧是给路由函数单独写单测不依赖 LLM。路由函数是图的核心逻辑但它不调模型所以可以完全脱离外部服务测试。我通常会准备十几条不同意图的测试数据覆盖所有分支和兜底分支确保任何输入都有确定的出口。第三板斧是先用可视化工具把图画出来再写代码。很多团队习惯用 PowerDesigner 画 UML 状态图这个习惯在 Agent 场景下同样适用。先把节点、口径、回退路径画清楚写代码反而只是体力活。图一旦画错写代码时再返工代价极高。5.3 性能成本与安全合规的实操建议状态图不是免费的。每个节点之间的 State 序列化、路由判断、日志记录都有开销但这类开销通常远小于模型调用。真正要控制的是模型调用次数。我习惯在路由节点用便宜的小模型在内容生成节点才用更强的模型。比如意图分类用最快最便宜的小模型回复生成用高智能模型整体成本能省一大截。缓存也很有用。search_order这类工具节点如果查询的结果和上次一样可以直接复用 State 里的结果不必每次都调外部系统。这个优化点看起来很小但在高频售后场景能把 QPS 压力降下来。最后是数据合规。用户工单信息属于敏感数据不应该把完整内容无限期留在状态上下文里。状态图中的messages我通常会按轮次做裁剪或者摘要既保证模型看到关键上下文又不把原始敏感字段长期驻留。别说状态图是纯内存所以无所谓生产环境一旦涉及日志采集、审计导出这些细节问题都会被放大。实际用下来的一点体会状态图最关键的不是图引擎本身而是“先设计后实现”的纪律。我现在的习惯是每次要写新流程先花半小时在纸上画节点和边直到自己能向同事讲清楚每个分支再动手写代码。如果画到一半发现分支太多、回退太多那几乎可以肯定这个流程需要拆成多个子图或引入消息队列。最后分享一个调试小技巧你在 State 里加一个last_update_reason字段每个节点都写入“这个字段为什么被更新”排查线上问题的时候能看到一条完整的时间线比看一堆分散日志管用得多。踩了几次坑之后这个字段已经成了我所有 Agent 项目的标配。