1. 从一个 Java 老兵的困惑说起：Agent 到底是什么

做了七八年 Java 后端，CRUD 写了无数遍，Spring 那套东西闭着眼睛都能搭起来。但最近一年，身边越来越多人开始聊 Agent，什么 AI Agent、Agent 开发、Agent 框架，听得我一愣一愣的。最开始我以为这又是哪个新出的微服务框架，结果一查发现完全不是一回事。这篇文章就是把我从 Java 后端视角理解 Agent 的整个过程梳理出来，给同样困惑的 Javaer 一个参考。

先说结论：Agent 不是框架，不是中间件，也不是某种新的设计模式。它是一种让大语言模型（LLM）从"只会聊天"变成"能自己干活"的系统架构。你可以把它理解成一个有了手和脚的 ChatGPT——它不仅能回答问题，还能自己决定去调用什么工具、查什么数据、执行什么操作，然后根据结果决定下一步干什么。

对于 Java 开发者来说，这个概念其实不陌生。我们平时写的 Service 层编排逻辑，本质上就是在做类似的事情：根据条件判断调用哪个下游服务，拿到结果后再决定下一步。Agent 的核心区别在于，这个"判断和决策"的过程不再由你硬编码，而是交给 LLM 来动态决定。这就是为什么它叫"智能体"而不是"工作流"。

这篇文章适合哪些人看？如果你是有 Java 基础、想了解 Agent 但不知道从哪下手的后端开发，那正好。如果你已经在用 Spring AI 或者 ADK 尝试搭 Agent，但对其中的设计思路还不太清晰，也能从里面找到一些共鸣。我会尽量用 Java 开发者熟悉的类比来讲，不堆砌术语，把"Agent 是什么、怎么运转、和传统开发有什么区别"这几个问题讲透。

2. Agent 的核心架构拆解：和写 Java 服务有什么不同

2.1 传统 Java 服务与 Agent 的本质差异

先拿一个最常见的场景对比。假设你要做一个"根据用户问题查询订单状态"的功能。

传统 Java 写法是这样的：Controller 接收请求，Service 层根据请求参数判断是要查订单还是要查物流，然后调用对应的 DAO 或者远程接口，组装结果返回。整个流程是你提前设计好的，if-else 写得明明白白，每条路径都可预测。

Agent 的写法完全不同。你把"查询订单状态"这个能力封装成一个工具（Tool），把用户的问题直接扔给 LLM，LLM 自己判断："用户问的是订单状态，我应该调用 queryOrder 这个工具，参数是订单号。"然后它调用工具拿到结果，再组织语言回复用户。如果用户接着问"那这个订单什么时候能到"，LLM 会判断需要调用物流查询工具，而不是订单查询工具。

核心差异在于：传统服务的控制流是你写的，Agent 的控制流是 LLM 在运行时决定的。这带来的好处是灵活性——你不需要为每种可能的用户意图都写一条分支。但代价是确定性下降——LLM 可能会判断错，可能会调用错误的工具，甚至可能陷入循环。

我刚开始接触的时候，最大的不适应就是这种"失控感"。写了这么多年 Java，习惯了每一步都可预测、可测试、可回滚。突然有一个东西，它的行为不是你能完全控制的，心里确实没底。但后来想明白了：Agent 不是替代传统服务，而是在传统服务之上加了一层"智能调度"。你的工具（Tool）本身还是那些可靠的 Java 方法，只是调用它们的方式变了。

2.2 Agent 的四大核心组件

不管用什么语言、什么框架，一个 Agent 基本都包含这四个部分：

第一，LLM（大脑）。这是决策中心，负责理解用户意图、选择工具、组织回复。你可以用 GPT、Claude、通义千问等等，选哪个取决于你的场景和成本预算。对于 Java 开发者来说，Spring AI 已经封装了主流模型的调用接口，切换模型只需要改配置。

第二，Tools（手脚）。这是 Agent 能调用的外部能力。可以是一个查询数据库的方法，一个调用 REST API 的客户端，一个执行计算的函数。在 Java 里，你平时写的 Service 方法稍加改造就能变成 Tool。关键是你要把方法的用途、参数含义用自然语言描述清楚，因为 LLM 是根据这些描述来决定要不要调用的。

第三，Memory（记忆）。这是 Agent 的上下文管理。短期记忆就是当前对话的历史消息，长期记忆可能涉及向量数据库存储的知识。Java 开发者可以把它类比成 HttpSession——只不过存的不是用户登录状态，而是对话上下文。这里有个坑：上下文不是越长越好，太长了会超出模型的 token 限制，而且会增加成本。所以需要做上下文窗口管理，比如只保留最近 N 轮对话，或者对历史消息做摘要压缩。

第四，Planning（规划）。这是 Agent 决定"先做什么、再做什么"的能力。简单的 Agent 可能只做一步工具调用就返回结果，复杂的 Agent 需要拆解任务、按顺序执行多个步骤。比如用户说"帮我分析上个月的销售数据并生成报告"，Agent 需要先查数据、再计算、再生成文本、最后可能还要调用导出工具。这个规划过程可以是 LLM 一次性生成一个计划，也可以是 ReAct 模式那样"想一步做一步"。

用一个 Java 开发者熟悉的类比：Agent 就像是一个微服务编排引擎，但编排逻辑不是你在 YAML 里写死的，而是 LLM 在运行时动态生成的。Tools 就是你的各个微服务，Memory 就是状态存储，Planning 就是编排逻辑。

2.3 为什么 Java 开发者需要关注 Agent

有人可能会问：Agent 开发不是 Python 的天下吗？Java 凑什么热闹？

确实，目前 Agent 生态里 Python 占主导，LangChain、AutoGPT 这些都是 Python 的。但情况在变化。一方面，企业级应用大部分还是 Java 写的，Agent 要落地到生产环境，不可能完全绕开 Java 技术栈。另一方面，Spring AI 和 Google 的 ADK（Agent Development Kit）都在积极支持 Java/Kotlin，说明这个方向是被看好的。

更重要的是，Java 开发者在构建 Agent 时有一个天然优势：我们习惯了处理并发、事务、异常、监控这些生产级问题。很多 Python 写的 Agent demo 看起来很酷，但一到生产环境就各种问题——并发上不去、错误处理不完善、没有可观测性。这些恰恰是 Java 开发者擅长的领域。

所以我的判断是：Agent 的核心逻辑用 Python 做原型没问题，但真正要扛并发、要稳定运行的企业级 Agent，Java 的机会很大。这也是我花时间研究这个方向的原因。

3. 从零搭建一个最小可用 Agent：Java 视角的实操路径

3.1 技术选型：Spring AI 还是 ADK

如果你是一个 Java 开发者，想动手搭一个 Agent，目前主要有两条路：

Spring AI是 Spring 生态的 AI 集成框架，优势是和你现有的 Spring Boot 项目无缝集成。你可以在现有的 Controller 里直接注入 ChatClient，几行代码就能调用 LLM。定义 Tool 也很简单，加个 @Tool 注解就行。缺点是 Agent 相关的高级功能（比如多 Agent 协作、复杂的 Planning）还在完善中。

ADK（Agent Development Kit）是 Google 推出的 Agent 开发框架，支持 Java 和 Kotlin。它的 Agent 抽象更完整，内置了多 Agent 编排、工具管理、会话管理等功能。如果你是从零开始做一个 Agent 项目，ADK 的结构化程度更高。缺点是和 Spring 生态的集成需要自己做一些适配。

我的建议是：如果你是在现有 Spring Boot 项目里加 Agent 能力，选 Spring AI；如果是独立做一个 Agent 应用，可以试试 ADK。两者并不冲突，核心概念是相通的。

3.2 最小 Agent 的实现步骤

下面用一个具体例子走一遍。假设我们要做一个"天气查询 Agent"，用户用自然语言问天气，Agent 自己决定调用天气 API。

第一步，定义 Tool。在 Spring AI 里，就是写一个普通的 Java 方法，加上注解：

@Component public class WeatherTool { @Tool(description = "根据城市名称查询当前天气状况") public String getWeather( @ToolParam(description = "城市名称，例如：北京、上海") String city) { // 实际项目中这里调用天气 API return city + "今天晴，气温 25 度"; } }

注意 description 的写法。这不是给你看的注释，是给 LLM 看的。LLM 会根据这段描述判断：用户问天气的时候，我应该调用这个方法。所以描述要准确、简洁，把方法的用途和参数含义说清楚。

第二步，创建 ChatClient 并注册 Tool。

@Configuration public class AgentConfig { @Bean public ChatClient chatClient(ChatClient.Builder builder, WeatherTool weatherTool) { return builder .defaultSystem("你是一个天气助手，帮助用户查询天气。") .defaultTools(weatherTool) .build(); } }

第三步，在 Controller 里调用。

@RestController public class AgentController { private final ChatClient chatClient; public AgentController(ChatClient chatClient) { this.chatClient = chatClient; } @GetMapping("/chat") public String chat(@RequestParam String message) { return chatClient.prompt() .user(message) .call() .content(); } }

就这么简单。当你访问/chat?message=北京今天天气怎么样的时候，LLM 会判断需要调用 getWeather 工具，传入"北京"，拿到结果后组织语言返回。

3.3 关键参数与配置说明

上面是最简版本，实际使用中还有几个关键配置需要关注：

模型选择。Spring AI 支持多种模型，通过配置文件切换：

spring: ai: openai: api-key: ${API_KEY} chat: options: model: gpt-4o-mini temperature: 0.7

temperature 控制输出的随机性。做 Agent 的时候，如果希望工具调用的判断更稳定，可以调低一点，比如 0.3。如果希望回复更自然多样，可以调高。

超时设置。LLM 调用可能比较慢，尤其是需要多轮工具调用的时候。建议设置合理的超时时间，避免请求堆积：

spring: ai: openai: chat: options: timeout: 30000

重试策略。LLM API 偶尔会失败，需要配置重试。Spring AI 内置了重试机制，可以通过配置调整重试次数和退避策略。

注意：不要在生产环境直接把 LLM 的原始输出返回给用户。LLM 可能会产生不准确的内容，建议在返回前做一层校验或者加上免责说明。

4. Agent 开发中的常见坑与排查思路

4.1 工具调用不触发或调错工具

这是最常见的问题。你定义了一个工具，但 LLM 就是不调用，或者调用了错误的工具。

原因通常有三个：一是工具描述写得不清楚，LLM 不理解这个工具是干什么的；二是系统提示词没有引导 LLM 使用工具；三是模型能力不够，小模型对工具调用的支持不好。

排查方法：先把工具描述改得更明确，把"查询天气"改成"根据城市名称查询该城市当前的天气状况，包括温度和天气现象"。然后在系统提示词里加一句"你可以使用提供的工具来帮助用户查询信息"。如果还不行，换个更强的模型试试。

我踩过的一个坑是：工具方法的参数名写得太抽象，比如叫param1，LLM 根本不知道要传什么。后来改成cityName并加上描述，问题就解决了。

4.2 多轮对话上下文丢失

用户问"北京天气怎么样"，Agent 回答了。用户接着问"那上海呢"，Agent 可能不知道"那上海呢"指的是天气。这是因为上下文没有正确传递。

解决方案：在调用 LLM 的时候，把历史消息一起传进去。Spring AI 的 ChatClient 支持传入消息列表：

List<Message> messages = new ArrayList<>(); messages.add(new SystemMessage("你是一个天气助手")); messages.add(new UserMessage("北京天气怎么样")); messages.add(new AssistantMessage("北京今天晴，25度")); messages.add(new UserMessage("那上海呢")); String response = chatClient.prompt() .messages(messages) .call() .content();

但要注意上下文长度。如果对话轮次很多，需要对历史消息做截断或摘要，否则会超出模型的 token 限制。

4.3 Agent 陷入循环或执行超时

复杂任务中，Agent 可能会反复调用同一个工具，或者在不同工具之间来回跳转，导致死循环。

排查思路：首先看日志，确认 Agent 到底调用了哪些工具、传了什么参数。然后检查工具返回值是否清晰——如果工具返回的结果让 LLM 无法判断下一步该干什么，它就可能反复尝试。

解决手段：设置最大迭代次数，比如最多允许 10 轮工具调用，超过就强制结束并返回当前结果。另外，在系统提示词里明确告诉 LLM"如果已经获取到足够信息，请直接回复用户，不要重复调用工具"。

下面是一个常见问题速查表：

4.4 并发场景下的注意事项

Java 开发者天然关注并发。Agent 服务在高并发下有几个特殊问题：

Token 消耗。每次请求都要调用 LLM API，并发高了 token 消耗会很大。建议做请求合并或者缓存常见问题的回答。

会话隔离。不同用户的对话上下文必须隔离，不能串。用 sessionId 或者 conversationId 来区分，每个会话维护自己的消息列表。

限流与降级。LLM API 通常有 QPS 限制，需要做限流。当 LLM 不可用时，要有降级方案，比如返回预设的提示信息而不是直接报错。

提示：生产环境的 Agent 服务建议加上可观测性，记录每次请求的 token 消耗、工具调用次数、响应时间等指标，方便后续优化和问题排查。

5. Agent 学习路线与进阶方向

5.1 从 Java 开发者到 Agent 开发者的学习路径

如果你已经会 Java，想往 Agent 方向发展，我建议按这个顺序来：

第一阶段，理解概念。搞清楚 LLM、Prompt、Tool、Memory、Planning 这几个核心概念。不需要深入模型原理，但要理解它们各自的作用和相互关系。这个阶段看几篇好的博客、跑几个 demo 就够了。

第二阶段，动手实践。用 Spring AI 或者 ADK 搭一个最简单的 Agent，比如天气查询、待办事项管理这种。重点体会"LLM 决定调用哪个工具"这个过程。这个阶段会遇到很多小问题，但都是宝贵的经验。

第三阶段，深入架构。研究多 Agent 协作、RAG（检索增强生成）、Agent 记忆管理等进阶话题。看看开源项目是怎么做的，比如 Dify、Coze 这些平台的架构设计。

第四阶段，生产落地。把 Agent 部署到生产环境，处理并发、监控、成本控制这些工程问题。这才是 Java 开发者真正发挥优势的地方。

5.2 值得关注的技术方向

多 Agent 协作。单个 Agent 能力有限，多个 Agent 分工协作可以处理更复杂的任务。比如一个负责理解需求，一个负责执行，一个负责审核。这有点像微服务架构，每个 Agent 是一个独立的服务。

Agent 安全。当 Agent 能调用外部工具的时候，安全问题就来了。怎么防止 Prompt 注入？怎么限制 Agent 的权限？怎么审计 Agent 的操作？这些都是企业级应用必须考虑的。

Agent 可观测性。传统服务的监控指标（QPS、延迟、错误率）在 Agent 场景下不够用。你还需要监控 token 消耗、工具调用成功率、LLM 决策质量等。这个方向目前还没有特别成熟的方案，是个机会。

Agent 与工作流的结合。纯 Agent 的灵活性高但确定性低，纯工作流的确定性高但灵活性差。实际生产中，往往是两者结合：关键路径用工作流保证确定性，非关键路径用 Agent 提供灵活性。

5.3 一些个人体会

从 Java 后端转 Agent 开发，最大的挑战不是技术，而是思维方式。我们习惯了确定性——输入 A 必然得到 B，测试用例覆盖所有分支。但 Agent 的行为是概率性的，同样的输入可能得到不同的输出。这需要你接受一定的不确定性，同时通过工程手段把不确定性控制在可接受的范围内。

另一个体会是：不要为了用 Agent 而用 Agent。有些场景用传统的 if-else 就能解决，没必要引入 LLM。Agent 适合的是那些规则难以穷举、需要理解自然语言、需要动态决策的场景。判断标准很简单：如果你能用清晰的流程图把逻辑画出来，那大概率不需要 Agent。

最后，Java 开发者在 Agent 领域其实有独特的优势。我们擅长构建稳定、可观测、可维护的系统，这些能力在 Agent 从 demo 走向生产的过程中至关重要。所以不用觉得自己是"转行"，更像是"扩展"——把已有的工程能力应用到新的场景里。