1. 从“第9掌”说起为什么偏偏是ReactAgent如果你一路跟过“降SpringAI阿里”这个系列前面的招式应该都已经熟得差不多了。CompletableFuture、WebClient、Spring AI的ChatModel调用、RAG、Function Calling……每一步都在解决“怎么让AI真正干活”的问题。到了第9掌“或跃在渊”话题收敛到ReactAgent——一个在Spring AI框架里非常容易被误解、被低估但实际价值极高的组件。先说结论ReactAgent是Spring AI全家桶里最接近“自主AI”的一个模块。前面的招式是你主动编排AI流程到了ReactAgent这里流程本身变成了AI的推理结果。你告诉它目标它自己决定下一步调什么函数、查什么数据、怎么验证结果甚至自己决定什么时候收工。标题里“或跃在渊”四个字出自《乾卦》九四爻讲的是审时度势、待机而动。你品一下这恰好是ReactAgent设计哲学的精准概括——它不是无脑地一条路走到黑而是在每一轮都评估“当前信息够不够要不要再走一步”直到有足够信心输出答案才停下。我这次接手的实际需求是个典型的“智能审核”场景一个内容安全审核系统需要自动判断一段提交给平台的文案是否合规。听起来简单但真正的坑在于合规判定不是一个纯模型能力问题它需要调用内部审核规则引擎、需要查历史案例库、需要判断敏感词命中后的上下文语义甚至需要根据命中情况决定是直接拒绝、转人工还是标记待定。纯靠Prompt让大模型“猜”结果不可控纯靠代码写死规则又谈不上“智能”。ReactAgent正好卡在这两者之间——它是你和大模型之间的一个“策略中间层”。适合看这篇的人我默认三类一是已经会用Spring AI做基础对话但没玩过Agent的Java读者二是Spring Cloud微服务团队想把AI能力嵌入现有业务流程的人三是纯粹对Agent架构感兴趣、想看看Java生态里和LangChain有什么区别的人。你不用有Agent的理论基础但我会默认你会Spring Boot基本用法。2. 整体设计与思路拆解ReactAgent到底拆了谁的台2.1 为什么是ReAct而不是纯工具调用在Spring AI里实现Agent能力目前官方路线就是ReAct模式。ReAct这个名字是 Reasoning Acting 的合体核心思想是让模型在每一轮先“思考”再“行动”行动结果作为新的观察信息重新喂给模型形成一个循环。整个循环的终止条件由模型自己根据系统提示词和观测信息来判断。有人会问Function Calling不是也能让模型调工具吗为什么不直接用这是我在实际开发中踩过之后才彻底想明白的。Function Calling确实能让模型在生成过程中选择调用某个工具但它本质上是“一次性”的决策——模型根据已有上下文决定“此刻要不要调这个函数、传什么参数”你拿到结果后是由外部代码来决定下一步的。换句话说编排主动权在代码手里你写死了“如果结果包含XX就走YY”。而ReactAgent不一样它的编排主动权在模型手里。模型在每一轮输出中不仅决定调什么工具还决定“要不要调”“调完之后继续做什么”甚至当它觉得信息足够时直接输出最终答案。从开发者的角度看你只需要给它一个目标系统提示词里的任务描述一组工具Tool注解的方法一个观察窗口用户消息或历史上下文。剩下的事情全由模型自主决定。对于审核场景这就很关键了——审核规则实在太多太碎你不可能为每一条规则写一个代码分支。你只能把规则引擎暴露成工具让模型自己决定“这个问题要不要去查规则库”。2.2 Spring AI的ReactAgent架构全览Spring AI对ReAct的实现官方类名叫ReactiveReactAgent在1.0.0-M系列版本里包路径是org.springframework.ai.react。它和Spring WebFlux一样走的是响应式流名字里的“Reactive”也因此而来。整个执行链路分三个关键件第一是ChatClient。它就是模型的连接器负责向OpenAI、通义千问、Ollama等模型发起对话请求。ReactAgent内部通过它做推理但它不是直接用你普通对话的方式调用而是走ChatModel的工具调用通道把模型的响应结构化解析出“是否要调用工具”的信号。第二是ToolExecutor。这是所有Tool注解方法的执行器。Spring AI扫描你定义的Bean方法把方法签名转成JSON Schema描述给模型模型返回一个包含函数名和参数的JSONToolExecutor负责反射调用并把结果重新包成消息给模型。第三是ReactAgentStateGraph。这个类内部维护了一个Agent状态机记录当前的推理历史、观察结果、剩余最大迭代次数。每一轮循环它都会检查模型输出如果是工具调用就执行工具并回填观察值如果是最终答案就终止流程。这是和旧版“一个while循环调模型”方式的核心区别——新版的状态机让整个流程可追踪、可限制、可干预。整体流程用大白话说就是用户给了一个审核请求 → Agent把请求和目标拼给模型 → 模型“思考”后说“我需要先查敏感词规则库” → Agent找到对应工具执行把结果拿回来 → 把结果作为观察信息再喂给模型 → 模型再次“思考”说“现在信息够了我来给出结论” → Agent把结论返回给调用方。这个模式我在那边落地后的第一感受是代码量真的只有传统分支式审核逻辑的五分之一而且加新规则几乎不用改代码。2.3 为什么选Spring AI而不是LangChain4j国内Java圈子做Agent其实更多会提LangChain4j。老实说LangChain4j在工具调用生态和社区文档方面确实成熟不少但它和Spring Boot的原生集成度不如Spring AI。我这里说的集成度不是“能不能跑”而是三层匹配一是AOT编译与GraalVM原生镜像支持Spring AI从M6版本开始就把ReactAgent状态机设计成native-friendly类型推断全部显式化不会在运行时反射踩原生镜像的坑二是Spring Boot Actuator自动上报Agents的执行次数、工具调用耗时可以直接打进Prometheus里LangChain4j的监控方案基本靠手动埋点三是与Spring Security的上下文传递调用Agent的服务可以把登录用户信息直接注入到工具方法参数里而LangChain4j的UserContext传递需要你自己写ThreadLocal桥接。当然这不是说LangChain4j不行它其实有它的好。只是在“已有Spring Boot体系”的背景下Spring AI的这几项原生优势确实让团队内部省了很多事。3. 核心细节解析与实操要点提示词、工具与状态控制3.1 系统提示词的配置智能审核场景的关键中的关键网络热词里大家反复搜的就是“SpringAI系统提示词怎么配置”这一块我必须花最大的篇幅讲因为在ReactAgent里系统提示词不是“给AI一个好人设”那么简单它实际上是整个Agent的控制协议。我在审核场景里给ReactAgent配的系统提示词结构上分四层每一层都有明确作用。第一层是角色与任务边界。告诉模型它是“内容安全审核助手”任务是对输入内容给出合规判定。这一层必须写清“只做审核不做其他回答”否则用户消息里夹带“顺便帮我写个文案”就会被模型顺手接了——不是模型坏是你没约束。第二层是判定标准与分级规则。需要明确给出审核的分级体系比如“PASS/ REVIEW(转人工) / REJECT(拒绝)”每一级对应的触发条件要尽量具体。不要写“涉政违法”这种大词要给可操作的具体信号比如“出现明确色情行为描写”“出现人身攻击词汇”“存在医疗建议但无资质声明”“涉及未成年人隐私信息”等等。越具体模型越不容易自由发挥。第三层是工具使用策略。告诉模型什么时候该查工具、什么时候直接输出。比如“当遇到不确定的专业名词时查询知识库工具”“当客户要求兜底审核时调用规则引擎工具”。这一层的关键是让模型明白工具是辅助不是每轮都非得调用。第四层是输出格式与终止条件。告诉模型最终回答必须是一个特定JSON结构包含result、confidence、reason三个字段并且解释达到什么信息量后可以直接结束流程不要反复调工具拖着不输出。这里我强烈建议系统提示词不要用纯文本拼接要用Spring AI的PromptTemplate。具体做法是定义PromptTemplate对象利用PromptTemplate(系统提示词模板, Map.of(rules, rulesContent, toolPolicy, toolPolicy))的方式在运行时填充变量。这样做的好处是审核规则如果经常更新你可以走配置中心把rulesContent这个变量动态下发Agent不用重新部署。伪代码String systemText 你是一个内容安全审核助手。你的任务是分析用户提交的内容并给出合规判定。 判定标准如下 {rules} 工具使用策略 {toolPolicy} 当信息足够时请以JSON格式输出判定结果格式如下 {result: PASS|REVIEW|REJECT, confidence: 0-1, reason: 简要说明} ; PromptTemplate pt new PromptTemplate(systemText); Message systemMessage pt.createMessage(Map.of( rules, rulesContent, toolPolicy, toolPolicy )); // 构造Agent的UserMessage用同样方式注入用户输入 Message userMessage new UserMessage(requestText);这里有一个容易忽略的坑Spring AI在生成请求模型时ChatModel的多轮对话是独立消息传输的系统提示词的替换变量如果包含“多余换行”或“JSON注释符”个别模型尤其是本地部署的Qwen会直接把注释拼到输出里导致解析失败。稳妥做法是对规则文本做一次strip()并且在提示词里明写“不要输出额外解释只输出JSON”。3.2 Tool注解工具的边界设计哪些函数可以做工具ReactAgent的工具就是带Tool注解的普通Spring Bean公有方法。我的经验是Agent的工具设计必须遵循“粗粒度”原则——每个工具做完一件完整的事情尽量返回结构化的、已经处理好的数据而不是让模型拿着原始数据再二次加工。举个例子。审核场景里有三个工具是我实际用了的第一个是searchBlacklistKeyword(String text)返回ListString表示文本中命中了哪些黑名单词。这个方法内部可以走ES的IK分词或AC自动机返回结果只给词条不给位置信息降低模型的认知负担。第二个是queryRuleEngine(String ruleCode)返回指定审核规则的完整细则。比如传入RULE_1001返回“该规则针对医疗健康内容要求必须有执业医师资格证明或免责声明。”模型拿到这个规则后才知道用户提交的内容有没有违背它。第三个是checkHistoricalCase(String similaryText)返回相似历史案例的判定结果。这个工具在多轮审核里特别有用。比如用户第一次提交了一个“高仿包”的文案模型判了REVIEW第二次又提交一个类似的模型查历史案例发现上次判的是REJECT它就跟进直接给REJECT了——这就是“记忆能力”的落地方式。工具方法的长这样Service public class ReviewTools { Tool(description 检查文本中是否命中黑名单关键词返回命中的词条列表) public ListString searchBlacklistKeyword(String text) { return blacklistService.match(text); } Tool(description 根据规则编号查询审核规则的具体细则返回规则文本) public String queryRuleEngine(String ruleCode) { return ruleService.getRuleDetail(ruleCode); } }注意Tool注解里的description字段。这个字段直接决定模型会不会在合适的时候调用这个工具它会被序列化成工具Schema传给模型。描述写得好不好直接关系模型判断的准确率。我见过有人把描述写成“查询规则”结果模型每轮都去调白白增加延迟和成本。务必把触发条件写进去比如“只有当文本包含医疗、金融、教育类建议且无法确定合规性时才调用查询规则”。3.3 最大迭代次数你以为的无限循环保护ReactAgent有一个配置项叫maxIterations默认是10。很多人以为这只是“防止死循环”的安全阀其实它还直接决定了模型愿意花多少步去“搞清楚再回答”。我在审核场景里做过一个对比实验同样的用户请求maxIterations3时模型在第二步直接放弃调工具凭直觉输出结果maxIterations10时模型先查关键词列表、再查历史案例、最后走到规则引擎三步之后给了REJECT判定。这说明maxIterations不只是保护更是模型“做功深度”的暗示。因此配置它时别一刀切要根据具体场景调整。一般问答类Agent3步够审核类需要查多个数据源的10~15步合理如果每步还要调用外部HTTP接口比如OCR、视频抽帧每一步耗时可能到秒级那就得结合超时时间里外一起考虑不要把步数盲目拉高。配置方式在ReactiveReactAgent.builder()上链式调用ReactiveReactAgent agent ReactiveReactAgent.builder() .chatClient(chatClient) .toolExecutor(toolExecutor) .maxIterations(10) .build();3.4 响应式APIFlux 里的每一步你都能看见前面反复讲“Reactive”这里展开说说为什么这个设计对生产环境是加分项。Spring AI的ReactAgent调用返回的是FluxAgentResponse你订阅它时可以根据AgentResponse内部的StepType判断当前是哪一轮TOOL_CALL表示正在调工具OBSERVATION表示模型看到了工具结果FINAL_ANSWER表示最终输出。这在集成时太有用了。比如审核场景产品要求“如果模型要转人工前端必须弹一个用户确认框”。你用Flux可以这么写agent.execute(prompt) .doOnNext(resp - { if (resp.getStepType() StepType.TOOL_CALL) { log.info(Agent is calling tool...); } if (resp.getStepType() StepType.FINAL_ANSWER) { log.info(Final result: {}, resp.getResult()); } }) .subscribe();如果你的服务是经典Servlet模式而不是WebFlux也可以用.blockLast()阻塞到最终结果。但我的建议是在Spring Boot的RestController里直接返回Mono审核结果让网关层处理异步路由这样一次调用不占用Servlet线程高并发下的成本收益非常明显。4. 实操过程与核心环节实现Spring AI集成与本地模型调优4.1 完整项目落地从Maven坐标到Bean装配如果你是从零开始搭这个项目直接贴依赖和骨架代码百试不爽。Spring AI 1.0.0-M6以后的组件都在里程碑仓库里所以Maven的repositories要加一段repositories repository idspring-milestones/id nameSpring Milestones/name urlhttps://repo.spring.io/milestone/url snapshots enabledfalse/enabled /snapshots /repository /repositories dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-react/artifactId version1.0.0-M6/version /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai/artifactId version1.0.0-M6/version /dependency !-- 如果用通义千问就换 spring-ai-qwen 起步依赖 -- /dependencies然后就是最常规但最关键的Bean配置。ChatClient要自己new出来别直接把这个交给容器否则你没法在提示词模板里灵活替换内容。ToolExecutor要从Spring容器里拿工具Bean官方自动装配可以直接注入。Configuration public class AgentConfig { Bean public ReactAgentGenerator reviewAgent( ChatModel chatModel, ReviewTools reviewTools) { ChatClient chatClient ChatClient.builder(chatModel) .defaultSystem(systemPromptText()) // 这里也可以把提示词塞进去 .build(); ToolExecutor toolExecutor new ToolExecutor( chatModel.getObjectMapper(), List.of(reviewTools) // 多个工具类可以都放进来 ); return ReactiveReactAgent.builder() .chatClient(chatClient) .toolExecutor(toolExecutor) .maxIterations(10) .build(); } }这个配置里最容易出问题的点是chatModel.getObjectMapper()。如果这个ObjectMapper和你项目SpringMVC的ObjectMapper不是同一个实例工具参数序列化时可能出现字段缺失或类型转换错。稳妥做法是直接注入ObjectProviderObjectMapper单独给ToolExecutor new一个自己的实例也行但千万别让ToolExecutor用默认ObjectMapper——它在某些版本里不注册JavaTimeModuleLocalDateTime参数直接炸。4.2 本地模型部署与Prompt适配不要说“请”要下命令我这次的实践里审核Agent最初接的是云端模型后来换成了本地Ollama部署的qwen2.5:14b。为什么换因为审核内容涉及商户数据不能出内网这个理由就足够扎实了。但换完就发现一个典型问题本地模型的指令遵循能力明显弱于云端大模型。具体表现是同样一段提示词云端模型会严格遵守JSON输出格式本地模型却偶尔在JSON前后加一段解释文字。这不是模型不行是本地模型的训练对齐度差异。解决办法不是在提示词里加“请务必”这种恳求而是把所有指令改成祈使句增加强制性比如“必须只输出JSON不得输出任何解释”。在输出格式定义里直接给出例子few-shot比instruction有效得多。把系统提示词里的“判定标准”压缩成简单短句列表长段落反而让14B模型抓不住重点。实测下来14B模型在审核判定这种短文本分类任务上准确率能达到云端同prompt的90%以上但延迟从云端模型平均800ms变成本地燃气灶级5秒起。要让生产可用必须加一层本地模型的流式输出视角给前端做成“思考中…”“正在核查黑名单…”的交互节奏用户就没那么焦虑了。4.3 常见的编译期和运行期异常清单这部分全是血泪挑高频的三个说第一个工具参数绑定失败。模型返回的JSON参数和Java方法签名不匹配最常见的是把String传给Integer参数。Spring AI抓到这种错误会抛出ToolExecutionException默认会把异常信息直接喂回给模型让模型“自己纠正”。听起来很智能但部分模型看到异常后直接放弃治疗返回一个“抱歉我无法完成”的FINAL_ANSWER。我的处理是自定义一个ToolErrorHandler捕获异常后把它包成一条友好的内部消息“工具调用参数不合法请尝试其他方式”而不是把原始异常栈给模型。第二个循环不终止。模型在一个工具结果上反复横跳比如先查了黑名单又查规则又查黑名单。原因基本是系统提示词里缺“终止意图”的引导。我给提示词加了一句“当背景信息足够支持你做出判定时立即停止工具调用并输出最终结论”。不要小看这句话它直接把平均迭代次数从7降到了4。第三个并发安全。Agent的execute是线程安全的理论上可以共享单例。但我第一次用的时候在一个Service里注入了ReactAgent多用户并发审核时发现A用户的结果串到了B用户的日志里。排查后确认不是Agent状态泄漏而是我的工具类ReviewTools里用了实例字段缓存中间结果。这个纯粹是水平问题——工具类千万保持无状态所有中间数据都通过参数传递。5. 智能审核场景落地实录从“能跑”到“敢用”5.1 完整审核流程的Agent编排真正进入“智能审核”的生产环境之前我在沙箱里跑了一整套流程这里直接给一套最典型的会话执行轨迹你看了就懂ReactAgent的内部逻辑了。用户提交内容模拟一段化妆品广告文案“本产品使用后7天内皱纹减少50%无效退款。”第1轮Agent收到消息系统提示词要求核查是否符合广告法规范。模型思考输出调用searchBlacklistKeyword文本中是否有“绝对化用语”或“夸大宣传”命中。工具执行结果命中关键词列表返回[无效退款, 7天内皱纹减少50%]。第2轮Agent把上述命中结果作为观察信息重新交给模型。模型思考输出“命中绝对化承诺类关键词需要进一步确认规则RULE_1002。”调用queryRuleEngine(RULE_1002)。工具执行结果返回规则内容“化妆品功效宣传需有医学证据支撑不可使用承诺性用语。禁止使用‘无效退款’。”第3轮Agent把规则内容灌给模型此时模型输出最终答案{result:REJECT, confidence:0.95, reason:广告文案含绝对化承诺用语违反RULE_1002}。整个实际耗时大约7秒本地Ollama模型最终判定准确且稳定。同一段文案扔给纯Prompt对话模型不带任何工具模型会给出PASS——因为14B模型没有外部知识的支撑它不知道规则库里有这条禁令。这就是Agent和Prompt模式的本质差别Prompt只能靠模型记忆Agent可以查证。5.2 与规则引擎的深度整合Agent不是来替代码的我在项目里踩得最深的一个认知坑是团队里有人以为上了ReactAgent之后原来的硬编码审核逻辑就可以扔了。事实完全相反。Agent最适合做的是“需要判断”的分流工作而不是“不需要判断”的批量计算。我的最终架构是三层第一层是原有的硬编码黑名单AC自动机服务一秒能过滤几万条Agent根本不需要介入第二层是Agent动态编排的语义审核负责处理那些黑名单无法覆盖、但规则能解释的内容第三层是规则引擎服务它既被第一层直接调用也被Agent当作工具查询。简单说Agent更像是“先观察再决定把哪些工作交给哪些模块”的调度员而不是把所有计算都抢到自己手里。硬规则是地基Agent是在地基上盖的决策层。这个设计的好处是万一Agent因为模型推理错误给了一个不靠谱的结论最坏情况也就是一次错误分流——但结果还是会被最终的业务校验兜底挡住。生产环境里”AI出错不可怕可怕的是出错没兜底“是铁律。5.3 数据权限与审计审核场景的隐形需求切入审核场景后你会发现Agent业务逻辑写好了还有一个更麻烦的需求每一次自动判定都必须可追溯。监管和客户都会问“你为什么判REJECT”“这个结论的依据是什么”。ReactAgent的FluxAgentResponse设计在这里救了我——每一步包括模型思考、工具调用、工具结果、最终结论它都有结构化记录。我把每一步都落库成一张大宽表字段包括sessionId、stepType、agentName、inputContent、outputContent、toolName、toolArgs、timestamp。前端审核后台可以直接按session回放Agent的“思考轨迹”。这不仅仅是合规需求更是调试利器。实际的审核结论出了问题我不用再盲猜直接把某个session的完整轨迹拉出来看模型是在哪一步“想歪了”秒级定位。这点算是整个方案里性价比最高的一件事。6. 常见问题与排查技巧实录从现象到根因6.1 问题速查表现象排查方向大概率根因Agent完全不调用工具看系统提示词是否写了工具触发条件看ChatModel返回的tool_calls是否为空模型不理解工具描述或者提示词里没有给出使用工具的场景示例工具调用后卡住不输出查看Flux流是否到达OBSERVATION后停止查看ChatModel连接是否超时模型配置了过小的 timeout或者工具结果太大被截断最终答案格式不是JSON检查系统提示词的输出格式是否包含例子检查模型temperature是否过高本地小模型指令遵循弱需要few-shot约束多轮审核结果互相矛盾打开历史案例工具调试看模型是否真的查询了历史库没把历史查询工具说明成“必须使用”模型靠记忆瞎编并发请求工具间数据串场检查工具类是否有实例字段工具类必须是无状态单例不能缓存中间结果6.2 实测排错案例从“正常运行”到“神秘崩溃”最诡异的一次故障是Agent线上运行了半个月某天突然大面积返“REVIEW”结果就是无理由转人工。排查过程如下最开始看日志发现模型每轮都在调queryRuleEngine但返回的规则文本是同一个——看起来没问题。随后检查规则引擎服务发现配置中心推送了一版新规则结果新规则变更了一个字段类型导致Agent工具方法接收参数时反序列化失败。但由于我从ToolErrorHandler里把异常包装成了“请再试一次”的提示模型没注意到错误反而提前终止了循环输出结果自然判定成了REVIEW转人工。这个案例的教训特别大规则引擎的数据结构变更必须做兼容周期或者直接在工具方法里用Map接收参数不要用强类型DTO直接解析外部下发的数据错误处理掩盖错误不一定是对的。如果工具异常提示让模型“再试一次”但模型各玩各的那还是会在生产里依赖到“异常镇定”的运气。更好的做法是异常时不隐藏真实错误短暂进入降级模式——比如直接返回“工具不可用请根据已有信息做保守判定”。6.3 监控与日志不要等出了事再想怎么查生产上了Agent以后我立刻加了三类监控指标第一类是Agent执行次数与平均步数。步数异常升高往往意味着提示词措辞大改后模型变得困惑。第二类是工具调用耗时分布。尤其是规则引擎服务一旦P99超过300msAgent整体延迟会呈线性放大。因为这个过程是串行的一步慢步步慢。第三类是大模型输出失败率通过Spring Boot Actuator的指标暴露后接Prometheus。线上报警取了两个值失败率超过5%直接报警走人工应急方案步数超过8报警提醒去检查提示词是不是被改松了。日志方面每一条Agent执行记录都打一行agent_summary日志包含session、耗时、步数、结果级别。排查问题先看这行再深入Trace效率提升不是一个量级。7. 实操心得ReactAgent这条路值得走但想清楚“边界”再走写到这里我个人在实际操作中体会最深的一点是ReactAgent不是银弹。Spring AI这个实现最出彩的地方是它把Agent收敛成了一个可限制、可观测、可兜底的工程组件。同样一段AI能力它可以把不可控的大模型推理变成受控的“有限步数、有限工具、有限风险”的执行过程。这一点对于任何想在生产环境里接入Agent的Java团队都很关键。我强烈建议你首次接入时务必从“单一审核场景”或“单一客服场景”这种边界清晰的任务开始不要一上来就做一个“万能助手”。我在“或跃在渊”这一章里踩的坑全部来自“想让它处理太多事”。边界设得越窄提示词越好写工具越容易设计模型越不容易跑飞。最后再分享一个小技巧ReactAgent的系统提示词不是固定不变的它是可以随业务动态生成的。我在代码里维护了一个“提示词模板仓库”规则变了、工具加了提示词模板也通过配置中心随时更新。这听起来是很常识的事但绝大多数团队接了Agent后就把提示词当一次性代码写了后面每次调规则都要改代码重新部署体验非常痛苦。把提示词当作一等配置资产来管理你会发现Agent的可维护性直接翻倍。