1. 为什么 Java 工程师转 AI Agent 有天然优势这两年身边不少 Java 老哥都在焦虑AI Agent 这么火是不是又要重新学 Python、重新学一套技术栈我一开始也这么想直到真正用 LangChain4j 和 Spring AI 把几个 Agent 项目跑起来之后才发现Java 工程师转型 AI Agent其实比想象中顺得多甚至有些地方是天然优势。先说结论Java 工程师做 AI Agent核心不是重学一门语言而是把已有的工程能力迁移到新的编排层上。Agent 的本质是什么是让大模型能思考、能调用工具、能记住上下文、能循环执行直到完成任务。拆开看这里面 80% 是工程问题——状态管理、并发控制、超时重试、可观测性、权限隔离这些恰恰是 Java 后端天天在干的事。剩下 20% 才是模型相关的 prompt 设计、工具描述、召回策略。我见过太多 Python 出身的同学写 Agent Demo 很溜一到生产环境就崩并发一上来线程池打满、工具调用超时没有兜底、上下文无限增长把 token 烧穿、多个 Agent 之间状态互相污染。这些问题在 Java 生态里都有成熟解法Spring 的依赖注入、线程池管理、Resilience4j 的熔断限流、Micrometer 的指标埋点直接拿来就能用。所以这篇我不打算写成又一篇AI Agent 入门科普而是站在一个写了七八年 Java、最近一年扎进 Agent 落地的从业者角度把原理、选型、实操、踩坑一条线讲透。适合谁看有 Java 基础、想转 AI Agent 方向的后端工程师已经在用 LangChain4j 或 Spring AI 但卡在落地环节的同行以及想搞清楚Agent 到底怎么扛并发的技术负责人。看完你至少能自己搭一个能上生产的 Agent 骨架而不是停留在调 API 的玩具阶段。2. 先把原理吃透ReAct 到底在循环什么2.1 ReAct 不是框架是一种思考-行动的循环范式很多人一上来就问LangChain4j 和 Spring AI 哪个好其实这个问题问早了。你得先明白 Agent 的底层范式否则换哪个框架都是照猫画虎。目前主流 Agent 的骨架基本都绕不开ReActReasoning Acting它的核心就一句话让模型在想和做之间反复横跳直到它自己认为任务完成。具体循环长这样Thought思考模型根据当前上下文推理下一步该干什么。Action行动模型决定调用某个工具并给出参数。Observation观察工具执行返回结果塞回上下文。回到第 1 步直到模型输出 Final Answer。听起来简单但魔鬼在细节里。我拿一个真实场景举例用户问帮我查一下北京今天天气如果下雨就提醒我带伞。Agent 的第一轮 Thought 是我需要查天气Action 是调用getWeather(北京)Observation 返回小雨。第二轮 Thought 是下雨了需要提醒用户Action 是调用sendReminder(带伞)然后输出最终答复。这里有个关键点很多人忽略ReAct 的循环次数必须设上限。我踩过的坑是早期没设maxIterations模型偶尔会陷入我再确认一下的死循环一个请求烧掉几万 token 还不出结果。LangChain4j 里默认是 10 次Spring AI 需要自己配生产环境我一般压到 5 到 8 次配合超时兜底。2.2 Function Calling 是 ReAct 的手脚别搞混ReAct 是大脑的思考模式Function Calling工具调用是手脚的执行机制。现在主流大模型都原生支持 Function Calling你把工具的描述名字、参数、用途以 JSON Schema 的形式传给模型模型在需要时会返回一个结构化的调用请求而不是纯文本。为什么这个区分重要因为纯文本解析工具调用是极其脆弱的。早期我用正则去抠模型输出里的Action: xxx模型稍微换个措辞就解析失败。原生 Function Calling 返回的是结构化 JSON稳定得多。LangChain4j 的Tool注解、Spring AI 的Tool注解底层都是帮你把 Java 方法转成模型能理解的 Schema再把模型的调用请求反序列化成方法调用。提示工具方法的描述description写得越清楚模型选错工具的概率越低。我习惯在描述里写清楚什么时候用和什么时候不要用比只写功能有效得多。2.3 记忆、规划、工具Agent 的三根支柱把 ReAct 拆得更细一点一个能用的 Agent 需要三样东西记忆Memory短期记忆是当前对话的上下文长期记忆是跨会话的知识。短期记忆的坑是 token 爆炸长期记忆的坑是召回不准。规划Planning简单任务靠 ReAct 单循环就够复杂任务需要任务分解比如先拆成子任务再逐个执行。工具ToolsAgent 能调用的外部能力查数据库、调 API、发消息都算。这三根支柱里Java 工程师最容易上手的是工具层因为本质就是写 Service 方法加个注解。最难的是记忆管理因为它直接关系到成本和效果。我后面会专门讲怎么用滑动窗口加摘要压缩来控制上下文。3. 框架选型LangChain4j 还是 Spring AI3.1 两个框架的定位差异这是被问得最多的问题。我的判断是LangChain4j 更像全家桶Spring AI 更像Spring 生态的原生公民。LangChain4j 的设计思路跟 Python 的 LangChain 一脉相承抽象层次多组件丰富各种 ChatModel、EmbeddingModel、VectorStore、Retriever、Agent 都有现成实现多路召回、RAG 这些高级玩法开箱即用。缺点是抽象层多出问题排查链路长版本迭代快偶尔有 breaking change。Spring AI 走的是 Spring 一贯的路子约定优于配置跟 Spring Boot 无缝集成Tool、ChatClient这些 API 设计得很Spring。如果你团队本来就是 Spring Boot 技术栈用 Spring AI 的迁移成本几乎为零。缺点是生态相对新一些高级 RAG 特性不如 LangChain4j 丰富而且 Spring AI Alibaba 这类扩展的维护节奏需要关注。3.2 选型对照表维度LangChain4jSpring AI生态丰富度高组件齐全中核心够用Spring 集成需手动配置原生无缝学习曲线抽象多稍陡平缓符合 Spring 习惯RAG 能力强多路召回现成够用需自己组装版本稳定性迭代快相对稳适合场景复杂 Agent、RAG 重度企业级、Spring 技术栈3.3 我的实际选择建议如果你是从零起步、团队全是 Spring 背景先用 Spring AI 把最小闭环跑通别一上来就上 LangChain4j 的复杂抽象。等业务真的需要多路召回、复杂 Agent 编排时再考虑引入 LangChain4j 或者两者混用。我现在的项目就是混用的主流程用 Spring AI 的ChatClient和ToolRAG 部分用 LangChain4j 的EmbeddingStore和ContentRetriever。两者并不冲突都是操作同一批模型 API只是封装不同。注意混用时要统一模型客户端配置避免两套框架各自维护一份 API Key 和超时配置否则排查问题时会很痛苦。4. 从零搭一个能用的 Agent完整实操4.1 环境与依赖准备先明确技术栈Spring Boot 3.2、JDK 17、Spring AI 1.0.x或对应稳定版、一个大模型服务我用的是兼容 OpenAI 协议的国内模型服务接百炼的 Qwen 系列也很顺。Maven 依赖核心就几个dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency配置文件里配好 base-url、api-key、model 名称。这里有个坑不同模型服务的 base-url 路径不一样有的要带/v1有的不带配错了会报 404 而不是明确的鉴权错误排查半天。4.2 定义工具把 Service 方法变成 Agent 的手脚工具定义是整个 Agent 最实在的部分。以查订单为例Component public class OrderTools { private final OrderService orderService; public OrderTools(OrderService orderService) { this.orderService orderService; } Tool(description 根据订单号查询订单状态。当用户询问订单进度、物流、是否发货时使用。参数必须是完整的订单号。) public OrderInfo queryOrder(ToolParam(description 订单号例如 ORD20240101001) String orderNo) { return orderService.queryByNo(orderNo); } }几个实操要点描述要写何时用不只是是什么。模型选工具靠的就是这段描述。参数类型尽量简单String、int、boolean 最稳复杂对象容易让模型生成错误的 JSON。工具方法要幂等或可重试因为模型可能重复调用同一个工具。返回值要精简别把整个数据库实体塞回去token 会爆。我一般返回一个精简的 DTO。4.3 组装 AgentChatClient 工具 记忆Spring AI 里组装一个带工具的对话客户端大概是这样Configuration public class AgentConfig { Bean public ChatClient agentChatClient(ChatClient.Builder builder, OrderTools orderTools) { return builder .defaultSystem(你是一个订单助手帮用户查询订单状态。不确定时先询问不要编造订单信息。) .defaultTools(orderTools) .build(); } }调用时String reply agentChatClient.prompt() .user(帮我查下订单 ORD20240101001 到哪了) .call() .content();框架会自动完成 ReAct 循环模型判断要调queryOrder框架执行工具把结果回传模型再生成自然语言答复。你写的是同步代码底层帮你跑了整个循环。4.4 记忆管理控制上下文不爆炸默认情况下每次请求是独立的多轮对话需要显式管理记忆。Spring AI 提供ChatMemoryLangChain4j 提供ChatMemoryStore。我的做法是滑动窗口 摘要压缩保留最近 N 轮完整对话N 一般取 6 到 10。更早的对话用一次模型调用压缩成一段摘要塞在系统提示里。关键信息订单号、用户 ID单独抽出来存结构化字段不依赖模型记忆。这样既控制了 token又不会丢掉关键上下文。实测下来一个中等复杂度的客服 Agent单次请求 token 能压到原来的三分之一。4.5 参数计算maxIterations 和超时怎么定这两个参数直接决定 Agent 的稳定性和成本。我的经验公式maxIterations任务平均需要的工具调用次数 × 2再封顶。简单查询类取 5复杂多步任务取 8 到 10。单次工具超时下游 API 的 P99 延迟 × 1.5。数据库查询一般 2 秒外部 API 一般 5 秒。整体请求超时maxIterations × 单次工具超时 模型推理时间。别设太短否则复杂任务会被误杀。举个例子一个订单 Agent平均调 2 次工具单次工具超时 3 秒模型推理每次约 2 秒。那整体超时 5 × 3 5 × 2 25 秒我一般设 30 秒留余量。5. 生产落地并发、成本与可观测性5.1 AI Agent 怎么扛并发这是热词里高频出现的问题也是 Java 工程师的主场。Agent 请求的特点是长耗时、高 token 消耗、下游依赖多跟传统 CRUD 接口完全不是一个模型。我的并发方案分三层第一层请求入口限流。用 Resilience4j 或 Sentinel 对 Agent 接口做限流按用户维度或全局维度。因为模型服务本身有 QPS 限制打爆了大家一起挂。第二层线程池隔离。Agent 调用是阻塞的同步模型客户端必须用独立线程池别跟主业务线程池混用。核心线程数按模型服务的并发能力定我一般设 20 到 50队列用有界队列满了直接拒绝而不是无限堆积。第三层异步化。对于耗时特别长的 Agent 任务改成异步提交 轮询结果或 SSE 推送。用户不用干等服务端也不会因为长连接堆积。Bean(agentExecutor) public ThreadPoolTaskExecutor agentExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setCorePoolSize(30); executor.setMaxPoolSize(50); executor.setQueueCapacity(100); executor.setRejectedExecutionHandler(new ThreadPoolExecutor.AbortPolicy()); executor.setThreadNamePrefix(agent-); return executor; }注意队列一定要有界。我见过用无界队列的流量高峰时任务堆了几万个内存直接 OOM而且用户拿到的是几分钟前的过期结果。5.2 成本控制token 就是钱Agent 的成本比普通接口高一个数量级因为每次请求都要过模型而且 ReAct 循环会放大 token 消耗。几个实操手段工具返回值精简只返回模型需要判断的字段别返回整个对象。系统提示复用把不变的系统提示放在前面利用模型的 prompt 缓存部分服务支持。小模型干小事意图识别、参数抽取这类简单任务用小模型复杂推理才用大模型。缓存高频结果相同问题相同参数的结果缓存起来直接返回。我做过统计光是把工具返回值从完整实体改成精简 DTO单次请求 token 就降了 40%。5.3 可观测性Agent 出问题怎么查Agent 最麻烦的是它为什么这么答。传统日志不够用你需要记录完整的 ReAct 轨迹每一轮的 Thought、Action、Observation 都要落库或打日志。我一般记录这几个字段traceId、用户输入、每轮的工具调用及参数、每轮的工具返回、最终输出、总 token 数、总耗时。这样出问题时能完整回放。Spring AI 和 LangChain4j 都支持监听器Listener可以在工具调用前后埋点。指标方面用 Micrometer 暴露几个关键指标请求量、成功率、平均迭代次数、平均 token 消耗、P99 延迟。这几个指标一波动基本能定位到是模型问题还是工具问题。6. 常见问题与排查技巧实录6.1 高频问题速查表现象可能原因排查方向模型不调用工具直接瞎答工具描述不清 / 系统提示没约束检查 description加必须调用工具约束工具调用参数错误参数 Schema 太复杂简化参数类型加示例陷入死循环没设 maxIterations设上限 超时上下文超长报错记忆没裁剪滑动窗口 摘要并发高时大量超时线程池/连接池不足隔离线程池调大连接池返回结果不稳定模型温度太高降到 0 到 0.3工具重复调用模型没拿到上次结果检查 Observation 是否正确回传6.2 几个我踩过的坑坑一工具方法抛异常直接中断整个循环。早期我的工具方法没做异常处理下游 API 一超时整个 Agent 就崩了。正确做法是工具内部 catch 异常返回一个调用失败原因 xxx的结构化结果让模型自己决定是重试还是换方案。坑二系统提示写太长反而效果差。我一度把系统提示写到两千字结果模型开始忽略后面的约束。后来精简到五百字以内只保留最关键的规则效果反而更好。模型对超长提示的注意力是衰减的。坑三多轮对话里模型记错了订单号。这是记忆管理的经典问题。解决办法是把关键实体订单号、用户 ID从对话历史里抽出来作为结构化参数单独传给模型而不是指望它从历史里翻。坑四不同模型对 Function Calling 的支持程度不一样。有的模型返回的 JSON 格式不规范有的不支持并行工具调用。切换模型时一定要回归测试工具调用链路别以为换个模型名就完事。6.3 独家避坑技巧给工具加防抖同一个工具在短时间内被相同参数调用多次直接返回缓存结果避免模型抽风重复调用。给 Agent 加兜底回复当迭代次数用尽还没出结果时返回一个友好的兜底话术而不是抛异常给用户。灰度上线新 Agent 先小流量跑观察工具调用成功率和用户满意度再逐步放量。准备降级方案模型服务不可用时降级到规则引擎或人工客服别让整个功能挂掉。7. 学习路线与后续扩展如果你现在还是 Java 后端想系统转 AI Agent我给一条我实际走过的路线第一步把 ReAct 和 Function Calling 的原理搞懂不用写代码先理解循环和工具调用机制。第二步用 Spring AI 跑通一个最小 Agent就一个工具、一个对话感受整个链路。第三步加上记忆管理和多工具处理多轮对话和工具选择。第四步做并发和成本优化这是从 Demo 到生产的关键一跃。第五步引入 RAG用 LangChain4j 的检索能力给 Agent 接上私有知识库。再往后可以扩展的方向很多多 Agent 协作一个负责规划、一个负责执行、Agent 的可观测性平台、基于工作流的 Agent 编排。这些我还在摸索等有成熟经验再单独写。最后分享一个我个人的体会Java 工程师转 AI Agent最大的障碍不是技术是心态。别觉得自己不懂 Python、不懂算法就做不了Agent 落地拼的是工程能力而这恰恰是 Java 工程师的强项。把模型当成一个不太靠谱但很聪明的下游服务用你熟悉的工程手段去约束它、兜底它、观测它事情就成了一大半。