Spring AI Alibaba 的 Graph Workflow 功能我一开始以为它只是把几个流程节点串起来直到自己在一个 Agent 项目里被模型自由发挥折腾到怀疑人生才意识到它不是锦上添花而是 Agent 工程化的关键拼图。我见过太多 Agent 项目停在了演示阶段模型能回答问题、能调用工具、能给出看起来不错的结果。但一旦要上线问题就来了——它为什么走这条路为什么这次调了知识库、上次没有能不能让它在关键步骤前停下来等人确认如果流程中间断了能不能恢复重跑Graph Workflow 解决的正是这一连串问题。它不会把 Agent 变回死板的规则脚本而是把“模型自由决策”的范围收缩到指定的节点内把节点之间的流转逻辑显式画出来、管起来。简单说单点灵活整体可控。这篇文章不打算写成官方文档复述。我会用一个最小项目实战的视角拆一下 Spring AI Alibaba 图工作流怎么落地哪些设计真正决定可用性以及从“跑通”到“能上线”中间还要补哪些东西。1. 先搞清楚Agent 开发为什么会滑向“不可控”1.1 自由 Agent 的爽与痛很多人第一次玩 Agent都会被它的自由感吸引。你给模型一个目标它会自己拆解任务、选择工具、生成回复。看起来非常智能甚至有点“自主”。但真实工程里这种自由是有代价的。代价之一是随机性。模型不是确定性系统同样的问题两次调用可能走完全不同的路径。今天它能先查资料再总结明天可能直接凭记忆回答。今天它会调用搜索工具明天可能觉得不需要。如果 Agent 要处理的是重要业务这种随机性就是隐患。代价之二是不可审计。自由链路下你很难回答“它刚才到底做了什么”。日志里只有模型输入输出但为什么选择这一步、为什么跳过某一步事后很难还原。一旦线上出问题排查成本很高。代价之三是难以干预。流程里总会有一些高风险动作比如发送通知、修改订单、对外输出承诺。自由 Agent 可能在你还没确认时就做了。这不是模型不够聪明而是边界没有定义清楚。所以纯粹靠“提示词约束”来让 Agent 可控本质上聊胜于无。提示词能影响行为但不能保证行为。1.2 工作流不是回归老路而是给 Agent 装上轨道很多人一听“工作流”第一反应是这不就是传统规则引擎吗是不是把 AI 做成了 if else不是。传统工作流把每一步都写死模型没有决策空间。而 Graph Workflow 的定位是流程骨架固定节点内部可以灵活。你在图上定义“有哪些节点、节点之间怎么连、什么时候走分支”但每个节点内部仍然可以调用模型、解析语义、生成内容。这个边界很重要。模型不是一个完全失控的执行者而是一个在指定工位上的操作员。它可以在“分类”节点里决定这条消息属于哪个类别但不能跳过分类直接去“生成回答”。它可以在“生成回答”节点里自由组织语言但不能绕过“人工审批”节点直接对外发送。这样做的好处是你保留了 AI 的语义能力同时获得了流程的确定性。每一步都有名字、有输入输出、有执行记录。出问题时可以明确知道是哪一个节点出了问题而不是对整个 Agent 一头雾水。1.3 Spring AI Alibaba 在这类问题里扮演什么角色Spring AI Alibaba 不是第一个做 Agent 编排的框架但它对 Java 技术栈的团队非常友好。它把模型接入、对话补全、结构化输出、工具调用这些能力统一到 Spring 体系里。你可以用熟悉的 Bean、配置、依赖注入来组织代码而不是在一个孤立脚本里调模型 API。Graph Workflow 是其中的一部分思路把 Agent 行为定义成一张有向图节点执行函数边决定流转方向。加上 Alibaba 生态里的工程化组件比如日志、监控、配置管理等整个项目可以更快融入现有后端体系。这也是我建议 Java 团队优先考虑它的原因不是因为它能“自动生成 Agent”而是因为它能让你在一个已经成熟的工程环境里把 Agent 当成一个普通的后端服务来开发、测试、部署和维护。2. 用 Graph Workflow 跑通一个最小 Agent 项目2.1 我选择的最小场景技术问答质检 Agent直接讲概念很难建立体感。我建议做一个足够小但包含关键要素的项目技术问答质检 Agent。它的业务逻辑是接收一个问题。先对问题做分类比如“知识库可回答”还是“需要模型自由回答”。如果知识库可回答就查询知识库获取候选资料。如果资料充足就基于资料生成答案资料不充足则转模型直答。生成答案后对质量做一次校验校验不通过则重写或转人工。最终输出答案和过程摘要。这个场景好在哪里它既有模型判断分类、质量校验又有确定流程查询、输出还包含条件分支和人审入口。用图工作流来组织正好能把所有关键特性都覆盖到。2.2 先把图结构画出来再写代码很多初学者容易犯一个错误拿到需求后直接写代码结果边写边想流程最后代码和服务逻辑缠在一起。我更建议先画图。不用专门工具纸笔或者白板都行。把节点列出来把箭头连起来把分支条件写清楚。这个过程看着简单但能逼你提前思考哪些步骤必须有先后顺序哪些步骤可以并行哪个分支应该由模型决定哪个分支应该由代码决定哪些步骤如果失败是重试还是跳转以质检 Agent 为例图结构大致是输入节点接收原始问题。分类节点模型判断问题类型。知识库查询节点按分类结果查资料。资料充足判断节点代码判断或模型判断选择生成方式。生成回答节点调用模型生成答案。质量校验节点校验答案是否合格。人工审核节点不合格转人工合格直接输出。输出节点返回最终结果。这些节点的连接关系就是一张有向图。代码只是把这张图翻译成可执行程序。2.3 环境准备与依赖边界正式开始项目前先确认几件最基础的事JDK 17 及以上版本目前 Spring Boot 3.x 基本是标配。一个可用的 Spring Boot 项目建议先通过官方脚手架生成。Spring AI Alibaba 依赖具体版本以官方文档为准。这个框架版本迭代比较快不同版本的 API 可能略有差异直接照抄旧教程不一定能编译通过。模型 API Key比如通义千问或者其他通过 OpenAI 兼容接口接入的模型。本地日志配置至少要有控制台日志跑通之前不需要引入复杂监控组件。依赖边界要注意先跑通一个 no-op 的空图再接入真实模型调用。不要一开始就同时引入向量库、Redis、消息队列那样出问题时根本分不清是哪一层坏了。2.4 一个最小可运行的图结构示例下面是一个示意代码重点展示 Graph Workflow 的组织方式具体 API 以你使用的官方版本为准。Graph graph Graph.builder() .id(qa-agent) .addNode(input, inputNode) .addNode(classify, classifyNode) .addNode(knowledge, knowledgeNode) .addNode(generate, generateNode) .addNode(qualityCheck, qualityCheckNode) .addNode(humanReview, humanReviewNode) .addNode(output, outputNode) .edge(input, classify) .edge(classify, knowledge) .edge(knowledge, generate) .edge(generate, qualityCheck) .condition(qualityCheck, output, passed - passed.booleanValue()) .condition(qualityCheck, humanReview, passed - !passed.booleanValue()) .edge(humanReview, output) .build();节点内部的核心逻辑一般是一个函数式组件接收统一的上下文对象执行完返回结果。比如分类节点Node classifyNode context - { String question context.get(question); String result chatClient.call(请把这个问题分类为: knowledge 或 general。问题: question); context.set(category, result); return context; };实际开发里节点内部可能还会包含工具调用、重试逻辑、异常处理。但第一版不要想那么多目标只有一个图上每一个节点都能被顺序执行并且能看到日志输出。跑通之后再逐步把模型调用、分支条件、人工审核加进去。先确认骨架是通的再填肉。3. 从“单点跑通”到“可控灵活兼备”关键设计3.1 状态管理让每个节点知道“我在哪”图工作流跑起来以后你会很快意识到一个问题节点之间怎么传数据如果每个节点单独定义入参出参图一旦复杂接口会非常臃肿。更常见的做法是用一个统一的上下文对象贯穿整个流程。每个节点从上下文里读需要的数据处理完把结果写回上下文。这个上下文就是整张图的“共享工作台”。上下文里至少要包含几类数据当前执行状态走到哪个节点了执行是否成功。业务数据用户输入的 question、查询到的资料、生成的答案。中间结果分类结果、质量评分、错误原因。额外信息执行超时时间、重试次数、版本号。要注意上下文对象不能设计成全局单例。每次执行 Agent都要创建一份新的上下文否则并发请求会互相污染。关于这一点后面排查链路里还会专门讲。3.2 条件路由把模型判断放进流程边界里图工作流最有价值的能力之一是支持条件路由。一个节点执行完不是机械地走到下一个固定节点而是根据结果决定下一步。条件路由的难点不在代码而在“条件从哪里来”。如果条件来自规则比如“资料条数大于3就走生成节点否则走直答节点”那是稳定可控的。如果条件来自模型判断比如“模型判断这个问题更适合知识库回答”就引入了一个不确定性来源。你必须先定义清楚模型输出的格式。我常用的做法是要求模型只输出一个固定标识比如 JSON{category:knowledge}然后代码解析这个 JSON。解析失败或者返回不认识的标识就落入默认分支。String raw classify(modelResult); Category category parseCategory(raw); // 可能抛异常 if (category UNKNOWN) { context.set(route, default); } else { context.set(route, category.name()); }模型输出不稳定不是 bug你一定要在流程设计里给不稳定留出口。默认分支不是“偷懒”而是让异常情况有明确去处。3.3 人工审批节点把高风险步骤交给人可控 Agent 的另一个关键是支持“人在环里”。如果有一步操作的影响比较大比如给用户发邮件、修改数据库、对外接口调用流程应该在这里暂停等人工确认后继续。图工作流非常适合表达这种暂停。你可以在图里定义一个人工审核节点这个节点不调用模型而是把当前状态持久化生成一条待办任务等审批接口回调后继续往下走。比如前面质检 Agent 里质量校验不通过时可以转人工审核。人工审核节点接收到“质检失败”的上下文后把问题和答案展示给审核人员。审核人员点击通过流程才进入输出节点。这种设计的好处是风险动作永远有一条“人最后把关”的路径。模型负责生成人负责判断“能不能发”。3.4 记忆和上下文图工作流里的信息传递Graph Workflow 本身不负责长期记忆。它更像是一张交通地图负责把车从 A 点送到 B 点。至于车上装了什么货物、要不要中途补货是节点和外部存储要解决的问题。短记忆可以放在上下文对象里。比如多轮对话场景每轮的问题和答案都追加到上下文的 messages 字段里。但要注意长度控制把所有历史对话一股脑塞给模型很快会撞上上下文窗口。长记忆建议交给外部存储。比如把用户偏好、历史行为写入数据库或向量库。节点执行时按需读取而不是把整张表都放进图里。实际项目里你会遇到“这个 Agent 需要记住上一步的结果”的场景。这时候先想清楚这个记忆是本次流程的中间状态还是下一次流程要用的持久化数据。前者放上下文后者放存储。图工作流要做的是保证状态传递清晰而不是替代数据库。4. 实操中容易踩坑的排查链路4.1 问题先分四层输入、节点、流转、资源Agent 项目一旦出问题新手容易直接怀疑模型反复调整提示词。其实很多问题根本不在模型。我一般会按这个顺序排查输入层原始输入是否符合预期格式对不对有没有空值上下文里是否缺少必要字段节点层单个节点执行是否正常是模型调用失败还是解析逻辑出错节点有没有异常被吞掉流转层图是否按预期从一个节点走到下一个节点条件路由返回了什么值边有没有连错资源层模型 API 是否限流超时时间是不是太短连接池、线程池有没有被打满这四个层次先检查哪个取决于现象。如果完全没输出先看输入和资源如果输出了但不符合预期先看节点和流转。4.2 图不按预期执行时的排查顺序假设你发现质量校验不通过本应转到人工审核结果直接走到了输出。这类问题非常典型。排查顺序应该是先看日志里质量校验节点实际返回了什么。是 true 还是 false还是解析异常后走了默认值。看条件路由函数。比如passed - passed.booleanValue()如果 passed 是 null会发生什么是不是默认走了 false 分支。看图定义。质量校验到人工审核的边到底是在哪个 builder 里配的有没有因为复用了旧对象导致配置覆盖。看模型输出。质量校验如果是模型判断模型是否真的输出了预期格式如果输出一段解释parse 失败后是不是被 catch 后返回了“合格”这类问题最难的往往不是逻辑而是状态没打日志。所以每个节点执行完至少输出一行结构化日志节点名、耗时、关键字段、下一跳结果。4.3 模型输出不稳定导致路由漂移怎么办模型输出不稳定几乎是 Agent 开发里必然要面对的事。你给模型一个 JSON 格式要求它偏偏多解释一句你让它输出 true/false它输出 “Yes”。解决思路不是“把提示词写得更强”而是从流程上做一些防御解析失败不要直接抛异常而是走一个默认分支。默认分支可以是人工审核也可以是一条保守路径。对关键判断做二次校验。比如分类节点如果模型给出的分类不在预设枚举里可以让它重试一次或者换一个小一点的模型判断。不要把模型输出直接当作强类型使用。先转字符串再走解析器解析后再做白名单校验。在节点内部设置超时和重试。模型调用偶尔会超时超时后重试一次往往就能恢复。这些不是“额外工作”而是图工作流必要的容错设计。没有容错图越复杂越容易断。4.4 并发和重复执行时的状态隔离图工作流项目从单测走向线上时第一个撞上的坑往往是并发问题。如果你在代码里把上下文对象定义为 static或者用了一个全局 Map 保存状态那么两个用户同时发起请求时数据就会互相覆盖。A 用户的问题还没处理完B 用户的数据就把它冲掉了。这个问题在演示时不会出现因为一次只跑一个请求但并发一上来立刻暴露。正确的做法是每次执行 Agent 时都创建一个新的上下文对象整个流转过程的临时状态只存在于这次执行内部。如果需要持久化比如人工审批也要带着唯一的执行 ID 去存取不能用一个全局字段。另外还要考虑重复执行。如果流程中断从某个节点重跑时节点是否希望被幂等执行批量插入、消息发送、外部调用等副作用操作一定要加幂等判断否则重试一次可能造成重复动作。5. 适用边界什么时候该用 Graph Workflow什么时候别硬上5.1 适合 Graph Workflow 的场景不是所有 Agent 都必须用 Graph Workflow但以下几种情况它是非常合适的选择流程步骤明确。比如“先分类、再检索、再生成、再校验”业务本身有顺序要求。需要审计和复现。比如客服、审核、金融分析场景事后要说清楚“为什么得到这个结果”。需要人工审批。比如自动写邮件、自动改配置、自动下单高风险操作必须有人确认。需要精细控制模型行为。你不希望模型自己决定要不要跳过某些步骤而是让它在固定节点里发挥作用。团队是 Java 技术栈。希望把 Agent 融入现有 Spring Boot 服务体系而不是另起一套脚本。在这些场景里Graph Workflow 的价值不是让流程“看起来高级”而是把不确定性风险压缩到最小范围。5.2 不适合的场景反过来有些场景硬套图工作流反而会抑制 Agent 的能力。开放探索型任务。比如“帮我研究一个陌生领域找到关键信息”任务边界模糊连步骤都不确定画不出图。需要模型自主规划的工具调用链。比如让 Agent 自己决定先搜什么、再看什么网站、最后怎么总结。如果预设路线很可能限制它的发现能力。原型验证阶段。只是测试一个想法还没想清楚流程先用一个自由 Agent 跑一阵子比一开始就画图更有效率。这时候更合适的是先做一个自由 Agent让它探索等跑出一个相对稳定的流程后再把稳定的路径沉淀成 Graph Workflow。换句话说图工作流不是 Agent 的起点而是它成长后的骨架。5.3 它和 MCP、记忆、Skill 是配合关系不是替代关系讨论 Agent 开发时很多人被各种概念弄晕MCP、记忆、Skill、Workflow、Agent 框架到底哪个是哪个我常用一个类比Graph Workflow 是交通路线图它决定车从 A 到 B 怎么走MCP 是公路系统它规定车怎么接入加油站、维修点也就是工具接入的标准协议记忆是车的货仓和仓库系统决定数据怎么存、怎么取Skill 是车上的标准化技能包比如“如何查天气”“如何生成周报”。它们解决的是不同层级的问题不是互相替代。节点内部需要调用一个外部工具那可以通过 MCP 接入Agent 要记住用户偏好那需要在上下文或存储在节点设计里解决流程要稳定那靠 Graph Workflow 控制路由。真正开发一个可用 Agent往往四者都要组合使用。6. 把项目沉淀成可复用框架6.1 三步设计法先定流程骨架再定节点最后定路由条件如果现在要新做一个 Agent 项目我建议按三步走不要跳级第一步画流程骨架。把所有业务动作列出来标注哪些是必须顺序执行的哪些是允许分支的哪些需要暂停等人。第二步定义节点。每个节点只做一件事并且要有清晰的输入、输出、异常行为。如果某个节点要做三件事就拆成三个节点。第三步定路由条件。明确哪个分支由代码规则决定哪个分支由模型判断决定。模型判断的分支一定要设计默认路径。这个顺序的好处是先把稳定边界画好再往里填模型能力避免被模型的“自由发挥”带偏。6.2 节点开发清单输入、输出、异常、重试每个节点开发前可以对照下面这个表格检查检查项问题输入这个节点需要上下文里哪些字段字段不存在时怎么处理输出这个节点会把什么结果写回上下文写什么格式异常模型调用失败、解析失败、工具异常分别怎么处理重试这个节点可以重试吗重试有什么副作用边界输入为空、超长、格式异常时行为是什么日志至少输出节点名、耗时、关键结果字段。不需要每个节点都写得很重但脑子过一遍这张表能少很多上线后的意外。6.3 从演示走向生产还要补什么演示项目跑通后离生产使用还差几块拼图链路追踪。每次执行都有一个唯一执行 ID日志里带上这个 ID才能快速定位一次请求走过了哪些节点。指标监控。记录每个节点的耗时、成功率、失败原因。条件路由漂移率上升时说明模型或提示词需要调整。图版本管理。工作流不会一成不变。每次改图要能对应到版本号否则线上出了问题很难回滚。提示词版本管理。模型行为不只由代码决定提示词也是关键变量。最好把提示词作为配置或独立文件而不是硬编码在节点里。模型评估。不要只看一两个例子。准备一组测试问题跑完一个版本后对比输出才能知道这次改动是变好还是变坏。这些内容看着多但其实每个都是常规后端工程习惯。Graph Workflow 真正的好处是这些工程化能力可以围绕“图”这个结构来组织比追着一团自由逻辑做监控容易太多了。6.4 长期演进建议最后一点建议不要第一天就设计一个超级复杂的图。先从一条主链路开始输入 - 分类 - 生成 - 输出。跑通后再加知识库分支再加质量校验再加人工审核再加异常兜底。每加一个节点都单独验证一次确认没有破坏原有路径。图工作流最怕的不是节点多而是节点之间的隐性依赖。你以为两个节点是独立的实际上都依赖同一个上下文字段你以为某个分支永远不会走到结果模型输出格式一变就走进去了。所以每次改动后至少要跑一遍全链路测试再补条件分支的专项测试。Agent 项目的长期价值不在于你用了多新的模型也不在于你接了多少工具而在于你能不能把一次性的灵光表现变成一条稳定、可观测、可迭代的生产流程。Graph Workflow 给的就是这个“变稳定”的容器。先学会用它扎一条最小路径再慢慢扩展边界你会发现可控和灵活并不是非此即彼而是可以同时成立的。