1. 为什么要在 LangChain4j 和 LangGraph4j 上搭一层低代码工作流1.1 从“写死一个智能体”到“编排一类智能体”的转变过去一年我接触过不少智能体项目绝大多数起步阶段都是同一个套路用 LangChain4j 写一个AiServices接口挂上几个Tool接一个大模型跑通一个客服问答或者文档问答的 Demo。这个阶段很爽几十行代码就能看到效果。但真正往业务里推的时候问题立刻暴露出来——业务方今天要加一个“先查订单再判断是否退款”的分支明天要加一个“人工审核节点”后天又要求“不同租户走不同的提示词和工具集”。如果每一次变更都要改 Java 代码、重新打包、走一遍发布流程这个智能体基本就废了因为业务迭代的速度远快于研发发版的速度。这就是我决定在LangChain4j LangGraph4j之上再抽象一层低代码工作流平台的直接原因。LangChain4j 解决的是“单个智能体能力”的问题——模型调用、RAG 检索、工具调用、记忆管理它都封装得很扎实LangGraph4j 解决的是“多个节点之间怎么流转”的问题——它把状态机、条件边、循环、检查点这些图计算的概念带进了 Java 生态。但这两者加起来仍然是面向开发者的 API不是面向业务配置的界面。低代码这一层要做的就是把“图”和“节点”变成业务人员能在画布上拖拽、连线、填参数的东西把“提示词”“工具”“知识库”“条件表达式”变成表单里的字段。所以这个平台的定位很明确研发负责把原子能力模型、工具、检索器、外部 API注册成可复用的节点业务负责在画布上把这些节点连成一条能跑的流程。中间那层“图执行引擎”由 LangGraph4j 承担“节点内部逻辑”由 LangChain4j 承担。这个分层是我踩了不少坑之后才想清楚的后面会详细讲。1.2 三层架构的职责边界划分我把整个平台拆成三层这个划分方式直接决定了后面所有的技术选型和代码结构所以先讲清楚。最底层是能力层基于 LangChain4j 构建。这一层包含ChatLanguageModel的封装对接不同厂商的模型、EmbeddingModel、EmbeddingStore向量库、ContentRetrieverRAG 检索、Tool工具调用以及ChatMemory。这一层的特点是稳定、变化少、由研发维护。一个工具一旦注册进来它的入参出参 schema 就固定了业务层只能选择用或不用不能改它的内部实现。中间层是编排层基于 LangGraph4j 构建。这一层把能力层的原子能力包装成图的节点Node用边Edge和条件边ConditionalEdge定义流转逻辑用State承载节点之间传递的数据。LangGraph4j 的核心抽象是StateGraph它要求你定义一个状态类型然后每个节点接收状态、返回状态的部分更新。这一层的关键设计是状态 schema 的标准化——如果每个工作流都自定义一套状态结构那低代码层就没法做通用的表单渲染。我的做法是定义一个通用的WorkflowState内部用一个MapString, Object存业务数据再附加一些平台级的元数据字段如currentNode、traceId、errorInfo。最上层是配置层也就是低代码平台本身。这一层包含画布编辑器、节点属性面板、流程校验器、版本管理、发布与回滚。它不直接碰 LangChain4j 和 LangGraph4j 的 API而是通过一个中间表示IR来描述工作流。IR 是一个 JSON 结构描述了节点列表、节点类型、节点参数、边和条件。配置层产出 IR编排层把 IR 编译成 LangGraph4j 的StateGraph能力层提供节点执行时需要的具体实现。这个 IR 是整个平台的“契约”也是后面做版本对比、导入导出、跨环境迁移的基础。提示三层划分的核心价值在于变更隔离。业务改流程只动 IR不动代码研发加能力只动能力层不影响已有流程。如果这三层混在一起低代码就退化成了一个“配置化的 if-else”很快就会失控。1.3 为什么是 LangGraph4j 而不是自己写状态机有人会问工作流编排无非就是节点加跳转自己写一个状态机引擎不行吗我一开始也这么想过甚至用 Java 的enum加switch写过一个简易版本。但很快遇到几个绕不过去的问题。第一是循环与条件边。业务工作流里经常有“检索不满足条件就重新检索”“审核不通过就退回上一步”这种需求。自己写的状态机处理循环时很容易出现死循环或者状态污染。LangGraph4j 对循环有明确的支持配合检查点Checkpoint机制可以在每次节点执行后保存状态快照既方便调试也方便做“从某一步重新执行”。第二是状态合并语义。在并发或者多分支场景下多个节点可能同时更新状态的不同字段。LangGraph4j 定义了状态更新的合并规则默认是覆盖也支持自定义 reducer这个语义如果自己实现很容易出现字段丢失或者覆盖顺序不确定的问题。第三是可观测性。LangGraph4j 的图执行天然可以产出执行轨迹——经过了哪些节点、每个节点的输入输出是什么、条件边为什么走了这个分支。这个轨迹对于低代码平台至关重要因为业务人员排查问题时看不懂日志他们需要的是“流程走到哪一步卡住了”的可视化展示。当然LangGraph4j 也不是银弹。它的 Java 版本相比 Python 版本在生态和文档上还有差距某些 API 的设计偏底层需要自己封装一层才好用。但相比从零写一个状态机它至少把“图执行”这个最难的部分做对了。我的策略是图执行交给 LangGraph4j节点内部逻辑交给 LangChain4j平台层只做 IR 到图的编译和节点注册。2. 核心细节拆解IR 设计、节点模型与状态管理2.1 工作流 IR 的字段设计与设计意图IR 是整个平台的骨架它的设计质量直接决定了低代码层能做到多灵活。我最终定下来的 IR 结构大致如下简化版{ id: wf_order_refund, version: 1.2.0, name: 订单退款审核流程, stateSchema: { orderId: { type: string, required: true }, refundAmount: { type: number }, riskLevel: { type: string, enum: [low, medium, high] } }, nodes: [ { id: start, type: start, next: fetch_order }, { id: fetch_order, type: tool, toolName: orderQueryTool, inputMapping: { orderId: $.orderId }, outputMapping: { orderDetail: $.result }, next: risk_check }, { id: risk_check, type: llm, model: qwen-plus, promptTemplate: 根据订单信息判断风险等级{{orderDetail}}, outputMapping: { riskLevel: $.output }, next: route_by_risk }, { id: route_by_risk, type: condition, branches: [ { when: $.riskLevel low, next: auto_approve }, { when: $.riskLevel high, next: manual_review } ], defaultNext: manual_review } ], edges: [] }这里有几个设计决策值得展开说。节点 ID 与类型分离。id是流程内唯一的实例标识type决定这个节点由哪个执行器处理。这样同一个工具可以在流程里出现多次每次用不同的参数互不干扰。如果只用toolName做标识就没法处理“同一个工具调用两次”的场景。inputMapping 和 outputMapping 用 JSONPath。节点之间传递数据不直接操作状态对象而是通过 JSONPath 表达式做映射。这样做的好处是解耦——节点不需要知道状态里有哪些字段只需要声明“我从$.orderId取输入我把结果写到$.orderDetail”。低代码层的属性面板可以直接根据这个映射生成表单业务人员填字段名就行。JSONPath 的表达式能力也足够覆盖大部分场景比如$.orderDetail.items[0].price这种嵌套取值。条件节点的分支用表达式而非代码。when字段是一个表达式字符串平台内置一个轻量表达式引擎我用的是 Aviator因为它对 Java 友好、性能好、语法接近 JavaScript来求值。业务人员在界面上配置“当风险等级等于 low 时走自动审批”背后就是生成$.riskLevel low这样的表达式。这里要注意表达式沙箱——必须限制可调用的方法和类防止表达式注入。stateSchema 显式声明。虽然状态底层是MapString, Object但 IR 里要求显式声明 schema。这个 schema 有三个用途一是画布上做字段提示和类型校验二是流程发布前做静态检查比如某个节点引用了不存在的字段就报错三是给前端表单渲染提供依据。没有 schema 的话低代码就变成了“盲填”体验很差。2.2 节点执行器的抽象与注册机制节点是平台的能力单元每一种节点类型对应一个执行器。我定义的执行器接口大致是这样public interface NodeExecutor { String getType(); NodeResult execute(NodeContext context); default ValidationResult validate(NodeDefinition definition) { return ValidationResult.ok(); } }NodeContext里封装了当前节点的定义、当前工作流状态、以及能力层提供的各种资源模型、工具、检索器。NodeResult包含状态更新一个Map、下一个节点的选择可选条件节点用、以及执行元数据耗时、token 消耗等。目前平台内置的节点类型有这么几类节点类型作用底层依赖start流程入口初始化状态无end流程出口汇总输出无llm调用大模型支持提示词模板LangChain4j ChatLanguageModeltool调用注册的工具LangChain4j Toolrag检索知识库并注入上下文LangChain4j ContentRetrievercondition条件分支Aviator 表达式引擎loop循环执行子流程LangGraph4j 子图human人工审核节点平台任务队列code执行一段脚本受限GraalVM JS 或 Aviatorsubgraph调用另一个工作流LangGraph4j 子图注册机制我用的是 Spring 的ApplicationContext收集所有NodeExecutor的 Bean启动时按getType()建立索引。新增一种节点类型只需要实现接口并加上Component不需要改平台核心代码。这个扩展点是平台能持续演进的关键——后面要加“HTTP 请求节点”“消息推送节点”“数据库查询节点”都是同样的套路。注意code节点是最容易出安全问题的地方。我的做法是默认禁用只有管理员在租户级别显式开启后才能使用并且脚本运行在受限的沙箱里禁止文件 IO、网络访问和反射调用。即便如此生产环境我还是建议尽量用专用节点替代 code 节点。2.3 状态管理与检查点的落地细节LangGraph4j 的状态管理是它相对自己写状态机最大的优势但要用好需要理解几个细节。首先是状态的不可变性。LangGraph4j 的节点返回的是状态的“更新部分”而不是修改原状态。框架会把更新合并到当前状态生成新状态传给下一个节点。这个设计的好处是每次状态变更都有迹可循配合检查点可以做时间旅行调试。但代价是如果状态很大比如 RAG 检索回来一堆文档每次合并都有内存开销。我的优化是大对象用引用传递——状态里只存文档 ID 或者缓存 key实际内容放在一个WorkflowContext的外部缓存里节点通过 key 去取。其次是检查点的存储。LangGraph4j 支持内存和持久化两种检查点。开发调试用内存就够了但生产环境必须持久化否则流程中断后没法恢复。我选的是把检查点存到关系库MySQL序列化成 JSON。这里有个坑状态里的对象必须可序列化如果某个工具返回了一个不可序列化的对象比如数据库连接检查点保存就会失败。解决办法是在 outputMapping 阶段做一次转换只把需要传递的字段提取出来而不是把整个返回对象塞进状态。第三是人工节点的中断与恢复。人工审核节点执行时会抛出中断信号LangGraph4j 会保存当前检查点并暂停。等人工在平台上点了“通过”或“驳回”平台根据检查点恢复执行把人工的决策作为状态更新注入然后继续走后面的边。这个机制是低代码平台做“人机协同”流程的基础。实测下来恢复时要注意状态版本一致性——如果流程定义在暂停期间被修改了恢复时可能对不上节点。我的做法是检查点里记录流程版本号恢复时校验版本不一致就提示用户。3. 实操过程从零搭建一个可运行的最小平台3.1 环境准备与依赖引入先说一下技术栈的版本选择这块我踩过坑。LangChain4j 的版本迭代很快不同版本之间 API 有 breaking change。我目前稳定用的是 0.35.x 系列LangGraph4j 用的是 1.0.x。JDK 要求 17 以上因为 LangGraph4j 用了一些较新的语言特性。Maven 依赖大致如下dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-pgvector/artifactId version0.35.0/version /dependency dependency groupIdorg.bsc.langgraph4j/groupId artifactIdlanggraph4j-core/artifactId version1.0.0/version /dependency dependency groupIdcom.googlecode.aviator/groupId artifactIdaviator/artifactId version5.4.3/version /dependency这里有个选型问题经常被问到到底用 Spring AI 还是 LangChain4j。我的判断是看场景。Spring AI 的优势是和 Spring 生态无缝集成配置驱动适合快速接入模型做简单的问答。但它的工具调用、RAG、记忆管理这些能力相对 LangChain4j 还是薄一些尤其是多节点编排场景下LangChain4j 的AiServices抽象更灵活。而 LangGraph4j 本身就是 LangChain4j 生态的编排层两者配合最顺。所以这个平台我坚定选了 LangChain4j LangGraph4j 的组合。3.2 IR 到 StateGraph 的编译过程这是整个平台最核心的一段代码我把它单独放在一个WorkflowCompiler类里。编译过程分四步。第一步是解析 IR 并构建节点索引。把nodes数组遍历一遍建立id - NodeDefinition的映射同时校验每个节点的next或branches指向的节点是否存在。这一步能拦住大部分配置错误。第二步是为每个节点创建 LangGraph4j 的 AsyncNodeAction。每个节点执行器的execute方法被包装成一个返回MapString, Object的函数这个 Map 就是状态更新。包装的时候要做几件事从状态里按inputMapping提取输入、调用执行器、按outputMapping写回结果、记录执行元数据。private AsyncNodeActionWorkflowState wrapNode(NodeDefinition def, NodeExecutor executor) { return state - CompletableFuture.supplyAsync(() - { NodeContext ctx NodeContext.builder() .definition(def) .state(state.data()) .build(); NodeResult result executor.execute(ctx); MapString, Object update new HashMap(result.getStateUpdate()); update.put(_lastNode, def.getId()); update.put(_lastNodeCost, result.getCostMillis()); return update; }); }第三步是处理条件边。LangGraph4j 的条件边需要一个函数输入当前状态返回下一个节点的名称。我把 IR 里的branches编译成一个按顺序求值的函数第一个为真的分支胜出都不满足则走defaultNext。private AsyncEdgeActionWorkflowState compileCondition(NodeDefinition def) { return state - CompletableFuture.supplyAsync(() - { for (Branch branch : def.getBranches()) { Boolean matched (Boolean) AviatorEvaluator.execute( branch.getWhen(), state.data(), true); if (Boolean.TRUE.equals(matched)) { return branch.getNext(); } } return def.getDefaultNext(); }); }第四步是组装 StateGraph 并编译。把节点和边加进去指定入口节点调用compile()得到可执行的图。编译时可以传入检查点配置生产环境用持久化检查点开发环境用内存检查点。StateGraphWorkflowState graph new StateGraph(WorkflowState::new); for (NodeDefinition def : ir.getNodes()) { graph.addNode(def.getId(), wrapNode(def, executorRegistry.get(def.getType()))); } for (NodeDefinition def : ir.getNodes()) { if (condition.equals(def.getType())) { graph.addConditionalEdges(def.getId(), compileCondition(def)); } else if (def.getNext() ! null) { graph.addEdge(def.getId(), def.getNext()); } } CompiledGraphWorkflowState compiled graph.compile(checkpointConfig);编译结果可以缓存起来同一个版本的 IR 只编译一次。IR 变更时按版本号重新编译旧版本继续可用这样正在运行的流程不会因为新版本发布而中断。3.3 一个完整工作流的配置与运行实录拿一个“简历筛选工作流”来演示。业务需求是上传简历后先解析简历文本然后让大模型根据岗位要求打分分数高于 80 分自动进入面试邀约60 到 80 分进入人工复核低于 60 分直接淘汰。在画布上业务人员拖出这些节点一个start、一个tool简历解析工具、一个rag检索岗位要求知识库、一个llm打分、一个condition按分数分支、三个end对应三种结果。属性面板上llm节点的提示词模板配置成你是一个资深 HR请根据以下岗位要求对简历进行打分0-100 岗位要求{{jobRequirement}} 简历内容{{resumeText}} 只输出一个数字不要有其他内容。condition节点的分支配置成$.score 80走invite_interview$.score 60 $.score 80走manual_review默认走reject保存后平台生成 IR点击“试运行”上传一份简历可以看到执行轨迹start - parse_resume - retrieve_job - score_resume - route_by_score - invite_interview每个节点的输入输出、耗时、token 消耗都展示在轨迹面板上。如果打分结果不符合预期可以直接在轨迹面板上修改某个节点的输出然后“从该节点重新执行”不用从头跑一遍。这个功能在调试提示词的时候特别省时间。发布时平台做一次静态校验检查所有字段引用是否存在、所有边是否可达、是否有孤立节点、条件分支是否覆盖了所有情况。校验通过后生成版本号写入发布记录。线上调用通过一个统一的WorkflowRuntime.invoke(workflowId, version, inputs)接口内部加载对应版本的编译结果并执行。4. 常见问题与排查技巧实录4.1 节点执行失败的排查路径工作流跑不起来原因通常集中在几个地方。我整理了一个排查顺序基本能覆盖 90% 的问题。现象可能原因排查方法流程启动即失败入口节点未指定或 IR 格式错误检查 IR 的start节点是否存在JSON 是否能反序列化某节点报“字段不存在”inputMapping 引用了状态里没有的字段在轨迹面板看该节点执行前的状态快照条件分支总是走默认表达式求值结果不是布尔用 Aviator 的调试模式打印表达式结果工具调用超时工具内部 HTTP 请求未设超时检查工具实现的超时配置平台层也要设节点级超时检查点保存失败状态里有不可序列化对象检查 outputMapping 是否把整个返回对象塞进了状态人工节点恢复后走错分支流程版本在暂停期间变更检查点里记录版本号恢复时校验这里重点说两个我踩过的坑。第一个坑是 JSONPath 的 null 处理。如果$.orderDetail是 null$.orderDetail.price会抛异常而不是返回 null。我的做法是在映射引擎里对 null 做短路——路径中任何一段为 null整个表达式返回 null而不是抛异常。这样节点拿到 null 输入时可以自己决定怎么处理而不是直接崩掉。第二个坑是条件表达式的类型比较。Aviator 里$.score 80如果score是字符串85比较结果可能不符合预期。解决办法是在 stateSchema 里声明类型平台在写入状态时做一次类型转换保证number类型的字段存进去就是Number。这个转换看起来多余但能省掉大量“为什么 85 分没进面试”的诡异问题。4.2 性能与并发场景下的注意事项工作流平台上线后性能问题往往不是出在单个节点而是出在状态传递和检查点上。我实测过一个 20 节点的流程状态里塞了 5MB 的文档内容每次检查点保存要 200ms 以上整个流程跑下来光检查点就花了 4 秒。优化手段有这么几个。一是状态瘦身。大对象不进状态只存引用。文档内容放在一个带 TTL 的本地缓存里状态里存docRef: doc_12345节点需要时通过WorkflowContext去取。这样状态大小能控制在几 KB 级别检查点开销可以忽略。二是检查点异步化。不是每个节点都需要同步保存检查点。我的策略是普通节点异步保存人工节点和循环入口同步保存。异步保存用单独的线程池不阻塞主流程。这样既保证了关键节点的可恢复性又不拖慢整体速度。三是节点级超时与重试。每个节点执行器可以配置超时时间和重试次数。LLM 节点超时设 30 秒工具节点设 10 秒重试次数默认 1 次。重试时要保证幂等——如果工具是“创建订单”重试可能导致重复创建。我的做法是在节点定义里加一个idempotent标记非幂等节点不自动重试失败后走错误处理分支。四是并发分支的合并。LangGraph4j 支持一个节点有多个出边这些边会并发执行。并发分支写状态时如果写同一个字段会出现覆盖。解决办法是每个并发分支写不同的字段或者用自定义 reducer 做合并比如列表追加。我在平台层做了一个校验如果两个并发分支的 outputMapping 指向同一个字段发布时就报错。4.3 低代码层与代码层的边界把控做低代码平台最大的诱惑是“什么都想做成配置”但我的经验是边界要清晰该写代码的地方不要硬塞进配置。适合配置化的流程流转、条件分支、提示词模板、字段映射、模型选择、工具选择、超时重试参数。这些是业务人员能理解、且变更频繁的部分。不适合配置化的复杂的业务计算、特殊的数据转换、需要调用多个外部系统的聚合逻辑、性能敏感的批处理。这些应该封装成工具节点由研发实现业务只负责选用。如果硬要用 code 节点在流程里写这些逻辑最后会变成“用配置写代码”比直接写代码还难维护。我见过一些平台试图用可视化方式做复杂的循环和嵌套逻辑结果画布上连线像蜘蛛网业务人员根本看不懂。我的做法是限制单层流程的复杂度——如果一个流程超过 30 个节点就提示拆分成子流程。子流程通过subgraph节点调用主流程保持清晰。这个约束看起来限制了灵活性实际上提升了可维护性。提示低代码平台的“低代码”不是“零代码”。研发永远需要提供原子能力业务永远需要理解业务逻辑。平台的价值是让两者的协作更顺畅而不是消灭其中一方。5. 平台扩展与后续演进方向5.1 多租户与权限隔离的实现思路平台要真正落地多租户是绕不开的。不同部门、不同项目组的工作流要隔离但又需要共享一些公共的工具和知识库。我的设计是租户 - 工作空间 - 工作流三级结构。租户是最顶层的隔离单位工作空间是租户内的项目分组工作流属于某个工作空间。隔离的维度有三个数据隔离工作流定义、执行记录、检查点按租户分库或分表、能力隔离工具和知识库可以标记为租户私有或全局共享、配额隔离每个租户的模型调用量、并发执行数有上限。配额这块我用的是令牌桶算法在节点执行前检查配额超限就拒绝执行并返回明确错误。权限模型用的是 RBAC角色有管理员、开发者、业务配置者、只读用户。开发者能注册工具和模型业务配置者能编辑工作流但不能改工具只读用户只能看。这个粒度基本够用再细就要上 ABAC 了但复杂度会陡增。5.2 可观测性让业务人员也能看懂执行轨迹低代码平台的可观测性和传统后端服务不一样。后端看日志和指标业务人员看的是“我的流程走到哪了、为什么卡住”。所以轨迹面板的设计很关键。我的轨迹面板展示这几层信息节点级——每个节点的开始结束时间、状态、耗时、输入输出摘要边级——条件边为什么走了这个分支表达式的求值结果是什么状态级——每个节点执行前后的状态 diff哪些字段变了成本级——每个 LLM 节点的 token 消耗和预估费用。对于失败的节点面板上直接展示错误堆栈的摘要和排查建议。比如“字段$.orderId不存在请检查上游节点的 outputMapping 是否写入了该字段”。这种提示比抛一个NullPointerException有用得多。轨迹数据我存了两份一份是完整的含状态快照保留 7 天用于深度调试一份是摘要的只有节点和耗时保留 90 天用于统计和审计。这样既控制了存储成本又保证了排查问题时数据够用。5.3 从工作流到智能体集群的演进现在平台跑的是单个工作流但业务需求已经在往“多个智能体协作”的方向走了。比如一个销售场景需要“线索分析智能体”“话术生成智能体”“跟进提醒智能体”协同工作。这其实就是 LangGraph4j 的子图能力可以覆盖的场景——每个智能体是一个子图主图负责调度和状态传递。我接下来的演进计划是引入智能体注册中心每个智能体注册自己的能力和输入输出契约主流程通过agent节点调用。调用时可以指定同步或异步异步的话主流程继续走智能体完成后通过回调更新状态。这个模式在 LangGraph4j 里可以用subgraph加检查点实现但需要解决跨子图的状态映射和错误传播问题。另一个方向是工作流的自动优化。平台积累了大量的执行轨迹可以分析哪些节点耗时最长、哪些条件分支很少走到、哪些提示词效果不好。基于这些数据给出优化建议比如“这个 LLM 节点平均耗时 8 秒建议换更快的模型”或者“这个分支过去 30 天只走了 2 次考虑合并”。这个能力还在探索阶段但数据基础已经在了。我在实际搭建和运营这个平台的过程中最大的体会是低代码的价值不在于让不懂技术的人写流程而在于让懂业务的人能直接表达业务逻辑同时让懂技术的人能专注于原子能力的建设。LangChain4j 和 LangGraph4j 提供了很好的底层支撑但真正决定平台好不好用的是 IR 设计是否合理、节点抽象是否清晰、错误提示是否友好这些“脏活累活”。如果你也在做类似的事情建议先把 IR 和节点模型定下来用两三个真实业务场景跑通再考虑画布和权限这些外围功能。顺序反了很容易做出一个好看但不好用的空壳。
基于LangChain4j与LangGraph4j的低代码智能体工作流平台实战
1. 为什么要在 LangChain4j 和 LangGraph4j 上搭一层低代码工作流1.1 从“写死一个智能体”到“编排一类智能体”的转变过去一年我接触过不少智能体项目绝大多数起步阶段都是同一个套路用 LangChain4j 写一个AiServices接口挂上几个Tool接一个大模型跑通一个客服问答或者文档问答的 Demo。这个阶段很爽几十行代码就能看到效果。但真正往业务里推的时候问题立刻暴露出来——业务方今天要加一个“先查订单再判断是否退款”的分支明天要加一个“人工审核节点”后天又要求“不同租户走不同的提示词和工具集”。如果每一次变更都要改 Java 代码、重新打包、走一遍发布流程这个智能体基本就废了因为业务迭代的速度远快于研发发版的速度。这就是我决定在LangChain4j LangGraph4j之上再抽象一层低代码工作流平台的直接原因。LangChain4j 解决的是“单个智能体能力”的问题——模型调用、RAG 检索、工具调用、记忆管理它都封装得很扎实LangGraph4j 解决的是“多个节点之间怎么流转”的问题——它把状态机、条件边、循环、检查点这些图计算的概念带进了 Java 生态。但这两者加起来仍然是面向开发者的 API不是面向业务配置的界面。低代码这一层要做的就是把“图”和“节点”变成业务人员能在画布上拖拽、连线、填参数的东西把“提示词”“工具”“知识库”“条件表达式”变成表单里的字段。所以这个平台的定位很明确研发负责把原子能力模型、工具、检索器、外部 API注册成可复用的节点业务负责在画布上把这些节点连成一条能跑的流程。中间那层“图执行引擎”由 LangGraph4j 承担“节点内部逻辑”由 LangChain4j 承担。这个分层是我踩了不少坑之后才想清楚的后面会详细讲。1.2 三层架构的职责边界划分我把整个平台拆成三层这个划分方式直接决定了后面所有的技术选型和代码结构所以先讲清楚。最底层是能力层基于 LangChain4j 构建。这一层包含ChatLanguageModel的封装对接不同厂商的模型、EmbeddingModel、EmbeddingStore向量库、ContentRetrieverRAG 检索、Tool工具调用以及ChatMemory。这一层的特点是稳定、变化少、由研发维护。一个工具一旦注册进来它的入参出参 schema 就固定了业务层只能选择用或不用不能改它的内部实现。中间层是编排层基于 LangGraph4j 构建。这一层把能力层的原子能力包装成图的节点Node用边Edge和条件边ConditionalEdge定义流转逻辑用State承载节点之间传递的数据。LangGraph4j 的核心抽象是StateGraph它要求你定义一个状态类型然后每个节点接收状态、返回状态的部分更新。这一层的关键设计是状态 schema 的标准化——如果每个工作流都自定义一套状态结构那低代码层就没法做通用的表单渲染。我的做法是定义一个通用的WorkflowState内部用一个MapString, Object存业务数据再附加一些平台级的元数据字段如currentNode、traceId、errorInfo。最上层是配置层也就是低代码平台本身。这一层包含画布编辑器、节点属性面板、流程校验器、版本管理、发布与回滚。它不直接碰 LangChain4j 和 LangGraph4j 的 API而是通过一个中间表示IR来描述工作流。IR 是一个 JSON 结构描述了节点列表、节点类型、节点参数、边和条件。配置层产出 IR编排层把 IR 编译成 LangGraph4j 的StateGraph能力层提供节点执行时需要的具体实现。这个 IR 是整个平台的“契约”也是后面做版本对比、导入导出、跨环境迁移的基础。提示三层划分的核心价值在于变更隔离。业务改流程只动 IR不动代码研发加能力只动能力层不影响已有流程。如果这三层混在一起低代码就退化成了一个“配置化的 if-else”很快就会失控。1.3 为什么是 LangGraph4j 而不是自己写状态机有人会问工作流编排无非就是节点加跳转自己写一个状态机引擎不行吗我一开始也这么想过甚至用 Java 的enum加switch写过一个简易版本。但很快遇到几个绕不过去的问题。第一是循环与条件边。业务工作流里经常有“检索不满足条件就重新检索”“审核不通过就退回上一步”这种需求。自己写的状态机处理循环时很容易出现死循环或者状态污染。LangGraph4j 对循环有明确的支持配合检查点Checkpoint机制可以在每次节点执行后保存状态快照既方便调试也方便做“从某一步重新执行”。第二是状态合并语义。在并发或者多分支场景下多个节点可能同时更新状态的不同字段。LangGraph4j 定义了状态更新的合并规则默认是覆盖也支持自定义 reducer这个语义如果自己实现很容易出现字段丢失或者覆盖顺序不确定的问题。第三是可观测性。LangGraph4j 的图执行天然可以产出执行轨迹——经过了哪些节点、每个节点的输入输出是什么、条件边为什么走了这个分支。这个轨迹对于低代码平台至关重要因为业务人员排查问题时看不懂日志他们需要的是“流程走到哪一步卡住了”的可视化展示。当然LangGraph4j 也不是银弹。它的 Java 版本相比 Python 版本在生态和文档上还有差距某些 API 的设计偏底层需要自己封装一层才好用。但相比从零写一个状态机它至少把“图执行”这个最难的部分做对了。我的策略是图执行交给 LangGraph4j节点内部逻辑交给 LangChain4j平台层只做 IR 到图的编译和节点注册。2. 核心细节拆解IR 设计、节点模型与状态管理2.1 工作流 IR 的字段设计与设计意图IR 是整个平台的骨架它的设计质量直接决定了低代码层能做到多灵活。我最终定下来的 IR 结构大致如下简化版{ id: wf_order_refund, version: 1.2.0, name: 订单退款审核流程, stateSchema: { orderId: { type: string, required: true }, refundAmount: { type: number }, riskLevel: { type: string, enum: [low, medium, high] } }, nodes: [ { id: start, type: start, next: fetch_order }, { id: fetch_order, type: tool, toolName: orderQueryTool, inputMapping: { orderId: $.orderId }, outputMapping: { orderDetail: $.result }, next: risk_check }, { id: risk_check, type: llm, model: qwen-plus, promptTemplate: 根据订单信息判断风险等级{{orderDetail}}, outputMapping: { riskLevel: $.output }, next: route_by_risk }, { id: route_by_risk, type: condition, branches: [ { when: $.riskLevel low, next: auto_approve }, { when: $.riskLevel high, next: manual_review } ], defaultNext: manual_review } ], edges: [] }这里有几个设计决策值得展开说。节点 ID 与类型分离。id是流程内唯一的实例标识type决定这个节点由哪个执行器处理。这样同一个工具可以在流程里出现多次每次用不同的参数互不干扰。如果只用toolName做标识就没法处理“同一个工具调用两次”的场景。inputMapping 和 outputMapping 用 JSONPath。节点之间传递数据不直接操作状态对象而是通过 JSONPath 表达式做映射。这样做的好处是解耦——节点不需要知道状态里有哪些字段只需要声明“我从$.orderId取输入我把结果写到$.orderDetail”。低代码层的属性面板可以直接根据这个映射生成表单业务人员填字段名就行。JSONPath 的表达式能力也足够覆盖大部分场景比如$.orderDetail.items[0].price这种嵌套取值。条件节点的分支用表达式而非代码。when字段是一个表达式字符串平台内置一个轻量表达式引擎我用的是 Aviator因为它对 Java 友好、性能好、语法接近 JavaScript来求值。业务人员在界面上配置“当风险等级等于 low 时走自动审批”背后就是生成$.riskLevel low这样的表达式。这里要注意表达式沙箱——必须限制可调用的方法和类防止表达式注入。stateSchema 显式声明。虽然状态底层是MapString, Object但 IR 里要求显式声明 schema。这个 schema 有三个用途一是画布上做字段提示和类型校验二是流程发布前做静态检查比如某个节点引用了不存在的字段就报错三是给前端表单渲染提供依据。没有 schema 的话低代码就变成了“盲填”体验很差。2.2 节点执行器的抽象与注册机制节点是平台的能力单元每一种节点类型对应一个执行器。我定义的执行器接口大致是这样public interface NodeExecutor { String getType(); NodeResult execute(NodeContext context); default ValidationResult validate(NodeDefinition definition) { return ValidationResult.ok(); } }NodeContext里封装了当前节点的定义、当前工作流状态、以及能力层提供的各种资源模型、工具、检索器。NodeResult包含状态更新一个Map、下一个节点的选择可选条件节点用、以及执行元数据耗时、token 消耗等。目前平台内置的节点类型有这么几类节点类型作用底层依赖start流程入口初始化状态无end流程出口汇总输出无llm调用大模型支持提示词模板LangChain4j ChatLanguageModeltool调用注册的工具LangChain4j Toolrag检索知识库并注入上下文LangChain4j ContentRetrievercondition条件分支Aviator 表达式引擎loop循环执行子流程LangGraph4j 子图human人工审核节点平台任务队列code执行一段脚本受限GraalVM JS 或 Aviatorsubgraph调用另一个工作流LangGraph4j 子图注册机制我用的是 Spring 的ApplicationContext收集所有NodeExecutor的 Bean启动时按getType()建立索引。新增一种节点类型只需要实现接口并加上Component不需要改平台核心代码。这个扩展点是平台能持续演进的关键——后面要加“HTTP 请求节点”“消息推送节点”“数据库查询节点”都是同样的套路。注意code节点是最容易出安全问题的地方。我的做法是默认禁用只有管理员在租户级别显式开启后才能使用并且脚本运行在受限的沙箱里禁止文件 IO、网络访问和反射调用。即便如此生产环境我还是建议尽量用专用节点替代 code 节点。2.3 状态管理与检查点的落地细节LangGraph4j 的状态管理是它相对自己写状态机最大的优势但要用好需要理解几个细节。首先是状态的不可变性。LangGraph4j 的节点返回的是状态的“更新部分”而不是修改原状态。框架会把更新合并到当前状态生成新状态传给下一个节点。这个设计的好处是每次状态变更都有迹可循配合检查点可以做时间旅行调试。但代价是如果状态很大比如 RAG 检索回来一堆文档每次合并都有内存开销。我的优化是大对象用引用传递——状态里只存文档 ID 或者缓存 key实际内容放在一个WorkflowContext的外部缓存里节点通过 key 去取。其次是检查点的存储。LangGraph4j 支持内存和持久化两种检查点。开发调试用内存就够了但生产环境必须持久化否则流程中断后没法恢复。我选的是把检查点存到关系库MySQL序列化成 JSON。这里有个坑状态里的对象必须可序列化如果某个工具返回了一个不可序列化的对象比如数据库连接检查点保存就会失败。解决办法是在 outputMapping 阶段做一次转换只把需要传递的字段提取出来而不是把整个返回对象塞进状态。第三是人工节点的中断与恢复。人工审核节点执行时会抛出中断信号LangGraph4j 会保存当前检查点并暂停。等人工在平台上点了“通过”或“驳回”平台根据检查点恢复执行把人工的决策作为状态更新注入然后继续走后面的边。这个机制是低代码平台做“人机协同”流程的基础。实测下来恢复时要注意状态版本一致性——如果流程定义在暂停期间被修改了恢复时可能对不上节点。我的做法是检查点里记录流程版本号恢复时校验版本不一致就提示用户。3. 实操过程从零搭建一个可运行的最小平台3.1 环境准备与依赖引入先说一下技术栈的版本选择这块我踩过坑。LangChain4j 的版本迭代很快不同版本之间 API 有 breaking change。我目前稳定用的是 0.35.x 系列LangGraph4j 用的是 1.0.x。JDK 要求 17 以上因为 LangGraph4j 用了一些较新的语言特性。Maven 依赖大致如下dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-pgvector/artifactId version0.35.0/version /dependency dependency groupIdorg.bsc.langgraph4j/groupId artifactIdlanggraph4j-core/artifactId version1.0.0/version /dependency dependency groupIdcom.googlecode.aviator/groupId artifactIdaviator/artifactId version5.4.3/version /dependency这里有个选型问题经常被问到到底用 Spring AI 还是 LangChain4j。我的判断是看场景。Spring AI 的优势是和 Spring 生态无缝集成配置驱动适合快速接入模型做简单的问答。但它的工具调用、RAG、记忆管理这些能力相对 LangChain4j 还是薄一些尤其是多节点编排场景下LangChain4j 的AiServices抽象更灵活。而 LangGraph4j 本身就是 LangChain4j 生态的编排层两者配合最顺。所以这个平台我坚定选了 LangChain4j LangGraph4j 的组合。3.2 IR 到 StateGraph 的编译过程这是整个平台最核心的一段代码我把它单独放在一个WorkflowCompiler类里。编译过程分四步。第一步是解析 IR 并构建节点索引。把nodes数组遍历一遍建立id - NodeDefinition的映射同时校验每个节点的next或branches指向的节点是否存在。这一步能拦住大部分配置错误。第二步是为每个节点创建 LangGraph4j 的 AsyncNodeAction。每个节点执行器的execute方法被包装成一个返回MapString, Object的函数这个 Map 就是状态更新。包装的时候要做几件事从状态里按inputMapping提取输入、调用执行器、按outputMapping写回结果、记录执行元数据。private AsyncNodeActionWorkflowState wrapNode(NodeDefinition def, NodeExecutor executor) { return state - CompletableFuture.supplyAsync(() - { NodeContext ctx NodeContext.builder() .definition(def) .state(state.data()) .build(); NodeResult result executor.execute(ctx); MapString, Object update new HashMap(result.getStateUpdate()); update.put(_lastNode, def.getId()); update.put(_lastNodeCost, result.getCostMillis()); return update; }); }第三步是处理条件边。LangGraph4j 的条件边需要一个函数输入当前状态返回下一个节点的名称。我把 IR 里的branches编译成一个按顺序求值的函数第一个为真的分支胜出都不满足则走defaultNext。private AsyncEdgeActionWorkflowState compileCondition(NodeDefinition def) { return state - CompletableFuture.supplyAsync(() - { for (Branch branch : def.getBranches()) { Boolean matched (Boolean) AviatorEvaluator.execute( branch.getWhen(), state.data(), true); if (Boolean.TRUE.equals(matched)) { return branch.getNext(); } } return def.getDefaultNext(); }); }第四步是组装 StateGraph 并编译。把节点和边加进去指定入口节点调用compile()得到可执行的图。编译时可以传入检查点配置生产环境用持久化检查点开发环境用内存检查点。StateGraphWorkflowState graph new StateGraph(WorkflowState::new); for (NodeDefinition def : ir.getNodes()) { graph.addNode(def.getId(), wrapNode(def, executorRegistry.get(def.getType()))); } for (NodeDefinition def : ir.getNodes()) { if (condition.equals(def.getType())) { graph.addConditionalEdges(def.getId(), compileCondition(def)); } else if (def.getNext() ! null) { graph.addEdge(def.getId(), def.getNext()); } } CompiledGraphWorkflowState compiled graph.compile(checkpointConfig);编译结果可以缓存起来同一个版本的 IR 只编译一次。IR 变更时按版本号重新编译旧版本继续可用这样正在运行的流程不会因为新版本发布而中断。3.3 一个完整工作流的配置与运行实录拿一个“简历筛选工作流”来演示。业务需求是上传简历后先解析简历文本然后让大模型根据岗位要求打分分数高于 80 分自动进入面试邀约60 到 80 分进入人工复核低于 60 分直接淘汰。在画布上业务人员拖出这些节点一个start、一个tool简历解析工具、一个rag检索岗位要求知识库、一个llm打分、一个condition按分数分支、三个end对应三种结果。属性面板上llm节点的提示词模板配置成你是一个资深 HR请根据以下岗位要求对简历进行打分0-100 岗位要求{{jobRequirement}} 简历内容{{resumeText}} 只输出一个数字不要有其他内容。condition节点的分支配置成$.score 80走invite_interview$.score 60 $.score 80走manual_review默认走reject保存后平台生成 IR点击“试运行”上传一份简历可以看到执行轨迹start - parse_resume - retrieve_job - score_resume - route_by_score - invite_interview每个节点的输入输出、耗时、token 消耗都展示在轨迹面板上。如果打分结果不符合预期可以直接在轨迹面板上修改某个节点的输出然后“从该节点重新执行”不用从头跑一遍。这个功能在调试提示词的时候特别省时间。发布时平台做一次静态校验检查所有字段引用是否存在、所有边是否可达、是否有孤立节点、条件分支是否覆盖了所有情况。校验通过后生成版本号写入发布记录。线上调用通过一个统一的WorkflowRuntime.invoke(workflowId, version, inputs)接口内部加载对应版本的编译结果并执行。4. 常见问题与排查技巧实录4.1 节点执行失败的排查路径工作流跑不起来原因通常集中在几个地方。我整理了一个排查顺序基本能覆盖 90% 的问题。现象可能原因排查方法流程启动即失败入口节点未指定或 IR 格式错误检查 IR 的start节点是否存在JSON 是否能反序列化某节点报“字段不存在”inputMapping 引用了状态里没有的字段在轨迹面板看该节点执行前的状态快照条件分支总是走默认表达式求值结果不是布尔用 Aviator 的调试模式打印表达式结果工具调用超时工具内部 HTTP 请求未设超时检查工具实现的超时配置平台层也要设节点级超时检查点保存失败状态里有不可序列化对象检查 outputMapping 是否把整个返回对象塞进了状态人工节点恢复后走错分支流程版本在暂停期间变更检查点里记录版本号恢复时校验这里重点说两个我踩过的坑。第一个坑是 JSONPath 的 null 处理。如果$.orderDetail是 null$.orderDetail.price会抛异常而不是返回 null。我的做法是在映射引擎里对 null 做短路——路径中任何一段为 null整个表达式返回 null而不是抛异常。这样节点拿到 null 输入时可以自己决定怎么处理而不是直接崩掉。第二个坑是条件表达式的类型比较。Aviator 里$.score 80如果score是字符串85比较结果可能不符合预期。解决办法是在 stateSchema 里声明类型平台在写入状态时做一次类型转换保证number类型的字段存进去就是Number。这个转换看起来多余但能省掉大量“为什么 85 分没进面试”的诡异问题。4.2 性能与并发场景下的注意事项工作流平台上线后性能问题往往不是出在单个节点而是出在状态传递和检查点上。我实测过一个 20 节点的流程状态里塞了 5MB 的文档内容每次检查点保存要 200ms 以上整个流程跑下来光检查点就花了 4 秒。优化手段有这么几个。一是状态瘦身。大对象不进状态只存引用。文档内容放在一个带 TTL 的本地缓存里状态里存docRef: doc_12345节点需要时通过WorkflowContext去取。这样状态大小能控制在几 KB 级别检查点开销可以忽略。二是检查点异步化。不是每个节点都需要同步保存检查点。我的策略是普通节点异步保存人工节点和循环入口同步保存。异步保存用单独的线程池不阻塞主流程。这样既保证了关键节点的可恢复性又不拖慢整体速度。三是节点级超时与重试。每个节点执行器可以配置超时时间和重试次数。LLM 节点超时设 30 秒工具节点设 10 秒重试次数默认 1 次。重试时要保证幂等——如果工具是“创建订单”重试可能导致重复创建。我的做法是在节点定义里加一个idempotent标记非幂等节点不自动重试失败后走错误处理分支。四是并发分支的合并。LangGraph4j 支持一个节点有多个出边这些边会并发执行。并发分支写状态时如果写同一个字段会出现覆盖。解决办法是每个并发分支写不同的字段或者用自定义 reducer 做合并比如列表追加。我在平台层做了一个校验如果两个并发分支的 outputMapping 指向同一个字段发布时就报错。4.3 低代码层与代码层的边界把控做低代码平台最大的诱惑是“什么都想做成配置”但我的经验是边界要清晰该写代码的地方不要硬塞进配置。适合配置化的流程流转、条件分支、提示词模板、字段映射、模型选择、工具选择、超时重试参数。这些是业务人员能理解、且变更频繁的部分。不适合配置化的复杂的业务计算、特殊的数据转换、需要调用多个外部系统的聚合逻辑、性能敏感的批处理。这些应该封装成工具节点由研发实现业务只负责选用。如果硬要用 code 节点在流程里写这些逻辑最后会变成“用配置写代码”比直接写代码还难维护。我见过一些平台试图用可视化方式做复杂的循环和嵌套逻辑结果画布上连线像蜘蛛网业务人员根本看不懂。我的做法是限制单层流程的复杂度——如果一个流程超过 30 个节点就提示拆分成子流程。子流程通过subgraph节点调用主流程保持清晰。这个约束看起来限制了灵活性实际上提升了可维护性。提示低代码平台的“低代码”不是“零代码”。研发永远需要提供原子能力业务永远需要理解业务逻辑。平台的价值是让两者的协作更顺畅而不是消灭其中一方。5. 平台扩展与后续演进方向5.1 多租户与权限隔离的实现思路平台要真正落地多租户是绕不开的。不同部门、不同项目组的工作流要隔离但又需要共享一些公共的工具和知识库。我的设计是租户 - 工作空间 - 工作流三级结构。租户是最顶层的隔离单位工作空间是租户内的项目分组工作流属于某个工作空间。隔离的维度有三个数据隔离工作流定义、执行记录、检查点按租户分库或分表、能力隔离工具和知识库可以标记为租户私有或全局共享、配额隔离每个租户的模型调用量、并发执行数有上限。配额这块我用的是令牌桶算法在节点执行前检查配额超限就拒绝执行并返回明确错误。权限模型用的是 RBAC角色有管理员、开发者、业务配置者、只读用户。开发者能注册工具和模型业务配置者能编辑工作流但不能改工具只读用户只能看。这个粒度基本够用再细就要上 ABAC 了但复杂度会陡增。5.2 可观测性让业务人员也能看懂执行轨迹低代码平台的可观测性和传统后端服务不一样。后端看日志和指标业务人员看的是“我的流程走到哪了、为什么卡住”。所以轨迹面板的设计很关键。我的轨迹面板展示这几层信息节点级——每个节点的开始结束时间、状态、耗时、输入输出摘要边级——条件边为什么走了这个分支表达式的求值结果是什么状态级——每个节点执行前后的状态 diff哪些字段变了成本级——每个 LLM 节点的 token 消耗和预估费用。对于失败的节点面板上直接展示错误堆栈的摘要和排查建议。比如“字段$.orderId不存在请检查上游节点的 outputMapping 是否写入了该字段”。这种提示比抛一个NullPointerException有用得多。轨迹数据我存了两份一份是完整的含状态快照保留 7 天用于深度调试一份是摘要的只有节点和耗时保留 90 天用于统计和审计。这样既控制了存储成本又保证了排查问题时数据够用。5.3 从工作流到智能体集群的演进现在平台跑的是单个工作流但业务需求已经在往“多个智能体协作”的方向走了。比如一个销售场景需要“线索分析智能体”“话术生成智能体”“跟进提醒智能体”协同工作。这其实就是 LangGraph4j 的子图能力可以覆盖的场景——每个智能体是一个子图主图负责调度和状态传递。我接下来的演进计划是引入智能体注册中心每个智能体注册自己的能力和输入输出契约主流程通过agent节点调用。调用时可以指定同步或异步异步的话主流程继续走智能体完成后通过回调更新状态。这个模式在 LangGraph4j 里可以用subgraph加检查点实现但需要解决跨子图的状态映射和错误传播问题。另一个方向是工作流的自动优化。平台积累了大量的执行轨迹可以分析哪些节点耗时最长、哪些条件分支很少走到、哪些提示词效果不好。基于这些数据给出优化建议比如“这个 LLM 节点平均耗时 8 秒建议换更快的模型”或者“这个分支过去 30 天只走了 2 次考虑合并”。这个能力还在探索阶段但数据基础已经在了。我在实际搭建和运营这个平台的过程中最大的体会是低代码的价值不在于让不懂技术的人写流程而在于让懂业务的人能直接表达业务逻辑同时让懂技术的人能专注于原子能力的建设。LangChain4j 和 LangGraph4j 提供了很好的底层支撑但真正决定平台好不好用的是 IR 设计是否合理、节点抽象是否清晰、错误提示是否友好这些“脏活累活”。如果你也在做类似的事情建议先把 IR 和节点模型定下来用两三个真实业务场景跑通再考虑画布和权限这些外围功能。顺序反了很容易做出一个好看但不好用的空壳。
