这次我们来看 Spring AI Alibaba 生态里的 Graph / Workflow 模块。很多 Java 后端做 Agent 都有一个痛点用纯 Prompt 让模型自由发挥效果好但不可控手写 if-else 把每个步骤写死稳但太僵硬。Spring AI Alibaba Graph 的思路就是在两者之间找平衡把 Agent 流程拆成节点、边、状态让模型在节点内做决策让开发者在节点间控制走向。这个项目最大的价值是让 Java 开发者用自己最熟悉的 Spring Boot 方式去开发 Agent。没有 GPU 门槛不需要单独部署 Python 推理服务只要有一个模型 API Key 就能跑起来。它天然支持 REST API 暴露也方便接批量任务。本文会从零开始建工程、引入依赖、配置模型供应商、定义节点和条件分支、跑通一个“可控 灵活”的 Agent 流程再把它封装成接口最后补上性能观察、问题排查和工程化建议。如果你是 Java 后端、Spring Boot 用户或者正在做企业内部智能体、客服工单、数据分析助手这类偏流程化的 AI 应用这篇文章可以直接收藏。1. 核心能力速览先给一张总览表快速判断这个东西适不适合你。能力项说明项目类型Java 开源框架Spring AI Alibaba 生态中的 Graph / Workflow 编排能力核心功能基于图结构的 Agent 流程编排支持节点、条件分支、状态传递、流程复用开发语言Java基于 Spring Boot / Spring AI硬件要求普通开发机即可无需 GPU模型推理依赖云端 API 或内网模型服务依赖环境JDK 17、Maven / Gradle、Spring Boot 3.x启动方式标准 Spring Boot 应用启动接口能力流程可封装为 REST API适合 Web 服务集成批量任务可通过任务队列 异步线程 独立流程实例实现批量处理日志与可观测节点执行顺序、状态变化可通过日志和链路追踪查看适合场景客服 Agent、工单分类、RAG 查询、审批辅助、数据查询助手等从这张表能看出来Spring AI Alibaba Graph 不是一个大而全的 AI 平台它解决的是“如何把模型能力编排进 Java 业务系统”的问题。2. 适用场景与使用边界先明确一个容易混淆的点Spring AI Alibaba Graph 里的 Graph 不等于图数据库它也替代不了 Neo4j 这类图数据库。这里说的 Graph 是“流程编排图”节点是业务动作边是流转关系。如果你需要做知识图谱存储、实体关系查询应该去用图数据库如果你需要的是一个 Agent 的执行流程才用 Graph / Workflow 模块。适合这个项目的典型场景客服工单处理先判断意图再查订单信息最后生成回复。RAG 问答助手先判断问题是否需要检索再决定走知识库还是直接回答。数据分析 Agent先理解用户问题再生成查询语句最后汇总结果。审批流智能助手读取审批状态判断条件调用对应处理节点。这些场景都有共同特点流程可枚举但每个节点的执行方式需要模型参与。纯规则写死太复杂纯模型自由发挥不可控Graph 编排是中间态。使用边界也需要说清楚不适合完全开放式的自由聊天。如果你要求 Agent 完全没有流程约束Graph 反而会限制你。模型调用依赖外部 API 时输入数据会发送到模型服务端。涉及用户手机号、证件号、内部业务数据时必须先做脱敏、授权确认和合规评估。节点内使用模型做决策不等于模型一定正确。条件分支的关键位置需要加校验和兜底逻辑。从工程角度看Graph 模块的价值不是“把流程画出来”而是把流程变成可测试、可监控、可复用的代码。3. 环境准备与前置条件这套东西跑起来的环境要求很低核心依赖是 JDK、Maven、Spring Boot 和模型服务的 API Key。前置项要求说明JDKJDK 17 或更高版本Spring Boot 3.x 的基线要求构建工具Maven 3.6 或 Gradle 7.5推荐 Maven依赖管理最简单Spring BootSpring Boot 3.2 及以上版本以 Spring AI Alibaba 官方兼容版本为准模型 API通义千问 DashScope API Key或 OpenAI 兼容接口没有 Key 也可以先走本地 mock但不推荐开发机4 核 8G 内存即可本地只是 Java 进程不做模型推理端口8080 或自定义端口和现有服务冲突时改配置网络能访问模型 API 服务如果走内网模型网关则要能访问内网网关模型供应商配置是关键。Spring AI Alibaba 最大的特点之一是开箱即用地接入国内模型服务比如通义千问同时也支持 OpenAI 兼容协议。你只需要在application.yml里配好 Base URL 和 API KeySpring AI 会统一封装对话、嵌入等能力。不需要 GPU。这一点对多数后端团队很友好本地开发机完全跑得动瓶颈只在模型 API 的响应耗时。4. 本地部署与项目初始化4.1 创建 Spring Boot 工程推荐直接用 Spring Initializr 创建工程或者在你的 IDE 里新建一个 Spring Boot 项目。工程信息参考Groupcom.exampleArtifactspring-ai-agent-demoJDK17依赖先不勾选后续手动加spring-ai-alibaba相关依赖4.2 引入 Spring AI Alibaba 依赖pom.xml需要先加 Spring AI BOM再引入对应模块。具体版本号以 Maven 中央仓库和官方文档发布为准下面用变量占位parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version relativePath/ /parent properties java.version17/java.version spring-ai-alibaba.version1.0.0-M2/spring-ai-alibaba.version /properties dependencies dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter/artifactId version${spring-ai-alibaba.version}/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies注意spring-ai-alibaba目前版本非常活跃API 也在演进。如果你用的版本和我这里不同类名和配置项可能有差异务必以官方文档和release note为准。4.3 配置模型供应商在src/main/resources/application.yml中配置模型服务spring: application: name: spring-ai-agent-demo ai: dashscope: api-key: ${DASHSCOPE_API_KEY} base-url: https://dashscope.aliyuncs.com/api/v1 chat: options: model: qwen-plus temperature: 0.7如果你的环境使用 OpenAI 兼容接口配置方式类似关键是把base-url指向你的模型网关并填上对应的 Key。把 Key 放在环境变量里不要硬编码提交到代码库。4.4 启动验证在工程根目录执行mvn spring-boot:run启动成功后先写一个最简单的测试调一次模型对话接口确认模型配置没问题再进入 Graph 流程开发。RestController RequestMapping(/api/demo) public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient chatClient) { this.chatClient chatClient; } GetMapping(/chat) public String chat(RequestParam String message) { return chatClient.call(message); } }访问http://127.0.0.1:8080/api/demo/chat?message你好能正常返回模型结果说明环境已经就绪。5. Spring AI Alibaba Graph 核心概念与编程模型5.1 从“一句 Prompt”升级为“流程编排”普通模型调用是“输入一句话输出一段文本”。Agent 项目一旦复杂就要拆成多个步骤先做意图识别再决定调哪把工具最后把工具结果整合成回复。如果这些步骤全写在一次模型调用里效果不稳定写在业务代码里又要处理大量 if-else。Graph 模块的思路是把步骤抽象成节点用图结构描述节点之间的流转关系。5.2 节点Node节点是流程中的最小执行单元。它可以是简单的业务代码比如查数据库、调外部 API也可以是模型调用比如分类、抽取、生成。每个节点接收当前状态执行自己的逻辑最后把新数据写回状态。5.3 状态State状态是贯穿整个流程的数据容器。流程初始输入、每个节点产生的中间结果、最终输出都放在状态对象里。设计阶段最重要的就是定义状态结构字段尽量精简避免把大对象塞进状态导致内存压力。5.4 条件分支Condition条件分支决定流程下一步走向。比如意图识别节点返回“查天气”流程就走天气查询节点返回“查订单”就走订单查询节点。Graph 模块允许你在边上配置条件只有满足条件的节点才会被触发执行。5.5 边与图结构节点是顶点边是流转关系。一个简单的有向图可以做到串行流程A - B - C条件分支A - B 或 C循环处理节点不满足条件时回到前序节点这种结构最大的价值是流程可视化、可测试、可组合。5.6 示例一个三段式 Agent 流程下面用一个最小示例说明编程模型。这个 Agent 只做三件事判断用户问题类型、根据类型选择处理逻辑、生成最终回复。public class IntentNode implements Node { Override public Object execute(State state) { String userInput state.getValue(user_input, String.class); String intent classify(userInput); state.setValue(intent, intent); return state; } }public class OrderQueryNode implements Node { Override public Object execute(State state) { String orderId state.getValue(order_id, String.class); String result queryOrder(orderId); state.setValue(query_result, result); return state; } }public class ReplyNode implements Node { Override public Object execute(State state) { String queryResult state.getValue(query_result, String.class); String reply generateReply(queryResult); state.setValue(reply, reply); return state; } }这只是示意代码。真实环境的 Spring AI Alibaba Graph 模块会有更完整的泛型定义、异步支持和生命周期钩子但核心思想一致每个节点只做一件事数据通过 State 流动。6. 实战开发可控 灵活兼备的 Agent 项目现在用一个稍微完整的案例串起来用户输入问题Agent 先判断是否需要查询订单系统需要则走查询节点不需要则直接回答最后生成回复。6.1 项目包结构src/main/java/com/example/agent/ ├── AgentApplication.java ├── controller/ │ └── AgentController.java ├── node/ │ ├── IntentNode.java │ ├── OrderQueryNode.java │ └── ReplyNode.java ├── flow/ │ └── AgentFlow.java └── state/ └── AgentState.java6.2 定义状态public class AgentState { private String userInput; private String intent; private String orderQueryResult; private String reply; private boolean needQuery; // getter / setter 省略 // 实际开发建议直接使用 Map 或 Record 包装 }一个原则状态字段不要贪多。越简单越容易排查问题也有利于批量任务时序列化。6.3 定义节点意图识别节点这里采用“模型判断 规则兜底”的方式先用 Prompt 让模型分类如果返回结构不完整再用关键词兜底保证流程不会因为一次模型输出异常就中断。public class IntentNode implements Node { private final ChatClient chatClient; public IntentNode(ChatClient chatClient) { this.chatClient chatClient; } Override public Object execute(State state) { String userInput state.getValue(user_input, String.class); String prompt 你是客服意图识别器。 如果用户问题涉及订单查询、物流查询、退款进度返回 ORDER 否则返回 GENERAL。只返回一个单词。\n用户问题 userInput; String rawIntent chatClient.call(prompt).trim(); String intent normalizeIntent(rawIntent); state.setValue(intent, intent); state.setValue(need_query, ORDER.equals(intent)); return state; } private String normalizeIntent(String raw) { if (raw.toUpperCase().contains(ORDER)) { return ORDER; } return GENERAL; } }订单查询节点里面是业务逻辑可以查数据库、调内部 API也可以直接返回模拟数据。回复生成节点把结果拼成最终答案。6.4 配置流程流程配置是把节点连成图的地方。核心是定义从哪个节点开始按什么条件走哪条边最终在哪个节点结束Configuration public class AgentFlowConfig { Bean public Flow agentFlow(IntentNode intentNode, OrderQueryNode orderQueryNode, ReplyNode replyNode) { return Flow.build() .from(intentNode) .when(state - isOrderIntent(state), orderQueryNode) .otherwise(replyNode) .from(orderQueryNode) .next(replyNode) .end(replyNode); } }这种写法的好处是流程定义集中在配置层节点只关心自己的业务逻辑条件路由一目了然。后面要加节点、改分支只动配置不碰业务代码。6.5 执行流程Service public class AgentService { private final Flow agentFlow; public AgentService(Flow agentFlow) { this.agentFlow agentFlow; } public String run(String userInput) { State state new State(); state.setValue(user_input, userInput); State resultState agentFlow.execute(state); return resultState.getValue(reply, String.class); } }到此一个可控 灵活的 Agent 项目骨架已经跑通。可控体现在流程的节点和分支由代码确定灵活体现在每个节点内部可以使用模型做判断模型输出变化不会影响整体流程骨架。7. 功能测试与效果验证流程写完之后不要直接接接口先做功能验证。推荐按下面几个维度测。7.1 基础流程测试输入一个通用问题例如“你好我想咨询一下退换货政策”。预期结果IntentNode识别为GENERAL不触发OrderQueryNode直接走ReplyNode生成回复。判断标准日志中节点执行顺序是IntentNode - ReplyNode回复内容与问题相关。7.2 条件分支测试输入“帮我查一下订单 20250101 的物流状态”。预期结果IntentNode识别为ORDER触发OrderQueryNode再走ReplyNode。判断标准日志中出现OrderQueryNode执行记录回复内容包含订单查询结果。7.3 异常输入测试输入空字符串、乱码、超长文本。预期结果是流程不崩溃模型或兜底逻辑能输出合理回复。这个测试主要用于确认节点的异常兜底是否有效。7.4 验证清单测试项输入示例预期输出判断标准基础流程你好正常回复节点顺序正确意图分类查物流走订单查询节点分支生效未知意图随便聊聊走通用回复兜底生效空输入空字符串返回提示信息不抛异常流程重复执行同一输入多次结果一致或稳定状态无串扰一定要给每个测试用例单独记录日志查看节点执行顺序和耗时。流程编排类项目最怕“结果不对但不知道走到哪个节点”。8. 接口 API 与批量任务集成8.1 将 Agent 流程暴露为 REST APIRestController RequestMapping(/api/agent) public class AgentController { private final AgentService agentService; public AgentController(AgentService agentService) { this.agentService agentService; } PostMapping(/run) public AgentResponse run(RequestBody AgentRequest request) { long start System.currentTimeMillis(); String reply agentService.run(request.getMessage()); long cost System.currentTimeMillis() - start; return new AgentResponse(reply, cost); } }请求体{ message: 帮我查一下订单 20250101 的物流状态 }响应体{ reply: 订单 20250101 目前的物流状态是已签收。, cost: 1234 }8.2 curl 调用示例curl -X POST http://127.0.0.1:8080/api/agent/run \ -H Content-Type: application/json \ -d {message: 帮我查一下订单 20250101 的物流状态}接口能跑通后面就可以接到小程序、钉钉机器人、企业微信后台或者自己的管理系统里。8.3 批量任务设计思路大量数据需要跑 Agent 流程时不建议直接并发调用接口。更稳妥的做法是引入任务表字段说明task_id业务任务 IDinput输入文本或参数 JSONstatus初始、运行中、成功、失败retry_count重试次数result流程输出结果error_msg失败原因流程建议批量数据写入任务表状态为初始。定时任务扫描初始任务逐条提交到异步执行器。每条任务创建独立的流程实例跑完更新状态和结果。失败任务进入重试队列设置最大重试次数。记录每次执行的节点日志方便追踪。这个设计不依赖具体框架Spring Boot 原生定时任务 线程池就能实现。核心是保证每条 Agent 任务的状态隔离不要多个任务共用一个可变状态对象。9. 资源占用与性能观察9.1 本地进程资源Spring AI Alibaba Graph 项目本质是一个 Spring Boot 应用本地资源占用主要来自 JVM。jhsdb jmap --heap --pid 进程ID或者直接用 JConsole、Arthas 观察 JVM 堆内存、GC 和线程数。普通开发机运行单实例完全没有压力热点问题不在 Java 进程而在远程模型 API 的响应耗时。9.2 模型 API 延迟是主要瓶颈一次模型调用通常需要几百毫秒到几秒。一个流程如果有 3 个模型节点单次请求耗时就可能是 3 倍模型延迟。优化方向减少不必要的模型调用能用规则判断就不要让模型做。部分节点可以并行执行看 Graph 模块是否支持并行节点。设置合理的超时时间避免某个模型接口卡住整个流程。使用流式输出配合 SSE提升前端首字响应体验。9.3 并发和限流Agent 接口是 IO 密集型远程模型 API 通常有 QPS 限制。生产环境建议用信号量或线程池限制并发调用数。对模型 API 做客户端级限流。在网关层对/api/agent/run做限流。批量任务执行时控制最大并发线程数防止打爆模型服务。9.4 日志与链路追踪每个节点执行时打印一条结构化日志2026-01-01 12:00:00 INFO - flowagentFlow, nodeIntentNode, cost520ms, statusSUCCESS 2026-01-01 12:00:01 INFO - flowagentFlow, nodeOrderQueryNode, cost30ms, statusSUCCESS 2026-01-01 12:00:02 INFO - flowagentFlow, nodeReplyNode, cost800ms, statusSUCCESS加入traceId可以把一次完整流程的所有节点日志串起来排查问题时效率高很多。10. 常见问题与排查方法问题现象可能原因排查方式解决方案启动报依赖冲突Spring Boot / Spring AI 版本不匹配查看启动日志中的 Caused by用官方 BOM 统一版本避免手写版本号调用模型报 401API Key 配置错误或过期检查环境变量和配置中心重新生成 Key确认 base-url 正确节点一直没执行条件路由没有匹配对应分支开启 DEBUG 日志打印每个节点的判断结果检查 Condition 的返回值补充默认分支状态数据为空节点写入 Key 与读取 Key 不一致在节点入口打印 State 内容统一状态枚举或常量类管理 Key接口超时模型节点响应慢或模型 API 不稳定查看日志中单节点耗时提高超时时间增加重试优化流程减少模型调用批量任务同一结果多个任务共用了同一个 State 实例检查执行器是否 new 了新 State每个任务独立创建 State模型返回内容格式不稳定Prompt 约束不够强打印模型原始返回加输出解析和重试必要时用 JSON 输出格式最容易踩的坑有两个一个是版本升级后 API 变了老代码编译不过另一个是状态变量 Key 拼写不一致运行时不报错但结果为空。前者靠读官方 changelog 解决后者靠统一常量类和日志排查。11. 最佳实践与使用建议结合 Spring AI Alibaba Graph 的编排特性和 Agent 项目的通用工程问题给出一套可落地的实践建议。第一先跑通最小流程再扩展。第一次使用不要一上来就设计十几个节点先做“意图识别 - 回复”两个节点确认依赖和环境没问题再逐步加节点和分支。第二节点职责要单一。一个节点只做一件事分类只做分类查询只做查询生成只做生成。不要在一个节点里既调模型又查库又写日志否则后续排查和复用都会很痛苦。第三状态对象保持精简。状态是流程传递数据的容器字段越多序列化越重出错概率越高。批量任务场景下建议只放必要字段。第四条件分支必须考虑模型输出异常。模型永远可能返回超出预期的内容所以在分类节点、检查节点、输出解析节点都要有兜底逻辑比如默认走GENERAL分支、解析失败重试一次。第五模型参数先用保守值。温度参数不建议一开始就调高温度值越低输出越稳定。对流程控制类节点温度可以更低对创意回复类节点可以适当调高。第六日志和观测从第一天就做好。每个节点打印耗时、状态、结果摘要批量任务记录任务状态和重试次数。Agent 项目一旦出问题没有日志几乎没法查。第七合规边界要前置。所有发送到模型 API 的数据都要经过合规评估。涉及人脸、声音、个人隐私、商业机密的输入输出必须做脱敏、权限控制和授权确认。生成内容要加审核机制不能直接全量自动发布。12. 总结与下一步Spring AI Alibaba Graph 给 Java 后端提供了一条比较务实的 Agent 落地路径。它不要求你学 Python不要求你部署 GPU 推理服务核心是用 Spring Boot 的工程化思维把 AI 流程编排清楚。可控靠节点和边保证灵活靠节点内的模型决策实现这两者结合起来适合大多数偏业务流的智能体场景。建议你先做三件事跑通官方 Graph 示例工程理解节点和状态的关系然后把自己的第一个业务节点接进去比如订单查询或知识库检索最后把流程封装成 REST API接到实际业务入口。最容易踩的坑就是版本 API 变化和状态 Key 不一致动手前先看当前版本的官方 changelog。后续如果要在生产环境大规模使用可以继续补三块引入任务表和异步队列做批量执行、加好日志链路追踪、完善模型 API 限流和降级方案。把这几个点做完一个可控且灵活的生产级 Agent 项目就基本成型了。