1. 从“能跑”到“敢上生产”Java 智能体框架到底缺了什么过去一年我身边不少做 Java 后端的同行都在琢磨同一件事怎么把大模型能力塞进现有的 Spring Boot 服务体系里。大家试过的路子基本就那么几条——要么在业务代码里直接调 HTTP 接口把提示词硬编码在 Service 层要么用 Python 单独起一个智能体服务再通过内部 RPC 让 Java 主站去调用。第一种做法在 Demo 阶段看着挺美一旦要加多轮对话、工具调用、记忆管理代码就会迅速腐化成一座“提示词屎山”第二种做法则引入了额外的运维成本和跨语言调试的麻烦尤其是当团队里只有 Java 栈的兄弟时排查一个 Python 侧的异步问题能耗掉一整个下午。这个项目的出现恰好切中了这个痛点。它做的事情可以概括成一句话用 Spring Boot 和 Spring AI 把智能体该有的东西全部用 Java 重新实现一遍并且把生产环境才会关心的那些细节——会话隔离、工具注册、流式响应、可观测性——全部摊开给你看。它不是又一个“调通 API 就完事”的玩具而是一套有明确分层、有扩展点、有容错设计的全栈骨架。适合谁看如果你已经写过 Spring Boot 项目对 Bean 生命周期、自动配置、拦截器这些概念不陌生同时想搞清楚一个 Java 智能体从请求进来到响应出去中间到底经历了哪些环节那这篇内容就是为你准备的。我会按照自己读源码和实际搭环境的顺序把里面最值得关注的几个设计决策拆开来讲包括它为什么这么分层、每个扩展点解决什么问题、以及我在复现过程中踩到的那些文档里不会写的坑。2. 工程分层拆解一个请求进来后到底走了几条路2.1 接入层与控制层为什么 AgentController 不是简单转发很多人第一次看这类项目会习惯性地去找那个“核心类”以为会有一个叫AgentService的庞然大物把所有逻辑都吞进去。但这个项目的做法不太一样它把接入层和控制层分得很清楚。接入层负责的是协议适配——把 HTTP 请求体里的 JSON 映射成内部统一的AgentRequest对象同时处理鉴权、限流、跨域这些和业务逻辑无关的横切关注点。控制层则负责编排它拿到AgentRequest之后会根据请求里携带的agentId去注册中心查找对应的智能体定义然后决定这次调用是走同步返回还是流式返回。我一开始觉得这层有点多余直接在 Controller 里调 Service 不就行了后来在压测的时候才明白它的价值。当你想给所有智能体请求统一加一个“请求耗时超过 30 秒自动降级”的策略时只需要在控制层加一个切面完全不用动下面任何业务代码。这种分层带来的可测试性也很明显——你可以单独 Mock 掉注册中心只测控制层的路由逻辑不需要启动整个 Spring 上下文。注意如果你打算基于这套骨架做二次开发建议先花十分钟把AgentRequest和AgentResponse这两个 DTO 的字段含义搞清楚。后面所有的扩展点包括自定义工具、自定义记忆存储都是围绕这两个对象在做文章。2.2 智能体运行时Bean 作用域选错了会话就串了这是我认为整个项目里最值得细看的部分也是最容易踩坑的地方。智能体运行时负责的是“一次对话”的完整生命周期管理。它内部持有一个ChatClient实例来自 Spring AI以及一个工具回调注册表。关键点在于这个运行时对象的作用域不能是单例。如果你把它声明成默认的 Singleton Bean那么所有用户的对话历史都会混在一起A 用户问“我刚才说了什么”B 用户可能会收到 A 的上下文。项目里采用的做法是运行时对象本身是无状态的真正的会话状态被抽取到一个ConversationContext对象里这个对象通过ThreadLocal或者显式的参数传递来绑定到当前请求线程。但这里有个细节如果你用了 Spring AI 的流式响应响应式编程模型下ThreadLocal可能会失效因为线程会切换。所以更稳妥的方案是把ConversationContext作为参数一路透传下去而不是依赖线程绑定。我在复现的时候一开始图省事用了ThreadLocal结果在流式场景下偶尔会读到上一个请求的残留数据排查了半天才定位到线程复用的问题。2.3 工具调用与函数注册让大模型“动手”的关键环节智能体区别于普通聊天机器人的核心能力就是它能调用外部工具。这个项目里工具注册的设计思路是“声明式注册 运行时解析”。你只需要写一个普通的 Spring Bean在方法上加上自定义的AgentTool注解并在注解里描述这个工具的功能和参数含义框架启动时会自动扫描这些 Bean把它们的方法签名转换成大模型能理解的 JSON Schema 格式。这里有个设计取舍值得说为什么不用 Spring AI 原生的Function注解我猜测是为了做更细粒度的控制。原生的函数调用机制在参数校验和异常处理上比较薄而这个项目在工具执行前后各加了一层拦截器。前置拦截器可以做参数合法性检查比如某个工具要求传入的日期不能早于今天就可以在这里直接拒绝并返回一个结构化的错误信息给模型让模型自己纠正。后置拦截器则负责把工具执行结果包装成统一的格式同时记录调用耗时和成功率这些指标后面会暴露给监控系统。2.4 记忆与上下文管理短期窗口和长期存储的分界线记忆管理这块项目里明确区分了“短期对话窗口”和“长期记忆存储”两个概念。短期窗口就是最近 N 轮对话的原始消息列表直接拼接到提示词里发给模型。长期存储则是把历史对话做摘要或者向量化之后存到外部数据库需要的时候再检索回来。这个分界线画在哪里直接影响到成本和效果。我实测下来的感受是短期窗口的轮数不要设太大。很多人觉得把十轮对话全塞进去模型就能记住更多但实际上提示词长度增加带来的延迟和费用增长是线性的而模型对超长上下文的注意力衰减也是客观存在的。项目默认给的是 6 轮我觉得这个数字比较合理既能覆盖大多数多轮追问场景又不至于让每次请求的 token 消耗失控。长期存储那边项目预留了一个MemoryStore接口默认实现是基于内存的生产环境你需要自己换成 Redis 或者向量数据库的实现。3. 流式响应与阻塞模型的共存一个容易被低估的工程难题3.1 为什么智能体场景下流式输出几乎是必选项普通 REST 接口返回一个 JSON用户等两秒也能接受。但智能体场景不一样大模型生成一段三百字的回答可能需要五到十秒如果让用户盯着一个空白页面等十秒体验是灾难性的。流式输出让首字节到达时间从“生成完毕”提前到“生成开始”用户看到文字一个个蹦出来感知上的等待时间会大幅缩短。这个项目在流式这块做了比较完整的支持底层用的是 Spring 的SseEmitter配合 Spring AI 的流式 API。但这里有个 Java 后端开发者经常会忽略的问题流式接口和传统的阻塞式业务逻辑混用时会互相干扰。比如你的工具调用里有一个是查数据库这个查询本身是阻塞的如果它耗时过长会占住处理流式响应的线程导致后续的 token 推送被卡住。项目里的处理方式是把工具调用放到一个独立的线程池里执行流式主线程通过CompletableFuture等待结果同时设置超时时间。超时之后不是直接报错而是给模型返回一个“工具执行超时”的提示让模型基于已有信息继续生成回答。这个降级策略很实用我在实际测试中把某个工具的模拟延迟调到 10 秒模型确实会绕过它继续回答其他部分而不是整个请求挂掉。3.2 SseEmitter 的超时设置与连接保活SseEmitter的默认超时时间在不同容器下表现不一致Tomcat 下默认是 30 秒但如果你在网关层还有一层 NginxNginx 的proxy_read_timeout默认是 60 秒。这两个值如果没对齐就会出现“后端还在生成前端连接已经被网关掐断”的情况。项目里把SseEmitter的超时设成了 120 秒同时在配置文件中给出了 Nginx 侧的对应配置建议。这个细节很小但如果没有注意到线上就会出现偶发的“回答生成到一半突然断了”的投诉。另外流式响应期间如果长时间没有数据推送比如模型在思考一个复杂问题中间的网络设备可能会认为连接空闲而主动断开。项目里加了一个心跳机制每隔 15 秒发送一个空注释行保持连接活跃。这个做法在 SSE 协议里是标准操作但很多自己手写流式接口的开发者会漏掉。3.3 流式场景下的异常处理错误怎么传给前端同步接口抛异常直接返回一个错误码和错误信息就行了。流式接口不行因为 HTTP 状态码在流开始的时候就已经发出去了后面再出错只能通过流里面的数据来传递。项目里的做法是定义了一套流式事件协议每个 SSE 事件都有一个event字段标识类型比如message表示正常的文本片段tool_call表示正在调用工具error表示出错了done表示生成结束。前端根据event字段来决定怎么渲染。这种设计的好处是前端可以针对不同事件做不同的 UI 反馈。比如收到tool_call事件时可以在界面上显示“正在查询数据...”让用户知道系统在干活而不是卡住了。我在自己的项目里借鉴了这个思路把工具调用的名称也放进事件数据里前端就能显示“正在查询订单信息...”这样更具体的提示。4. 生产级细节那些 Demo 里不会告诉你的配置4.1 线程池隔离别让智能体请求拖垮整个应用智能体请求的特点是耗时长、并发量不可预测、可能触发外部工具调用。如果这些请求和普通的业务接口共用同一个 Tomcat 线程池一旦智能体请求堆积整个应用的线程都会被占满连健康检查接口都响应不了。项目里明确建议为智能体执行链路配置独立的线程池通过ThreadPoolTaskExecutor自定义一个 Bean核心线程数和最大线程数根据实际压测结果来定。我自己的经验值是核心线程数设为 CPU 核数的两倍最大线程数设为核心线程数的四倍队列容量不要太大否则请求排队时间会很长。更重要的是要配置拒绝策略当线程池满了之后直接返回一个“系统繁忙请稍后重试”的友好提示而不是让请求无限等待。这个拒绝策略在智能体场景下尤其重要因为用户已经习惯了等待如果你不明确拒绝他们可能会等更久然后更失望。4.2 可观测性日志里该打什么不该打什么智能体应用的日志是个雷区。一方面你需要记录足够的上下文来排查问题另一方面提示词和模型回复里可能包含用户隐私信息直接打到日志里会有合规风险。项目里的做法是把日志分成两层一层是结构化的调用日志只记录请求 ID、智能体 ID、耗时、token 消耗量、工具调用次数这些元数据不记录具体内容另一层是调试日志只有在开发环境或者特定排查场景下才开启记录完整的提示词和回复并且做了脱敏处理。我建议在日志里额外记录一个“提示词模板版本号”。因为智能体的行为很大程度上取决于提示词当你调整了提示词之后如果发现效果变差了能通过版本号快速定位到是哪次变更导致的。这个做法在多人协作维护提示词的场景下特别有用。4.3 配置外置与热更新提示词不该硬编码项目把提示词模板放在了resources/prompts/目录下通过 Spring 的ResourceLoader加载。这样做比硬编码在 Java 代码里好但还不够。生产环境经常遇到的情况是运营同学想调整一下机器人的语气难道还要重新打包发版吗更合理的做法是把提示词放到配置中心或者数据库里支持热更新。项目预留了PromptProvider接口默认实现是从 classpath 加载你可以很容易地替换成从数据库或配置中心读取的实现。不过热更新有个坑要注意如果提示词更新到一半某个请求正在使用旧提示词生成回答另一个请求已经用上新提示词了这本身没问题。但如果提示词模板里引用了某些变量而新模板的变量名和旧的不一致就会导致渲染失败。所以热更新的时候最好做一个版本校验确保新模板的变量集合是旧模板的超集或者至少给出明确的告警。5. 从零复现我搭环境时踩过的五个坑5.1 依赖版本冲突Spring AI 的里程碑版本要手动指定仓库Spring AI 目前还在快速迭代中很多版本没有发布到 Maven 中央仓库需要额外配置 Spring 的里程碑仓库。我第一次搭的时候没注意mvn clean install直接报找不到依赖。解决办法是在pom.xml里加上仓库配置或者在settings.xml里配好镜像。另外要注意 Spring AI 的版本和 Spring Boot 版本的兼容性项目 README 里给了一个推荐组合但如果你用的 Spring Boot 版本比推荐的新可能会遇到NoSuchMethodError这类运行时错误。我的建议是严格按项目推荐的版本组合来不要自己随意升级。5.2 API Key 的注入方式环境变量和配置文件的优先级项目默认从环境变量读取 API Key这是比较安全的做法避免密钥被提交到代码仓库。但本地开发的时候每次启动都要在 IDE 里配环境变量有点麻烦。我的做法是在本地建一个application-local.yml把密钥写进去然后把这个文件加到.gitignore里。同时利用 Spring 的配置优先级——环境变量高于配置文件——这样在服务器上部署时环境变量会自动覆盖本地的配置不需要改任何代码。提示如果你在容器环境里部署记得把密钥通过 Secret 的方式挂载不要直接写在 Dockerfile 或者编排文件的环境变量里那些地方容易被有权限的人看到。5.3 工具方法的参数类型限制不是所有 Java 类型都能被正确解析写自定义工具的时候方法参数的类型会影响框架生成 JSON Schema 的准确性。基本类型String、int、boolean和它们的包装类没问题但如果你用了自定义的 POJO 作为参数框架会尝试用反射去解析字段这时候如果 POJO 里有嵌套对象或者泛型集合生成的 Schema 可能会不完整导致模型传参时格式对不上。我踩过的坑是传了一个ListMapString, Object类型的参数模型完全不知道该怎么填。后来改成用 JSON 字符串接收然后在工具方法内部自己反序列化就稳定了。5.4 流式响应下的中文乱码编码问题比想象中隐蔽流式输出中文的时候如果编码设置不对会出现“半个汉字”的乱码现象。原因是 UTF-8 编码下一个汉字占三个字节如果每次推送的字节数不是三的倍数接收端就可能把三个字节拆到两次事件里。项目里通过设置SseEmitter的字符集为 UTF-8 来规避这个问题但如果你自己扩展了推送逻辑比如在工具调用事件里也推送中文描述记得也要确保编码一致。我在 Nginx 层还加了一个charset utf-8;的配置双保险。5.5 会话清理内存泄漏往往发生在你意想不到的地方如果短期记忆存在内存里一定要设置过期清理策略。项目默认用的是ConcurrentHashMap来存会话上下文但没有自动清理机制。这意味着如果用户量上来内存会一直涨。我的做法是加了一个定时任务每隔十分钟扫描一次把超过半小时没有活动的会话清理掉。更稳妥的方案是直接用 Redis 的过期键机制让 Redis 帮你管理生命周期。这个点很容易被忽略因为开发阶段会话少看不出问题一上生产就会暴露。6. 扩展思路这套骨架还能怎么改6.1 多智能体协作的雏形当前项目是单智能体架构一个请求对应一个智能体。但实际业务里经常需要多个智能体配合比如一个负责意图识别一个负责查数据一个负责生成最终回复。基于现有的工具调用机制其实可以做一个简单的多智能体编排把“调用另一个智能体”也封装成一个工具让主智能体决定什么时候把任务委派出去。这种做法的好处是不需要改动框架核心只需要注册一个新的工具实现。但要注意避免循环调用A 调 B、B 又调 A 的情况需要在工具层面加一个调用深度限制。6.2 提示词版本管理与 A/B 测试前面提到提示词热更新再往前走一步就是 A/B 测试。你可以在PromptProvider里根据用户 ID 的哈希值来决定返回哪个版本的提示词然后通过日志里的版本号来对比不同版本的效果指标比如平均对话轮数、用户满意度评分、工具调用成功率。这套机制不需要很复杂关键是先把版本号埋进去后面做分析的时候才有数据基础。6.3 成本控制token 用量监控与预算告警智能体应用的 token 消耗是实打实的成本。项目里已经记录了每次请求的 token 用量你可以把这些数据汇总起来按用户、按智能体、按天做统计。我自己的做法是设置了一个日预算阈值当某个智能体的日消耗超过阈值时自动发送告警通知同时临时降低它的最大回复长度限制。这个降级策略比直接停用要温和用户还能继续用只是回复短一些等预算重置或者人工调整阈值后再恢复。6.4 工具调用的幂等性设计当模型决定调用一个工具时它可能会因为网络抖动或者超时重试而重复调用同一个工具。如果你的工具是“查询订单”这种只读操作重复调用问题不大。但如果是“创建工单”这种写操作重复调用就会产生脏数据。项目里没有内置幂等性保障需要你在工具实现里自己处理。我的做法是在工具方法的参数里加一个由框架生成的requestId工具内部先检查这个 ID 是否已经处理过如果是就直接返回上次的结果。这个requestId可以基于当前对话的 ID 加上工具调用的序号来生成保证同一次对话里同一个工具的多次调用有不同的 ID但重试时 ID 不变。7. 一些个人体会这套骨架我前前后后搭了三遍第一遍是纯粹照着 README 走跑通就结束了第二遍是带着问题去读源码把每个扩展点的调用链路画了一遍第三遍是尝试替换掉一些默认实现比如把内存记忆换成 Redis、把提示词加载换成数据库。三遍下来最大的感受是Java 生态做智能体应用优势不在于算法创新而在于工程治理。Spring 的依赖注入、AOP、事件机制这些成熟的基础设施能让你在构建智能体时少写很多胶水代码把精力集中在提示词设计和工具实现上。另一个体会是不要试图一次性把所有生产级特性都加上。我见过一些团队项目还没跑通就开始搞多智能体、搞向量数据库、搞复杂的监控面板结果核心的对话流程都不稳定。合理的顺序是先让单智能体跑通把工具调用和流式响应调稳然后再逐步加上记忆持久化、可观测性、成本控制这些。这个项目本身也是这么演进的从代码结构上能看出来核心的运行时逻辑很精简外围的扩展点留得很足这种“核心稳定、外围灵活”的架构思路比具体用了什么技术更值得借鉴。