1. 为什么 Java 工程师转 AI Agent 有天然优势1.1 从 CRUD 到智能体差的不是智商是视角我带过不少从 Java 后端转过来的兄弟他们最常问的一句话就是“我天天写 Controller、Service、Mapper跟 AI 八竿子打不着转 Agent 是不是得从头学 Python 和算法”每次我都跟他们说你手里那套工程化的本事恰恰是现在 AI Agent 落地最缺的东西。AI Agent 说白了就是一个能自己思考、自己调工具、自己循环干活的程序。它跟普通接口最大的区别在于普通接口是你调一次它返回一次Agent 是给它一个目标它自己决定调几次、调什么、什么时候停。这个“自己决定”的过程落到代码层面就是状态管理、循环控制、异常重试、超时熔断——这些东西 Java 工程师闭着眼睛都能写。我见过太多算法出身的朋友模型调得贼溜但一让他把 Agent 部署成能扛住线上流量的服务立马抓瞎。线程池怎么配、连接怎么复用、上下文怎么隔离、日志怎么打这些全是 Java 后端的看家本领。所以别妄自菲薄你缺的只是 AI 那一层的概念工程那一层你比谁都厚。1.2 生态已经补齐不用再羡慕 Python两三年前转 AI 确实痛苦因为工具链全在 Python 那边。但现在情况完全变了。LangChain4j和Spring AI这两个框架把 Java 侧的空白基本填满了。LangChain4j 相当于 Java 版的 LangChain链式调用、工具注册、记忆管理、RAG 检索这些都有Spring AI 则是 Spring 官方出手把 AI 能力做成了 Spring Boot 的 Starter你原来怎么写Service现在就怎么注入ChatClient。更关键的是Spring AI Alibaba这条线它把国内主流大模型的接入做了标准化封装通义千问、百炼平台这些都能直接对接。你不需要去研究每个厂商的 HTTP 接口长什么样框架帮你抹平了差异。这对 Java 工程师来说太友好了因为我们的思维习惯就是面向接口编程换模型就像换数据库驱动一样改个配置的事。所以现在的局面是Python 那边生态更全更前沿Java 这边生态更稳更工程化。你要做的是快速验证概念Python 可能更顺手你要做的是上线一个能扛并发、能接进现有微服务体系的东西Java 反而是更优解。1.3 这篇内容适合谁看如果你是有 Java 基础、写过 Spring Boot 项目、但对 AI Agent 只有模糊概念的工程师这篇就是给你写的。我会从 Agent 的核心原理讲起然后落到 LangChain4j 和 Spring AI 的具体代码再讲怎么把它做成能上线的服务。全程不堆公式不扯论文就讲一个后端工程师能听懂、能上手的东西。如果你已经用过 LangChain4j 或者 Spring AI但卡在“Demo 能跑上线就崩”的阶段那第三、四部分关于并发和排查的内容会对你有用。如果你还在观望要不要转那第一部分和最后一部分的经验分享应该能帮你做决定。2. AI Agent 的核心原理ReAct 到底在干什么2.1 一句话说清 Agent 和普通调用的区别普通调大模型流程是你给一段 prompt模型返回一段文本结束。Agent 的流程是你给一个目标模型返回一个“我要调用某个工具”的指令你的程序执行这个工具把结果再喂回给模型模型再决定下一步直到它认为任务完成返回最终答案。这个循环就是 Agent 的心脏。用生活化的例子说普通调用像是你问导航“从 A 到 B 怎么走”它给你一条路线就完事了。Agent 像是你雇了个司机你说“送我去机场”他自己看路况、自己决定要不要绕路、自己加油、自己找停车位最后把你送到。你只给了目标过程他自己搞定。这个“自己决定”的能力靠的就是ReAct模式。ReAct 是 Reasoning Acting 的缩写翻译过来就是“边想边做”。模型先输出一段思考Thought然后决定要执行的动作Action程序执行完把观察结果Observation返回模型再基于新信息继续思考。这个 Thought-Action-Observation 的循环就是 Agent 的工作流。2.2 ReAct 循环的四个角色拆开看一个 ReAct Agent 里有四个关键角色。第一个是目标也就是用户给的原始问题比如“帮我查一下北京明天天气如果下雨就提醒我带伞”。第二个是推理器就是大模型本身它负责根据当前掌握的信息决定下一步干什么。第三个是工具箱里面装着 Agent 能调用的所有工具比如查天气的接口、发提醒的接口。第四个是执行器就是你的 Java 代码负责真正去调那些工具把结果拿回来。这四个角色里Java 工程师真正要写的是工具箱和执行器推理器是模型的事目标来自用户。所以你的工作量其实很清晰定义工具、实现工具、把工具注册给 Agent、处理循环和异常。这跟写一个带重试机制的服务编排逻辑没有本质区别。我刚开始理解 ReAct 的时候总觉得“模型自己决定调什么”很玄乎。后来想明白了模型输出的其实是一段结构化的文本比如Action: get_weather, Action Input: {city: 北京}你的程序解析这段文本找到对应的工具去执行。所谓“智能”是模型在决定输出哪段文本而执行层面全是确定性的代码。这个认知一打通后面写起来就顺了。2.3 为什么 Java 工程师容易在这里踩坑第一个坑是把 Agent 当成一个“更聪明的接口”。很多人第一次写 Agent还是用同步阻塞的思路一个请求进来从头跑到尾中间调了五次模型、三次工具整个线程被占死。Demo 阶段没问题一上并发就雪崩。Agent 的调用链比普通接口长得多一次请求可能耗时十几秒甚至几十秒你必须用异步的思路去设计。第二个坑是忽略上下文管理。Agent 每轮循环都要把之前的对话历史、工具调用记录一起发给模型这个上下文会越来越长。如果不做截断或者摘要token 消耗会爆炸而且模型注意力会被稀释越跑越傻。Java 里管理这个上下文其实就是管理一个 List但什么时候截、怎么截有讲究。第三个坑是工具设计的粒度。新手容易把工具设计得太粗比如一个工具叫“处理用户请求”里面啥都干。这样模型根本不知道该什么时候调它。工具应该像微服务一样职责单一、参数明确、返回值结构化。你写过的那些 RESTful 接口设计原则在这里完全适用。3. LangChain4j 与 Spring AI 选型对比3.1 两个框架的定位差异LangChain4j 的定位是“AI 能力的全家桶”它不依赖 Spring你可以在任何 Java 项目里用。它的 API 设计更贴近 Python 的 LangChain链式调用风格明显AiServices、ChatLanguageModel、EmbeddingStore这些概念跟 Python 侧能对上。如果你之前看过 LangChain 的教程转过来会很快。Spring AI 的定位是“Spring 生态的 AI 扩展”它把 AI 能力做成了 Spring Boot 的自动配置。你用spring-boot-starter-ai-openai或者spring-ai-alibaba-spring-boot-starter配置好 API Key直接Autowired注入ChatClient就能用。它的优势是跟你现有的 Spring 体系无缝融合事务、AOP、配置管理这些都能直接复用。我的建议是如果你的项目本身就是 Spring Boot 微服务体系优先用 Spring AI接入成本最低。如果你要做一些比较复杂的 Agent 编排或者想用 LangChain4j 特有的多路召回、工具链这些能力那就用 LangChain4j。两者也可以混用Spring AI 管基础对话LangChain4j 管复杂 Agent各取所长。3.2 核心能力对照表能力项LangChain4jSpring AI基础对话ChatLanguageModelChatClient工具调用Tool注解 AiServicesTool注解 ChatClient记忆管理ChatMemory多种实现ChatMemory基础实现RAG 检索完整的 Embedding Store Retriever支持但相对简单多模型接入支持广泛通过 Starter 支持与 Spring 集成需手动配置原生自动配置学习曲线稍陡概念多平缓符合 Spring 习惯这张表不是绝对的两个框架都在快速迭代。但大方向是LangChain4j 功能更全更灵活Spring AI 集成更顺更省心。选哪个取决于你的项目阶段和团队习惯。3.3 我的实际选型经验我自己的做法是分阶段。项目初期验证概念用 Spring AI因为配置简单半小时就能跑通一个带工具调用的 Agent。等概念验证通过要往深里做 RAG、多路召回、复杂工具编排的时候引入 LangChain4j 做补充。这样既享受了 Spring AI 的便捷又拿到了 LangChain4j 的能力。有一点要注意两个框架的版本迭代都很快尤其是 Spring AI 还在往 1.0 正式版走的过程中API 会有变动。我的经验是锁定版本不要盲目追新。生产环境用哪个版本就在pom.xml里写死升级前先在测试环境跑一遍回归。我踩过一次坑升级了一个小版本ChatClient的某个方法签名变了编译直接报错排查了半天。4. 从零搭建一个能用的 Agent4.1 环境准备与依赖引入先说环境。JDK 17 是底线Spring AI 和 LangChain4j 的新版本都要求 17 以上。Maven 3.8Spring Boot 3.2。如果你还在用 JDK 8那得先升级这不是可选项。Spring AI 的依赖引入以对接通义千问为例pom.xml里加dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-spring-boot-starter/artifactId version1.0.0-M6.1/version /dependency然后在application.yml里配置spring: ai: dashscope: api-key: ${DASHSCOPE_API_KEY} chat: options: model: qwen-plus temperature: 0.7API Key 不要硬编码在配置文件里用环境变量注入。这是基本的安全习惯我见过有人把 Key 提交到 Git 仓库结果被人刷了几千块钱的 token。LangChain4j 的依赖dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai-spring-boot-starter/artifactId version0.35.0/version /dependency配置方式类似也是 API Key 模型名。两个框架的配置项命名不同但逻辑一样。4.2 定义你的第一个工具工具是 Agent 的手脚。在 Spring AI 里定义一个工具就是写一个方法加上Tool注解Component public class WeatherTools { Tool(description 查询指定城市的当前天气) public String getWeather(ToolParam(description 城市名称) String city) { // 实际调用天气 API return city 今天晴25度; } }description非常重要模型就是靠这段描述来决定什么时候调这个工具的。描述要写清楚“这个工具干什么、什么时候用”不要写“查询天气”这么笼统。我一般会写成“当用户询问某个城市的实时天气状况时调用此工具输入城市中文名”。在 LangChain4j 里工具定义类似也是注解方式但注册方式不同需要通过AiServices的 builder 把工具类传进去。4.3 组装 Agent 并跑通第一个循环Spring AI 里组装一个带工具的 AgentRestController public class AgentController { private final ChatClient chatClient; public AgentController(ChatClient.Builder builder, WeatherTools weatherTools) { this.chatClient builder .defaultTools(weatherTools) .build(); } GetMapping(/ask) public String ask(RequestParam String question) { return chatClient.prompt() .user(question) .call() .content(); } }启动项目访问/ask?question北京今天天气怎么样你会看到模型自动调用了getWeather工具然后把结果组织成自然语言返回。这个过程中Spring AI 帮你处理了工具调用的解析、执行、结果回填你只需要关注工具本身的实现。LangChain4j 的组装方式interface Assistant { String chat(String message); } Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .tools(new WeatherTools()) .build(); String answer assistant.chat(北京今天天气怎么样);两种方式都能跑通Spring AI 更贴近 Spring 的编程习惯LangChain4j 更接近 Python 侧的写法。选你顺手的就行。4.4 加上记忆让 Agent 记住上下文没有记忆的 Agent每次对话都是失忆的。加上记忆很简单Spring AI 里配置一个ChatMemoryBean public ChatMemory chatMemory() { return MessageWindowChatMemory.builder() .maxMessages(20) .build(); }然后在构建ChatClient时传入。maxMessages控制保留多少轮对话设太大 token 消耗高设太小模型记不住。我一般设 10 到 20 轮具体看业务场景。如果是客服类应用可能需要保留更多如果是单次任务型少一点无所谓。LangChain4j 的记忆管理更细有MessageWindowChatMemory、TokenWindowChatMemory等多种策略。TokenWindowChatMemory按 token 数来截断比按消息条数更精确适合对成本敏感的场景。5. 让 Agent 扛住并发Java 工程师的主场5.1 Agent 的并发模型跟普通接口不一样普通接口的耗时主要在数据库查询几十毫秒级别线程池开个 200 就能扛住不错的 QPS。Agent 不一样一次请求可能调 3 到 5 次模型每次模型调用 2 到 10 秒再加上工具执行的时间整个链路可能 15 到 30 秒。这意味着一个线程被占用的时间是普通接口的几百倍。如果你还用传统的 Tomcat 线程池模型200 个线程每个请求占 20 秒那 QPS 只有 10。稍微来点流量线程池就满了后面的请求全部排队或者被拒绝。这不是模型的问题是你的并发模型没跟上。5.2 异步化是必选项解决方案是把 Agent 的调用链异步化。Spring AI 支持返回Flux或者CompletableFutureLangChain4j 也有异步 API。核心思路是不要让 Tomcat 的工作线程去等模型返回而是把模型调用提交到专门的线程池工作线程立刻释放去处理下一个请求。GetMapping(/ask-async) public CompletableFutureString askAsync(RequestParam String question) { return CompletableFuture.supplyAsync(() - chatClient.prompt().user(question).call().content(), agentExecutor ); }agentExecutor是一个专门给 Agent 用的线程池大小根据你的模型并发限制来定。如果模型侧允许 50 并发那线程池核心线程数设 50 左右队列用有界队列避免无限堆积。5.3 超时、重试与熔断Agent 链路长任何一环出问题都会拖垮整个请求。模型调用可能超时工具执行可能失败网络可能抖动。你必须给每一环都加上超时和重试。模型调用的超时我一般设 30 秒超过就放弃。重试最多 2 次用指数退避。工具执行的超时根据工具性质定查数据库的设 3 秒调外部 API 的设 10 秒。熔断用 Resilience4j 或者 Sentinel当某个工具的失败率超过阈值直接熔断避免雪崩。这些配置在 Spring Boot 里都是现成的你原来怎么给 Feign 客户端配超时熔断现在就怎么给 Agent 配。思路完全一样只是对象从 HTTP 调用变成了模型调用和工具调用。5.4 上下文隔离与资源控制多用户并发时每个用户的对话上下文必须隔离。Spring AI 的ChatMemory默认是按会话 ID 隔离的你要确保每个请求带上正确的会话 ID。如果会话 ID 生成有问题A 用户的对话历史可能被 B 用户看到这是严重的事故。资源控制方面除了线程池还要控制单个用户的请求频率。防止有人恶意刷接口把你的 token 额度耗光。用 Redis 做个简单的限流每个用户每分钟最多 10 次 Agent 调用超过就拒绝。这个逻辑用 Spring 的拦截器或者 AOP 都能实现不复杂但必须有。6. 常见问题与排查技巧实录6.1 模型不调工具怎么办这是最常见的问题。你定义好了工具但模型就是不用直接自己编答案。原因通常有三个工具描述不清楚、模型能力不够、prompt 没引导好。先检查工具描述。Tool的 description 要写清楚使用场景不要只写功能。比如“查询天气”改成“当用户询问天气时调用输入城市名返回该城市当前天气”。再检查模型小模型对工具调用的支持可能不好换成 qwen-plus 或者 qwen-max 试试。最后在 system prompt 里加一句“你可以使用提供的工具来获取信息不要自己编造”。6.2 工具调用参数解析失败模型输出的参数格式不对比如你要 JSON它给你一段自然语言。这种情况通常是模型对参数格式理解不到位。解决办法是在ToolParam的 description 里把格式要求写清楚比如“城市名称只填城市中文名不要带‘市’字”。如果还不行就在 system prompt 里给一个调用示例。6.3 循环停不下来Agent 有时候会陷入死循环反复调同一个工具。这通常是因为工具返回的结果模型不满意它就一直重试。你需要在代码里加一个最大循环次数限制比如最多 10 轮超过就强制返回当前结果。Spring AI 和 LangChain4j 都支持配置这个上限别忘了设。6.4 常见问题速查表问题现象可能原因排查方向模型不调工具描述不清/模型弱改描述、换模型、加 prompt 引导参数解析失败格式要求不明确在 description 里写清格式和示例循环不停止无最大轮次限制配置 maxIterations响应特别慢同步阻塞/上下文过长异步化、截断上下文token 消耗高上下文未截断/工具返回太长限制记忆轮数、精简工具返回值并发上不去线程池配置不当用独立线程池、异步化6.5 几个我踩过的坑第一个坑工具返回值太长。我有个工具返回了一整页 HTML结果模型上下文直接被撑爆。工具返回值要精简只返回模型需要的关键信息格式用 JSON 或者简单文本。第二个坑忘了设超时。有一次模型侧网络抖动一个请求挂了 5 分钟把线程池占满了整个服务不可用。从那以后所有模型调用和工具调用我都强制设超时。第三个坑会话 ID 冲突。早期我用用户 ID 当会话 ID结果同一个用户开两个浏览器窗口对话历史串了。后来改成用户 ID 会话随机串问题解决。7. 我的转型路径与几点实在建议7.1 学习路线不用贪多我自己的路径是先花两天把 ReAct 的概念搞清楚不用看论文看几篇博客加一个 Demo 就够了。然后花一周用 Spring AI 跑通一个带工具调用的 Agent再花一周加上记忆和 RAG。整个过程不到一个月就能做出一个能演示的东西。不要一上来就啃 LangChain4j 的全部文档概念太多容易劝退。先用 Spring AI 建立信心等遇到 Spring AI 搞不定的场景再去 LangChain4j 里找答案。这种问题驱动的方式学起来最快。7.2 Java 的底子别丢转型 AI Agent 不代表 Java 那套东西没用了。恰恰相反你的并发编程、JVM 调优、Spring 生态、微服务治理经验在 Agent 上线阶段全是硬通货。我见过太多 AI 项目死在工程化上不是模型不行是服务扛不住。所以别觉得写 CRUD 是浪费时间那些经验换个场景就是核心竞争力。7.3 先做出来再做好我最大的体会是不要追求一次做到完美。第一个版本能跑通就行工具粗糙点没关系prompt 不优雅也没关系。先让它动起来你才能看到真实的问题在哪里。我第一个 Agent 的工具返回值格式乱七八糟但跑通之后我立刻就知道该怎么改了。纸上谈兵永远发现不了真问题。最后分享一个小技巧调试 Agent 的时候把每一轮的 Thought、Action、Observation 都打到日志里。这样出问题的时候你能清楚看到模型在哪一步走偏了。这个日志我到现在还留着排查效率比瞎猜高十倍。