Spring Boot + Spring AI 打造生产级 Java AI Agent 全栈实践

做 Java 后端的同学们，最近是不是有点焦虑？看着身边同行用 Python 把 AI Agent 玩出花，自己手头的 Spring Boot 项目似乎离"智能"很远。别急，这段时间我一直在折腾一个项目：Java 版 Personal Agent，基于 Spring Boot + Spring AI 全栈开源。项目完整地实现了从零搭建一个生产级个人助手，不只是跑通 Demo，而是把连接池、重试、持久化、流式输出这些后端的看家本领，全跟 AI 应用结合了起来。

这个项目做完之后我最大的感受是：Java 生态做 AI Agent 完全可行，而且 Spring AI 的抽象设计让这套系统的工程质量和可维护性，比很多临时拼凑的 Python 脚本高出不少。这篇文章就把整个项目的设计思路、核心实现、生产化细节全榨干了摊开给你看，从架构选型到代码实现，从流式输出到并发控制，再到我实际踩过的几个坑，新手可以直接照着抄，有点经验的朋友也可以对比一下自己的方案。

1. 整体设计与思路拆解：为什么是 Spring AI，Agent 的骨架长什么样

1.1 先说结论：为什么用 Spring Boot + Spring AI 而不是 LangChain

很多 Java 开发者看到 AI 应用，第一反应是：那我直接调 HTTP 接口不就行了，为什么要引入 Spring AI 这个框架？这个问题我也纠结过。真正开始设计这个 Personal Agent 的时候，我列了一下需求：对话管理、工具调用、持久化记忆、多模型切换、流式输出、并发控制。如果用原生 HTTP 客户端去调大模型接口，这些需求全都要自己造轮子，而且每个模型厂商的接口格式还不一样，后期维护是噩梦。

Spring AI 的优势在于它做了几层非常关键的抽象。第一层是 ChatClient，把不同厂商的 Chat API 统一成一个接口，我换模型厂商只需要改配置，业务代码一动不用动。第二层是 Tool Calling 机制，它把 Java 方法的参数自动序列化成模型需要的 JSON Schema，模型返回的工具调用参数又自动反序列化成 Java 对象，类型安全这一块比 Python 系框架都要强。第三层是 Advisor 机制，它类似于 Spring AOP 在 AI 链路上的应用，可以在消息发送前、返回后插入各种处理逻辑。

我这套架构选型其实还有一个很实际的理由：项目要对接现有的业务系统，比如日历、邮件、待办事项这些工具，这些都是典型的 Java 服务。用 Spring Boot 可以非常自然地把这些能力注册成 Agent 的工具，而 Spring AI 天然兼容这种 Spring 家族的配置方式和生命周期管理。如果是纯 Python 方案，在 Java 体系里反而成了二等公民。

1.2 Agent 的整体架构：从用户对话到工具执行的完整链路

先拿出一张我项目里的模块划分，这是我在需求分析阶段就该想明白的：

处理一条用户消息的完整链路是这样的：用户发送消息到 Web 层，这个请求会被封装成一个 UserMessage 对象，带上会话 ID。Agent 编排层拿到消息后，会根据会话 ID 从记忆管理层拉取历史消息，拼装成完整的消息列表，然后调用 ChatClient。模型如果认为需要调用工具，返回的响应里会带工具调用 ID 和参数 JSON。编排层解析之后，根据工具名去注册表找到对应的 Java 方法，反射调用并拿到结果，再把结果作为工具响应消息回传给模型，让模型继续推断，这个循环一直到模型不再请求工具为止。

这个设计本质上是把 Agent 的推理循环显式地做成了代码。一开始我想过用完全自动化的方式，就是让模型自己决定什么时候结束，但后来发现对于生产系统，必须有一个可控的外层循环，否则完全不可观测，也容易出现死循环。所以我在编排层设置了一个最大迭代次数，默认是 5 次，超过就强制终止，这个参数在下文的生产化细节会详细说。

2. 核心细节解析与实操要点：工具调用、上下文管理、流式输出逐个击破

2.1 工具调用（Function Calling）的正确打开方式

工具调用是整个 Agent 的灵魂，也是新手最容易写崩的地方。Spring AI 里注册一个工具非常简单，只需要在一个 Bean 方法上加上 @Tool 注解：

@Component public class TodoToolService { @Tool(description = "创建一条新的待办事项，参数 title 是必填项，dueDate 使用 yyyy-MM-dd 格式") public String createTodoItem(String title, @ToolParam("yyyy-MM-dd") String dueDate) { TodoItem item = todoService.add(title, dueDate); return "创建成功: " + item.getId(); } }

就这么简单，Spring AI 会在启动时扫描所有带 @Tool 注解的方法，把方法名、参数描述、格式要求都生成成 JSON Schema，显式注册到模型接口的 tools 参数里。

不过这里有一个非常关键的坑：工具的描述信息决定了模型能不能正确调用它。我发现模型对工具的描述理解能力参差不齐，写得太宽泛就会经常出现参数瞎传的情况。比如"创建待办"和"创建一条待办事项，title 为必填字符串，dueDate 可选日期，格式为 yyyy-MM-dd，如果用户说'明天'要换算成具体日期"效果完全不同。前一种模型经常把日期格式传错，后一种基本很少出错。所以封装工具的时候，我养成了一个习惯：用一小段话把参数格式、边界条件、默认值处理都写清楚，这比模型每次都能聪明地理解你的意图可靠得多。

还有模型的 JSON 输出稳定性问题，Spring AI 已经帮我解决了很大一部分，它内部对工具调用的响应做了解析，如果模型给出了非法 JSON，会通过格式修正机制自动重新往模型里发一次提示。但在生产环境，我仍然建议对这个过程做一个兜底：捕获解析异常，主动返回一条工具错误信息，而不是让整个对话栈崩掉。

2.2 上下文管理：不是把所有历史都塞给模型

做过几轮 Agent 对话的人都会发现，直接把所有历史消息一股脑传给模型，很快 token 就不够用了，反应也越来越慢。我在这套项目里做了两层记忆管理。

第一层是短窗口记忆，每个会话维护最近的轮次列表，但设置一个 max 值，默认 10 轮。超过后，最早的消息会被放进一个"滚动摘要"里，由一个小模型定期生成摘要，在下一次对话时把摘要作为系统提示词的一部分。这个做法比单纯截断消息友好很多，保留了对早期信息的理解能力，token 占用又很稳定。

第二层是向量记忆，把用户每条消息和 Agent 的关键回复做 Embedding，存入向量数据库。当用户在一个新会话里问"我之前跟你提过的那本技术书是什么？"时，系统会先做一次向量检索，把最相关的历史消息找出来，拼装进当前上下文。这个跨会话的记忆能力是 Personal Agent 区别于普通客服机器人的核心功能。

实现上我使用的是 Spring AI 自带的向量存储抽象，它支持很多种实现，我选的是内存型加上一个可选的本地持久化模式，这样在开发环境不用额外起服务，生产可以直接切到独立存储。Embedding 模型我也接了，用的是开源模型。整套记忆管理的关键在于：向量检索的结果要做一个相关度阈值过滤，低于阈值的就直接忽略，否则会引入大量无关历史干扰模型判断。

2.3 流式输出的"三次握手"：SSE 推送不能只开个接口

用户问一个问题，如果 Agent 要工具循环两三轮才给出最终结果，那前端如果是同步等结果，体验是极其糟糕的——可能用户在界面上看到"请稍等"要转好几秒钟。这个项目里我把流式输出做成了标配，不只是聊天内容流式，连"工具调用过程"也是流式的。

Spring AI 的 ChatClient 支持.stream()方法，返回一个 Flux 流。我在 Web 层用 Spring MVC 的 SseEmitter 接收这个流，然后把事件推给前端。关键细节在于，事件类型要区分好：

event: agent_start data: {"sessionId": "xxx"} event: tool_call_start data: {"toolName": "query_calendar", "args": {"date":"2026-05-01"}} event: tool_call_end data: {"toolName": "query_calendar", "result": "..."} event: message_delta data: {"content": "你好，我是你的..."} event: agent_end data: {"status": "done"}

前端只要能消费 SSE 协议就能逐段展示进度，包括"正在查询日历"这种中间状态。对用户来说，他看到的不是一只静态的加载转圈，而是 Agent 实实在在思考的过程，信任感和体验差非常多。整个链路的实现其实就是一个 EventPublisher 类在编排层发布事件，SSE 控制器订阅事件推给客户端。

这里要注意一个非常实际的生产问题：SSE 连接不能无限制地挂着。我在服务端做了一个守护线程，如果一个会话超过 60 秒没有空闲数据推送，就关闭这个 SSE。因为模型在思考时不会发数据，如果用户感觉卡住了，前端需要能自动重连，而不是等一个永远不回来的流。另外 SseEmitter 的异步线程要设置超时时间，防止容器默认的 30 秒超时直接切掉连接。

3. 生产级细节：看起来是 AI 项目，实际上是工程问题

3.1 并发控制与会话隔离：Agent 不能"精神分裂"

Personal Agent 一旦对外服务，首先面临的就是并发问题。同一个用户可能同时在手机和网页发起两个请求，如果这两个请求都修改同一个会话的历史消息，Agent 的记忆就会污染，出现"精神分裂"。

我的方案是引入会话级分布式锁，锁的粒度是 sessionId。在进入 Agent 编排层之前，先尝试获取会话锁，拿不到就直接返回"当前会话正在处理其他请求，请稍候"。Redis 实现天然支持过期时间，我设置的过期时间是 30 秒，超过就自动释放，防止系统异常导致死锁。同时本地内存里还有一层更快的 ConcurrentHashMap 锁，避免了所有请求都打 Redis 的开销。

下面是核心的锁服务实现思路，我给一个简单可用的版本：

public class SessionLockManager { private final StringRedisTemplate redisTemplate; private static final String LOCK_PREFIX = "agent:lock:"; private static final Duration LOCK_TTL = Duration.ofSeconds(30); public boolean tryLock(String sessionId) { String key = LOCK_PREFIX + sessionId; Boolean success = redisTemplate.opsForValue() .setIfAbsent(key, Thread.currentThread().getId() + "", LOCK_TTL); return Boolean.TRUE.equals(success); } public void unlock(String sessionId) { String key = LOCK_PREFIX + sessionId; redisTemplate.delete(key); } }

这里还要处理一个隐藏问题：模型推理有超时，但超时发生时我们还在持有锁，必须用 try-finally 释放。我把整个编排逻辑封装在一个方法里，锁的释放放在 finally 块中，就算抛出 Runtime 异常也能保证锁释放，不会阻塞用户的后续会话。

3.2 重试与熔断别瞎写：AI 接口和数据库不是一个套路

大模型接口和数据库接口的重试逻辑完全两回事。数据库挂了你重试可能就恢复了，但模型接口返回 429（限流）或 5xx，很多情况下是暂时的，合理重试有效。但模型返回 400 这种参数错误，重试一万次也是浪费钱。

我在模型调用这一层做了一个全局的重试拦截器，它根据异常类型和状态码分类处理。429 和 503 会触发指数退避重试，初始 1 秒，最多 4 次，每次翻倍，并且加上一个随机抖动，防止多个请求同时重试再次把限流触发。业务级的 RuntimeException 不重试，直接向上抛出，让编排层决定是否要告诉用户"系统繁忙"。

熔断这一块，我用的是 Resilience4j，集成非常轻量。熔断器的策略是，在一个 30 秒的滑动窗口内，如果模型调用的失败率超过 30%，就打开熔断器，后续 10 秒内的请求直接快速失败，不再真正去打模型接口。10 秒后尝试放行少量请求探测恢复，成功了就逐步关闭熔断。这里模型接口的调用的特点是高延迟（通常 3-10 秒），所以熔断器的时间窗口要设得比普通 HTTP 大很多，否则会因为延迟高导致统计窗口一直处于打开状态。

3.3 Token 计算与成本控制：别到月底看账单才傻眼

做一个 Personal Agent，如果不关心 token 成本，上线基本上就是烧钱。我在项目中实现了多级成本控制机制。

首先在模型适配层，每轮对话都会计算预估输入 token 和最大输出 token，并实时检查当前会话累计消耗是否超限。我在配置里设置了用户日额度、会话额度两级限制，一旦超限，Agent 会直接提示"今日对话额度已用完"，同时整轮请求会被快速拒绝。这个限制必须放在编排层的最前面，不能等消息进了模型才拦截。

为了准确统计 token，我使用的是模型响应里的 usage 字段，这个字段是真实消耗数，不是估算。对于工具调用消耗的 token，也都累加在会话的总账上。我做了个数据库表来记录每条消息的模型、输入输出 token 数和耗时，每天结束跑一个汇总任务，把这个数据推给后台的看板。

3.4 可观测性：Agent 的内部的每一步都要能追踪

生产环境出了事故，最绝望的事情就是日志打出来只有一行："模型返回异常"。你完全不知道是哪一轮工具调用出了问题，也不知道当时用户问的是什么。所以从项目一开始，我就给整套 Agent 链路打通了全链路追踪。

核心做法是在消息进入 Agent 编排层时生成一个 traceId，通过 SLF4J 的 MDC 机制把它塞进日志上下文，整个链路的所有日志，包括工具调用、模型请求、重试事件、熔断触发，都会自动带上有同一个 traceId。配合日志平台，我可以通过一个 traceId 拉出整次对话的完整生命周期日志。

另外我在 Agent 编排层加了一个关键日志点，格式类似：

[traceId=xxx, session=xxx] [model_request] model=gpt-4o, promptTokens=123, completionTokens=45, totalTokens=168, costEstimate=0.003 [traceId=xxx, session=xxx] [tool_call] tool=query_calendar, args={userId="..."}, result={"count":3}

一天结束，从日志平台拉这些数据做聚合，直接就能分析出哪个工具调用次数最多、哪个工具平均耗时最长、哪个模型成本占比最大。有了这些数据，优化方向就非常清晰，而不是拍脑袋。

4. 完整实操：从零搭建项目骨架到跑通首轮对话

4.1 建项目与核心配置：Spring Boot + Spring AI

项目基础是 Spring Boot 3.x 版本，JDK 17。我建议用 Maven 管理依赖，最关键的是在 pom.xml 引入 Spring AI BOM：

<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>1.0.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

随后引入 starter-web 和 spring-ai-starter-model-openai。我用的模型接口是 OpenAI 兼容协议，但实际接入的是国内的开放平台提供的模型服务，因为这样响应速度快一些。配置方面，在 application.yml 里设置：

spring: ai: openai: base-url: https://your-endpoint.example.com/v1 api-key: ${AI_API_KEY} chat: options: model: your-model-name temperature: 0.7 max-tokens: 2048

这些配置本质上就是把模型厂商的信息从代码里剥离出去，换供应商只改配置。我另外封装了一个 ModelConfig 类，根据不同的配置文件，可以灵活地在多个模型之间切换，比如大模型负责推理、小模型负责摘要和 Embedding。

4.2 核心代码逻辑：ChatClient 的组装与 Agent 编排循环

接下来是 Agent 服务的核心逻辑。在 Spring AI 里，ChatClient 可以像构建器一样装配各种功能。我创建了一个 AgentService，核心方法如下：

@Service public class AgentService { private final ChatClient chatClient; private final ToolRegistry toolRegistry; public AgentService(ChatClient.Builder chatClientBuilder, List<ToolService> toolServices) { this.chatClient = chatClientBuilder .defaultSystem("你是一个高效可靠的个人助理，可以管理用户的待办、日程，回答用户的问题。回答尽量简洁...") .defaultTools(toolServices.toArray()) .build(); } public Flux<AgentEvent> chat(String sessionId, String userMessage) { // 1. 获取会话锁 // 2. 加载历史消息 // 3. 组装 Prompt // 4. 调用 chatClient.stream() // 5. 通过事件流发布工具调用状态和消息增量 } }

在 stream 的 Flux 里，Spring AI 会把模型的流式响应拆分成一个个 Token 的 Flux，我在 map 里把它转换成自定义的 AgentEvent，然后通过 Sinks 类发布出去，SSE 控制器订阅这个 Sinks 就能把实时结果推到前端。这里特别建议流式响应不要走 WebFlux 的全局方案，因为 SSE 加 Sinks 的模式对接现有 Spring MVC 项目更平滑，而且可以复用原有拦截器和过滤器链。

4.3 工具的注册与执行：反射调用之前的细节

工具注册这一块，Spring AI 自动扫描 @Tool 注解的方法，但生产上我加了一层校验。工具方法的入参必须是基本类型、String、或简单 POJO，复杂嵌套对象容易在模型参数反序列化时出问题。如果工具需要多个参数，我建议封装成一个 POJO 作为入参，因为模型对 JSON 对象参数的生成比多个独立参数稳定得多。

工具执行完了，返回类型也用字符串最稳妥。Spring AI 在把工具结果回传给模型时，需要的是字符串，如果工具返回一个对象，框架会序列化成 JSON 字符串，这里如果没有经过严格测试，可能会因为对象里有循环引用导致序列化异常。所以我所有工具方法统一返回 String，内部自己负责格式化输出结果。

4.4 会话记忆的持久化：不重启就丢人

对话记忆如果只放在内存的 ConcurrentHashMap 里，一重启就全没了。我的实现中，会话历史在每轮结束都完整写入数据库。表结构大概是：session_id、message_role（user/assistant/tool）、content、message_time、token_usage。每次 Agent 编排层的循环结束，都会批量插入这一轮产生的所有消息。查询的时候按时间升序拉出来，组转成 Prompt 的消息列表。

摘要记忆存在另一张表，每次生成新摘要就覆盖旧摘要，因为摘要只保留最近的状态。向量数据单独存到向量存储中。这三层数据的一致性要注意：数据库会话历史的变更和向量数据写入必须在一个事务里完成，否则会出现向量里有记录但原始消息没落库的不一致状态。

5. 常见问题与排查技巧实录：我踩过的那些坑

5.1 模型"幻觉"导致工具参数名对不上，怎么兜底

我在最初测试时经常遇到模型返回了工具调用意图，但参数名跟方法签名对不上。比如我定义的工具参数叫 userCode，模型传了一个 user_id 进来。Spring AI 的解析会直接报错。实话讲，这个问题目前没有完美解法，模型对 JSON Schema 的理解还没有强到绝对稳定。

我用的是多级兜底方案。第一级是框架自带的转换，Spring AI 会把 JSON 值按类型转换；第二级是我在代理层做字段名模糊匹配，如果发现参数缺失但不影响调用，就用默认值补上；第三级，如果核心参数缺失，直接返回错误字符串给模型，让它重新生成，例如"工具 query_user 需要参数 userCode（String），你传的参数缺少该字段，请重新调用"。有了这个反馈机制，下一次模型基本会纠正自己。

5.2 Stream 中断导致前端卡死，排查思路分享

生产环境遇到过一个最棘手的 bug：某个用户反馈对话框"卡死"了，刷新也没用。排查下来，是模型在生成到一半时断连，基础服务返回了连接重置错误，但 SSE 的异常处理没有触发，导致前端一直开着等待，却永远等不到下个事件。

排查思路是先去链路日志看这个会话是否收到了模型服务的完成事件。日志显示没有，说明模型侧确实中断了。然后检查异常捕获，发现有一个自定义的全局异常处理器把 SSE 相关的异常都吞掉了，导致 SseEmitter 一直不结束。修复方法是重写 SseEmitter 的错误处理：任何异常发生时，不仅要把异常事件推给前端，还必须执行 emitter.complete()，不给前端留挂死的可能。另外前端也做了 30 秒无消息自动重连的逻辑，双保险才彻底解决这个问题。

5.3 成本突增的排查：向量记忆命中太泛

有一段时间我观察每日 token 成本突然涨了 40%，一开始以为是把生产模型换成了更大参数的版本，查了配置发现没有。后来从日志统计里发现，是向量记忆的检索结果过于宽泛，每条消息都额外塞进了 2000 多 token 的历史记录。原因是我给的向量检索 topK 设置成了 5，而且是固定值，没有做相关度阈值过滤。

修复方法很简单：针对每个检索结果计算相似度得分，低于 0.75 的结果直接丢弃。实测下来，平均每条消息额外携带的历史记录从 2000 token 降到了 600 token 左右，整体 token 成本下降了一大截。这是个典型的细节问题，看起来不起眼，但放大到生产流量上就是实实在在的钱。

5.4 小技巧：怎么用测试数据验证 Agent 多轮对话不跑偏

最后分享一个测试小技巧。Agent 做多轮对话时，最容易出现的问题是上下文污染。我有一套固定的验证用例，每次代码改完都会跑一遍，比如：

• 第一轮："帮我安排明天的会议，下午 3 点。"
• 第二轮："改到后天。"
• 第三轮："看看我这个月有哪些天没有会议。"

这三轮如果 Agent 都能正确处理，说明会话级记忆和摘要记忆的基本链路是通的。我还专门写了一个集成测试基类，启动完整的 Spring 容器去跑这几个用例，每次 CI 都会执行。AI 应用的测试不应该只测工具方法本身，一定要有端到端的多轮会话回归测试，这是保证项目强壮性的底线。

有些人觉得 Agent 项目就是调包，真做下来才知道，生产级的难度全在工程细节：并发、成本、可观测性、容错兜底。我这个项目把这些细节全部开源出来了，如果你也在用 Java 技术栈做个人助理或者智能客服方向，直接参考这套架构，至少能省掉两三个月的填坑时间。代码上的事，多动手跑一遍，比看任何文章都管用。