做 Java 后端的朋友这两年应该都有种焦虑看着 Python 社区里 LangChain、AutoGPT、CrewAI 这些框架轮番刷屏自己的 Spring Boot 项目想接个 AI 能力却总觉得隔了一层膜。我也一样团队里全是 Java 工程师从零转 Python 不现实硬套 Spring AI 又觉得自定义能力不够。折腾了小半年之后我的结论是Java 生态其实已经有一对能打的组合——LangChain4j 负责和模型对话、管理工具LangGraph4j 负责把多步流程编排成可控的图。这篇文章把我基于它们设计的一套低代码工作流通用智能体平台架构完整梳理一遍从选型理由、整体分层、核心实现到踩坑记录尽量讲透希望能给同样在 Java 技术栈里做智能体开发的朋友一条清晰可走的路线。1. 为什么是 LangChain4j LangGraph4j而不是其他组合1.1 Java 技术栈做智能体的三条路线先说我为什么没直接上 Spring AI。Spring AI 的定位是“Spring 生态的 AI 抽象层”它把 ChatModel、EmbeddingModel、VectorStore 这些概念做成了类似 JdbcTemplate 的规范。好处很直接如果你只需要简单调用通义千问、OpenAI 或者本地 Ollama几行配置就完事。但坏处也很明显到了 Agent 和流程编排这个层面它提供的还只是非常初级的工具调用能力。一旦你的流程里有分支、循环、并行、人工审批这些真实业务里绕不开的结构Spring AI 能帮到你的其实很有限。社区里有个问题被反复问“现在到底用 Spring AI 还是 LangGraph4j”我的答案是如果只是做一个简单 ChatBot用 Spring AI 完全够如果你要做一个平台让业务人员拖拖拽拽就能跑通一条包含多次模型调用、工具调用、条件分支的智能体流程那必须找一个能真正落地工作流的执行内核LangGraph4j 是当前 Java 生态里最接近这个定位的选择。LangChain4j 则恰好补齐了 LangGraph4j 不擅长的部分模型供应商接入、消息历史管理、文档切分、检索增强、工具描述生成、结构化输出解析。你可以把 LangChain4j 理解为“和模型打交道的工具箱”把 LangGraph4j 理解为“把多步骤流程串成图的执行器”。这两个框架实际上并不是竞争关系LangGraph4j 的官方文档里甚至直接演示过和 LangChain4j 的整合用法。我选型时把几条候选路线都认真对比过全部自研编排引擎工作量完全不可控状态管理、并发控制、重试机制、持久化这些坑都要自己趟一遍在人力有限的情况下不建议。只用 Spring AI 加代码硬编码流程对固定的极少数流程够用流程数量一旦增加运维和迭代成本会指数级上升业务人员也完全无法参与配置。只用 LangGraph4j 不用 LangChain4j会导致模型接入代码大量重复尤其是工具定义和结构化输出解析写起来非常繁琐。LangChain4j LangGraph4j一个管模型交互一个管流程编排各司其职是目前 Java 生态里组合拳最合理的方案。1.2 两者如何分工模型交互与流程编排LangGraph4j 真正打动我的不是它叫“LangGraph 的 Java 移植”而是它把 Agent 从“循环调用模型直到结束”的黑盒变成了“节点 边 状态”的白盒。在低代码平台里这是一个决定性的优势。原因很简单低代码平台的用户不光是研发还有产品经理、运营、实施顾问他们不关心模型内部怎么思考但特别关心“当条件 A 满足时走这个分支”“当工具返回错误时重试两次然后进入人工处理”这类业务规则能不能表达清楚。LangGraph4j 提供的核心原语其实只有三个State图中的共享状态、Node一个执行单元、Edge节点之间的连接包括普通边和条件边。所有复杂流程最后都能落到这三个原语上。比如一个“智能客服先查知识库查不到就调用内部 API 查订单再查不到就转人工”的流程翻译成图就是入口节点 - 知识库检索节点 - 条件判断节点 -命中LLM 回答节点 / 未命中API 查询节点- 人工接管节点。这种表达方式非常接近我们在低代码画布上拖出来的那张流程图所以它天生适合作为低代码工作流引擎的内核。2. 低代码工作流通用智能体平台的整体架构2.1 平台分层设计我把整个平台拆成四层每一层负责的事情分得很清楚交互层可视化工作流编排画布、节点属性配置表单、运行状态监控、日志查看。这一层是用户直接面对的部分体验好不好基本由这层说了算。编排层把用户在画布上拖拽生成的 JSON 定义转换成语义化的工作流模型再交给执行引擎。还负责校验节点配置、检查环形依赖、生成部署版本。执行层以 LangGraph4j 为核心执行器按图结构逐节点执行维护状态、控制并行串行、做重试和超时。基础设施层模型网关统一管理不同供应商的 API 地址和密钥、向量数据库、工具注册中心、对象存储、消息队列、任务调度。这里有一个很关键的设计取舍编排层和执行层之间必须隔着一个“工作流定义模型”而不是直接让前端把页面操作映射成 LangGraph4j 的 Java 对象。原因在于执行内核是可以替换的。今天你选 LangGraph4j半年后如果社区出现了更好的编排内核只要工作流定义还是标准的 JSON Schema切换成本就不会太高。我在设计时把“核心领域模型”定义为有哪些节点类型、哪些连接关系、哪些数据契约而不是“某个框架的某个类”这个抽象让整个平台的天花板高了很多。2.2 工作流引擎与 Agent 编排到底差在哪做过传统工作流比如 Camunda、Flowable的人可能会问直接用 BPMN 引擎不行吗我的看法是BPMN 非常适合审批流、任务分配、会签并行这类以“人”为中心的场景但对于“模型根据上下文决定下一步做什么”的 Agent 场景显得拧巴。BPMN 要求预先定义完备的网关条件而 AI 场景里很多分支条件是运行期动态产生的——你不知道模型会不会输出一个需要调用工具的意图除非你实时解析它的输出。LangGraph4j 的条件边天然支持“这个节点跑完后根据状态动态决定走哪条边”这就是 Agent 需要的模式。所以我的平台里保留了一张“工作流”的表底层是 LangGraph4j 的图条件分支不强制写死在前端的静态配置里而是可以挂一段“动态路由函数”让模型或代码决定下一步去向。2.3 节点类型设计平台最初版本的节点类型我建议先收着不要一上来就铺十几个类型。我最终定了六类节点类型核心作用典型配置LLM 节点调用大模型生成回答或决策模型名称、System Prompt、输入字段、输出字段工具节点调用注册中心里的外部工具工具名、入参映射、超时时间、失败策略条件节点根据状态做分支路由规则表达式、true 分支、false 分支知识库节点相似度检索并写入状态向量库配置、topK、query 字段、输出字段人工确认节点暂停执行等待人工审批审批人、提示信息、确认后分支子工作流节点调用另一张工作流图实现复用子工作流 ID、入参映射、出参映射这六类覆盖了社区里大部分智能体场景RAG 问答、内容生成、业务助理、异常升级等等。节点多不一定好每多一个节点类型画布交互、数据校验、执行引擎、测试用例都要同步扩展维护成本会拖垮低代码平台本身。3. 核心实现要点拆解3.1 工作流 DSL画布如何映射成一张可执行的图下面是一个简化后的工作流定义 JSON你可以感受一下低代码画布上的“图”怎么落成配置{ id: rag_order_query, name: 订单查询智能助手, nodes: [ { id: entry, type: start, next: retrieve }, { id: retrieve, type: vector_store, params: { topK: 5, queryField: user_query, outputField: knowledge_chunks }, next: check }, { id: check, type: condition, params: { expression: {knowledge_chunks}.length 0 maxScore 0.7 }, branches: { true: llm_answer, false: tool_order_query } }, { id: llm_answer, type: llm, params: { model: qwen-plus, prompt: 你是一个订单客服请根据知识库内容回答用户问题。, inputField: knowledge_chunks, outputField: answer }, next: human_confirm }, { id: tool_order_query, type: tool, params: { toolName: query_order, args: { orderId: {user_query_order_id} }, outputField: order_result }, next: llm_answer }, { id: human_confirm, type: human_confirm, params: { message: 请确认以下回答是否发送给用户, inputField: answer }, next: end } ] }所有“图”的表达都收敛成“节点数组 每个节点上的 next 指向 条件节点的 branches 分支表”前端画布和 JSON 之间是一一对应的可以互相反推。这套 DSL 在后端要做三件事第一是校验节点 ID 是否存在、是否有不可达节点、是否有环。除非人工确认节点和重试循环否则默认不允许出现环。第二是通过拓扑排序生成节点的执行顺序同时做静态分析用于后端展示“预计执行步骤数”。第三是生成 LangGraph4j 的图构建代码这一步是用户配置翻译成执行内核的关键。翻译后的 Java 代码大概是这个意思StateGraphWorkflowState graph new StateGraph(WorkflowState::new); for (WorkflowNode node : def.getNodes()) { graph.addNode(node.getId(), ctx - executeNode(node, ctx)); } // 根据 next 和 branches 添加边 for (WorkflowNode node : def.getNodes()) { if (condition.equals(node.getType())) { graph.addConditionalEdges(node.getId(), state - evaluateCondition(node, state), node.getBranches()); } else if (node.getNext() ! null) { graph.addEdge(node.getId(), node.getNext()); } } return graph.compile();实际代码会比这段示意复杂但核心思路就是DSL 是唯一的模型来源LangGraph4j 只是执行后端前端、校验、监控都围绕 DSL 展开。3.2 状态管理与上下文传递LangGraph4j 的每个执行实例都持有一个 State 对象它贯穿整个图的生命周期。我的设计把状态分成三层全局状态存放用户问题、最终的 answer、中间结果等用名字直接访问。节点局部配置每个节点的 params在节点执行前从全局状态里渲染出真实的参数。会话级外部存储当全局状态越来越大比如超过 64KB时把历史消息和大的 chunk 文本放到 Redis 或对象存储State 里只保存引用 key。这里最容易踩的坑是把大文本直接塞进全局状态。LLM 节点一次检索如果返回 20 个文档每个 1000 字状态里就是 2 万字的文本如果流程里有 5 个节点都往状态里写大文本内存和序列化开销一下子就上来了。我的做法是在 DSL 里就声明“哪个字段是临时字段、执行完即删”把中间结果控制在必需的最小集。实际定义 State 时我会用类似下面的结构public class WorkflowState { private MapString, Object global; private MapString, Object local; private ListMapString, Object parallelResults; // getters/setters }State 的另一个重点是并发安全。LangGraph4j 支持并行分支如果两个并行分支同时往同一个字段写值会有覆盖问题。我建议所有写入状态的字段在运行时做 append 型聚合比如 parallelResults 字段定义为 List各分支往尾部追加各自的结果避免相互覆盖。这一点尤其重要因为低代码画布上很容易拖出几个并行节点用户通常不会意识到后端在共享状态。3.3 模型调用与工具注册模型调用我全部走 LangChain4j 的 ChatLanguageModel 抽象而不是直接请求供应商 SDK。这样换来两个非常实际的好处换模型供应商只需改一个工厂方法对接 OpenAI、通义千问、Ollama 都是一套代码工具调用这块 LangChain4j 已经帮你处理了“模型要求调工具 - 你执行 - 把结果返回给模型”这组循环还支持流式输出。工具注册中心要解决的不仅仅是“把方法变成 JSON Schema 给模型看”更重要的是权限、重试、超时、审计。我给每个工具定义了元信息名称和描述模型靠描述决定要不要调用这个工具。入参格式定义参数类型、必填项以及如何从状态里取参数。是否需要人工确认高风险操作如发消息、改数据可以强制走人工确认节点。调用超时时间和失败策略超时是重试还是降级降级走哪个分支。注册工具的时候框架会自动用 LangChain4j 的 ToolSpecifications 生成模型所需的 function calling 描述。有一点我特别提醒工具描述里必须写清楚“什么时候用这个工具、什么时候不要用”模型选错工具的几率会明显下降。这是从 LangChain4j RAG 实践中得到的经验文档和工具描述的质量直接影响最终效果很多人容易忽略这一点。3.4 低代码面板与后端的联动逻辑前端画布我采用的是主流的节点图编辑器思路——左侧拖拽节点到画布右侧动态渲染属性表单最终产出上面定义的 JSON。这里有一个开发时很容易忽略的体验问题属性表单的字段依赖节点类型变化很大。比如 LLM 节点要配 prompt、模型名、输入输出字段而条件节点要配表达式和分支。所以后端需要为每种节点类型准备一个 JSON Schema 描述表单结构前端拿到 Schema 后动态渲染组件。这样前端不用硬编码表单后端每新增节点类型前端自动就适配了。“部署”动作在后端做的事是先把 JSON 定义解析成 WorkflowDefinition 对象经过格式校验和语义校验生成一个不可变的部署版本号再调用 LangGraph4j 构建成 CompiledGraph缓存到内存中的图谱注册表里。每次运行时根据工作流版本号获取对应的 CompiledGraph执行时把状态初始化和运行时参数注入。运行接口本身不直接和节点的具体逻辑耦合治理起来非常干净。4. 实操过程与踩坑实录4.1 最小可运行原型的搭建步骤如果你要从零开始复现这套平台我建议按下面顺序推进每一步都可以单独验证出了错也知道是哪个环节第一步新建一个 Spring Boot 3.2 Java 17 项目引入依赖。dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version1.0.0-beta1/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version1.0.0-beta1/version /dependency dependency groupIdorg.bsc.langgraph4j/groupId artifactIdlanggraph4j-core/artifactId version1.0.0/version /dependency第二步先不碰低代码直接用 LangGraph4j 手工写一个三节点图LLM - 条件判断 - 工具调用确认框架本身工作正常。这一步是为了排除框架使用方式的变量同时让团队熟悉核心 API。第三步定义 JSON DSL Schema写一个解析器把 JSON 转换成 LangGraph4j 的 StateGraph。此时可以用订单查询工作流通一个 JUnit 测试。测试通过后再引入低代码面板让前端输出 JSON 而不是 Java 代码。第四步把模型调用封装成 ChatLanguageModel 工厂支持通过配置切换 OpenAI 或本地模型。建议一开始就用接口隔离模型供应商否则后续换模型会很痛苦。第五步加工具注册中心注册两三个真实业务工具比如查询订单、发送企业微信消息。工具注册成功后画布上的工具节点能参数映射到工具方法基本闭环就形成了。这几个步骤看似简单我实际调了整整两周才跑顺主要原因在于 LangGraph4j 版本迭代快官方示例和当前版本 API 有出入。所以我把实际踩过的坑单独整理了一节读者大概率也会遇到。4.2 典型问题与排查技巧第一个高频问题版本兼容性。LangChain4j 每两三个月就有新版本LangGraph4j 也在快速迭代两边的 API 都不是很稳定。我建议锁版本并且把依赖升级作为独立任务处理不要一边写业务功能一边顺手升版本。我自己遇到过最典型的情况是升级 LangGraph4j 后 State 的 get/update 接口签名变化导致全链路编译不过。解决办法是每个版本升级前先跑已有的工作流测试集确保全绿再合入。第二个问题是模型超时导致整个工作流卡死。LLM 调用是网络调用如果不设置超时长响应或供应商故障会让流程挂几分钟。我的做法是把 ChatLanguageModel 的 timeout 配置暴露到节点级别工具节点和 LLM 节点分开设置超时默认 30 秒重试最多 2 次两次重试之间按指数退避。同时在执行层加一个全局执行超时比如整个工作流超过 10 分钟强制终止并返回错误信息给前端。第三个问题是状态字段命名冲突。低代码画布上用户随意起节点名两个节点都叫 output 时就可能相互覆盖。我在解析 DSL 时对所有“暴露到全局状态的字段”做名字校验要求必须唯一并且在生成图时给每个节点读写字段加内部前缀比如节点 llm_answer 写入的字段在内部是 llm_answer.answer只有显式声明输出给下一个环节的字段才会转换成不带前缀的全局名。这样基本杜绝了命名冲突。第四个大坑是条件表达式解析。最初我打算直接用 EL 表达式引擎但发现用户写的表达式经常是业务风格比如“knowledge 不为空且分数大于 0.7”。后来换成 JSONPath 加简单比较操作符并给前端提供一个可视化条件编辑器用户在界面上配置“字段得分 大于 0.7”这种规则后端翻译成内部表达式。低代码平台需要在意的是用户心智模型而不是工程师喜欢的最小化语法。4.3 性能与稳定性优化在性能方面我做了几件事CompiledGraph 实例在内存里做了缓存不每次请求都重建图对模型调用做连接池复用LangChain4j 内部使用 OkHttp需要配置合理的连接池大小对知识库检索节点做缓存同一个问题的 embedding 结果可以缓存 5 分钟对工具调用结果按参数哈希做短时缓存避免重复调用外部系统。稳定性方面最需要注意的是重试机制的写法。LangGraph4j 支持在一个节点上加重试次数但不要把无限重试用在一个会持续失败的外部服务上。我在工具节点上加了一个 fallback 节点概念工具连续失败两次后可以走“人工处理”分支让用户决定降级方案。平台最终给人的感觉应当是“在工作流级别就能看到失败和恢复的路径”而不是黑洞式重试。我也专门测过运行时长较长的任务。我在平台的执行层引入了一个异步执行模型工作流的运行不占住用户的 HTTP 请求线程。当用户点击运行后接口立刻返回一个 executionId前端通过轮询或 WebSocket 订阅执行状态。这也是 LangGraph4j 适合这个场景的原因——执行状态可以序列化必要时可以持久化到数据库服务重启后恢复执行。这个能力对生产环境至关重要因为真实的业务工作流经常要跑几十秒甚至几分钟不能因为一次发布或一次重启就丢失执行进度。5. 后续扩展方向与个人体会5.1 平台能力的延伸方向目前这套架构跑通之后我接下来准备做三件事。第一是多租户支持在 DSL 和状态对象里带上 tenantId图实例按租户隔离工具注册中心按租户过滤可见范围避免不同客户之间互相看到对方的工具和数据。第二是工作流版本管理和灰度发布部署生成版本号后在网关层做按比例分流让一部分流量走新版本一部分走旧版本跑一段时间后根据错误率和耗时决定是否全量切换。第三是人机协同增强把“人工确认节点”升级成可以指定执行人、截止时间、会签模式的完整任务中心这样才能覆盖更广的企业场景。5.2 我的几点实操体会最后说几句个人实际的体会。选 LangChain4j LangGraph4j 这个组合最大的收获不是“框架很新很酷”而是它让我终于可以在 Java 团队里把 Agent 从 Demo 推到生产。LangChain4j 的模型抽象省去了大量供应商对接的细节LangGraph4j 的白盒流程让我能和业务同事沟通“这里为什么会走这个分支”这种可解释性在项目推进里非常宝贵。如果你也准备在 Java 技术栈里搭建类似的低代码智能体平台我的建议是先别急着铺大而全的界面和几十种节点类型先把一个垂直场景比如订单查询助手从画布配置到执行出结果走通。路径短、价值可见团队信心也会起来。之后再去加工具、加节点类型、加多租户每走一步都回归测试、验证效果。这样迭代平台才能越做越稳而不是越做越复杂。