企业官网建设流程全解析

1. 为什么我要自己搭一个Agent循环

市面上关于Agent的框架已经多到挑花眼，LangChain、LlamaIndex、AutoGPT各有各的玩法，但真正落到Java后端项目里，能跟Spring生态无缝衔接的方案其实没几个。Spring AI从1.0版本开始提供了ChatClient和ToolCallback的基础能力，但官方文档里关于ReAct循环的完整实现案例少得可怜，大部分示例只停留在“调一次模型、返回一次结果”的层面。这就导致一个很尴尬的局面：你想在现有的Spring Boot项目里加一个能自主决策、多步推理的Agent，翻遍文档发现要么自己从头写循环，要么硬塞一个Python服务进来做胶水层。

我这次的项目目标很明确：在一个标准的Spring Boot 3.x项目里，用Spring AI搭一个显式的ReAct循环Agent，让它能根据用户问题自主决定是否调用工具、调用哪个工具、拿到工具结果后继续推理，直到给出最终答案。整个链路不依赖任何外部Agent框架，纯靠Spring AI的ChatClient加上自己写的循环控制逻辑。这样做的好处是调试链路完全透明，每一步的提示词、模型返回、工具调用记录都能打日志，出了问题不用去翻框架源码猜它到底干了什么。

这篇文章适合已经有Spring Boot基础、了解Spring AI基本用法、想进一步把Agent能力落地到生产项目的后端开发者。如果你还没接触过Spring AI，建议先跑通一个最简单的ChatClient调用再回来看，不然可能会在依赖配置那一步卡住。全文会按照“整体设计思路→核心细节拆解→完整实操过程→常见问题排查”的顺序展开，每个环节都会附上我实际踩过的坑和对应的解决方案。

2. 整体设计思路与方案选型

2.1 为什么选择显式ReAct循环而不是隐式封装

ReAct这个词拆开看就是Reasoning加Acting，核心思想是让模型在每一步先输出思考过程，再决定执行什么动作，拿到动作结果后继续下一轮思考。市面上很多框架把这个循环封装得很深，你只需要注册工具、传一个用户问题进去，框架内部自动帮你跑完整个循环。这种隐式封装在Demo阶段很爽，但到了生产环境就会暴露几个致命问题。

第一个问题是循环控制不透明。框架什么时候决定停止、什么时候继续调用工具、最大循环次数是多少，这些参数往往藏在配置文件的某个角落，出了问题只能靠猜。第二个问题是提示词不可控。隐式封装通常有一套固定的提示词模板，你想根据业务场景微调某句话的措辞，发现根本找不到入口。第三个问题是调试困难。当Agent给出一个错误答案时，你没法快速定位是模型推理错了、工具返回错了、还是循环控制逻辑有bug。

显式ReAct循环就是把这三层全部摊开：提示词我自己拼、循环条件我自己写、每一步的输入输出我自己打日志。代价是代码量会多一些，但换来的是完全的可控性和可观测性。对于一个要上生产的Agent来说，这个交换非常划算。

2.2 Spring AI在这个方案里承担什么角色

Spring AI在这个架构里主要负责三件事：第一是封装底层模型调用，把不同模型提供商的API差异抹平，我只需要调ChatClient.prompt()就能拿到模型返回；第二是提供工具调用的标准化接口，通过ToolCallback把Java方法暴露给模型，模型返回的工具调用请求会被自动解析成方法调用；第三是管理对话上下文，ChatClient内部维护了消息历史，我不用自己拼Message列表。

但Spring AI没有做的一件事是循环控制。它提供了单次调用的能力，但“调用→判断是否需要工具→执行工具→把结果塞回上下文→再次调用”这个循环需要我自己写。这正是显式ReAct循环的核心所在。

2.3 整体架构分层

整个Agent拆成四层：最底层是模型接入层，用Spring AI的ChatClient对接具体模型；往上是工具层，把业务能力封装成ToolCallback；再往上是循环控制层，负责驱动ReAct循环的运转；最上层是接口层，对外暴露一个简单的REST接口接收用户问题。

循环控制层的核心逻辑是一个while循环，每次循环做四件事：把当前消息历史发给模型、解析模型返回、如果返回中包含工具调用请求就执行工具并把结果追加到消息历史、如果返回的是最终答案就跳出循环。循环的终止条件有两个：模型给出了不含工具调用的最终回答，或者达到了预设的最大循环次数。

2.4 关键参数选型与计算依据

最大循环次数这个参数需要根据业务场景来定。我这次做的场景是客服问答类Agent，用户问题通常需要1到3次工具调用就能解决，所以最大循环次数设成5比较合理。设太小会导致复杂问题没处理完就强制终止，设太大又会在模型陷入死循环时浪费大量token。5这个数字的计算逻辑是：正常场景最多3次工具调用，留2次余量应对模型偶尔的多余推理步骤。

超时时间方面，每次模型调用设30秒超时，整个Agent请求设120秒总超时。30秒的依据是主流模型在正常负载下响应时间通常在5到15秒之间，30秒足够覆盖网络抖动和模型排队的情况。120秒总超时的计算是：5次循环乘以每次最多30秒，再留30秒给工具执行和网络传输。

温度参数设成0.1而不是默认的0.7，原因是Agent场景需要模型输出稳定的推理结果，过高的温度会导致同样的输入产生不同的工具调用决策，这在生产环境是不可接受的。0.1的温度能让模型在保持一定灵活性的同时，输出足够稳定的决策。

3. 核心细节解析与实操要点

3.1 消息角色的正确使用方式

ReAct循环里消息角色的使用非常关键，用错了会导致模型行为异常。Spring AI里主要有四种角色：System、User、Assistant、Tool。System消息用来设定Agent的身份和行为规范，只在对话开始时设置一次。User消息是用户输入的问题。Assistant消息是模型的返回，包括它的推理过程和工具调用请求。Tool消息是工具执行的结果，需要关联到具体的工具调用ID。

我踩过的一个坑是：把工具执行结果用User角色塞回消息历史。这样做模型虽然也能处理，但它会把工具结果当成用户说的话，导致后续推理出现混乱。正确的做法是用Tool角色，并且必须带上对应的toolCallId，这样模型才能把工具结果和之前的工具调用请求对应起来。

另一个坑是System消息的位置。Spring AI的ChatClient默认会把System消息放在最前面，但如果你手动拼消息列表，一定要确保System消息在第一条。我试过把System消息放在中间，结果模型完全忽略了里面的行为规范，输出格式乱七八糟。

3.2 工具定义与参数描述的技巧

工具定义的质量直接决定了模型能不能正确调用。Spring AI通过@Tool注解来标记一个方法为可调用工具，注解里的description字段是给模型看的，必须写得足够清晰。我一开始把description写得很简短，比如“查询订单”，结果模型经常在不该调用的时候调用它。后来改成“根据订单号查询订单的详细状态，包括物流信息和预计送达时间，仅在用户明确提供了订单号时调用”，调用准确率明显提升。

工具方法的参数描述同样重要。每个参数都要用@ToolParam注解说明含义和格式要求。比如订单号参数要注明“订单号格式为纯数字，长度12位”，这样模型在提取参数时会更准确。如果参数是枚举类型，最好在描述里列出所有可选值，避免模型传入非法值。

还有一个细节是工具方法的返回值类型。建议统一返回String，把结构化数据转成JSON字符串再返回。这样做的好处是模型对JSON格式的理解比较稳定，而且避免了复杂对象序列化时可能出现的各种问题。如果返回的是Java对象，Spring AI会尝试自动序列化，但遇到循环引用或者复杂泛型时容易出错。

3.3 循环终止条件的精确判断

判断模型返回是否包含工具调用请求，不能简单地检查返回文本里有没有特定关键词。正确的方式是检查ChatResponse里的toolCalls字段是否为空。Spring AI在模型返回工具调用请求时，会把这些请求放在AssistantMessage的toolCalls列表里，同时content字段可能为空或者包含推理文本。

我遇到过一个边界情况：模型在返回最终答案的同时，toolCalls字段里还有一个空的工具调用对象。这种情况如果不处理，循环会继续执行，但执行工具时因为参数为空而报错。解决方案是在判断时同时检查toolCalls是否为空以及每个toolCall的name是否有效。

最大循环次数的判断要放在循环体开头而不是结尾。放在开头的好处是当达到最大次数时，可以直接返回当前已有的推理结果，而不是先执行一次工具再退出。我一开始放在结尾，结果最后一次工具调用的结果被丢弃了，模型基于不完整的信息给出答案，准确率下降明显。

3.4 对话历史的管理策略

随着循环次数增加，消息历史会越来越长，最终可能超出模型的上下文窗口。我采取的策略是保留完整的System消息和最近N轮对话，N的值根据模型上下文窗口大小来定。对于32K上下文窗口的模型，保留最近10轮对话比较安全，每轮按平均500token计算，10轮大约5000token，加上System消息和工具定义，总token数控制在8000以内。

如果业务场景需要更长的记忆，可以考虑对历史消息做摘要压缩。具体做法是在消息历史超过阈值时，调用模型对前面的对话生成一段摘要，然后用摘要替换掉原始消息。这个操作会增加一次模型调用，所以只在必要时触发。

还有一个容易忽略的点是工具调用结果的长度。有些工具返回的数据量很大，比如查询订单返回了完整的物流轨迹，可能有几千个字符。这些内容全部塞进消息历史会快速消耗上下文窗口。我的做法是在工具方法内部对返回结果做截断，只保留模型决策所需的关键信息，比如物流状态和最新一条轨迹，而不是返回全部轨迹。

4. 完整实操过程与核心环节实现

4.1 项目依赖与基础配置

先创建一个标准的Spring Boot 3.x项目，在pom.xml里加入Spring AI的依赖。需要引入的是spring-ai-openai-spring-boot-starter（如果你用的是其他模型提供商，换成对应的starter）。版本方面建议用1.0.0-M5或更高，低版本的一些API还不稳定。

<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> <version>1.0.0-M5</version> </dependency>

application.yml里配置模型接入信息，包括base-url、api-key、model名称。这里要注意的是超时配置，Spring AI默认的超时时间比较短，需要手动调大。

spring: ai: openai: base-url: https://your-model-endpoint/v1 api-key: ${API_KEY} chat: options: model: gpt-4o-mini temperature: 0.1 max-tokens: 2048

温度设成0.1的理由前面已经说过，max-tokens设成2048是因为Agent场景下模型的推理文本通常不会太长，2048足够覆盖大部分情况，同时避免模型生成过多无关内容。

4.2 工具类的定义与注册

创建一个OrderTools类，里面定义两个工具方法：查询订单状态和取消订单。每个方法都用@Tool注解标记，description要写得详细。

@Component public class OrderTools { @Tool(description = "根据订单号查询订单的详细状态，包括物流信息和预计送达时间。仅在用户明确提供了订单号时调用此工具。") public String queryOrderStatus( @ToolParam(description = "订单号，格式为纯数字，长度12位") String orderId) { // 模拟查询逻辑 if (orderId == null || orderId.length() != 12) { return "{\"error\": \"订单号格式不正确\"}"; } return "{\"orderId\": \"" + orderId + "\", \"status\": \"已发货\", \"estimatedDelivery\": \"2025-01-15\"}"; } @Tool(description = "取消指定订单。仅在用户明确表达了取消意图并且提供了订单号时调用。") public String cancelOrder( @ToolParam(description = "订单号，格式为纯数字，长度12位") String orderId) { return "{\"orderId\": \"" + orderId + "\", \"result\": \"取消成功\"}"; } }

工具类定义好之后，在ChatClient的配置里注册这些工具。Spring AI会自动扫描带有@Tool注解的方法，但需要显式地把工具类实例传给ChatClient。

@Configuration public class AgentConfig { @Bean public ChatClient chatClient(ChatClient.Builder builder, OrderTools orderTools) { return builder .defaultSystem("你是一个客服助手，负责处理订单相关问题。你可以调用工具来查询或取消订单。在回答用户之前，先思考是否需要调用工具。如果需要，请明确说明你要调用哪个工具以及为什么。") .defaultTools(orderTools) .build(); } }

System提示词里明确要求模型先思考再行动，这是ReAct模式的关键。如果不加这句话，模型可能会直接给出答案而不调用工具，导致Agent退化成普通的问答机器人。

4.3 循环控制器的核心实现

循环控制器是整个Agent的心脏，我把它写成一个独立的Service类。核心方法接收用户问题字符串，返回最终答案字符串。

@Service public class ReActAgentService { private static final Logger log = LoggerFactory.getLogger(ReActAgentService.class); private static final int MAX_ITERATIONS = 5; private final ChatClient chatClient; public ReActAgentService(ChatClient chatClient) { this.chatClient = chatClient; } public String execute(String userQuestion) { List<Message> messages = new ArrayList<>(); messages.add(new SystemMessage("你是一个客服助手...")); messages.add(new UserMessage(userQuestion)); for (int i = 0; i < MAX_ITERATIONS; i++) { log.info("ReAct循环第{}轮，当前消息数：{}", i + 1, messages.size()); ChatResponse response = chatClient.call( new Prompt(messages) ); AssistantMessage assistantMessage = response.getResult().getOutput(); messages.add(assistantMessage); List<AssistantMessage.ToolCall> toolCalls = assistantMessage.getToolCalls(); if (toolCalls == null || toolCalls.isEmpty()) { log.info("模型给出最终答案，循环结束"); return assistantMessage.getContent(); } for (AssistantMessage.ToolCall toolCall : toolCalls) { log.info("执行工具：{}，参数：{}", toolCall.name(), toolCall.arguments()); String toolResult = executeToolCall(toolCall); messages.add(new ToolResponseMessage( List.of(new ToolResponseMessage.ToolResponse(toolCall.id(), toolCall.name(), toolResult)) )); } } log.warn("达到最大循环次数，返回当前结果"); return "抱歉，处理您的问题需要更多步骤，请稍后再试或联系人工客服。"; } private String executeToolCall(AssistantMessage.ToolCall toolCall) { // 根据toolCall.name()路由到具体的工具方法 // 这里简化处理，实际项目中可以用反射或策略模式 try { ObjectMapper mapper = new ObjectMapper(); JsonNode args = mapper.readTree(toolCall.arguments()); if ("queryOrderStatus".equals(toolCall.name())) { return orderTools.queryOrderStatus(args.get("orderId").asText()); } else if ("cancelOrder".equals(toolCall.name())) { return orderTools.cancelOrder(args.get("orderId").asText()); } return "{\"error\": \"未知工具\"}"; } catch (Exception e) { log.error("工具执行失败", e); return "{\"error\": \"" + e.getMessage() + "\"}"; } } }

这段代码有几个关键点需要展开说明。第一，消息列表的构建方式。我用了一个ArrayList手动管理消息，而不是依赖ChatClient内部的对话记忆。这样做的好处是每次循环的消息历史完全可控，方便打日志和调试。第二，工具执行的路由逻辑。示例里用了简单的if-else，实际项目中建议用策略模式或者Map来管理工具名到执行方法的映射，避免方法多了之后if-else膨胀。第三，ToolResponseMessage的构造。必须带上toolCall.id()，否则模型无法把工具结果和之前的调用请求关联起来。

4.4 接口层与异常处理

对外暴露一个简单的REST接口，接收用户问题，返回Agent的最终答案。

@RestController @RequestMapping("/api/agent") public class AgentController { private final ReActAgentService agentService; public AgentController(ReActAgentService agentService) { this.agentService = agentService; } @PostMapping("/chat") public ResponseEntity<Map<String, String>> chat(@RequestBody Map<String, String> request) { String question = request.get("question"); if (question == null || question.isBlank()) { return ResponseEntity.badRequest().body(Map.of("error", "问题不能为空")); } try { String answer = agentService.execute(question); return ResponseEntity.ok(Map.of("answer", answer)); } catch (Exception e) { log.error("Agent执行异常", e); return ResponseEntity.status(500).body(Map.of("error", "服务暂时不可用")); } } }

异常处理这块要注意的是，不要把模型调用的原始异常直接抛给前端，因为异常信息里可能包含API key或者内部端点地址。统一包装成“服务暂时不可用”这种模糊提示，详细的错误信息打到日志里。

4.5 完整调用链路演示

假设用户问“帮我查一下订单123456789012的状态”，整个链路的执行过程如下。

第一轮循环：消息历史里有System消息和User消息。模型返回Assistant消息，content字段是“我需要查询订单状态，调用queryOrderStatus工具”，toolCalls列表里有一个工具调用请求，name是queryOrderStatus，arguments是{"orderId": "123456789012"}。循环控制器检测到toolCalls非空，执行工具方法，得到结果{"orderId": "123456789012", "status": "已发货", "estimatedDelivery": "2025-01-15"}，把结果用ToolResponseMessage追加到消息历史。

第二轮循环：消息历史里有System、User、Assistant、Tool四条消息。模型基于工具返回的结果生成最终答案，content字段是“您的订单123456789012已发货，预计2025年1月15日送达”，toolCalls为空。循环控制器检测到toolCalls为空，返回最终答案，循环结束。

整个链路两次模型调用、一次工具调用，总耗时大约8到12秒，取决于模型响应速度。

5. 常见问题与排查技巧实录

5.1 模型不调用工具直接回答

这是最常见的问题，表现是用户问了一个需要查订单的问题，模型直接编了一个答案返回，完全没有调用工具。原因通常有三个：System提示词没有明确要求先思考再行动、工具description写得太模糊导致模型不知道什么时候该调用、温度参数太高导致模型行为不稳定。

排查步骤：先检查System提示词里有没有“先思考是否需要调用工具”这类引导语；再检查工具description是否清晰说明了调用场景；最后把温度降到0.1再试。如果三个都排查了还是不行，可以在User消息里加一句“请先查询订单状态再回答”，强制引导模型调用工具。

5.2 工具调用参数解析失败

模型返回的工具调用参数格式不对，导致JSON解析报错。常见的情况是模型把数字类型的订单号加上了引号变成字符串，或者参数名拼写错误。解决方案是在工具方法的参数描述里明确格式要求，比如“订单号为纯数字，不要加引号”。如果模型仍然传错，可以在executeToolCall方法里加一层容错处理，比如尝试把字符串转成数字再解析。

5.3 循环次数达到上限仍未给出答案

这种情况通常发生在问题比较复杂、需要多次工具调用的场景。排查思路是看日志里每一轮的工具调用记录，判断是模型在重复调用同一个工具（说明工具返回的结果没有满足模型的需求），还是模型在反复推理但不调用工具（说明提示词可能让模型陷入了某种循环）。

如果是重复调用同一个工具，检查工具返回的结果是否包含了模型需要的信息。比如模型查订单状态，工具只返回了“已发货”，模型可能觉得信息不够又查了一次。这时候需要在工具返回里加上更多细节，比如物流轨迹和预计送达时间。

如果是模型反复推理不调用工具，检查System提示词里有没有“如果信息足够就给出最终答案”这类终止引导语。没有的话模型可能会一直推理下去。

5.4 消息历史过长导致上下文溢出

当循环次数较多或者工具返回结果很大时，消息历史可能超出模型上下文窗口，表现为模型调用返回400错误，提示token超限。解决方案有两个：一是限制工具返回结果的长度，在工具方法内部做截断；二是限制消息历史的长度，只保留最近N轮对话。

我采用的是一个组合策略：工具返回结果超过500字符时自动截断，消息历史超过10轮时丢弃最早的对话（保留System消息）。这样能把总token数控制在一个安全范围内。

5.5 常见问题速查表

5.6 几个我踩过的坑

第一个坑是ToolResponseMessage的构造。我一开始只传了工具返回的内容，没有传toolCallId，结果模型完全忽略了工具结果，继续按自己的推理走。后来查了Spring AI的源码才发现，ToolResponseMessage必须带上toolCallId才能和之前的工具调用请求关联起来。

第二个坑是System消息的重复添加。我在循环里每次都往消息列表里加一条System消息，导致消息历史里有多条System消息，模型的行为变得很不稳定。正确的做法是System消息只在初始化时添加一次。

第三个坑是工具方法的线程安全。如果工具方法里用了成员变量来暂存状态，在多线程环境下会出现数据错乱。解决方案是工具方法尽量设计成无状态的，所有需要的数据都通过参数传入，需要返回的数据都通过返回值传出。

第四个坑是日志打印的粒度。一开始我把每一轮的消息历史完整打印出来，日志量巨大，排查问题时反而被淹没。后来改成只打印关键信息：当前轮次、模型返回的content摘要、工具调用名称和参数、工具返回结果摘要。这样日志量减少了80%，排查效率反而提高了。

6. 性能优化与扩展方向

6.1 减少不必要的模型调用

每次循环都会调用一次模型，这是整个链路里最耗时的环节。一个优化思路是在工具执行后，如果工具返回的结果已经足够回答用户问题，可以直接返回结果而不需要再调一次模型。判断逻辑可以写在循环控制器里：如果当前轮次只有一个工具调用且工具返回结果里包含了明确的答案字段，就直接返回。

但这个优化要谨慎使用，因为有些场景下模型需要对工具返回的结果做二次加工才能给出自然语言回答。我的做法是加一个配置开关，默认关闭这个优化，在特定场景下手动开启。

6.2 工具调用的并行执行

当模型在一轮里返回多个工具调用请求时，这些工具调用之间通常没有依赖关系，可以并行执行。Spring AI的ToolCallback接口本身不提供并行执行能力，但可以在循环控制器里用CompletableFuture来并行调用多个工具方法。

并行执行的收益取决于工具方法的耗时。如果工具方法是纯内存计算，并行收益不大；如果工具方法涉及数据库查询或远程调用，并行执行能显著缩短总耗时。我实测下来，两个各耗时200毫秒的工具调用，串行执行400毫秒，并行执行大约220毫秒。

6.3 对话记忆的持久化

当前实现里消息历史是存在内存里的，请求结束后就丢失了。如果要做多轮对话，需要把消息历史持久化到数据库或Redis里。持久化的关键是用一个sessionId来标识同一个用户的对话，每次请求时根据sessionId加载历史消息，请求结束后把更新后的消息历史存回去。

存储格式建议用JSON，把Message对象序列化成JSON字符串存储。反序列化时需要注意消息类型的区分，System、User、Assistant、Tool四种类型要能正确还原。

6.4 监控与告警

生产环境里需要监控几个关键指标：每次Agent请求的循环次数、总耗时、工具调用成功率、模型调用失败率。这些指标可以用Micrometer打点到Prometheus，然后在Grafana里做可视化。

告警规则建议设置两条：循环次数超过4次的请求占比超过10%时告警，说明提示词或工具设计可能有问题；模型调用失败率超过5%时告警，说明模型服务可能不稳定。

6.5 多模型切换的支持

Spring AI的一大优势是模型接入层的抽象做得比较好，切换模型提供商只需要改配置文件和依赖。但在Agent场景下，不同模型对工具调用的支持程度不一样，有些模型对ReAct模式的理解更好，有些模型在工具调用参数提取上更容易出错。

我的做法是在配置里加一个模型类型标识，在循环控制器里根据模型类型微调提示词。比如对工具调用能力较弱的模型，在System提示词里加更多的引导语和示例；对工具调用能力较强的模型，提示词可以写得更简洁。

7. 一些个人体会

这套显式ReAct循环的代码量其实不大，核心逻辑加起来不到200行，但调试过程中花的时间远超预期。最大的感受是Agent的行为高度依赖提示词的质量，同样的代码换个提示词，效果可能天差地别。我建议在提示词上多花时间迭代，每次调整后跑一组固定的测试用例，对比工具调用准确率和最终答案质量。

另一个体会是日志的重要性。Agent的调试不像普通接口那样看输入输出就能定位问题，你需要看到每一轮的推理过程、工具调用决策、工具返回结果。我在项目初期就加上了详细的日志，后面排查问题时省了很多时间。如果你准备在生产环境跑Agent，日志系统一定要提前规划好。

最后分享一个小技巧：在System提示词里加上“如果你不确定是否需要调用工具，先调用工具获取信息再判断”这句话，能显著减少模型该调用工具却不调用的概率。这个技巧在多个模型上都验证过，效果比较稳定。