1. 为什么 Java 工程师转 AI Agent 有天然优势这两年身边不少 Java 老哥都在焦虑AI 一波接一波自己写了七八年的 Spring Boot、MyBatis、微服务难道要被时代甩下车我一开始也这么想直到真正动手做了几个 AI Agent 项目之后才发现Java 工程师转型 AI Agent其实比想象中顺得多甚至有些地方比纯算法背景的人更有优势。先说结论AI Agent 不是让你去训模型而是让你去编排模型。它本质上是把大语言模型当成一个会思考但不太靠谱的实习生你负责给它搭好工具、定好流程、做好兜底。这套思路和 Java 工程师天天干的服务编排、接口治理、异常兜底几乎是一回事。你写过的那些 Controller、Service、DAO 分层你对事务、幂等、超时的理解在 Agent 开发里全都能用上。那 AI Agent 到底是个啥用大白话讲一个 Agent 就是大模型 工具 记忆 循环。大模型负责理解意图和决策工具负责真正干活查数据库、调接口、发消息记忆负责记住上下文循环负责想一步、做一步、看结果、再想下一步。这个循环就是热词里反复出现的ReActReasoning Acting模式。你不需要懂反向传播不需要会调参你需要的是把业务拆成模型能理解的步骤然后给它配上趁手的工具。适合看这篇的人有三类一是写了几年 Java、想切入 AI 但不知道从哪下手的后端工程师二是已经在用 LangChain4j 或 Spring AI 做 Demo、但一上生产就抓瞎的开发者三是团队里被安排研究一下 AI Agent 怎么落地的技术负责人。我会从原理讲到落地把踩过的坑、选型的逻辑、并发怎么扛这些实际问题都摊开说尽量让你看完就能动手。2. 核心概念拆解Agent、ReAct 与工具调用2.1 Agent 和普通大模型调用到底差在哪很多人第一次接触 Agent会觉得不就是调个 API 吗。我一开始也这么以为写了个chatClient.call(prompt)就觉得自己在做 AI 了。但普通调用和 Agent 的区别就像问路人和雇了个助理的区别。问路人你只能得到一句话雇助理他会自己去找资料、打电话、跑腿最后把结果交给你。具体到技术层面普通调用是单轮无状态的你给 prompt模型给回答结束。Agent 是多轮有状态的模型可以先说我需要查一下订单表你的代码执行查询把结果喂回去模型再基于结果决定下一步。这个模型决定调用哪个工具的能力就是Function Calling也叫 Tool Calling。它是 Agent 的地基没有它Agent 就退化成聊天机器人。这里有个关键认知模型本身不会执行任何代码。它只是输出一段结构化的 JSON告诉你我想调用 queryOrder 这个工具参数是 orderId123。真正执行的是你的 Java 代码。所以整个 Agent 的安全边界、权限控制、参数校验全都在你手里。这一点对 Java 工程师特别友好因为你本来就在写这些校验逻辑。2.2 ReAct 模式让模型边想边做ReAct 这个词看着唬人拆开就是 Reasoning推理和 Acting行动交替进行。它的核心思想是不要让模型一次性给出最终答案而是让它先输出思考过程再输出行动执行完拿到观察结果再进入下一轮思考。举个实际例子。用户问帮我查一下上个月销售额最高的三个商品并给每个商品生成一句推广文案。一个 ReAct Agent 的循环大概是这样Thought我需要先查上个月的销售数据按商品聚合排序。Action调用querySalesRanking(monthlast, topN3)。Observation返回 [商品A: 12万, 商品B: 9万, 商品C: 7万]。Thought数据拿到了现在需要为每个商品生成文案。Action调用generateCopy(productName商品A)依次处理。Observation拿到三段文案。Final Answer整合输出。这个循环的价值在于可解释、可干预。你可以在每一步加日志、加校验、加人工确认。相比之下如果你让模型一次性输出所有结果中间错了你根本不知道错在哪。我在生产环境里坚持用 ReAct 而不是一把梭就是因为出问题时能快速定位是哪一步的思考或工具调用出了问题。2.3 工具Tool设计Agent 能不能干活全看这个工具就是暴露给模型调用的方法。在 Java 里一个工具通常就是一个加了注解的方法。设计工具是 Agent 开发里最考验功力的部分我总结了三条铁律工具要单一职责。一个工具只干一件事别搞doEverything(String type, Map params)这种万能方法。模型看不懂这种模糊的接口很容易传错参数。描述要写给模型看。工具的方法名和描述不是给人看的是给模型看的。描述里要写清楚什么时候用这个工具参数是什么含义返回什么。我见过太多人描述写得含糊结果模型死活不调用。参数要强类型、可校验。用 Java 的 record 或 POJO 定义参数配合ToolParam之类的注解说明。模型传错类型时框架能帮你拦住而不是等到运行时才炸。提示工具的数量不是越多越好。我实测下来单个 Agent 挂 5 到 8 个工具时模型选择最准超过 15 个之后误选率明显上升。工具多了要么拆成多个 Agent要么做一层路由。3. 框架选型LangChain4j 还是 Spring AI3.1 两个框架的定位差异Java 生态里做 Agent绕不开 LangChain4j 和 Spring AI 这两个。热词里langchain4j和spring ai出现频率极高说明大家都在纠结选哪个。我的经验是看你的项目底色。LangChain4j 是社区驱动的灵感来自 Python 的 LangChain功能覆盖广Agent、RAG、多路召回、记忆管理都有现成实现迭代快。它的风格偏工具箱你想怎么拼就怎么拼灵活度高。缺点是 API 变动相对频繁版本升级偶尔要改代码。Spring AI 是 Spring 官方团队做的最大优势是和 Spring Boot 无缝集成。你熟悉的Bean、application.yml、自动装配那一套全都能用。它的抽象更克制主打少即是多。热词里spring ai alibaba、spring ai 2.0 连接百炼 qwen3.7这些说明国内用 Spring AI 接国产模型比如通义千问系列的场景越来越多。我个人的选型建议是这样的维度LangChain4jSpring AI上手难度中等概念多低Spring 开发者友好Agent 能力丰富ReAct 开箱即用逐步完善够用RAG 支持强多路召回成熟基础够用生态集成独立需自己接与 Spring 全家桶天然融合版本稳定性迭代快偶有破坏性变更相对稳适合场景复杂 Agent、RAG 重度企业级、已有 Spring 体系3.2 我的实际选择逻辑如果是新项目、团队全是 Spring 背景、要快速上线我选 Spring AI。配置简单模型切换只改 yml运维也熟悉。如果是 Agent 逻辑复杂、需要多路召回、需要精细控制记忆和工具链我选 LangChain4j它的抽象层次更细能抠的地方多。还有一种情况是两个一起用用 Spring AI 做模型接入和基础对话用 LangChain4j 做复杂的 Agent 编排。听起来别扭但实际项目里真有人这么干因为 Spring AI 的模型抽象确实省事而 LangChain4j 的 Agent 能力更成熟。不过我不太推荐新手这么搞容易把自己绕晕。注意无论选哪个都要把模型接入层和业务逻辑层隔离开。我见过有人把 OpenAI 的 SDK 直接散落在各个 Service 里后来要换成国产模型改了几十个文件。正确做法是定义一个ChatModel接口底层实现随便换。3.3 模型接入的坑接国产模型时最容易踩的坑是Function Calling 支持不一致。不是所有模型都完整支持工具调用有些模型虽然号称支持但返回的 JSON 格式不规范导致解析失败。我建议在选模型前先写个最小 Demo 测三件事能不能正确返回工具调用、参数格式对不对、多轮之后会不会忘记工具。另外spring ai 2.0.1这类版本号背后往往有 API 变化。升级前一定要看 release notes尤其是ChatClient、ToolCallback这些核心类的签名变化。我有次升级小版本Tool注解的参数名规则变了导致模型一直传错参数排查了大半天。4. 从零搭一个能用的 Agent完整实操4.1 环境准备与依赖先明确目标搭一个能查订单、能算退款、能回答售后问题的客服 Agent。技术栈用 Spring Boot 3 Spring AI模型接一个支持 Function Calling 的国产模型。依赖大概是这样dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency配置里把模型的 base-url、api-key、model 名字填好。这里有个细节超时时间一定要设。模型响应慢是常态默认超时经常不够我一般设 60 秒并且给工具调用单独设更短的超时避免一个慢工具拖垮整个请求。4.2 定义工具把业务能力暴露给模型工具类大概长这样Component public class OrderTools { private final OrderService orderService; public OrderTools(OrderService orderService) { this.orderService orderService; } Tool(description 根据订单号查询订单详情包括商品、金额、状态。当用户询问订单相关信息时使用) public OrderDetail queryOrder( ToolParam(description 订单号通常是纯数字字符串) String orderId) { return orderService.getById(orderId); } Tool(description 计算指定订单的可退款金额。当用户询问能退多少钱时使用) public RefundResult calcRefund( ToolParam(description 订单号) String orderId) { return orderService.calcRefund(orderId); } }注意描述里的措辞。我特意写了当用户询问订单相关信息时使用这是给模型的触发提示。实测下来描述里带上使用场景模型选工具的准确率能提升不少。4.3 组装 Agent 与对话循环Spring AI 里组装一个带工具的 ChatClient 很直接Bean public ChatClient chatClient(ChatClient.Builder builder, OrderTools orderTools) { return builder .defaultSystem(你是一个电商售后助手只能基于工具返回的事实回答不确定时如实告知用户) .defaultTools(orderTools) .build(); }System Prompt 是灵魂。我踩过的最大坑就是没写清楚边界结果模型开始编订单信息。加上只能基于工具返回的事实回答之后幻觉明显减少。你还可以在 System Prompt 里规定输出格式、语气、禁止事项。调用的时候String answer chatClient.prompt() .user(userInput) .call() .content();框架会自动处理模型要调工具 - 执行工具 - 结果回喂 - 模型继续这个循环。但你要知道它内部在循环因为循环次数是要设上限的。默认可能允许很多轮遇到模型钻牛角尖时会一直调工具。我一般限制最多 5 轮超过就返回兜底话术。4.4 记忆管理别让上下文无限膨胀多轮对话必须带历史但历史不能无限塞。我的做法是滑动窗口 摘要保留最近 N 轮原文更早的用模型压缩成一段摘要。N 一般取 6 到 10 轮。这样既保留了上下文又控制了 token 消耗。还有个细节工具调用的中间结果要不要进历史我的经验是不要全进。工具返回的大 JSON 塞进历史会迅速撑爆上下文而且模型下一轮未必用得上。我通常只把工具返回的关键字段摘要进历史原始结果存在会话缓存里需要时再取。5. 生产落地并发、稳定性与成本控制5.1 AI Agent 怎么扛并发热词里ai agent 怎么扛并发是个高频问题说明大家都卡在这。先说结论Agent 的并发瓶颈不在你的 Java 服务而在模型 API 的限流。你的 Spring Boot 服务本身扛几千 QPS 没问题但模型 API 通常有 RPM每分钟请求数和 TPM每分钟 token 数限制。一个 Agent 请求内部可能触发 3 到 5 次模型调用所以你的实际并发能力要除以这个倍数。我一般这样算假设模型限流 600 RPMAgent 平均每次请求调 4 次模型那你的 Agent 理论并发上限就是 150 请求/分钟也就是 2.5 QPS。这个数字往往比想象的低很多。应对手段有几个请求队列 限流。用信号量或令牌桶控制进入模型调用的并发数超出的排队。别让请求直接打到模型 API 上否则一限流全是报错。异步化。Agent 调用是 IO 密集型的用CompletableFuture或响应式编程能显著提升吞吐。Spring AI 支持流式返回配合 SSE 推给前端用户体验也好。缓存。相同或相似的问题结果可以缓存。尤其是那些查订单状态这类确定性查询缓存命中率很高。降级。模型不可用时退回到规则引擎或固定话术别让整个服务挂掉。提示我实测过一个反直觉的现象——把模型调用并发从 50 降到 20整体吞吐反而上升了。因为高并发下大量请求触发限流重试反而浪费了配额。找到那个甜点并发比一味加并发更重要。5.2 稳定性Agent 的失败模式Agent 的失败方式和普通接口完全不同你得专门设计兜底模型超时设超时 重试但重试要有上限且只对幂等的工具重试。工具调用死循环限制最大轮数超过就中断。参数解析失败模型传了非法参数捕获异常后把错误信息回喂给模型让它重试一次。幻觉模型编造了工具没返回的信息。靠 System Prompt 约束 关键信息二次校验。工具执行异常工具内部报错要把错误信息结构化返回给模型而不是抛异常中断。我一般会做一个Agent 执行追踪把每一轮的 Thought、Action、Observation 都记下来。出问题时一看日志就知道卡在哪。这个追踪在生产环境排查问题时价值极高强烈建议一开始就做。5.3 成本控制token 就是钱Agent 的 token 消耗比普通对话高得多因为每轮都要带上历史、工具定义、System Prompt。控制成本的手段精简 System Prompt。别写小作文能一句话说清就别写三句。工具定义按需加载。不是所有场景都需要所有工具可以按意图路由到不同的工具子集。历史摘要。前面说过的滑动窗口 摘要。小模型做路由。用一个便宜的小模型判断意图再决定要不要调用贵的大模型。结果缓存。确定性查询尽量缓存。我算过一笔账一个没优化的客服 Agent单次对话平均消耗 8000 token优化之后降到 2500 左右成本直接砍掉三分之二。这些优化不涉及模型能力纯粹是工程手段Java 工程师做起来得心应手。6. 常见问题与排查技巧实录6.1 模型不调用工具怎么办这是新手最常见的问题。排查顺序看工具描述是不是太模糊。改成当用户询问 X 时使用这种带场景的描述。看模型是否支持 Function Calling。有些模型需要显式开启。看 System Prompt 有没有引导。加一句你需要使用工具来获取事实信息。看参数类型。模型对复杂嵌套对象支持不好尽量用扁平的基本类型。6.2 工具调用参数总是错多半是参数描述不清。ToolParam的描述要写清楚格式比如订单号纯数字长度 18 位。另外能用 String 就别用复杂对象模型对 String 的处理最稳。6.3 多轮对话后模型失忆检查历史是不是被截断了。滑动窗口设太小会丢上下文设太大又费 token。我的经验是保留最近 6 轮更早的做摘要。另外关键信息比如订单号可以在 System Prompt 里动态注入不依赖历史。6.4 响应太慢Agent 慢是正常的因为内部有多轮模型调用。优化方向并行化独立的工具调用、用流式返回让用户先看到部分结果、把慢工具异步化。如果单轮模型调用就慢那是模型本身的问题换模型或换区域。6.5 常见问题速查表现象可能原因排查方向不调用工具描述模糊/模型不支持改描述、确认模型能力参数错误参数描述不清细化 ToolParam 描述死循环无轮数上限设置最大迭代次数幻觉严重System Prompt 太松加事实约束、二次校验响应慢多轮调用/模型慢并行化、流式、换模型并发上不去模型限流队列限流、异步、缓存成本高token 浪费精简 prompt、摘要、缓存6.6 几个独家避坑心得第一别在工具里做重活。工具应该快速返回耗时操作异步化。模型等工具超过几秒就会超时。第二给工具加幂等。模型可能重复调用同一个工具尤其是重试场景。查询类工具无所谓写操作类工具一定要幂等。第三日志要打全。Agent 的调试难度远高于普通接口因为决策过程在模型内部。把每轮的输入输出都记下来是排查问题的唯一依靠。第四先做窄场景。别一上来就做什么都能干的通用 Agent先做一个垂直场景比如只处理退款跑通了再扩。通用 Agent 的工具太多模型选择困难效果反而差。第五人工兜底要有。再好的 Agent 也会出错关键业务一定要留人工介入的入口。我做的客服 Agent遇到退款金额超过阈值就自动转人工这个设计救过我好几次。7. 学习路线与后续扩展方向如果你是从 Java 转过来的我建议的学习顺序是先把 Function Calling 玩明白写几个工具让模型调用然后理解 ReAct 循环手动实现一遍不依赖框架接着上框架用 Spring AI 或 LangChain4j 搭一个完整 Agent最后才是 RAG、多路召回这些进阶内容。热词里langchain4j easy rag、langchain4j 多路召回这些都是在你把基础 Agent 跑通之后才需要碰的。后续可以扩展的方向不少。一是RAG给 Agent 接上知识库让它能回答私有领域的问题。二是多 Agent 协作让多个专职 Agent 分工比如一个查数据、一个写文案、一个审核。三是工作流编排把 Agent 嵌入到更长的业务流程里热词里dify工作流转成spring ai java代码说的就是这个方向。四是可观测性给 Agent 加上完整的追踪、评估、回归测试体系这是上生产的必修课。我个人在实际操作中的体会是Java 工程师做 AI Agent最大的障碍不是技术而是心态。很多人觉得 AI 是算法工程师的地盘自己插不上手。但真正落地的时候你会发现把模型能力稳定、可靠、低成本地交付给业务靠的恰恰是后端工程师那套工程能力。模型会换、框架会变但你对并发、幂等、降级、可观测性的理解是穿越技术周期的硬通货。先动手写第一个工具比看一百篇原理文章都管用。