Java企业级ReAct Agent架构设计：从Demo到生产落地

1. 项目概述：为什么“架构先行”不是口号，而是Java企业级Agent落地的生死线

“架构先行 ReAct 推理基座重构，让企业 Agent 落地”——这个标题里没有一个字在讲模型多大、参数多高、推理多快，它直指Java技术团队在AI浪潮中最真实、最焦灼的困境：我们买了大模型API，写了几个Prompt，调通了工具链，甚至跑出了Demo，可为什么半年过去，它还在测试环境吃灰？为什么业务方说“看不懂AI怎么想的”，运维说“一出问题全链路黑盒”，安全团队直接叫停上线？答案就藏在这八个字里：“架构先行”。这不是工程美学的修饰词，而是Java生态下AI Agent能否从PPT走进生产系统的分水岭。ReAct本身是方法论，是Reason（推理）与Act（行动）的闭环，但把它塞进Spring Boot里、和MySQL事务绑在一起、跟XXL-JOB定时任务混着跑，不加抽象、不设边界、不控流程，那它就是个披着智能外衣的脆弱脚本。JBoltAI v4.4的这次重构，本质上是一次面向企业级交付的“外科手术”：把原本长在业务代码里的ReAct逻辑，连根拔起，移植到一个独立、稳定、可审计的基座上。这个基座不处理具体业务，只干四件事：定义思考的节奏、规范行动的契约、统一观察的格式、记录每一步的指纹。它像一座桥，一端连着业务开发者的敏捷迭代，另一端连着企业对稳定性、可观测性、合规性的刚性要求。你不需要懂LLM的梯度下降，但必须理解为什么AbstractReActChain要继承自Chain而非直接实现Runnable；你不必手写AST解析器，但得清楚剥离图表生成逻辑后，DataChatChain如何通过SPI机制动态加载不同渲染引擎。这背后是Java工程师最熟悉的语言：解耦、抽象、契约、可插拔。当你的Agent能在一个事务里完成数据库查询、调用外部风控服务、生成PDF报告并自动归档，而整个过程的每一步都能被日志追踪、被监控告警、被审计系统抓取原始输入输出时，“AI落地”才从一句愿景，变成了一行可部署、可运维、可追责的代码。

2. 内容整体设计与思路拆解：从“能跑通”到“敢上线”的四重架构跃迁

2.1 为什么传统ReAct实现注定在企业场景中“短命”

很多团队第一次尝试ReAct，往往是从一个简单的Spring Boot Controller开始的：接收用户Query，拼接Prompt，调用大模型API，解析返回的JSON Action指令，再根据指令去查DB或调HTTP，最后把结果塞回Response。这个流程在Demo阶段丝滑无比，但一旦接入真实业务，三周内必现三大症状：第一，逻辑污染——为了适配某个报表需求，硬编码了Excel导出逻辑，导致下次做知识库问答时，代码里赫然出现if (type.equals("report")) { exportToExcel(...) }；第二，状态失控——ReAct的Thought-Action-Observation循环本该是原子操作，但在分布式环境下，一次Action可能跨多个微服务，中间某步失败，整个推理链就卡死，既无法回滚，也无法续跑；第三，审计失明——安全审计要求留存所有AI决策依据，但你的日志里只有[INFO] call llm api success，没有Thought原文、没有Action参数、没有Observation原始数据。这些不是Bug，而是架构缺失的必然结果。ReAct范式天然要求“过程即价值”，而Java企业应用的核心诉求是“过程即资产”。两者若不通过架构对齐，技术债会指数级增长。JBoltAI v4.4的重构，正是从这三大症状反向推导出的四重跃迁路径。

2.2 第一重跃迁：从“功能堆砌”到“基座抽象”——定义ReAct的“Java语法”

在Java世界里，没有抽象就没有复用，没有契约就没有协作。v4.4抽取的AbstractReActChain，其核心价值远不止于“减少重复代码”。它强制定义了ReAct的四个Java级契约：

• protected abstract Thought generateThought(String input, Context context)：规定“思考”必须产出结构化Thought对象，而非字符串拼接。Thought类里封装了reasoningSteps（推理步骤列表）、plannedActions（预判动作列表）、confidenceScore（置信度），这为后续的审计追溯提供了结构化数据源。
• protected abstract <T> T executeAction(Action action, Context context)：规定“行动”必须通过Action接口执行，Action接口强制包含toolName、parameters、timeoutMs三个字段。这意味着任何工具调用，无论是查ES还是调飞书机器人，都必须先注册到ToolRegistry，且超时时间由基座统一管控，杜绝了RestTemplate裸调导致的线程池耗尽。
• protected abstract Observation parseObservation(Object rawResult, Action action)：规定“观察”必须将原始响应（可能是JSON、XML、二进制流）标准化为Observation对象，其中rawContent存原始数据，parsedContent存解析后结构体，errorInfo存异常堆栈。这解决了企业最头疼的“结果不可信”问题——业务方质疑AI结论时，可直接比对rawContent与parsedContent，确认是模型幻觉还是解析错误。
• public final ChainResult run(String input, Context context)：提供final的run方法，固化“思考→行动→观察→循环”主流程，并在每步前后注入beforeStep()/afterStep()钩子。这个final方法是基座的“宪法”，任何子类都不能绕过它去自定义流程，从而保证了所有Agent行为的可预测性。

这个抽象层的价值，在于它把ReAct从一种LLM Prompt技巧，升格为Java应用中的一等公民。它不再依赖开发者对Prompt Engineering的个人经验，而是依赖对Java接口契约的理解。一个刚毕业的实习生，只要会写@Override generateThought，就能贡献一个新Agent，因为基座已替他扛下了线程安全、重试策略、熔断降级等企业级难题。

2.3 第二重跃迁：从“单体耦合”到“能力解耦”——让每个模块都“各司其职”

早期Agent项目常犯一个致命错误：把“能做什么”和“怎么做”混为一谈。比如一个“智能问数”Agent，代码里同时存在SQL生成逻辑、JDBC连接管理、ECharts图表渲染、PDF导出工具调用。这种写法在单机Demo时无懈可击，但放到企业级场景，立刻暴露出三个硬伤：第一，变更风险高——业务要求新增一个“导出为CSV”功能，你得动SQL生成、JDBC、图表、PDF四块代码，任何一个环节出错，整个Agent就挂；第二，技术栈绑架——图表渲染用了ECharts，但前端团队明年要切Vue3+Vite，你得重写所有图表逻辑；第三，能力复用难——知识库检索Agent也需要PDF导出，但你只能复制粘贴那段代码，或者搞个CommonUtils.exportPdf()，结果PDF版本升级，两个Agent同时崩。v4.4的解耦设计，是用Java最朴素的“组合优于继承”原则，构建了一个能力矩阵：

• 推理基座（AbstractReActChain）：只负责流程控制，不碰任何业务逻辑。
• 工具中心（ToolRegistry）：所有外部能力（DB查询、API调用、文件处理）都以Tool接口形式注册，Tool实现类只专注一件事，比如JdbcQueryTool只管SQL执行与结果映射，PdfExportTool只管模板填充与流生成。
• 渲染引擎（RenderEngine）：图表、PDF、Markdown等所有输出格式，都通过RenderEngineSPI接口接入。业务方选型时，只需在application.yml里配置render-engine: echarts或render-engine: chartjs，无需改一行Java代码。
• 上下文管理（ContextManager）：负责跨步骤传递数据，如用户Session、权限Token、事务ID。它采用ThreadLocal+InheritableThreadLocal双模式，确保在@Async异步调用或CompletableFuture链式调用中，Context仍能准确透传。

这种解耦带来的直接好处是：当安全团队要求所有PDF导出必须添加水印时，你只需修改PdfExportTool一个类；当运维要求所有外部调用必须增加OpenTelemetry TraceID时，你只需在ToolRegistry的execute方法里统一注入。所有变更都被严格限制在单一模块内，这是企业级系统可持续演进的生命线。

2.4 第三重跃迁：从“黑盒执行”到“白盒可观测”——把推理过程变成可审计的“数字证据”

企业不敢用AI，核心痛点从来不是“不准”，而是“不知为何不准”。审计部门要的不是“AI说张三信用分低”，而是“AI基于哪三条征信记录、运用什么规则、参考哪个模型版本，得出此结论”。v4.4的可视化落地，绝非前端加个进度条那么简单，它是一套贯穿全链路的可观测性基建：

• 推理步骤追踪（StepTrace）：每次run()调用，基座自动生成唯一traceId，并在每一步generateThought、executeAction、parseObservation时，创建StepRecord对象，记录stepId、stepType（THOUGHT/ACTION/OBSERVATION）、startTime、endTime、input、output、errorStack。这些记录默认写入内存环形缓冲区，可通过Actuator端点/actuator/reaction-trace/{traceId}实时查询。
• 结构化日志（StructuredLogging）：所有StepRecord不走log.info()，而是通过MDC注入traceId、stepId，并序列化为JSON格式输出。一条典型日志长这样：

  { "timestamp": "2026-05-27T18:17:21.123Z", "level": "INFO", "thread": "http-nio-8080-exec-5", "traceId": "tr-7a8b9c0d1e2f3a4b", "stepId": "st-1", "stepType": "THOUGHT", "input": "用户问：上季度华东区销售额Top3的产品是什么？", "output": { "reasoningSteps": ["需查询sales_data表", "按region='华东' and quarter='Q3'过滤", "按amount降序取前3"], "plannedActions": [{"toolName":"jdbc-query","parameters":{"sql":"SELECT product_name FROM sales_data WHERE region='华东' AND quarter='Q3' ORDER BY amount DESC LIMIT 3"}}] } }

  这种日志可被ELK或Splunk直接索引，审计人员用KQL一句traceId: "tr-7a8b9c0d1e2f3a4b"就能拉出完整推理链。
• 前端实时渲染（LiveRendering）：前端通过SSE（Server-Sent Events）订阅/api/v1/agent/trace/{traceId}/stream，基座在每步afterStep()时推送JSON事件。前端用React Flow渲染思维导图，节点颜色区分Thought（蓝色）、Action（绿色）、Observation（橙色），连线标注耗时。业务方看到的不再是“Loading...”，而是“正在分析问题（0.2s）→ 正在查询数据库（1.8s）→ 正在生成图表（0.5s）”，每一个环节都透明、可质疑、可验证。

这套可观测体系，让AI从“黑盒决策者”转变为“透明协作者”。当业务方质疑“为什么没查华南区”，你可以直接打开Trace，指出Thought里明确写了region='华东'，问题出在用户输入歧义，而非AI错误。这种确定性，是企业AI落地的信任基石。

2.5 第四重跃迁：从“功能可用”到“生产就绪”——补齐企业级的最后一块拼图

很多技术人认为，只要功能跑通，剩下的就是“运维的事”。但在Java企业环境，安全、性能、稳定性从来不是附加题，而是入场券。v4.4在场景与安全上的双重优化，全是踩坑后淬炼出的硬核经验：

• 无结果友好反馈（Null-Safe Response）：大模型在复杂Prompt下常出现“思考正确但行动失败”的情况，比如Thought规划了查DB，但Action参数拼错导致SQL异常，最终返回空。传统做法是抛出500错误，用户看到一片空白。v4.4在afterStep()钩子里植入了智能兜底：当Observation.errorInfo非空且parsedContent为空时，基座自动触发fallbackStrategy，生成人性化提示：“未找到符合条件的数据，建议检查区域名称是否准确，或尝试更宽泛的查询条件”。这背后是FallbackRendererSPI的灵活扩展，业务方可以自定义不同场景的兜底文案。
• JWT认证体系重构（Stateless Auth）：旧版JWT校验在每次Action前都调用JwtDecoder解码，性能瓶颈明显。v4.4改为在ContextManager初始化时一次性解码，将userId、roles、permissions缓存到Context对象中，后续所有工具调用直接读取缓存值。实测QPS从800提升至2400。更关键的是，所有敏感字段（如手机号、身份证号）在写入日志前，由SensitiveDataFilter统一脱敏，规则可配置，避免审计翻车。
• 权限系统加固（RBAC+ABAC）：修复了旧版角色匹配的N+1查询问题，将权限校验从@PreAuthorize注解下沉到Tool执行前。JdbcQueryTool会校验当前用户是否有query:sales_data权限；PdfExportTool则结合ABAC策略，判断context.get("dataLevel") == "CONFIDENTIAL"时禁止导出。这种细粒度控制，让AI Agent真正融入企业现有安全体系。

这第四重跃迁，把ReAct从一个“能工作的算法”，变成了一个“可交付的企业级产品”。它不再需要额外的“运维适配层”，开箱即用，符合Java团队对生产环境的所有预期。

3. 核心细节解析与实操要点：读懂AbstractReActChain的每一行设计哲学

3.1 AbstractReActChain的骨架：为什么final run()是不可动摇的“宪法”

AbstractReActChain的public final ChainResult run(String input, Context context)方法，是整个架构的“心脏起搏器”。它的final修饰符不是为了防继承，而是为了防破坏。我们来逐行拆解这个方法的精妙设计：

public final ChainResult run(String input, Context context) { // 1. 初始化全局上下文，注入traceId、startTime等元数据 Context initContext = initGlobalContext(context); // 2. 创建推理链执行器，支持同步/异步/流式三种模式 ChainExecutor executor = createExecutor(initContext); // 3. 执行主循环，最大迭代次数由配置项re-act.max-loop控制 ChainResult result = executor.execute(input, (currentInput, currentContext) -> { // 4. 每一步前，记录StepRecord并触发beforeStep钩子 StepRecord thoughtRecord = beforeStep(StepType.THOUGHT, currentInput, currentContext); // 5. 执行思考，生成Thought对象 Thought thought = generateThought(currentInput, currentContext); // 6. 记录Thought输出，并触发afterStep钩子 afterStep(thoughtRecord, thought, currentContext); // 7. 判断是否终止：Thought里有finalAnswer字段，或达到最大迭代次数 if (thought.hasFinalAnswer()) { return new ChainResult(thought.getFinalAnswer(), true); } // 8. 否则执行Action StepRecord actionRecord = beforeStep(StepType.ACTION, thought.toString(), currentContext); Action action = thought.getPlannedAction(); Object rawResult = executeAction(action, currentContext); Observation observation = parseObservation(rawResult, action); afterStep(actionRecord, observation, currentContext); // 9. 将Observation作为下一轮输入，继续循环 return new ChainResult(observation.getParsedContent().toString(), false); }); // 10. 最终清理资源，如关闭数据库连接、释放内存 cleanupResources(initContext); return result; }

这段代码的每一个数字标注，都对应一个企业级设计考量：

• 第1步的initGlobalContext：不是简单new Context()，而是从ContextManager获取一个预置了traceId（UUID生成）、startTime（System.nanoTime()）、tenantId（从RequestHeader提取）的Context。这保证了即使Agent内部启动了10个异步线程，所有日志、监控指标都归属同一个trace。
• 第2步的createExecutor：根据context.get("executionMode")动态选择SyncChainExecutor、AsyncChainExecutor或StreamingChainExecutor。比如智能问数场景用同步模式保证强一致性，而知识库摘要场景用流式模式，让用户看到“正在阅读第1/50页文档”的实时反馈。
• 第3步的max-loop配置：硬编码为5，这是经过200+真实业务case压测得出的黄金值。少于5步，复杂任务无法完成；多于5步，模型幻觉概率陡增。配置项re-act.max-loop=5写在application.yml里，运维可热更新。
• 第4、6步的beforeStep/afterStep：这两个钩子是可观测性的入口。beforeStep创建StepRecord并写入内存缓冲区；afterStep则将StepRecord的endTime、output、errorStack补全，并触发StepTraceListener事件（可监听发送到Kafka供审计）。
• 第7步的hasFinalAnswer判断：Thought类里有一个finalAnswer字段，类型为Optional<String>。基座强制要求：只有当Thought明确设置了finalAnswer，才终止循环。这杜绝了“模型胡说八道还强行结束”的情况。如果Thought没设finalAnswer，基座会自动将observation.parsedContent转为字符串，作为下一轮currentInput，形成真正的闭环。

这个final方法的设计哲学是：把最易出错、最需统一的流程，锁死在基座里；把最需定制、最富业务价值的部分，开放给子类实现。它像Java的Collections.sort()，你永远不能重写排序算法，但可以自由定义Comparator。

3.2 ToolRegistry的注册机制：如何让“调用外部服务”变得像调用本地方法一样安全

ToolRegistry是ReAct Agent的“手脚”，它的设计直接决定了Agent的健壮性。v4.4的注册机制，彻底摒弃了“手动new Tool()再put到Map”的原始做法，采用Spring Boot原生的@Component+@Order自动装配：

@Component @Order(1) public class JdbcQueryTool implements Tool { @Autowired private JdbcTemplate jdbcTemplate; @Override public String getToolName() { return "jdbc-query"; // 必须与Thought中plannedAction.toolName完全一致 } @Override public Object execute(Map<String, Object> parameters, Context context) throws ToolException { // 1. 权限校验：从Context中提取userId，查询RBAC权限表 if (!permissionService.hasPermission(context.getUserId(), "query:db")) { throw new ToolException("No permission to query database"); } // 2. 参数校验：使用JSR-303注解，自动校验parameters合法性 JdbcQueryParams params = new JdbcQueryParams(); BeanUtils.copyProperties(parameters, params); Set<ConstraintViolation<JdbcQueryParams>> violations = validator.validate(params); if (!violations.isEmpty()) { throw new ToolException("Invalid parameters: " + violations); } // 3. 执行SQL，自动开启事务（如果Context中声明了transactionRequired） TransactionStatus status = null; try { if (context.isTransactionRequired()) { status = transactionManager.getTransaction(new DefaultTransactionDefinition()); } List<Map<String, Object>> result = jdbcTemplate.queryForList(params.getSql(), params.getArgs()); return result; } catch (Exception e) { if (status != null) { transactionManager.rollback(status); } throw new ToolException("JDBC query failed", e); } } }

这个JdbcQueryTool的实现，体现了企业级Tool的三大铁律：

• 契约优先：getToolName()返回的字符串，是Thought中toolName的唯一标识。基座在executeAction时，通过toolRegistry.getTool(action.getToolName())精准匹配，不存在“找不到工具”的运行时异常。
• 安全内建：权限校验、参数校验、事务管理全部内嵌在Tool内部，而非由基座或业务代码调用。这意味着，无论哪个Agent调用jdbc-query，都自动享有同一套安全策略。运维只需修改JdbcQueryTool，所有Agent立即生效。
• 错误归一：所有异常都包装为ToolException，它继承自RuntimeException，但携带errorCode、errorMessage、suggestion三个字段。基座捕获后，会将errorCode写入StepRecord.errorCode，供监控系统按错误码聚合告警。比如TOOL_JDBC_TIMEOUT表示数据库超时，TOOL_PERMISSION_DENIED表示权限不足。

这种设计让Tool注册从“手工配置”变为“零配置发现”。你只需写一个@Component类，Spring Boot启动时自动扫描、自动注册、自动排序（@Order控制执行优先级）。当业务需要新增一个FeignApiTool调用内部微服务时，代码结构完全一致，只是execute方法里换成feignClient.invoke(...)。这种一致性，是团队规模化协作的基础。

3.3 ContextManager的上下文透传：解决分布式环境下“我在哪、我是谁、我要干什么”的终极方案

ReAct的Thought-Action-Observation循环，本质是一个有状态的长事务。但在Spring Cloud微服务架构下，一次Agent调用可能横跨API网关、认证服务、Agent服务、数据服务、文件服务等多个进程。如何保证userId、tenantId、traceId等关键上下文，在跨进程、跨线程、跨异步调用时不丢失？v4.4的ContextManager给出了教科书级答案：

• ThreadLocal基础层：在initGlobalContext()中，将Context对象存入ThreadLocal<Context>。这是单线程内的基石，保证同一线程内所有代码共享同一Context。
• InheritableThreadLocal增强层：当Agent内部启动@Async任务（如异步生成PDF），ThreadLocal会失效。ContextManager重写了InheritableThreadLocal的childValue()方法，确保子线程创建时，自动拷贝父线程的Context副本。
• CompletableFuture适配层：对于supplyAsync()、thenApply()等链式异步调用，ContextManager提供了ContextAwareCompletableFuture包装器：

  public static <U> CompletableFuture<U> supplyAsyncWithContext( Supplier<U> supplier, Context context) { // 在调用前，将context绑定到当前线程 ContextManager.setContext(context); try { return CompletableFuture.supplyAsync(supplier) .whenComplete((result, throwable) -> { // 异步完成后，清理线程局部变量 ContextManager.clearContext(); }); } finally { // 确保即使supplier抛异常，context也被清理 ContextManager.clearContext(); } }

• 跨进程传播层：在Tool执行HTTP调用时（如调用飞书机器人API），ContextManager自动将traceId、userId、tenantId注入HTTP Header：

  HttpHeaders headers = new HttpHeaders(); headers.set("X-Trace-ID", context.getTraceId()); headers.set("X-User-ID", context.getUserId()); headers.set("X-Tenant-ID", context.getTenantId());

  对端服务（如飞书机器人）只需在Filter里读取这些Header，调用ContextManager.setContextFromHeaders(headers)，即可重建Context。

这套四层透传机制，让Context像空气一样无处不在。业务开发者写代码时，只需context.getUserId()，完全不用关心它来自哪里、如何传递。当运维在SkyWalking里看到一条完整的调用链，从API网关→Agent服务→JDBC查询→PDF生成，所有Span都带着同一个traceId和userId时，这就是架构设计成功的最直观证明。

3.4 RenderEngine的SPI扩展：为什么图表渲染不该是Agent的“亲儿子”

在v4.4之前，DataChatChain的代码里充斥着if (chartType.equals("bar")) { renderBarChart(...) } else if (chartType.equals("pie")) { renderPieChart(...) }。这种写法的问题在于：图表逻辑与推理逻辑深度耦合，前端换框架、业务换需求、安全加水印，都得动Agent核心代码。v4.4用Java SPI（Service Provider Interface）彻底解耦：

• 定义SPI接口：

  public interface RenderEngine { String getName(); // 如 "echarts", "chartjs" byte[] render(ChartSpec spec, Context context) throws RenderException; boolean supports(ChartType type); // 支持的图表类型 }

• 提供默认实现：EchartsRenderEngine、ChartJsRenderEngine、PdfRenderEngine各自打包为独立jar，通过META-INF/services/com.jboltai.render.RenderEngine文件声明。
• 运行时动态加载：RenderEngineFactory在启动时扫描所有jar，根据application.yml配置的render-engine: echarts，加载对应实现。

这种设计带来的实操价值是颠覆性的：

• 前端技术栈自由切换：当公司决定从Vue2+ECharts迁移到Vue3+AntV时，前端团队只需发布一个新的AntVRenderEnginejar包，运维在配置中心把render-engine改成antv，重启Agent服务，所有图表自动焕然一新，Agent代码一行不改。
• 安全合规一键落地：安全团队要求所有PDF必须添加公司水印。PdfRenderEngine的render()方法里，只需在生成PDF流前，插入addWatermark(pdfDocument)一行代码。发布新jar包，全量Agent自动获得水印能力。
• A/B测试成为可能：RenderEngineFactory可配置render-engine-strategy: weighted，按权重分发请求。比如70%流量走EchartsRenderEngine，30%走ChartJsRenderEngine，对比用户点击率、加载时长，用数据驱动技术选型。

这印证了一个朴素真理：在企业级系统中，最强大的功能，往往不是写出来的，而是组装出来的。SPI机制让Agent从“单体应用”进化为“能力平台”，这是架构先行最深刻的体现。

4. 实操过程与核心环节实现：从零搭建一个可审计的ReAct Agent

4.1 环境准备与依赖引入：用最简配置启动企业级Agent基座

搭建v4.4 ReAct基座，第一步不是写代码，而是配置好“生产就绪”的基础设施。我们以Spring Boot 3.2 + Java 17为基准，给出最小可行配置：

• pom.xml核心依赖：

  <dependencies> <!-- JBoltAI ReAct基座核心 --> <dependency> <groupId>com.jboltai</groupId> <artifactId>jboltai-react-core</artifactId> <version>4.4.0</version> </dependency> <!-- Spring Boot Web与Actuator（必备监控） --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency> <!-- 数据库连接池（HikariCP） --> <dependency> <groupId>com.h2database</groupId> <artifactId>h2</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-jdbc</artifactId> </dependency> <!-- OpenTelemetry观测性（可选但强烈推荐） --> <dependency> <groupId>io.opentelemetry.instrumentation</groupId> <artifactId>opentelemetry-spring-boot-starter</artifactId> </dependency> </dependencies>

  关键点说明：

  • jboltai-react-core是v4.4的基座jar，它不包含任何具体业务逻辑，只提供AbstractReActChain、Tool、Context等核心抽象。
  • spring-boot-starter-actuator是企业级运维的生命线，它暴露了/actuator/reaction-trace端点，让审计人员能随时查询任意trace。
  • H2数据库是演示首选，但生产环境请务必替换为MySQL/PostgreSQL，并在application.yml中配置连接池参数（spring.datasource.hikari.*）。

• application.yml最小配置：

  server: port: 8080 spring: datasource: url: jdbc:h2:mem:testdb driver-class-name: org.h2.Driver username: sa password: password h2: console: enabled: true # 开启H2 Console，方便调试 # JBoltAI ReAct核心配置 jboltai: react: max-loop: 5 # ReAct最大迭代次数 timeout-ms: 30000 # 全局超时30秒 tool: default-timeout-ms: 10000 # 工具默认超时10秒 render-engine: echarts # 默认渲染引擎 # Actuator端点暴露 management: endpoints: web: exposure: include: health,info,metrics,threaddump,reaction-trace endpoint: reaction-trace: show-details: ALWAYS

  这份配置的精妙之处在于：它没有一行是关于“AI模型”的。jboltai.react下的所有配置，都是围绕流程控制、超时管理、可观测性展开的。这再次印证了“架构先行”的真谛——先搭好舞台，再请演员登台。

4.2 编写第一个ReAct Agent：知识检索型AgentRAG的完整实现

现在，我们基于AbstractReActChain，实现一个最典型的Agent：知识检索（AgentRAG）。它能接收用户自然语言提问，从向量数据库中检索相关文档片段，再让大模型生成答案。整个过程必须全程可追溯。

• Step 1：定义AgentRAG类

  @Component public class AgentRAG extends AbstractReActChain { @Autowired private VectorStore vectorStore; // 向量数据库客户端 @Autowired private LlmClient llmClient; // 大模型API客户端 @Override protected Thought generateThought(String input, Context context) { // 1. 从Context中提取用户ID、租户ID，用于向量检索的权限过滤 String userId = context.getUserId(); String tenantId = context.getTenantId(); // 2. 构建检索Query：将用户输入转为向量，并添加租户过滤条件 VectorQuery query = VectorQuery.builder() .text(input) .tenantId(tenantId) .topK(3) .build(); // 3. 执行向量检索，获取最相关的3个文档片段 List<DocumentChunk> chunks = vectorStore.search(query); // 4. 生成Thought：明确写出检索逻辑、返回的chunk ID，为审计留痕 return Thought.builder() .reasoningSteps(Arrays.asList( "将用户输入'" + input + "'向量化", "在租户" + tenantId + "的知识库中检索相似文档", "获取到" + chunks.size() + "个相关片段，ID为：" + chunks.stream().map(DocumentChunk::getId).collect(Collectors.joining(",")) )) .plannedActions(Collections.singletonList( Action.builder() .toolName("llm-generate") .parameters(Map.of("prompt", buildPrompt(input, chunks))) .build() )) .build(); } @Override protected <T> T executeAction(Action action, Context context) { // AgentRAG只调用llm-generate工具，其他Action由基座路由 if ("llm-generate".equals(action.getToolName())) { return (T) llmClient.generate((String) action.getParameters().get("prompt")); } throw new IllegalArgumentException("Unsupported tool: " + action.getToolName()); } @Override protected Observation parseObservation(Object rawResult, Action action) { // 将大模型返回的原始字符串，解析为结构化Observation String response = (String) rawResult; return Observation.builder() .rawContent(response) .parsedContent(Map.of("answer", response)) .build(); } // 辅助方法：构建Prompt，包含检索到的文档片段 private String buildPrompt(String userInput, List<DocumentChunk> chunks) { StringBuilder prompt = new StringBuilder(); prompt.append("你是一个专业的知识助手，请根据以下参考资料回答问题。\n\n"); for (int i = 0; i < chunks.size(); i++) { prompt.append("参考资料").append(i + 1).append("：\n") .append(chunks.get(i).getContent()).append("\n\n"); } prompt.append("问题：").append(userInput).append("\n\n"); prompt.append("请直接给出答案，不要解释推理过程。");