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 走到节点 C，C 判断结果不合格，又指回 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只负责查订单系统，把结果写进 State；generate_reply只负责生成回复文案。每个节点内部都足够短，即使模型调用失败了，你也知道该重试哪个节点，而不是整个 Agent 从头再来。

节点内部还需要做防御式处理：模型返回格式不符合预期时，是自己修正还是走异常边？工具超时了是重试还是直接转人工？这些在节点实现里想清楚，比放到图外面做全局 try-catch 有效得多。

2.4 Edge 和 ConditionalEdge：把“如果”写进图里

固定边很简单，A 节点结束后一定去 B 节点。复杂的是条件边。LangGraph4j 的addConditionalEdges允许你提供一个路由函数，函数的输入是当前 State，返回值是“下一步节点名”。

这个设计的好处是，路由逻辑集中在一个地方，可单测、可替换。我在路由函数里一般只写纯逻辑，不做模型调用，不做 IO。比如根据intent字段判断走answer_node还是human_node，就把映射表写好，搞清楚置信度边界。如果你在路由函数里又去调一次模型，等于埋了一颗雷：路由结果本身不可控，而且每次执行图的成本翻倍。

条件边多了以后，建议在路由函数里加一个兜底分支。模型总会出现“我判断不出来这是哪类意图”的情况，这时候应该默认走人工或安全回复，而不是让图抛异常。这个兜底逻辑是 Agent 稳定性的关键设计，很多线上故障都出在“模型返回了意料之外的值，路由函数没接住”。

3. 从 0 到 1 搭一个可运行的 LangGraph4j Agent

3.1 场景定义：一个带人工兜底的售后工单助手

为了不空谈，我挑一个典型但不过于复杂的场景：用户提交售后工单，Agent 先做意图识别，再决定是直接检索订单信息并生成回复，还是转人工处理。这个场景具备分支、节点流转、状态写入和人工介入，非常适合用来理解状态图。

我用到的 State 字段大致是这样：

图结构就三跳：入口节点做意图识别；然后条件路由，普通咨询直接答复，复杂问题转人工；答复节点最后生成文案。一旦needHuman为 true，流程走到human_handle节点后就挂起，等待人工处理完成再结束。

3.2 代码骨架与关键实现

下面代码是 LangGraph4j 常见的写法，版本相关的 API 建议以官方文档为准，但核心思想不变。依赖坐标大致长这样：

<dependency> <groupId>org.bsc.langgraph4j</groupId> <artifactId>langgraph4j-core</artifactId> <version>1.0.0</version> </dependency> <dependency> <groupId>org.bsc.langgraph4j</groupId> <artifactId>langgraph4j-spring-ai</artifactId> <version>1.0.0</version> </dependency>

定义状态对象，核心是提供一个初始 State 构建方式，以及把部分更新合并回 State 的逻辑。为节省篇幅，我直接用简单的 Map 风格做演示：

public class AfterSaleAgent { private final ChatClient chatClient; public AfterSaleAgent(ChatClient chatClient) { this.chatClient = chatClient; } // 节点1：意图识别。只用轻量提示词，不调用任何外部工具。 Map<String, Object> classifyIntent(Map<String, 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：根据意图查询订单信息。 Map<String, Object> searchOrder(Map<String, Object> state) { String sessionId = state.get("sessionId").toString(); String orderInfo = queryOrderSystem(sessionId); return Map.of("orderInfo", orderInfo); } // 节点3：生成回复文案。 Map<String, Object> generateReply(Map<String, 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(Map<String, 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"; } Map<String, Object> humanHandle(Map<String, Object> state) { // 实际项目中这里会发送通知并等待人工处理。 // 处理完成后将结果写回 state。 state.put("draftReply", "工单已转人工，处理进度稍后会通过消息通知您。"); return state; } }

这是节点层。接着把它们组装成图：

StateGraph<Map<String, 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 走到 B，B 又无条件回到 A，Agent 就会自己跑成一个死循环。我在状态图里会给循环节点加一个最大跳数，放在 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 项目的标配。