1. 为什么 Java 工程师转 AI Agent 有天然优势这两年身边不少 Java 老哥都在焦虑AI Agent 这么火是不是又要重新学一门语言、重新换一套技术栈我一开始也这么想直到真正用 LangChain4j 和 Spring AI 把几个 Agent 项目跑起来之后才发现Java 工程师转型 AI Agent其实比想象中顺得多甚至有些地方比 Python 选手更有优势。先说结论AI Agent 的本质不是“训练模型”而是“编排能力”。它要做的事情是把大模型的推理能力、外部工具的调用能力、记忆的存储能力、流程的控制能力串起来形成一个能自主决策、能动手干活的系统。这件事的核心是工程能力而不是算法能力。而工程能力恰恰是 Java 工程师十几年如一日在 Spring 生态里练出来的看家本领。你想想一个 Agent 要调用数据库、要发 HTTP 请求、要做事务控制、要做权限校验、要做并发限流、要做可观测性——这些不都是 Java 后端每天在干的事吗LangChain4j 和 Spring AI 做的事情本质上就是把这些能力用一套统一的抽象封装起来让你用熟悉的注解、Bean、依赖注入的方式去定义 Agent。你不需要从零理解什么叫“链”什么叫“工具调用”因为这些东西在 Java 世界里早就有对应的概念了。所以这篇文章我不打算写成又一篇“AI Agent 入门科普”那种文章网上一抓一大把。我想做的是把 Java 工程师转型路上真正会卡住的几个点讲透ReAct 到底怎么在 Java 里落地、LangChain4j 和 Spring AI 该怎么选、多路召回和 RAG 怎么接、并发怎么扛、以及那些文档里不会写的坑。看完你至少能自己动手搭一个能跑起来的 Agent而不是停留在“知道有这么个东西”的阶段。2. 先把 AI Agent 的核心原理掰开揉碎2.1 Agent 和普通大模型调用到底差在哪很多人第一次接触 Agent会觉得它就是个“会调用工具的 ChatGPT”。这个理解不算错但太浅了。普通的大模型调用是一问一答你给 prompt它给回复结束。而 Agent 是一个循环它拿到任务后会自己判断“我现在信息够不够”“我需不需要调个工具”“调完工具之后结果对不对”“要不要再调一次”直到它认为任务完成才输出最终答案。这个循环就是 Agent 的灵魂。用一句话概括Agent LLM 工具 记忆 循环控制。LLM 负责推理和决策工具负责和外部世界交互记忆负责保存上下文和历史循环控制负责决定什么时候停。举个具体例子。你让 Agent “帮我查一下北京今天的天气如果下雨就提醒我带伞”。普通大模型调用只能瞎编一个天气。而 Agent 会这样跑第一步它判断需要调用天气查询工具第二步它生成工具调用参数城市北京第三步工具返回“小雨”第四步它根据结果判断需要提醒带伞第五步输出最终回复。整个过程可能来回好几轮这就是 Agent 和普通调用的本质区别。2.2 ReAct 模式让 Agent 能思考也能行动ReAct 是 Reasoning Acting 的缩写是目前最主流的 Agent 推理范式。它的核心思想特别朴素让模型在每一步都先“想一想”再“做一做”然后根据做的结果继续想。具体来说ReAct 把 Agent 的每一步拆成三个部分Thought思考模型分析当前状态决定下一步该干什么Action行动模型选择一个工具并生成调用参数Observation观察工具执行后返回结果作为下一轮思考的输入这三步循环往复直到模型在 Thought 阶段判断“我已经有足够信息回答用户了”就会输出 Final Answer。为什么 ReAct 这么重要因为它解决了纯推理模型的一个致命问题幻觉。如果只让模型凭空回答它会一本正经地胡说八道。但 ReAct 强制模型在行动前先思考、行动后看结果相当于给它加了一个“事实校验”的环节。工具返回的真实数据会不断纠正模型的推理方向最终答案的可靠性大幅提升。在 Java 里实现 ReActLangChain4j 和 Spring AI 都提供了现成的抽象。LangChain4j 有AiServices配合Tool注解Spring AI 有ChatClient配合Tool注解。你只需要把工具方法标注出来框架会自动帮你把 ReAct 循环跑起来。但这里有个关键点框架帮你跑循环不代表你不需要理解循环。因为一旦出问题比如工具调用死循环、参数解析失败、上下文爆炸你还是得回到 ReAct 的每一步去排查。2.3 工具调用是怎么在 Java 里实现的工具调用Tool Calling / Function Calling是 Agent 的手和脚。在 Java 里它的实现路径大致是这样的你用注解比如Tool标记一个普通 Java 方法并写好方法描述框架在启动时扫描这些方法把方法名、参数结构、描述信息转成 JSON Schema每次调用 LLM 时框架把这个 Schema 一起发给模型模型判断需要调用某个工具时返回一个结构化的调用请求工具名 参数框架解析这个请求反射调用对应的 Java 方法方法返回值被序列化后作为 Observation 塞回对话历史模型基于新的对话历史继续推理这个流程听起来简单但实际落地时坑不少。比如方法描述写得不好模型就不知道该什么时候调参数类型太复杂模型生成的 JSON 就对不上返回值太大直接把上下文撑爆。这些后面会专门讲。2.4 记忆机制Agent 的短期和长期记忆Agent 的记忆分两层。短期记忆就是当前对话的上下文通常用一个消息列表维护每轮对话把用户输入、模型输出、工具调用结果都追加进去。长期记忆则是跨会话的需要持久化到数据库或向量库用的时候通过检索召回。短期记忆最大的问题是上下文窗口有限。一个 Agent 跑几轮工具调用消息列表就能轻松突破几千 token。如果不做处理要么超限报错要么成本飙升。常见的处理方式有三种滑动窗口只保留最近 N 轮、摘要压缩把旧对话总结成一段话、向量召回把历史存起来需要时检索。LangChain4j 提供了ChatMemory接口Spring AI 有ChatMemory抽象都支持这几种策略。长期记忆在 Java 里通常用向量数据库实现比如 Milvus、PgVector、Redis Stack。把历史对话或知识文档做 embedding 后存进去需要时用相似度检索召回。这就是 RAG 的基础。3. LangChain4j 和 Spring AI 到底怎么选3.1 两个框架的定位差异这是 Java 工程师转型时第一个要面对的选择题。我的建议是别纠结两个都学但先学哪个取决于你的项目场景。LangChain4j 的定位是“Java 版的 LangChain”它的设计思路更贴近 Python 生态抽象层次丰富功能覆盖广。它支持大量的模型提供商、向量库、工具集成RAG 相关的组件特别全多路召回、重排序、查询转换这些高级玩法都有现成实现。如果你要做的是一个功能复杂的 Agent 应用尤其是 RAG 占比较大的场景LangChain4j 会更顺手。Spring AI 的定位是“Spring 生态原生的 AI 框架”。它的设计哲学是“约定优于配置”和 Spring Boot 的集成度极高。你熟悉的Bean、ConfigurationProperties、自动装配、Actuator 监控在 Spring AI 里都能直接用。如果你是在一个已有的 Spring Boot 项目里加 AI 能力或者团队对 Spring 生态依赖很深Spring AI 的接入成本更低。3.2 核心能力对比维度LangChain4jSpring AI模型支持非常广几乎覆盖主流厂商覆盖主流扩展也方便RAG 能力组件丰富多路召回、重排序齐全基础 RAG 完善高级玩法需自己扩展工具调用Tool注解灵活Tool注解和 Spring 集成好记忆管理ChatMemory多种实现ChatMemory抽象清晰生态集成独立生态需自己整合无缝融入 Spring Boot学习曲线概念较多抽象层次深对 Spring 开发者几乎零门槛可观测性需自己接天然支持 Micrometer、Actuator从表格能看出来两者不是替代关系而是各有侧重。我个人的实际用法是RAG 密集的部分用 LangChain4j业务编排和对外服务用 Spring AI。两者可以在同一个项目里共存因为它们底层都是 HTTP 调用模型 API不冲突。3.3 选型时容易踩的坑第一个坑是版本兼容性。LangChain4j 迭代很快不同版本之间 API 变动不小。Spring AI 相对稳定但和 Spring Boot 版本有绑定关系。选型时一定要先确认版本矩阵别上来就拉最新版很容易踩到依赖冲突。第二个坑是模型提供商的适配。不同厂商的 API 格式、参数命名、返回结构都有差异。LangChain4j 和 Spring AI 都做了适配层但适配层不是万能的。比如某些厂商的流式返回格式特殊或者工具调用的 JSON 结构不标准就需要你自己写适配代码。选型前先用最小 demo 把目标模型跑通别等到项目中期才发现模型不支持某个关键特性。第三个坑是过度设计。很多新手一上来就想搞多 Agent 协作、搞复杂的 RAG 流水线结果基础的工具调用还没跑通。我的建议是先用最简单的 ReAct 单 Agent 跑通一个真实场景比如“查数据库 生成报告”再逐步加复杂度。4. 从零搭一个能跑的 Java Agent4.1 环境准备和依赖配置先明确技术栈Spring Boot 3.x Spring AI 一个支持工具调用的模型。这里以 Spring AI 为例因为对 Spring 开发者最友好。Maven 依赖大致是这样dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency配置文件里配好模型地址、API Key、模型名称。这里要注意API Key 千万别硬编码在代码里用环境变量或者配置中心。我见过太多人把 Key 提交到 Git 仓库结果被人刷爆账单。spring: ai: openai: api-key: ${AI_API_KEY} base-url: ${AI_BASE_URL} chat: options: model: ${AI_MODEL} temperature: 0.7temperature这个参数值得说一下。做 Agent 的时候temperature 不建议设太高。因为 Agent 需要稳定地做决策、生成结构化的工具调用参数温度太高会导致输出不稳定工具调用经常解析失败。我一般设 0.1 到 0.3 之间需要创意输出的场景再单独调高。4.2 定义第一个工具工具就是一个普通的 Spring Bean 方法加上Tool注解。关键是方法描述要写清楚这是模型判断“什么时候调这个工具”的唯一依据。Component public class WeatherTools { Tool(description 查询指定城市的当前天气返回温度和天气状况) public String getWeather( ToolParam(description 城市名称例如北京、上海) String city) { // 实际项目中这里调用真实天气 API return city 晴25摄氏度; } }这里有个经验工具描述要写成“给模型看的说明书”而不是“给同事看的注释”。要明确说明这个工具能做什么、参数是什么格式、返回什么。描述写得越清楚模型调用越准确。我试过把描述从“查天气”改成“查询指定城市的当前天气返回温度和天气状况”工具调用的准确率明显提升。4.3 组装 Agent 并跑通 ReAct 循环有了工具接下来把它注册到 ChatClient 里Configuration public class AgentConfig { Bean public ChatClient chatClient(ChatClient.Builder builder, WeatherTools weatherTools) { return builder .defaultSystem(你是一个智能助手可以调用工具帮用户解决问题。) .defaultTools(weatherTools) .build(); } }然后在 Service 里调用Service public class AgentService { private final ChatClient chatClient; public AgentService(ChatClient chatClient) { this.chatClient chatClient; } public String chat(String message) { return chatClient.prompt() .user(message) .call() .content(); } }就这么几行代码一个能调用工具的 Agent 就跑起来了。当你问“北京天气怎么样”模型会自动判断需要调用getWeather生成参数city北京框架执行工具把结果塞回对话模型再生成最终回复。整个过程 ReAct 循环是框架自动跑的你不需要手写循环逻辑。4.4 加上记忆让 Agent 记住上下文上面的例子是无状态的每次对话都是全新的。要让它记住上下文需要加 ChatMemoryBean public ChatMemory chatMemory() { return MessageWindowChatMemory.builder() .maxMessages(20) .build(); } Bean public ChatClient chatClient(ChatClient.Builder builder, WeatherTools weatherTools, ChatMemory chatMemory) { return builder .defaultSystem(你是一个智能助手。) .defaultTools(weatherTools) .defaultAdvisors(new MessageChatMemoryAdvisor(chatMemory)) .build(); }MessageWindowChatMemory是滑动窗口策略只保留最近 20 条消息。这个数字要根据你的模型上下文窗口和单条消息平均长度来定。如果消息很长20 条可能就超限了如果消息很短可以适当放大。我的经验是先设一个保守值跑起来看实际 token 消耗再调。5. RAG 和多路召回在 Java 里怎么落地5.1 RAG 的基本流程RAG检索增强生成解决的是“模型不知道你的私有知识”这个问题。基本流程是把文档切块、做 embedding、存进向量库用户提问时把问题也做 embedding在向量库里找最相似的几块拼进 prompt 一起发给模型。在 LangChain4j 里这套流程有现成的组件EmbeddingStoreTextSegment store new InMemoryEmbeddingStore(); EmbeddingModel embeddingModel ...; // 入库 Document doc Document.from(你的文档内容); DocumentSplitter splitter DocumentSplitters.recursive(500, 50); ListTextSegment segments splitter.split(doc); ListEmbedding embeddings embeddingModel.embedAll(segments).content(); store.addAll(embeddings, segments); // 检索 Embedding queryEmbedding embeddingModel.embed(用户问题).content(); ListEmbeddingMatchTextSegment matches store.findRelevant(queryEmbedding, 5);DocumentSplitters.recursive(500, 50)的意思是每块最多 500 个字符块之间重叠 50 个字符。重叠是为了避免关键信息刚好被切在边界上。这个参数很关键切太大检索不精准切太小语义不完整。我的经验是中文文档 300 到 500 字符比较合适英文可以到 800 到 1000。5.2 多路召回为什么能提升效果单路向量检索有个天然缺陷它只擅长语义相似不擅长关键词精确匹配。比如用户搜“Spring AI 2.0.1 版本更新”向量检索可能召回一堆讲 Spring AI 概念的文章但就是找不到那个具体版本号。这时候就需要多路召回向量检索 关键词检索BM25同时跑然后合并结果。LangChain4j 支持把多个检索器组合起来RetrieverTextSegment vectorRetriever EmbeddingStoreContentRetriever.builder() .embeddingStore(store) .embeddingModel(embeddingModel) .maxResults(5) .build(); RetrieverTextSegment keywordRetriever ...; // BM25 检索器 RetrieverTextSegment multiRetriever new MultiRetriever(List.of( vectorRetriever, keywordRetriever)); ContentAggregator aggregator new ReRankingContentAggregator(...);多路召回之后通常还要加一个**重排序Rerank**步骤。因为多路召回的结果可能有重复、有噪声重排序模型会根据查询和文档的真实相关性重新打分排序把最相关的排到前面。这一步对最终效果提升很明显尤其是召回数量大的时候。5.3 实操中的参数调优RAG 的效果好坏八成取决于参数调优。我整理了几个关键参数和我的经验值参数作用经验值说明chunk size文档切块大小300-500 字符中文偏小英文偏大chunk overlap块间重叠chunk size 的 10%-20%避免边界信息丢失maxResults召回数量5-10太多会撑爆上下文minScore相似度阈值0.6-0.7过滤低质量召回rerank topN重排后保留数3-5最终进 prompt 的数量这些值不是固定的要根据你的文档类型和查询特点调。比如技术文档关键词密集chunk 可以小一点叙事性文档语义连贯chunk 要大一点。调参的唯一方法是准备一批真实查询跑一遍看召回质量别凭感觉设。6. 并发和性能Agent 怎么扛住真实流量6.1 Agent 的性能瓶颈在哪Agent 和普通接口最大的区别是延迟高且不稳定。一次 Agent 调用可能包含多轮 LLM 请求和多次工具调用每轮 LLM 请求动辄几秒。如果串行执行一个请求跑十几秒很正常。所以 Agent 的性能优化核心是减少串行等待。瓶颈主要有三个LLM 调用延迟、工具调用延迟、上下文长度导致的 token 处理延迟。LLM 调用延迟你控制不了但可以通过流式返回改善用户体验工具调用延迟可以通过并行化优化上下文长度可以通过记忆压缩和 RAG 精准召回控制。6.2 并发控制的关键手段第一连接池和超时设置。LLM API 调用本质是 HTTP 请求必须配连接池和合理的超时。超时设太短会频繁失败设太长会拖垮线程池。我的经验是连接超时 5 秒读取超时 60 秒因为 LLM 生成长文本确实慢。第二限流和降级。Agent 服务一定要有限流否则突发流量会把 API 配额打满。可以用 Resilience4j 做限流和熔断超过阈值直接返回降级响应而不是让请求堆积。第三异步化。工具调用如果互相独立可以用CompletableFuture并行执行。比如一个 Agent 需要同时查天气、查汇率、查库存这三个工具没有依赖关系完全可以并行。CompletableFutureString weatherFuture CompletableFuture.supplyAsync( () - weatherTools.getWeather(北京)); CompletableFutureString rateFuture CompletableFuture.supplyAsync( () - rateTools.getRate(USD, CNY)); CompletableFuture.allOf(weatherFuture, rateFuture).join();第四流式返回。Spring AI 和 LangChain4j 都支持流式输出用FluxString或者 SSE 推给前端。用户能立刻看到模型在“打字”感知延迟大幅降低。虽然总耗时没变但体验完全不一样。6.3 上下文爆炸的预防Agent 跑多轮之后对话历史会越来越长最终撑爆上下文窗口。预防手段有三个一是滑动窗口只保留最近 N 轮二是摘要压缩把旧对话用模型总结成一段话三是把历史存进向量库需要时检索召回。我实际项目里的做法是组合使用最近 5 轮保留原文5 轮之前的做摘要超过 20 轮的存向量库。这样既保证了近期上下文的完整性又控制了 token 消耗。7. 常见问题排查和避坑清单7.1 工具调用不触发怎么办这是最常见的问题。模型该调工具的时候不调或者该调 A 工具却调了 B。排查思路检查工具描述是否清晰模型能不能看懂这个工具是干什么的检查系统提示词有没有引导模型使用工具检查模型本身是否支持工具调用有些小模型不支持检查参数类型是否过于复杂模型生成不了对应的 JSON我的经验是工具描述里加上使用场景比如“当用户询问天气时使用此工具”比单纯描述功能有效得多。7.2 工具调用死循环怎么破模型有时候会反复调用同一个工具陷入死循环。原因通常是工具返回的结果模型不满意或者模型理解错了任务。解决办法是设置最大迭代次数超过就强制中断并返回当前结果。LangChain4j 和 Spring AI 都支持配置最大工具调用轮数一般设 5 到 10 轮就够了。7.3 常见问题速查表问题现象可能原因解决方向工具不触发描述不清、模型不支持优化描述、换模型参数解析失败参数类型复杂、JSON 格式错简化参数、加校验死循环结果不满足、任务理解错设最大轮数、优化提示词上下文超限历史太长、召回太多记忆压缩、减少召回数响应太慢串行调用、无流式并行化、开流式结果不稳定temperature 太高调低温度召回不准chunk 不合理、无重排调 chunk、加重排7.4 几个文档里不会写的坑第一个坑模型返回的 JSON 不一定合法。即使你要求它输出 JSON它也可能多打一个逗号或者少一个引号。生产环境一定要加 JSON 解析的容错和重试。第二个坑工具返回值别太大。我见过有人把整个数据库查询结果塞回对话几万 token 直接把上下文撑爆。工具返回要做裁剪只返回模型需要的关键信息。第三个坑API Key 的额度监控。Agent 调用频率高很容易把额度跑光。一定要做用量监控和告警别等到线上挂了才发现。第四个坑不同模型的工具调用格式不一样。换模型的时候一定要重新测工具调用别以为换个模型名就完事了。8. 学习路线和进阶方向如果你是从零开始我建议按这个顺序走先用 Spring AI 跑通一个最简单的工具调用 Agent理解 ReAct 循环然后加上 ChatMemory理解记忆机制接着接一个向量库做 RAG理解检索增强最后做多路召回和重排序理解高级检索。每一步都要有能跑起来的代码别只看文档。进阶方向有几个一是多 Agent 协作让多个 Agent 分工完成复杂任务二是 Agent 的可观测性把每轮思考、每次工具调用都记录下来方便调试和优化三是成本优化通过缓存、模型分级、prompt 压缩等手段降低 token 消耗。我个人在实际操作中的体会是Java 工程师转 AI Agent最大的障碍不是技术而是心态。总觉得自己不懂算法、不懂模型就做不了 AI。但实际上 Agent 这一层拼的就是工程能力就是你怎么把模型、工具、记忆、流程编排好。这些东西 Java 工程师本来就在做只是换了个对象而已。把 ReAct 理解成一种特殊的业务流程把工具调用理解成一种特殊的 RPC把记忆理解成一种特殊的缓存你会发现一切都似曾相识。最后再分享一个小技巧调试 Agent 的时候把每一轮的 Thought、Action、Observation 都打日志打出来。这样你能清楚看到模型在想什么、调了什么、拿到了什么。大部分问题看一眼日志就定位了比瞎猜高效得多。