1. 为什么在 Java 生态里做智能体平台而不是直接套 Python 那套方案先交代一下背景。我在一家以 Java 技术栈为主的团队之前接手过一个内部工具平台的重构任务——业务方需要把大量重复的人工判断流程比如工单分类、合同初审、简历筛选这类自动化。第一反应当然是看 Python 那套LangChain、LangGraph、Dify、n8n 都是现成的社区活跃案例也多。但冷静下来盘了一下现状难点不在能不能做出来一个 demo而在能不能接进现有系统并长期维护。我们现有的核心系统是 Spring Cloud 微服务服务间走 HTTP 消息队列权限体系、审计日志、配置中心、监控报警全是围绕 Java 生态建的。如果为了智能体单独拉一套 Python 服务意味着要维护两套部署链路、两套日志规范、两套配置管理还要解决 Java 服务频繁调用 Python 服务的网络开销和稳定性问题。对一个小团队来说这个隐性成本是扛不住的。当时恰好在调研 LangChain4j——注意这是 LangChain 的 Java 版本不是套壳封装而是官方出品的 Java 实现API 设计和 Python 版的核心概念对齐但针对 Java 生态做了很多适配。比如它的ChatLanguageModel接口把 OpenAI、Ollama、Azure OpenAI、Qwen 等模型统一抽象成一套调用方式切换模型基本不需要改业务代码。LangGraph4j 则是 LangGraph 的 Java 移植版把图状态、节点流转、条件边这些概念搬过来了。结论很明确用 Java 生态的 LangChain4j LangGraph4j 做底座把工作流编排能力封装成低代码平台这条路线最贴合我们的实际约束。这篇文章就是记录整个架构设计过程中我认为最有价值的思考以及踩过的坑。适合谁看准备在 Java 技术栈里做智能体应用、想搞低代码工作流平台、或者正在纠结Spring AI 和 LangGraph4j 怎么选的开发者。我会尽量把选型逻辑、架构分层、核心实现思路和故障排查经验都讲透。2. 平台总体架构从可视化画布到图执行引擎的分层拆解低代码工作流平台的本质是让业务人员用拖拽的方式描述什么时候做什么事而平台负责把这些描述翻译成计算机能执行的程序。落到智能体场景这句话的含义是用户拖拽的节点不只是发邮件调接口还包括调用大模型检索知识库判断上一步结果是否符合预期这类语义。2.1 三层核心模型定义层、执行层、运行时层我最终将平台拆成三层每一层职责单一避免后面改需求时牵一发动全身。第一层是工作流定义层。用户通过前端画布拖拽节点、连线、配置参数前端把整个图序列化成一份 JSON 结构的 DSL。这份 DSL 就是工作流的源代码会存入数据库并做版本管理。这一层只负责描述不负责执行。第二层是执行引擎层。它读取 DSL构建出可运行的图对象然后驱动节点依次执行。这是整个平台的心脏也是 LangGraph4j 发挥价值的地方。引擎需要处理状态传递、分支判断、循环回退、异常重试还要预留人工审批这类暂停等待的能力。第三层是运行时支撑层。包括模型调用网关统一代理各种大模型 API、知识库服务向量检索、文档解析、外部系统连接器HTTP 调用、数据库操作、消息通知以及日志、监控、审计等横切能力。低代码面板上每一个能力节点背后都对应运行时层的一个具体服务。这个分层的好处很直接业务方只需关注第一层平台开发者集中精力搞第二层运行时层则可以独立扩展加一个新工具节点不需要碰引擎代码。2.2 关键设计决策DSL 先行很多团队做低代码平台一上来先搞可视化编辑器结果前端画得很开心后端执行的时候发现图信息表达不清楚于是反复改协议。我这次反过来先把 DSL 定死前端画布只是 DSL 的编辑器和渲染器。DSL 我参考了 LangGraph4j 的 StateGraph 结构但做了一层简化方便非技术用户理解。一个工作流定义的核心字段如下{ graph: { nodes: [ { id: node_start, type: start, name: 开始, config: {} }, { id: node_llm_1, type: llm, name: 调用大模型, config: { modelId: qwen-plus, promptTemplateId: contract_review_001, inputMapping: { contractText: trigger.data.contractText }, outputKey: reviewResult } }, { id: node_condition_1, type: condition, name: 判断是否通过, config: { expression: #{reviewResult.passed} true } } ], edges: [ { from: node_start, to: node_llm_1 }, { from: node_llm_1, to: node_condition_1 }, { from: node_condition_1, to: node_end_pass, condition: true }, { from: node_condition_1, to: node_end_reject, condition: false } ] }, metadata: { version: 1.2.0, owner: risk_control_team, description: 合同初审工作流 } }注意inputMapping和outputKey这两个设计。前者定义了上一个节点产物中哪些数据喂给当前节点后者定义了当前节点产物在工作流状态中以什么名字存放。这套机制让节点之间不直接互相依赖而是通过状态沟通这样才能保证节点可以被自由替换和复用。这个 DSL 设计让我在后端实现时少走了大量弯路。执行引擎拿到 DSL 后按节点类型分发到不同的处理器处理器从状态中取输入、执行、写回输出完全不需要关心整个图长什么样。2.3 为什么状态用 Map 而不是强类型对象工作流执行过程中数据形态非常多样可能是大模型返回的 JSON、可能是数据库查询的多行结果、可能是 HTTP 接口的响应体。如果为每个节点类型定义强类型输入输出灵活度会大打折扣而且扩展新节点类型时还得改数据模型。我最终选择用一个MapString, Object作为工作流的全局状态LangGraph4j 官方也推荐类似思路。每个节点从状态里取自己关心的 key执行完把结果放回状态。简单粗暴却符合低代码的核心诉求——数据流靠命名约定而不是强类型契约。风险在于 key 冲突和数据格式的隐式约定。我的应对方案是状态 key 用节点 ID 做前缀比如node_llm_1.result再加上一层扁平化的快捷访问别名机制用户可以在节点的 inputMapping 里用trigger.data.fieldName这类路径表达式直接映射后端用一个小工具类解析路径字符串。这套方案在工程上足够用也避免了状态对象无限膨胀。3. 工作流引擎核心LangGraph4j 的状态图设计与节点抽象LangGraph4j 是这次架构里最核心的依赖。它的底层模型就是一个有状态的有向图节点是执行单元边是流转路径状态在整个图执行过程中被逐步更新。有些边带条件判断有些边是普通的顺序流转还有一类特殊的循环边配合状态变量可以实现重试直到满足条件这类复杂逻辑。3.1 StateGraph 的基本用法回顾给不熟悉的读者补充一下 LangGraph4j 的基础。它大概是这样的写法StateGraphAppState graph new StateGraph(AppState::new) .addNode(start, nodeStart) .addNode(llm_1, nodeLlm1) .addNode(condition_1, nodeCondition) .addEdge(start, llm_1) .addConditionalEdge(llm_1, new EdgeCondition(state - state.get(reviewResult.passed) ? pass : reject), Map.of(pass, end_pass, reject, end_reject)) .compile();每次执行图的入口调用graph.invoke(initialState)节点按定义依次触发State 对象在边上传递并更新。条件边通过EdgeCondition里的 Lambda 表达式判断走向。这套模型非常适合工作流场景因为它天然支持分支和循环。但有一个关键差异需要适应——传统工作流引擎比如 Flowable更强调流程实例的持久化和生命周期管理而 LangGraph4j 本质上更偏向内存中执行一次图计算。后面我会讲怎么补齐持久化这个短板。3.2 节点抽象把业务能力统一成 NodeExecutorLangGraph4j 的节点其实就是实现了特定函数接口的 Lambda。但如果直接把业务代码写在 Lambda 里平台就没法统一管理节点的超时、重试、日志和并发了。所以我在引擎层加了一个中间抽象节点执行器接口。任何能力要接入平台都必须实现这个接口public interface NodeExecutor { NodeType type(); MapString, Object execute(NodeContext ctx); }NodeContext里包含当前节点定义、全局状态、本次执行的 traceId、以及平台注入的各类客户端模型客户端、HTTP 客户端、向量库客户端等。每个具体执行器只管拿到数据、做处理、返回结果通用逻辑在引擎层统一拦截。举个实际节点——大模型调用节点的执行器核心逻辑public MapString, Object execute(NodeContext ctx) { LlmNodeConfig cfg ctx.getNodeConfig(LlmNodeConfig.class); // 1. 解析输入映射从状态里提取 prompt 的上下文 MapString, Object inputs MappingParser.resolve(cfg.getInputMapping(), ctx.getState()); // 2. 加载 prompt 模板渲染成最终发给模型的文本 String prompt promptTemplateManager.render(cfg.getPromptTemplateId(), inputs); // 3. 通过 LangChain4j 的 ChatLanguageModel 统一接口调用 ChatLanguageModel model modelGateway.getModel(cfg.getModelId()); ChatResponse response model.generate(ChatMessage.userMessage(prompt)); // 4. 解析结构化输出写入全局状态 MapString, Object output JsonParser.parse(response.aiMessage().text()); return Map.of(cfg.getOutputKey(), output); }这里把模板渲染模型调用结果解析全部分离平台使用者不需要关心底层细节只需要配置模板 ID 和输入映射。3.3 条件边的三种判断方式低代码平台上用户需要灵活地表达走哪条路。我实现了三种判断方式覆盖绝大多数场景表达式判断用 SpELSpring Expression Language写布尔表达式例如#{reviewResult.passed} true。适合简单比较。模型判断让大模型自己决定流向比如根据用户留言的情感倾向选择转人工还是直接回复。实现上是调用一次模型要求返回固定的枚举值。脚本判断支持 Groovy 脚本适合复杂逻辑比如多条数据求均值再比对阈值。这三种方式对应 LangGraph4j 里的EdgeCondition只是策略不同。实际用下来表达式判断占比超过八成模型判断适合开放性场景脚本判断权限比较敏感我限制只有平台管理员才能配置。3.4 循环回退的实现图内自环业务上经常有模型生成结果不合格就重新生成一次的需求。LangGraph4j 对此很友好因为你可以从某个节点加一条指向它自身或指向上游节点的边。举个例子合同审查工作流里模型抽取合同要素后要做一个质量校验——检查关键字段是否齐全。如果校验失败就回到模型节点重新抽取并附加上一次的错误信息。这个在 LangGraph4j 里就这么写.addNode(llm_extract, ...) .addNode(validate_extract, ...) .addConditionalEdge(validate_extract, new EdgeCondition(state - state.get(extract.errorCount) 0 ? retry : continue), Map.of(retry, llm_extract, continue, next_step))为了防止模型无限重试我在状态里加一个retryCount字段当它超过某阈值时强制走continue分支。这是个非常关键的生产级细节否则一旦模型持续输出不合格结果工作流会死循环把资源耗尽。4. 模型接入与知识增强LangChain4j 的抽象层与 RAG 落地工作流节点里大模型调用是最重要的能力。而 LangChain4j 的价值不只是统一调用 OpenAI/Ollama更在于它对对话记忆、工具调用、RAG、结构化输出都提供了标准化的接口。这让我在平台层只需要面向接口编程不需要关心具体模型供应商的实现差异。4.1 ChatLanguageModel 的模型网关封装平台底层接了个模型网关统一管理各模型供应商的 API Key、基础 URL、限流和降级策略。网关对上层暴露的不是 ChatGPT 的 SDK而是 LangChain4j 的ChatLanguageModel。选型时我在 Spring AI 和 LangChain4j 之间纠结过一阵。Spring AI 的优势是和 Spring 生态无缝集成但当时它的智能体、Tool Calling、Memory 抽象还不够成熟。LangChain4j 更贴近 LangChain 的 API 风格对图编排、链式调用的支持更完整社区文档也逐步齐全了。最终选了 LangChain4j加上 Spring AI 我们只用到它的 HTTP 接口能力没必要强行在一个框架里解决所有问题。模型网关的核心接口做了个约定public interface ModelGateway { ChatLanguageModel getModel(String modelId); }modelId对应数据库里一条模型配置记录包含供应商类型、模型名称、温度参数、超时时间等。工作流 DSL 里只需要写modelId: qwen-plus具体接的是哪家供应商、什么版本全部由平台管理员在后台配置流程设计者完全不需要关心。为了应对大模型服务偶发超时网关里还做了简单的重试对 5xx 或超时异常重试两次每次退避递增对 429 限流则不重试直接跳到节点的失败处理分支。这个策略在生产环境验证下来效果不错。4.2 RAG 节点向量检索塞进工作流低代码工作流里有一类节点用得非常频繁——知识库检索节点。业务人员把公司制度、产品手册、历史案例文档传到平台工作流启动后先检索相关知识片段再带着这些片段去调用大模型生成回答。LangChain4j 有一套完整的 RAG 抽象EmbeddingStore向量存储、EmbeddingModelembedding 模型、ContentRetriever检索器。我只需要面向接口做一个小封装让知识库节点能配置检索哪个知识库、取多少条、相似度阈值是多少。实际节点执行时做三件事拿到用户的查询文本调用EmbeddingModel.embed(text)生成查询向量。在EmbeddingStore里做相似度搜索取 TopK 结果。把检索到的文档片段按照来源—编号—正文的格式拼装成上下文注入 Prompt。这里我遇到的坑是检索质量。一开始用朴素的向量检索效果很差——用户问合同有效期是多久检索出的片段可能是合同模板里的其他条款。后来做了混合检索向量召回 关键词匹配BM25再加一条 RRFReciprocal Rank Fusion合并排序。LangChain4j 提供了默认的 RRF 实现但也有坑网上有人提到它的去重逻辑有缺陷我实际测试时也发现不同分段重复时排序会被污染所以我在合并后加了一道轻量去重逻辑按文档 ID 去重后再截断到 TopK效果稳定了很多。4.3 大模型结构化输出的处理工作流节点之间传数据大模型的输出必须是结构化数据否则后面没法做条件判断。LangChain4j 支持两种方式一是提示模型返回 JSON 之后解析为String二是使用严格的 Function Calling / Json Schema 约束模型输出。我在平台里推荐后者。具体做法是给每个大模型节点配置一个可选的输出 JSON Schema。LangChain4j 的ChatLanguageModel结合AiServices可以做到让模型直接返回一个 Java 对象底层是靠 Tool Calling 或者 JSON Mode 实现的。为了不把 Java 类写死我用了MapString, Object接收输出再套一层 JSON Schema 校验确保关键字段存在。校验失败的走条件边的重试分支再让模型带错修正。这套组合在生产环境扛住了不少真实业务稳定性比直接解析自由文本高一个量级。5. 低代码编排层的实践可视化工作流怎么跟图执行引擎对齐标题里的低代码三个字落到工程上是最费劲的部分。可视化编辑器、拖拽连线、参数表单、版本发布、测试运行每个模块都有不少门道。5.1 画布组件与 DSL 的映射关系我在前端画布上提供了六类基础节点开始节点、结束节点、模型节点、知识库节点、条件节点、工具节点。每类节点都有独立的配置面板用户在面板上填参数前端实时更新 DSL。这里最重要的原则是画布上每一个图形元素都要能 1:1 映射到 DSL 里一个对象。不允许出现画布上有图但 DSL 里找不到对应定义的情况。为此我定义了一套组件注册表前端每个组件注册表项包含组件类型标识对应 DSL 的type默认配置模板配置表单组件React/Vue 组件校验规则必填项、格式约束该节点支持哪些出边比如条件节点必须至少有两条出边这套注册表同时驱动了前端渲染和后端校验大大减少了前端画出来的图后端跑不了这类问题。5.2 版本管理与灰度发布低代码平台最怕的就是业务人员在生产环境改了一个节点配置整个工作流的行为都变了而且没有追溯能力。所以我在 DSL 里强制要求版本号每次保存生成新版本发布时可以选某一个历史版本回滚。执行引擎运行时通过版本号 发布时间窗口来决定用哪份 DSL。也就是说同一个工作流可以同时存在两个线上版本新发起的工作流走新版本老版本等存量实例跑完再自动下线。这个设计借鉴了微服务灰度发布的思想实际操作中帮我们避免了好几次线上事故。由于 LangGraph4j 本身没有持久化实例状态的能力我在引擎外层加了一个流程实例表。每个工作流被触发时先创建一条流程实例记录存下实例 ID、工作流版本号、初始输入、状态快照、当前所在节点。图执行过程中每完成一个节点异步把状态快照持久化到数据库。这样万一服务重启至少可以定位到实例卡在哪个节点也能回放执行历史。5.3 测试运行与调试调试是低代码平台的用户体验分水岭。我做了两个很实用的功能一是单节点测试。配置完一个模型节点后可以单独填测试输入平台直接渲染 Prompt、调用模型、展示结果不需要把整个工作流跑起来。二是全链路调试模式。运行时引擎会记录每个节点的输入输出到一张调试日志表前端以执行路径的形式展示哪个节点进入了、哪个条件边走了哪个分支、模型返回了完整原文、知识库检索命中了哪几个片段。业务人员自己就能快速定位问题很少再需要开发者帮忙看日志。这两个功能加起来把低代码平台从能画不能调提升到了画完能调能验实际使用率极高。5.4 人工审批节点的设计很多真实业务流程绕不开人工环节。比如合同初审工作流AI 先抽取条款并给出建议但最终盖章前需要法务人员确认。这个场景在纯图执行模型里是个挑战——图执行到一半需要暂停数小时甚至几天。我的方案是引入一个人工任务节点它不在图执行范围里阻塞而是图执行到该节点时创建一个待办任务并把当前工作流实例的状态置为 WAITING。引擎立即返回流程已暂停等待人工处理。人工处理完成后外部系统调用平台的继续执行接口传入处理意见。引擎读取该实例的历史状态从人工节点之后继续执行。说白了就是把阻塞变成外部事件驱动恢复。LangGraph4j 虽然本身不支持异步暂停但这套外层机制完全弥补了缺口而且实现成本不高。6. 上线后真正要命的坑上下文膨胀、超时边界与可观测性架构设计写起来都很顺但真实的肮脏细节全在运行期。这一节记录几个让我印象深刻的线上问题每个都花了不少于一个晚上排查。6.1 上下文膨胀状态 Map 越跑越大第一个坑发生在长链路工作流上。一个二十多个节点的工作流跑完之后数据库里存的流程实例状态快照有几 MB——每个节点的 JSON 输出都留在 Map 里包括大模型返回的完整原文、知识库片段全文、中间计算结果。问题不只是存储成本下一轮迭代的节点取状态时解析大 JSON 也变慢了。后来我做了两层优化精简存储状态快照持久化时剔除已不再被后续节点引用的 key通过分析 DSL 边关系做后向引用检查。分层状态把状态拆成持久区和临时区。持久区保存需要落库的关键结果临时区只存节点执行过程中的中间变量节点跑完自动清理。这两个改动让平均快照体积降了 70%效果非常显著。6.2 超时边界的拆分低代码平台一个隐藏问题就是用户不知道一个节点可能跑多久。模型调用可能 5 秒回来也可能 60 秒超时工具节点调外部接口对方可能需要 10 秒才响应。如果不显式处理超时整个工作流执行线程被拖死并发一高服务就雪崩。我最终在引擎层设置了两级超时节点级超时和工作流级超时。节点级默认 60 秒可以在 DSL 里覆写工作流级默认 15 分钟超过直接置为失败并触发告警。同时把所有对外的网络调用模型网关、HTTP 工具都配上独立的连接超时和读超时避免因为依赖服务的某个偶发抖动卡住整个流程。6.3 模型的幻觉分支问题条件边走模型的场景最需要防护。比如判断用户意图的模型节点如果模型输出了未定义的分支值——比如我们定义了TRANSFER和REPLY结果模型回了transfer|reply这种带分隔符的文本——工作流执行就会报错。我加了非常朴素的兜底识别不了的分支值一律走默认分支并给平台管理员推送一条告警让他知道模型开始不听话了。这是低代码平台里最容易被低估的健壮性问题但经历过一次线上事故后你会把它当成标配。6.4 可观测性从 traceId 到节点链路日志最后讲可观测性。智能体工作流比普通接口复杂在链路跨多个异构系统前端画布 → DSL → 图执行引擎 → 模型服务 → 知识库 → 外部 API。任何一个环节出问题如果日志里没有统一的关联 ID排查起来就是灾难。我的做法很朴素工作流实例启动时生成一个全局traceId在 DSL 解析、节点执行、模型调用、知识库检索的全部日志里都带上这个 ID。配合消息队列的 messageId整条链路的日志就能串联起来。线上环境我还加了一个节点执行耗时分布的监控指标按节点类型统计 P95 耗时。很快就能发现某个大模型节点的 P95 涨了 3 倍然后顺藤摸瓜定位到是模型供应商的服务波动还是 Prompt 变长导致推理变慢。这个监控指标帮我们在模型服务商出故障之前就提前感知到问题非常推荐。7. 一套亲测可行的架构演进路径先跑通场景再平台化最后分享一点亲测的落地建议。很多人看完前面的设计会觉得工程量大忍不住想一步到位把所有功能都做了。我的实际经验是先选一个高频业务场景用代码硬编码方式跑通验证智能体效果再把它改造成工作流 DSL最后再做可视化平台。第一阶段的目的是验证智能体到底能不能干这活。效果不好后面全白搭。第二阶段的目的是把单个场景从代码中拆出来让业务人员参与调整流程——这时候 LangGraph4j 的价值就开始体现了因为你可以快速改图结构不需要重写代码。第三阶段才是做画布和组件库把模型知识沉淀成平台能力。我自己在这个项目里最大体会是低代码平台最大的收益不是省掉开发工程师而是把业务人员从提需求—等排期—验收的漫长循环中解放出来。让懂业务的人自己调流程、测效果、发布版本平台的粘性和信任度会完全不一样。如果你也在做类似的 Java 智能体平台建议按这个路径走先用 LangChain4j 跑通模型接入再用 LangGraph4j 把流程写成可配置的图最后再上可视化画布。每一步都能验证价值每一步都不会白做。
