Java工程师转型AI Agent实战：从ReAct循环到生产级落地

1. Java 工程师转型 AI Agent 的底层逻辑与认知重构1.1 为什么 Java 工程师转 AI Agent 有天然优势很多 Java 工程师一听到 AI Agent 就觉得那是 Python 的天下跟自己没什么关系。我一开始也这么想直到真正动手做了两个企业级 Agent 项目之后才发现Java 工程师在这个领域其实有被严重低估的优势。先说最核心的一点AI Agent 的本质是一个分布式系统问题而不是一个算法问题。大模型负责推理但 Agent 要解决的是任务编排、状态管理、工具调用、异常重试、并发控制、可观测性——这些东西恰好是 Java 工程师干了十几年的老本行。你想想一个 Agent 要调用外部 API、要维护会话上下文、要做超时熔断、要记录每一步的执行链路这不就是一个微服务编排的场景吗只不过把原来的业务服务换成了 LLM 和 Tool。第二个优势是工程化能力。Python 生态在 AI 领域确实繁荣但很多 Python 项目在类型安全、依赖管理、并发模型、生产部署上是有短板的。Java 的强类型、成熟的构建工具链、Spring 生态的依赖注入和 AOP、JVM 的线程模型和内存管理这些在把 Agent 从 Demo 推向生产的过程中价值巨大。我见过太多 Python 写的 Agent Demo 很惊艳但一上生产就各种问题而 Java 工程师天然就会考虑这些。第三个优势是存量系统集成。国内绝大多数企业的核心业务系统是 Java 写的订单、库存、CRM、ERP 全是 Spring Boot 服务。你要在这些系统上叠加 AI 能力用 Java 直接集成比跨语言调用要顺畅得多。这也是为什么 Spring AI 和 LangChain4j 这两个 Java 生态的框架值得重点关注。1.2 AI Agent 到底是什么抛开概念看本质网上关于 AI Agent 的定义五花八门我用人话给你拆一下。一个 Agent 最小可用的形态就是三样东西一个能推理的大脑LLM、一组能干活的手Tool、一个能记住事情的笔记本Memory。然后外面套一个循环让大脑不断决定下一步该干什么直到任务完成。这个循环最经典的实现就是ReAct 模式Reasoning Acting。它的逻辑特别朴素让模型先想一步Thought决定要调用哪个工具Action拿到工具返回的结果Observation再基于结果继续想下一步如此往复。你可以把它理解成一个 while 循环循环体里就是问模型下一步干啥 → 执行 → 把结果喂回去。为什么 ReAct 这么重要因为它解决了纯 LLM 的两个致命问题一是幻觉模型不知道的事情会瞎编但有了工具它就能去查真实数据二是时效性和私有数据模型训练数据有截止日期也不知道你公司的内部信息但通过工具调用就能突破这个限制。理解了这一点你就明白 Java 工程师要做的事情是什么了把这个循环用 Java 健壮地实现出来把工具调用做得安全可靠把状态管理做得清晰可维护。至于模型本身调用 API 就行了不需要你去训练。1.3 技术选型Spring AI 还是 LangChain4j这是被问得最多的问题我直接给结论再解释。维度Spring AILangChain4j定位Spring 生态原生集成对标 Python LangChain上手难度低Spring 开发者无缝中概念较多抽象层次偏底层灵活偏高层开箱即用Agent 支持逐步完善中相对成熟生态整合Spring Boot 全家桶独立可整合任意框架适合场景已有 Spring 体系的企业快速验证、复杂 Agent我的实际选择逻辑是这样的如果你的项目已经是 Spring Boot 体系团队都是 Spring 背景优先 Spring AI因为学习成本最低依赖注入、配置管理、可观测性都能复用现有基建。如果你要快速搭一个复杂的多 Agent 系统或者需要 RAG、工具调用、记忆管理这些开箱即用的能力LangChain4j 更省事。至于网上有人问的 LangGraph4j那是做有状态、有分支、有循环的复杂工作流用的属于进阶需求。新手别一上来就搞这个先把单 Agent 的 ReAct 循环跑通再说。提示不要纠结选哪个框架两个都学一下 API 风格实际项目里按团队技术栈选。框架只是脚手架核心的 Agent 设计思想是通用的。2. 从零搭建第一个 Java AI Agent 的核心细节2.1 环境准备与依赖选型我以 Spring AI 为例因为大部分 Java 工程师的起点都是 Spring Boot。先看依赖这里有个坑要提前说Spring AI 的版本迭代很快不同版本 API 差异不小一定要锁定版本。dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version1.0.0-M4/version /dependency配置文件里配好模型接入信息注意 API Key 千万别硬编码进代码用环境变量或者配置中心spring: ai: openai: api-key: ${AI_API_KEY} base-url: ${AI_BASE_URL} chat: options: model: gpt-4o-mini temperature: 0.7这里解释几个关键参数。temperature控制输出的随机性做 Agent 的时候我建议调低一点0.2 到 0.5 之间因为 Agent 需要稳定地做决策太随机会导致工具选择飘忽不定。model的选择上做 Agent 不要一味追求最强模型因为 Agent 会多次调用模型成本和延迟会放大用中等能力的模型配合好的 Prompt 往往性价比更高。2.2 工具Tool的定义Agent 的手怎么造工具是 Agent 能力的边界你能调用什么工具Agent 就能干什么事。在 Spring AI 里定义工具很直观用注解就行Component public class WeatherTools { Tool(description 查询指定城市的实时天气输入城市名称返回温度和天气状况) public String getWeather(ToolParam(description 城市名称如北京) String city) { // 实际调用天气 API return weatherApi.query(city); } }这里有个极其重要的经验description写得好不好直接决定 Agent 能不能正确调用工具。模型是靠这段描述来判断什么时候该用这个工具的所以描述要写清楚三件事——这个工具干什么、什么场景下用、输入参数是什么格式。我踩过的坑就是描述写得太简略结果模型该调用的时候不调用不该调用的时候乱调用。再分享一个进阶技巧工具粒度要适中。太粗一个工具干太多事模型不好控制太细工具数量爆炸模型选择困难。我的经验是单个工具只做一件明确的事工具总数控制在 10 个以内超过就要考虑分组或者用子 Agent 来管理。2.3 手写一个 ReAct 循环理解 Agent 的心跳框架封装得再好我也建议你手写一遍 ReAct 循环这样你才能真正理解 Agent 在干什么。下面是一个简化版的核心逻辑public String runAgent(String userInput, int maxSteps) { ListMessage messages new ArrayList(); messages.add(new SystemMessage(SYSTEM_PROMPT)); messages.add(new UserMessage(userInput)); for (int step 0; step maxSteps; step) { // 1. 让模型思考并决定下一步 ChatResponse response chatModel.call(new Prompt(messages)); String output response.getResult().getOutput().getContent(); // 2. 判断是否要调用工具 if (isFinalAnswer(output)) { return extractAnswer(output); } // 3. 解析工具调用执行工具 ToolCall toolCall parseToolCall(output); String observation executeTool(toolCall); // 4. 把模型的思考和工具结果都加回上下文 messages.add(new AssistantMessage(output)); messages.add(new ToolResponseMessage(observation)); } return 达到最大步数限制任务未完成; }这段代码里有几个关键设计点值得展开。maxSteps 是必须的防止 Agent 陷入死循环我一般设 10 到 15 步复杂任务可以放宽。System Prompt 是灵魂要明确告诉模型它的角色、可用工具、输出格式要求。上下文管理是难点每轮都把历史消息加回去token 会迅速膨胀后面我会专门讲怎么优化。2.4 Prompt 工程Agent 的说明书怎么写很多人低估了 Prompt 在 Agent 里的作用觉得随便写写就行。实际上Agent 的 Prompt 就是它的行为规范写得好坏直接决定成败。一个合格的 Agent System Prompt 至少包含这几块角色定义你是谁你的职责是什么工具清单有哪些工具分别什么时候用输出格式必须按什么格式输出方便程序解析约束条件不能做什么遇到什么情况要停下来示例给一两个完整的思考-行动示例我常用的输出格式约定是这样的让模型输出结构化的内容方便解析Thought: 我需要先查询天气 Action: getWeather Action Input: {city: 北京}然后程序用正则或者 JSON 解析器提取 Action 和 Action Input。这里要注意不同模型对格式的遵循程度不一样有些模型会自作主张加一些额外内容所以解析逻辑要写得健壮解析失败要有兜底策略。3. 生产级 Agent 的关键能力实现3.1 记忆管理让 Agent 记住上下文又不爆 tokenAgent 的记忆分短期和长期。短期记忆就是当前会话的上下文长期记忆是跨会话的知识。新手最容易犯的错就是把所有历史消息一股脑塞给模型结果 token 爆炸、成本飙升、还容易超出上下文窗口。我的处理策略是分层管理。最近几轮对话保留原文更早的对话做摘要压缩。具体做法是维护一个滑动窗口窗口内保留完整消息窗口外的消息定期用模型总结成一段摘要替换掉原始消息。public ListMessage buildContext(ListMessage history, int windowSize) { if (history.size() windowSize) { return history; } // 窗口外的做摘要 ListMessage oldMessages history.subList(0, history.size() - windowSize); String summary summarize(oldMessages); ListMessage result new ArrayList(); result.add(new SystemMessage(以下是之前对话的摘要 summary)); result.addAll(history.subList(history.size() - windowSize, history.size())); return result; }长期记忆我一般用向量数据库存把重要的信息、用户偏好、历史结论向量化存起来需要的时候做相似度检索召回。LangChain4j 里这块封装得比较好Spring AI 也有对应的 VectorStore 抽象。注意摘要本身也是一次模型调用有成本。不要每轮都摘要可以按消息数量或者 token 数量触发比如超过 20 条消息或者超过 4000 token 才触发一次。3.2 并发与性能AI Agent 怎么扛住高并发这是 Java 工程师的强项也是面试里常被问到的点。Agent 的并发瓶颈主要在两个地方模型 API 调用的延迟和工具执行的耗时。先说模型调用。一次 Agent 任务可能要调用模型 5 到 10 次每次几百毫秒到几秒串行下来一个任务就是好几秒。优化思路是能并行的并行。比如多个独立的工具调用可以并发执行用 CompletableFuture 或者 Reactor 都能搞定ListCompletableFutureString futures toolCalls.stream() .map(call - CompletableFuture.supplyAsync(() - executeTool(call), executor)) .toList(); ListString results futures.stream() .map(CompletableFuture::join) .toList();再说限流和熔断。模型 API 一般都有 QPS 限制必须做客户端限流否则高峰期直接被限。我用 Resilience4j 做限流和熔断配置一个合理的并发上限超了就排队或者降级。还有一个容易被忽略的点连接池和超时设置。调用模型 API 的 HTTP 客户端要配好连接池超时时间要合理我一般设 30 秒太短容易误杀太长会拖垮整个线程池。3.3 可观测性Agent 出问题了怎么查Agent 最让人头疼的就是它为什么不按我想的做。这时候可观测性就是救命稻草。我要求每个 Agent 项目必须记录完整的执行链路每一步的输入、模型的思考、工具调用、工具返回、耗时。用 Micrometer 或者 OpenTelemetry 把这些埋点打出去配合日志系统出问题的时候能完整回放一次任务执行过程。我踩过的坑是早期没做埋点Agent 行为异常的时候完全靠猜后来加了链路追踪一眼就能看出是哪一步的 Prompt 有问题还是工具返回了脏数据。Around(execution(* com.example.agent..*(..))) public Object trace(ProceedingJoinPoint pjp) throws Throwable { long start System.currentTimeMillis(); try { Object result pjp.proceed(); log.info(Agent step: {}, cost: {}ms, result: {}, pjp.getSignature().getName(), System.currentTimeMillis() - start, result); return result; } catch (Exception e) { log.error(Agent step failed: {}, pjp.getSignature().getName(), e); throw e; } }3.4 安全与权限别让 Agent 闯祸Agent 能调用工具就意味着它能产生真实影响删数据、发消息、下单这些操作一旦失控后果严重。我的原则是最小权限 人工确认 操作审计。最小权限就是给 Agent 的工具只开放必要的权限比如查询工具只读写操作要单独授权。人工确认是针对高风险操作Agent 决定要执行的时候先暂停推给人工确认后再执行。操作审计就是所有工具调用都留痕谁在什么时候调了什么、参数是什么、结果是什么全部记录。行级权限这块在企业场景特别重要。比如一个查询订单的工具不同用户能查的订单范围不一样这个权限控制必须在工具内部实现不能指望模型去遵守。4. 常见问题排查与实战避坑指南4.1 Agent 不调用工具或者乱调用工具这是最高频的问题。排查思路按这个顺序来先看工具描述再看 System Prompt最后看模型能力。工具描述不清楚是最常见的原因。我遇到过一个案例工具描述写的是查询数据模型完全不知道查什么数据、什么时候该查。改成根据订单号查询订单的详细状态包括支付、发货、物流信息当用户询问订单进度时使用之后调用准确率大幅提升。System Prompt 里要明确告诉模型你有这些工具遇到 XX 情况必须用工具而不是自己回答。有些模型天生倾向于直接回答需要你在 Prompt 里强调。如果前两个都没问题那就是模型能力不够换个更强的模型试试。不同模型在工具调用上的表现差异很大这个要实测。4.2 工具调用参数解析失败模型输出的参数格式不符合预期解析就失败。解决办法有两个一是在 Prompt 里给出明确的参数格式示例二是解析逻辑要容错。比如模型可能输出{city: 北京}也可能输出city北京解析器要能处理多种格式实在解析不了就把原始输出作为参数传进去让工具自己处理。4.3 Agent 陷入死循环表现是同一个工具反复调用或者一直在思考不行动。根因通常是工具返回的结果模型无法理解或者任务本身无法完成但模型不知道放弃。解决办法设置 maxSteps 硬性限制在 Prompt 里告诉模型如果连续两次得到相同结果说明此路不通尝试其他方法或直接告知用户无法完成工具返回结果要结构化、清晰别返回一堆模型看不懂的原始数据。4.4 响应太慢前面讲过并发优化这里补充几个具体手段。流式输出能大幅改善体感虽然总耗时没变但用户能更快看到内容。缓存高频问题的结果相同问题直接返回。模型分级简单任务用小模型复杂任务才用大模型。预加载常用工具的数据减少实时查询。4.5 常见问题速查表问题现象可能原因排查方向解决手段不调用工具工具描述不清检查 description补充使用场景说明乱调用工具Prompt 约束不足检查 System Prompt明确调用条件参数解析失败输出格式不符看模型原始输出加格式示例容错解析死循环无步数限制看执行日志设 maxSteps提示放弃响应慢串行调用多看链路耗时并发流式缓存结果不准上下文丢失看记忆管理优化摘要和召回4.6 几个我踩过的坑第一个坑是过度依赖模型自主决策。早期我什么都让模型自己判断结果行为很不稳定。后来我把很多决策逻辑用代码固化下来模型只负责它擅长的部分稳定性大幅提升。记住能用代码确定的逻辑就别交给模型。第二个坑是忽略 token 成本。一个 Agent 任务动辄几万 token如果没做上下文优化成本会失控。上线前一定要算清楚单次任务的 token 消耗和对应的成本。第三个坑是没有降级方案。模型 API 挂了、限流了怎么办必须有降级策略要么返回缓存结果要么走规则引擎兜底不能让整个功能不可用。第四个坑是测试不充分。Agent 的行为有随机性同样的输入可能得到不同输出。测试要覆盖各种边界情况而且要多次运行观察稳定性不能跑一次通过就上线。5. 从练手项目到企业级落地的进阶路径5.1 适合练手的三个小项目第一个是智能问答助手接入公司文档做 RAG回答内部知识问题。这个项目能让你把 RAG 的完整链路跑通文档切分、向量化、检索、生成。第二个是自动化数据处理 Agent给它一个 Excel 或者数据库查询需求它自己决定调用哪些工具、怎么处理数据、最后生成报告。这个能练工具编排和结果整合。第三个是多轮任务助手比如订机票这种需要多步交互的任务练记忆管理和状态维护。这三个项目做完Agent 的核心能力你就都摸过一遍了。5.2 企业级落地的关键考量企业级和练手项目的差距主要在可靠性、可维护性、成本控制、安全合规这四个方面。可靠性要求 Agent 在各种异常情况下都能优雅处理可维护性要求 Prompt、工具、配置都能方便地迭代成本控制要求有明确的预算和监控安全合规要求权限、审计、数据脱敏都到位。我建议企业落地从小场景切入选一个高频、低风险、效果容易衡量的场景先跑通积累经验再扩展。别一上来就搞大而全的 Agent 中台容易翻车。5.3 关于 AI Agent 中台的思考现在很多公司在搞 Agent 中台我的看法是中台的价值在于统一管理工具、统一可观测性、统一权限而不是统一所有 Agent 的实现。不同业务场景的 Agent 差异很大强行统一反而会限制灵活性。中台应该提供的是基础设施和规范而不是具体的 Agent 实现。工具注册中心、Prompt 管理、链路追踪、成本统计、权限控制这些是中台该做的。至于每个 Agent 怎么设计、用什么框架应该给业务团队自由度。5.4 后续可以深入的方向把单 Agent 跑通之后可以往多 Agent 协作方向深入让多个专业 Agent 分工合作完成复杂任务。还可以研究Agent 的自我反思和优化让 Agent 能从失败中学习。Agent 评测体系也是个重要方向怎么量化评估一个 Agent 的好坏目前还没有特别成熟的方案。我个人在实际操作中的体会是Java 工程师转 AI Agent最大的障碍不是技术而是思维方式的转变。要从我写代码实现逻辑转变到我设计规则让模型自己决策这个转变需要多动手、多踩坑才能真正完成。框架和 API 都是次要的把 ReAct 的思想吃透把工程化的能力用上你就能做出靠谱的 Agent。