最近总有 Java 后端朋友问我一个很现实的问题写了五年 Java想在项目里接入大模型、做一个真正的 AI Agent是不是必须转 Python我的回答是不一定。调用大模型 API 本身对 Java 开发者来说毫无门槛真正让团队卡住的是 Agent 里那个反反复复的执行循环——“模型思考一步 → 调用一个工具 → 看到工具结果 → 再思考下一步”这个过程能不能被控制、被调试、被终止、被观测。本文以 Spring AI Alibaba Graph 为主线把 ReAct、Loop、Graph Engineering 三件事串起来讲ReAct 解决“模型怎么行动”Loop 解决“任务怎么多步推进”Graph 解决“流程怎么工程化”。我会从最基础的模型调用写起再手写一个 ReAct 循环最后用图编排重构同一个 Agent让它从“只能聊”变成“会查数据、能多次调用工具、可终止、可观测”的生产雏形。读完你可以回答三个问题Java 做 Agent 到底行不行、图编排比手写循环强在哪、自己项目里应该怎么接入。省流结论放在前面Java 做 AI Agent 的工程化能力在 Spring AI 和 Spring AI Alibaba 出现之后已经被补齐。真正需要投入理解的不是大模型 API而是循环控制与图编排。1. 这篇文章真正要解决的问题1.1 为什么 Java 开发者做 Agent 不能靠“单次问答”大模型做单次问答很简单用户提问接口返回答案。但 Agent 不是单次问答。举一个最常见的业务场景用户问“帮我查一下订单 O20250101 的物流状态”模型本身不知道你数据库里的订单数据它必须先调用你业务系统的接口拿到结果再组织最终回答。问题在于这个“调用接口”的动作往往不止一次。真实任务里模型可能要查订单、查物流、查退款状态、计算差价甚至要连续调用多个工具才能回答一个简单问题。于是你必须写一个循环让模型输出“我想调用哪个工具”程序执行工具把结果回传给模型模型再决定下一步。这个循环才是 Agent 和聊天机器人的本质区别。很多 Java 团队在这里犯了两个错误错误一把 Agent 当成一次问答调用大模型后直接返回工具调用根本走不通。错误二把 Agent 写成一个巨大的方法里面堆满 if/else 处理各种分支。第一种做法做不出真 Agent第二种做法在三个工具时还能撑十个工具时就完全失控。1.2 本文的核心判断Java 侧做 Agent 的技术栈已经成熟Spring AI 负责统一接入大模型Spring AI Alibaba Graph 负责流程的图编排。所以本文的核心判断是Java Agent 工程化的分水岭不在模型而在循环控制和图编排。谁能先把循环控制住谁就能把 Agent 从 demo 带向生产。1.3 哪些读者最适合看这篇文章正在公司 Java 项目中落地 AI 功能的后端开发对 LangGraph 有兴趣但不想因此换语言或重建一套技术栈已经用 Spring AI 做过简单问答想升级为真正的 Agent 团队想搞清楚 ReAct、Loop、Graph Engineering 到底是什么关系的读者。2. 先搞清楚ReAct、Loop、Graph Engineering 分别是什么2.1 ReAct让模型“想一步做一步”ReAct 来自论文《ReAct: Synergizing Reasoning and Acting in Language Models》。它的核心思想是让 LLM 在“推理”和“行动”之间交替模型先输出推理Thought再决定动作Action执行后看到结果Observation再进入下一轮推理。通俗理解ReAct 就像一个做事谨慎的新同事你问他一个问题他不会直接编答案而是先想“我需要什么数据”接着去查资料看完资料再回答。这个“查资料”的动作在代码里就是工具调用。需要注意一个关键点大模型本身不执行工具。模型只是输出一段结构化的“我想调用某个工具参数是什么”的意图真正的执行必须由 Java 程序完成。很多初学者把“工具调用”理解成“模型去调接口”这是错的。2.2 LoopAgent 不能没有循环为什么必须要有 Loop因为真实任务不能一步到位。还是订单查询的例子用户不提供订单号模型需要先调用“查找用户订单列表”工具拿到订单号后再调用“查询物流状态”工具。一次工具调用解决不了问题。写循环本身不难难的是循环的终止条件。一个生产级 Agent 至少需要四种终止方式模型判断已有足够信息输出最终回答达到最大循环轮数token 消耗或成本超过预算阈值用户主动中断任务。其中最容易踩坑的是只设最大轮数却不处理“工具调用一直失败、模型反复重试”的情况。结果是 Agent 空转成本一直涨问题却没有收敛。2.3 Graph Engineering把流程从代码变成图当工具超过十个流程出现大量分支时你不可能再靠一个大方法里的 if/else 维护逻辑。Graph Engineering 提供的是另一种抽象把做事的每一步定义成“节点”Node把节点之间的流转关系定义成“边”Edge把“下一步走哪里”定义成“条件边”Conditional Edge。图编排不是把代码变得更花哨而是把不可见的流程变得可见。每个节点是原子操作每条边是流转关系每个条件边是决策逻辑。这样的好处是流程一目了然评审和交接都容易节点可以单独测试和复用出问题能快速定位到具体环节配合状态快照可以做审计和回放。类比一下手写循环像在陌生城市来回问路图编排像拿到了导航地图每个路口都清晰标注。2.4 三个概念的关系ReAct 是思想告诉模型应该“先想再做”。Loop 是执行层面必然出现的结果模型必须反复进入“推理→行动→观察”的循环。Graph Engineering 是工程手段让这个循环可控、可视化、可维护。没有 ReAct模型不会主动调工具没有 LoopAgent 做不了多步任务没有 Graph Engineering复杂 Agent 会变成一堆不可维护的脚本。3. Java 生态做 AI Agent 的方案选型3.1 当前可用的四条路线Java 生态做 AI Agent目前没有标准答案但可选路线已经比较清晰方案模型接入Agent 编排能力适合场景直接 HTTP 调用手写无快速验证、不想引入框架Spring AI统一抽象基础调用已有 Spring Boot 项目想标准化接入Spring AI Alibaba统一抽象 增强图编排引擎需要可控、可观测的复杂 Agent 流程LangChain4j有抽象能力AI Service / 链式调用喜欢链式调用不依赖 Spring 容器如果你只是为了快速验证模型效果直接 HTTP 调用也可以。但如果要把 Agent 当核心业务模块长期维护我更推荐走 Spring AI 或 Spring AI Alibaba 路线。3.2 为什么更关注 Spring AI Alibaba GraphSpring AI Alibaba 是阿里开源的 Spring AI 增强方案它对标 LangGraph 的思路在 Java 侧提供了图编排能力。关注它的原因有三个第一和 Spring 技术栈融合好。配置、日志、Metrics、配置中心都可以沿用 Spring Boot 的标准方式团队上手成本低。第二图编排能力在 Java 生态里相对稀缺。在没有这个框架之前Java 开发者要么手写循环控制要么去维护一套自己设计的流程引擎工程成本很高。第三它的社区迭代快中文资料也越来越多。需要提醒的是版本迭代快意味着 API 可能频繁变化。所以阅读官方文档时要以你引入的版本为准不要死记某一个版本的写法。3.3 什么时候不要用图编排图编排不是银弹。如果你的业务流程是固定顺序比如 A 到 B 到 C 永远不变直接方法调用比图更简单。如果你只接一个工具比如做一个关键词回复机器人也用不上图。如果团队里还没有人真正理解循环和终止条件先补概念再上框架。判断标准很朴素当分支和回环开始让你觉得“代码维护不住了”再引入图编排。4. 环境准备与前置条件4.1 环境清单本文示例使用 Java 和 Spring Boot环境要求如下JDK 17 或更高版本Maven 3.6 或 GradleSpring Boot 3.x注意与 Spring AI 版本匹配一个可用的模型 API 服务本文使用 OpenAI 兼容接口的通用配置方式网络能访问模型服务。如果你的网络环境无法访问外部模型服务也可以换成通义千问等国内模型服务配置方式类似。本文重点是工程结构不绑定具体模型厂商。4.2 创建项目与引入依赖创建一个普通的 Spring Boot 项目在pom.xml中引入 Spring AI 相关依赖。版本号建议通过 BOM 统一管理不要每个依赖手写不同版本。!-- 文件路径pom.xml -- properties java.version17/java.version spring-ai.version请使用当前稳定的Spring AI版本/spring-ai.version /properties dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-spring-boot-starter/artifactId /dependency dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-graph-spring-boot-starter/artifactId /dependency /dependencies注意spring-ai-alibaba-graph-spring-boot-starter的坐标以你当前使用的 Spring AI Alibaba 版本为准。如果找不到该坐标可以去官方仓库查看当前推荐引入方式。图中编排相关 API 也可能会随版本调整。4.3 配置文件示例在application.yml中配置模型接入信息。这里以 OpenAI 兼容接口为例# 文件路径src/main/resources/application.yml spring: ai: openai: base-url: https://your-model-service.example.com/v1 api-key: ${LLM_API_KEY} chat: options: model: your-model-name temperature: 0.7需要强调的是api-key不要写死在配置文件里推荐通过环境变量注入。本文所有配置都以你的模型服务商实际文档为准。5. Spring AI Alibaba Graph 核心概念5.1 核心抽象图编排虽然听起来高级但核心概念并不多。理解下面这张表就理解了 80% 的图引擎概念作用StateGraph定义整张图的结构负责添加节点和边Node一个原子操作输入一个状态输出一个新状态Edge两个节点之间的连接关系ConditionalEdge条件边根据当前状态决定下一步走哪条边State在整个图中流动的上下文对象关键点是 State。在 Agent 循环里消息历史、工具结果、当前轮数、最终答案都应该放在 State 里而不是散落在局部变量或全局变量中。Graph 框架做的事情本质上是让 State 在节点间按图的定义流动。5.2 用表格理解一个 ReAct Graph下面是我们后面要实现的 Graph 结构。它包含四个节点正好对应 ReAct 循环节点名职责默认出边start图起点进入 agentagent调用大模型生成回复或工具调用意图进入 routeroute根据工具调用意图决定下一步进入 tools 或 endtools执行工具把结果写回 State回到 agentend结束流程返回最终状态无可以想象这个图里面有一个从tools回到agent的回路。这就是 ReAct 循环在 Graph 上的体现模型先推理再调工具看到工具结果后再推理直到 route 判断不需要调用工具走end结束。5.3 普通调用与图编排的本质差别普通 Spring AI 调用是“一次请求一次响应”消息列表在方法内手动维护每次调用前自己拼接上下文。图编排则不同状态贯穿整张图每个节点从 State 读取数据、处理后写回 State天然支持回环和分支。从工程视角看这两者的差别不在于功能而在于可控性。图编排让“流程”成为可以被设计和评审的对象而不是藏在代码逻辑里的一团隐式状态。6. 完整示例从基础调用到 ReAct 循环再到 Graph 工程化6.1 示例 1用 ChatClient 跑通一次大模型调用先写一个最基础的 Controller用 Spring AI 的 ChatClient 完成一次对话。这个例子能跑通之后再往 Agent 方向迭代。// 文件路径src/main/java/com/example/agent/controller/ChatController.java package com.example.agent.controller; import org.springframework.ai.chat.client.ChatClient; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder chatClientBuilder) { this.chatClient chatClientBuilder.build(); } GetMapping(/chat) public String chat(RequestParam String message) { return chatClient.prompt() .system(你是一个Java后端开发助手回答简洁、准确。) .user(message) .call() .content(); } }启动应用后访问/chat?message什么是ReAct就能拿到模型回答。这个例子说明Java 接入大模型确实不难。6.2 示例 2让模型调用业务工具在上面的基础上我们注册一个查询订单状态的工具。Spring AI 支持通过注解定义工具。// 文件路径src/main/java/com/example/agent/tool/OrderTools.java package com.example.agent.tool; import org.springframework.ai.tool.annotation.Tool; import org.springframework.stereotype.Component; Component public class OrderTools { Tool(根据订单号查询订单当前状态) public String getOrderStatus(String orderId) { // 真实项目里这里会调订单服务 return 订单号 orderId 的当前状态为已发货; } }然后修改 ChatController通过.tools(...)把工具挂到调用上chatClient.prompt() .user(帮我查一下订单 O20250101 的状态) .tools(new OrderTools()) .call() .content();此刻模型已经具备“调用工具”的能力。但注意这仍然是一次调用不是 Agent。如果模型第一次没拿到足够信息它就不知道该继续调什么。接下来就是 Loop 的职责。6.3 示例 3手动实现一个 ReAct 循环为了理解 Agent 的本质我们先不急着用图编排而是手写一个循环骨架。下面的代码用一个抽象网关ModelGateway屏蔽了不同版本 Spring AI 的 API 差异核心目的是展示循环结构。// 文件路径src/main/java/com/example/agent/core/ReActLoopAgent.java package com.example.agent.core; import java.util.ArrayList; import java.util.List; /** * 手动实现的 ReAct 循环骨架。 * 不同版本的 Spring AI 在消息类型、工具调用解析上的API略有差异 * 建议把模型调用、工具调用解析、工具执行分别封装成独立方法。 */ public class ReActLoopAgent { // 最大轮数防止模型一直调用工具无法收敛 private static final int MAX_TURNS 6; private final ModelGateway modelGateway; private final ToolRegistry toolRegistry; public ReActLoopAgent(ModelGateway modelGateway, ToolRegistry toolRegistry) { this.modelGateway modelGateway; this.toolRegistry toolRegistry; } public String run(String userInput) { // 消息历史是整个循环的“记忆”每一轮都在追加 ListChatMessage messages new ArrayList(); messages.add(new ChatMessage(system, 你是企业级Agent需要实时数据时必须调用工具。)); messages.add(new ChatMessage(user, userInput)); for (int turn 0; turn MAX_TURNS; turn) { ModelResponse response modelGateway.call(messages); // 关键分歧点模型有没有返回工具调用意图 ListToolInvocation invocations extractToolInvocations(response); if (invocations.isEmpty()) { // 没有工具调用说明模型已经具备足够信息回复 return response.content(); } // 有工具调用先追加模型的消息再逐条执行工具 messages.add(new ChatMessage(assistant, response.content(), invocations)); for (ToolInvocation invocation : invocations) { String toolResult toolRegistry.execute(invocation.toolName(), invocation.arguments()); messages.add(new ChatMessage(tool, toolResult, invocation.id())); } } // 循环上限不是业务结束而是保护措施 throw new IllegalStateException(Agent超过最大轮数仍未收敛请检查路由逻辑或终止条件); } private ListToolInvocation extractToolInvocations(ModelResponse response) { // 以Spring AI为例模型的响应中会携带工具调用列表。 // 不同版本字段名略有差异建议封装成独立方法并编写单元测试。 return response.toolCalls(); } }这个循环骨架解决了三个问题多轮工具调用、终止条件、工具结果回传。它的问题也很明显逻辑全部挤在一个类里分支一多就失去控制。这正是 Graph Engineering 要解决的。作为配套下面是一个简单的工具注册表实现。真实项目里可以在这个基础上做参数校验、权限控制和超时管理。// 文件路径src/main/java/com/example/agent/core/ToolRegistry.java package com.example.agent.core; import java.time.LocalTime; import java.util.HashMap; import java.util.Map; import java.util.function.Function; public class ToolRegistry { private final MapString, FunctionString, String tools new HashMap(); public ToolRegistry() { tools.put(get_current_time, arguments - 当前时间 LocalTime.now()); tools.put(get_order_status, arguments - 订单 arguments 状态已发货); } public String execute(String toolName, String arguments) { FunctionString, String tool tools.get(toolName); if (tool null) { throw new IllegalArgumentException(未知工具 toolName); } return tool.apply(arguments); } }注意这个ToolRegistry是简化版本。生产环境里工具执行不应该传原始字符串参数而应该传入结构化的 JSON 参数并做好类型校验。6.4 示例 4用 StateGraph 编排同一个 Agent接下来用 Spring AI Alibaba Graph 的思路把上面的循环改造成图。下面代码展示的是核心结构不同版本 API 名称可能略有差异但“StateGraph Node ConditionalEdge State” 这套结构是通用的。先定义状态类。Agent 运行过程中的所有上下文都放在 State 里// 文件路径src/main/java/com/example/agent/graph/AgentState.java package com.example.agent.graph; import java.util.List; public class AgentState { private ListMessage messages; private String toolResult; private int turn; private String finalAnswer; public AgentState(ListMessage messages) { this.messages messages; this.turn 0; } public ListMessage getMessages() { return messages; } public void setMessages(ListMessage messages) { this.messages messages; } public String getToolResult() { return toolResult; } public void setToolResult(String toolResult) { this.toolResult toolResult; } public int getTurn() { return turn; } public void setTurn(int turn) { this.turn turn; } public String getFinalAnswer() { return finalAnswer; } public void setFinalAnswer(String finalAnswer) { this.finalAnswer finalAnswer; } public boolean shouldCallTool() { // 实际实现中根据模型响应判断是否需要继续调用工具 return toolResult null turn 6; } }再定义三个节点AgentNode 负责调用模型RouteNode 负责判断走哪条边ToolNode 负责执行工具。// 文件路径src/main/java/com/example/agent/graph/GraphAgent.java package com.example.agent.graph; import java.util.List; /** * 图编排版Agent。 * 说明Node/StateGraph 等 API 在不同版本的 Spring AI Alibaba 中可能有差异 * 本文展示的是通用结构目的是帮助你建立图编排的心智模型。 */ public class GraphAgent { public AgentState buildAndRun(ListMessage initialMessages) { // 1. 创建图指定状态类型 StateGraphAgentState graph new StateGraph(AgentState.class); // 2. 添加节点 graph.addNode(agent, state - { // 调用大模型生成回复或工具调用意图 // 模拟一次模型调用 state.setTurn(state.getTurn() 1); return state; }); graph.addNode(tools, state - { // 执行工具把结果写回状态 state.setToolResult(工具执行结果); return state; }); // 3. 添加边 graph.addEdge(start, agent); // 4. 添加条件边agent 节点执行完后根据状态决定走 tools 还是 end graph.addConditionalEdge( agent, state - state.shouldCallTool() ? tools : end ); // 5. 工具执行完后回到 agent形成 ReAct 循环回路 graph.addEdge(tools, agent); // 6. 编译并执行 CompiledGraphAgentState compiledGraph graph.compile(); AgentState initialState new AgentState(initialMessages); return compiledGraph.invoke(initialState); } }上面这段代码中的graph.addNode(agent, state - {...})使用了 Lambda 表达式来定义节点的行为。实际框架中节点通常需要实现一个Node接口Lambda 写法方便演示核心含义相同。图中形成的回路是start - agent - route条件边 - tools - agent - ... - end。这就是 ReAct 循环在图中的表现。相比手写循环图编排的优势在于路由条件是明显的节点工具执行是独立节点每个环节都能单独测试。7. 运行结果与效果验证7.1 运行方式编译并启动项目mvn clean package -DskipTests mvn spring-boot:run如果是手动 ReAct 版本你可以写一个简单的 CommandLineRunner 调用ReActLoopAgent.run(现在几点了)。如果是 Graph 版本观察图执行完成后AgentState.finalAnswer的值。7.2 预期交互过程以“现在几点了”这个任务为例一个正常的 ReAct Agent 执行过程应该是轮次模型返回内容程序动作状态变化1调用工具 get_current_time执行工具toolResult 当前时间2基于工具结果输出最终回答结束循环finalAnswer 当前时间从日志里你应该看到两次模型调用记录第一次请求带了工具定义模型返回工具调用意图第二次请求携带了工具结果模型返回最终答案。如果只看到一次模型调用就返回了说明工具调用没有被触发优先检查模型是否支持 function calling以及工具定义是否正确。7.3 如何判断 Agent 是否正常工作判断标准不是“回答对不对”而是以下几件事是否全部成立模型确实产生了工具调用意图而不是直接猜答案程序确实执行了真实工具并把结果放回消息上下文循环在模型拿到足够信息后主动终止而不是等轮数耗尽最终回答引用了工具结果而不是凭空生成。如果最后一条不满足说明工具结果虽然返回了但没有被模型正确使用。常见原因是消息结构组装错误或者工具结果没有以正确格式拼接回消息列表。8. 常见问题与排查思路下面这张表总结了 Java 侧实现 ReAct Agent 时最高频的问题问题现象可能原因排查方式解决方案报 401/403 错误API Key 不对或模型服务不可达先用 curl 单独测试模型接口检查 Key、endpoint、网络连通性模型一直不调用工具所用模型不支持 function calling或工具定义格式有误查看响应中 toolCalls 是否为空换成支持工具调用的模型检查工具描述Agent 进入死循环模型反复调用工具但终止条件不生效打印每一轮的工具调用日志设置最大轮数增加收敛判断工具结果没有影响最终回答工具结果没有正确追加进消息列表打印追加后的完整消息历史将工具结果作为新消息加入上下文Graph 执行结果为空初始状态没有注入必要消息打印 StateSnapshot 或初始 State初始化消息列表并传入 Graph运行报 API 方法找不到Spring AI 或 Spring AI Alibaba 版本与示例不一致查看官方文档和 Maven 依赖树统一升级到兼容版本以官方示例为准排查 Agent 问题有一个通用顺序先确认模型接口通再确认工具能执行再确认工具结果回传最后确认循环终止条件。按这个顺序排查能省大量时间。9. 最佳实践与工程建议9.1 状态管理规范图的每个节点都应该只通过 State 交流数据。不要在节点之间用静态变量或者全局 Map 传递信息。原因很简单State 是图可观测的基础也是审计和回放的基础。如果状态散落在外部变量里Graph 的优势就丧失了。建议把 State 设计成不可变对象每次节点处理都返回新对象或者至少保证 State 的字段更新有明确日志。生产环境中在关键节点前后打印 StateSnapshot是排查 Agent 问题最有效的手段。9.2 节点设计规范每个节点只做一件事AgentNode 只负责模型交互ToolNode 只负责工具执行RouteNode 只负责路由判断。命名使用动词短语例如query_order_status、calculate_refund不要用do_something这种语义模糊的名字。节点之间要低耦合。判断一个节点是否合格就看你能不能脱离整张图单独测试它。如果你发现某个节点里既调模型又调工具还做了路由请拆开。9.3 可观测性与成本控制Agent 的成本比单次问答高得多。建议在工程上做三件事记录每次模型调用的 token 消耗和耗时为循环设置轮数和预算双重上限对工具调用做超时和失败重试控制。如果 Agent 会被外部用户频繁调用强烈建议增加一层缓存相同任务在指定时间窗口内直接返回历史结果避免重复调用模型。9.4 安全底线工具调用本质上暴露了业务系统接口安全问题必须前置工具参数必须做类型校验和白名单校验工具执行前要做权限检查不能让模型任意调用高危接口不要把数据库连接信息、内部接口地址直接暴露给模型模型提示词中不要拼接未经处理的用户输入防止提示词注入生产环境的模型 API Key 必须通过环境变量或密钥管理服务注入不能提交到代码仓库。9.5 版本管理Spring AI 和 Spring AI Alibaba 的迭代速度非常快Agent 图 API 也可能随版本调整。建议在项目中通过 BOM 锁定版本升级前先阅读官方 CHANGELOG并准备一套回归测试用例。Agent 类代码的回归测试最好包含“模型返回工具调用”“模型直接回答”“工具执行异常”“循环超过上限”四类场景。结束语真正想把 Agent 落到生产不是背几个 Graph API而是把 Agent 当成一个有状态的服务来设计消息是状态工具是能力循环是流程图是控制面。Java 生态不缺技术栈缺的是对 Agent 工程的正确理解。建议你先跑通示例 1再动手实现一个最简单的 ReAct 循环最后用图编排重构。当你把一个自己业务里的真实工具挂到图上之后对 Agent 工程化的理解会和只看文章完全不同。接下来的方向可以是把图里的节点拆成独立服务接入消息队列做异步化也可以继续研究多 Agent 协作、子图复用、人机回环等更复杂的编排方式。这套思路值得你花时间深入。
