1. 为什么 Java 工程师转 AI Agent 是当下最顺的一条路先把结论摆在前面Java 工程师转 AI Agent不是从零开始学一门新语言而是把已有的工程能力迁移到一个新的调用范式上。你过去写 Spring Boot 那套东西——依赖注入、分层架构、统一异常处理、连接池、线程池、可观测性——在 Agent 开发里一个都没浪费反而成了稀缺优势。市面上大量 Agent 教程是 Python 视角的讲的是 prompt 怎么写、chain 怎么串但真到了要扛并发、要做权限、要接企业已有系统的时候纯脚本思维就顶不住了。这时候 Java 工程师的价值就出来了。这篇内容我打算讲透三件事Agent 的底层运行原理到底是什么LangChain4j 和 Spring AI 这两条 Java 路线怎么选以及一个能真正落地的 Agent 从搭建到扛并发的完整过程。适合有 Java 基础、想切入 AI Agent 但不知道从哪下手的开发也适合已经在用 Python 玩 Agent、想看看 Java 生态现在到什么程度的同学。我不会只给你概念会把参数、配置、踩过的坑都摊开讲。先对齐一个认知AI Agent 不是更聪明的聊天机器人。普通 LLM 调用是你问我答一问一答就结束了。Agent 的核心是它能自己决定下一步做什么——调用哪个工具、要不要再查一次、结果够不够、要不要重试。这个自己决定的循环就是 ReActReasoning Acting范式。理解了这个循环你就理解了 Agent 的一切。2. Agent 底层原理拆解ReAct 循环到底在转什么2.1 从一次普通 LLM 调用说起普通调用长这样你给模型一段 prompt模型返回一段文本。整个过程是单向的模型没有手它不能查数据库、不能调接口、不能读文件。它只能基于训练时见过的知识和你给的上下文来回答。问题就来了。你问我们系统里订单号 12345 现在什么状态模型根本不知道因为这是你私有系统的实时数据。你要么把数据塞进 prompt上下文有限、还贵要么让模型有能力自己去查。Agent 就是干后面这件事的。2.2 ReAct 的三步循环ReAct 把一次任务拆成不断重复的三步Thought思考模型分析当前状态决定下一步要干什么。比如我需要先查订单状态得调用订单查询工具。Action行动模型输出一个结构化的调用请求指定工具名和参数。比如queryOrder(orderId12345)。Observation观察你的代码真正执行这个工具把结果返回给模型。模型看到结果后回到第一步继续思考直到它认为可以给出最终答案。这个循环会转很多圈。关键在于模型不直接执行任何东西它只输出我想调用什么真正执行的是你的 Java 代码。这一点极其重要因为它意味着所有权限控制、参数校验、超时处理、审计日志都握在你手里。这也是 Java 工程师的主场——你写的不是 prompt你写的是那个安全执行工具的运行时。2.3 工具调用是怎么被结构化出来的模型输出的是自然语言怎么变成可靠的函数调用两条路。一条是靠 prompt 约定格式让模型按{tool: ..., args: {...}}输出然后你解析。另一条是现在主流模型都支持的Function Calling / Tool Calling能力——你在请求里声明有哪些工具、每个工具的参数 schema模型会直接返回结构化的调用意图不用你自己解析字符串。Java 侧的做法通常是后者。LangChain4j 和 Spring AI 都提供了注解方式把一个普通 Java 方法标记成工具框架自动生成 schema 塞进请求。比如public class OrderTools { Tool(根据订单号查询订单当前状态) public String queryOrder(P(订单号) String orderId) { return orderService.getStatus(orderId); } }框架会把这个方法的名称、描述、参数类型转成模型能理解的工具定义。模型决定调用时框架负责把参数反序列化、反射调用你的方法、把返回值再喂回去。你写的还是普通 Java 方法只是多了一个注解。2.4 记忆与上下文管理Agent 要能多轮对话、要能记住前面查过什么就涉及记忆。简单做法是把历史消息全塞进上下文但 token 会爆。工程做法是分层短期记忆放当前会话的消息窗口长期记忆落到向量库做检索这就是 RAG 的用武之地。LangChain4j 里的ChatMemory、Spring AI 里的ChatMemory都是干这个的底层可以接内存、Redis 或者数据库。这里有个容易忽略的点记忆不是越多越好。上下文塞太多无关历史模型反而会跑偏还费钱。我一般会给会话设一个消息条数上限超出后做摘要压缩把老消息压成一段总结再放回去。3. Java 路线选型LangChain4j 还是 Spring AI3.1 两条路线的定位差异这是 Java 工程师最纠结的问题。我的判断是看你的项目是以 AI 为核心还是给现有 Spring 系统加 AI 能力。LangChain4j 更像一个独立的 AI 应用框架抽象层次丰富Agent、RAG、工具、记忆、多模型适配都做得比较全社区活跃迭代快。你想快速搭一个功能完整的 Agent它上手更顺。Spring AI 则是把 AI 能力Spring 化。它的哲学是如果你已经在写 Spring Boot那接入 AI 应该像接入一个JdbcTemplate一样自然。配置走application.ymlBean 走依赖注入可观测性接 Micrometer。它和 Spring 生态的融合度是 LangChain4j 比不了的。3.2 关键能力对照维度LangChain4jSpring AI定位独立 AI 应用框架Spring 生态的 AI 抽象层工具调用Tool注解成熟Tool注解逐步完善RAG 支持内置 Easy RAG开箱即用有 Advisor 机制需自己组装多模型适配覆盖广切换方便覆盖主流配置化与 Spring 集成需手动整合原生自动配置学习曲线概念多需理解框架对 Spring 开发者几乎零成本适合场景AI 为核心的新应用存量系统加 AI3.3 我的实际选择建议如果你是从零起一个新项目、Agent 逻辑复杂、要频繁试不同模型和工具组合我倾向 LangChain4j。它的AiServices能把一个接口直接变成 Agent声明式写法很省事。如果你是在一个已经跑了几年的 Spring Boot 单体或微服务里加 AI 能力比如给客服系统加个智能问答、给运营后台加个数据查询助手那 Spring AI 更合适。你不用引入一套新的编程范式团队里其他 Spring 开发者也能看懂。还有个现实情况这两个不是互斥的。我见过有项目用 Spring AI 做基础模型接入和配置管理用 LangChain4j 做复杂的 Agent 编排各取所长。别被必须二选一的思维框住。4. 从零搭一个能落地的 Agent完整实操4.1 环境与依赖准备先明确版本。Java 至少 17我建议直接上 21虚拟线程对 Agent 这种大量 IO 等待的场景收益明显。构建工具用 Maven 或 Gradle 都行下面以 Maven 举例。LangChain4j 的核心依赖dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.35.0/version /dependencySpring AI 的话用 starter 更省事dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency注意模型接入这块国内很多团队会用兼容 OpenAI 协议的国产模型服务。配置时把 base-url 和 api-key 换成对应服务的即可接口协议一致代码基本不用改。具体用哪家按团队合规要求来定。4.2 定义工具Agent 的手Agent 的能力边界由工具决定。我建议工具设计遵循三个原则单一职责、参数明确、返回结构化。Component public class DataQueryTools { private final OrderRepository orderRepository; public DataQueryTools(OrderRepository orderRepository) { this.orderRepository orderRepository; } Tool(根据订单号查询订单的当前状态和金额) public OrderInfo queryOrder(P(订单号纯数字字符串) String orderId) { return orderRepository.findById(orderId) .map(o - new OrderInfo(o.getId(), o.getStatus(), o.getAmount())) .orElseThrow(() - new IllegalArgumentException(订单不存在: orderId)); } Tool(统计指定日期范围内的订单总数) public long countOrders(P(开始日期格式 yyyy-MM-dd) String start, P(结束日期格式 yyyy-MM-dd) String end) { return orderRepository.countBetween(LocalDate.parse(start), LocalDate.parse(end)); } }工具描述要写清楚因为模型是靠描述来判断该不该调用这个工具的。描述含糊模型就会乱调或者不调。参数说明也一样格式要求写明白能大幅降低模型传错参数的概率。4.3 组装 AgentLangChain4j 的声明式写法public interface OrderAgent { SystemMessage(你是一个订单助手只能基于工具返回的真实数据回答禁止编造。) String chat(MemoryId String sessionId, UserMessage String message); } OrderAgent agent AiServices.builder(OrderAgent.class) .chatLanguageModel(model) .tools(new DataQueryTools(orderRepository)) .chatMemoryProvider(id - MessageWindowChatMemory.withMaxMessages(20)) .build();MessageWindowChatMemory.withMaxMessages(20)就是前面说的记忆窗口只保留最近 20 条消息防止上下文无限膨胀。MemoryId用来区分不同会话多用户场景下每个用户一个独立记忆。Spring AI 的写法思路类似用ChatClient加工具ChatClient client ChatClient.builder(chatModel) .defaultSystem(你是一个订单助手只能基于工具返回的真实数据回答。) .defaultTools(new DataQueryTools(orderRepository)) .build(); String answer client.prompt() .user(帮我查一下订单 12345 的状态) .call() .content();4.4 一次完整调用的执行链路拿帮我查一下订单 12345 的状态举例实际发生的事是用户消息进入 Agent连同系统提示、工具定义、历史记忆一起打包成请求发给模型。模型返回一个工具调用意图queryOrder(orderId12345)。框架反射调用你的queryOrder方法拿到OrderInfo。框架把结果序列化后作为 Observation 追加到消息里再次请求模型。模型看到数据生成自然语言回答订单 12345 当前状态是已发货金额 299 元。框架把最终回答返回同时把这一轮消息写入记忆。整个过程可能只转一圈也可能转好几圈比如模型先查订单、再统计、再对比。你要清楚的是每一圈都是一次真实的模型请求都消耗 token 和时间。这就是后面讲并发和成本优化的基础。5. 扛并发Agent 上生产必须过的坎5.1 并发瓶颈到底在哪很多人以为 Agent 慢是因为模型推理慢。对但不全对。真实链路里一次 Agent 调用可能包含 3 到 5 次模型请求每次请求的延迟在几百毫秒到几秒不等再加上工具执行查库、调接口的时间。这些时间绝大部分是 IO 等待不是 CPU 计算。这意味着什么意味着你不需要堆很多 CPU 核你需要的是让线程在等待时别占着资源。这正是虚拟线程的用武之地。5.2 用虚拟线程扛住高并发Java 21 的虚拟线程对这种大量阻塞在 IO 上的场景几乎是量身定做。传统线程池里一个线程等模型响应时就被占住了池子满了新请求就得排队。虚拟线程可以在等待时让出载体线程几千上万个并发请求也不会把平台线程耗尽。try (var executor Executors.newVirtualThreadPerTaskExecutor()) { ListFutureString futures requests.stream() .map(req - executor.submit(() - agent.chat(req.sessionId(), req.message()))) .toList(); // 收集结果 }实测下来同样的机器配置把线程池换成虚拟线程后Agent 接口的吞吐能提升好几倍尤其是那种单次调用要转好几圈的复杂任务。5.3 超时、重试与降级模型服务不是永远可用的。必须设超时而且要分层设单次模型请求的超时、整个 Agent 循环的总超时、工具执行的超时。我一般给单次模型请求设 30 秒整个 Agent 循环设 60 秒工具执行设 5 秒。重试要谨慎。模型请求失败重试是合理的但工具调用失败重试要小心副作用——如果工具是下单这种写操作重试可能造成重复下单。我的做法是读操作可以自动重试写操作要么不重试要么用幂等键保证安全。降级方案也得有。模型服务挂了怎么办可以降级到规则引擎或者返回一个当前服务繁忙请稍后再试的友好提示而不是让请求一直挂着直到超时。5.4 限流与成本控制Agent 是烧 token 的。一个复杂任务转五圈token 消耗是普通问答的好几倍。生产环境必须做限流按用户、按接口、按时间窗口都行。同时要监控 token 消耗设预算告警。还有个省钱技巧简单任务别用 Agent。如果一个问题不需要调用工具、不需要多步推理直接走普通 LLM 调用甚至走缓存就行。Agent 的循环是有成本的别滥用。6. 常见问题与排查技巧实录6.1 模型不调用工具怎么办这是最高频的问题。模型该调工具的时候不调直接编了个答案。排查顺序先看工具描述是不是太模糊。描述里要明确什么时候用这个工具。看系统提示有没有强调必须基于工具返回的真实数据回答禁止编造。看模型本身的能力。有些小模型对工具调用的支持就是弱换个能力强的模型试试。看工具数量。工具太多比如超过 20 个模型会挑花眼考虑分组或者按场景动态注入。6.2 参数传错或格式不对模型把日期传成2024年1月1日而不是2024-01-01或者把数字传成字符串。解决办法在参数描述里把格式要求写死同时在工具方法里做防御性校验格式不对就抛出清晰的错误信息让模型看到错误后自己纠正重试。6.3 循环停不下来模型一直调工具转十几圈还不给最终答案。这通常是任务描述太开放或者工具返回的结果让模型觉得还不够。对策设最大循环次数比如 10 次到了就强制让模型基于现有信息给答案同时优化工具返回别返回一大堆无关数据。6.4 常见问题速查表现象可能原因排查方向不调用工具描述模糊/模型弱/工具太多优化描述、换模型、分组注入参数格式错描述未约束格式描述写死格式方法内校验循环不停任务太开放/返回太杂设最大轮次、精简工具返回响应慢循环多/模型慢/无并发虚拟线程、超时、减少轮次token 超预算记忆太长/滥用 Agent压缩记忆、简单任务走直连结果不稳定温度太高降低 temperature结构化输出6.5 几个我踩过的坑第一个坑别把敏感数据直接塞进 prompt。用户隐私、密钥这类东西要么脱敏要么根本不让模型看到。工具执行在你这边你完全可以在返回给模型前做过滤。第二个坑日志要打全。Agent 出问题时你需要看到每一轮的 Thought、Action、Observation。没有这些日志排查就是盲人摸象。我一般会把整个循环过程结构化记录下来方便回放。第三个坑别迷信通用 Agent。一个 Agent 什么都能干往往什么都干不好。按业务场景拆成多个专用 Agent每个 Agent 工具少、提示清晰效果和稳定性都好得多。7. 关于转型这件事我自己的体会从 Java 后端转 AI Agent最难的不是学框架是换一种思维方式。以前写代码逻辑是你写死的输入输出确定。现在你要接受模型是个不确定的组件你的工程能力要用在约束和兜底上——用工具定义约束它能做什么用校验兜住它可能犯的错用超时和降级兜住它可能挂掉的情况。LangChain4j 和 Spring AI 这两个框架我建议都花点时间摸一遍。不用纠结先学哪个先动手把一个能查数据库、能多轮对话的小 Agent 跑起来比看十篇原理文章都管用。跑通之后你自然会遇到并发、成本、稳定性这些问题那时候再回头看这篇里的排查表会有完全不一样的感受。最后分享一个我常用的调试技巧把 Agent 的每一轮循环单独打日志标上轮次编号和耗时。你会发现很多模型不听话的问题其实是某一轮工具返回了意料之外的数据模型被带偏了。定位到具体是哪一轮出的问题解决起来就快多了。