企业官网建设流程全解析

最近一两年的AI应用开发圈子里，有个特别有意思的变化：当你跟做Java后端的同学聊起“要不要上个Agent”时，很多人第一反应不再是去搜LangChain或LangGraph，而是会问一句：“Spring能不能直接干这事？”

这其实反映了一个很现实的需求——绝大多数企业的核心业务系统都是Java技术栈，与其把AI能力拆出去单独搭一套Python服务，不如直接在Spring生态里把Agent做出来。Spring AI Alibaba的出现，恰好把这条路铺平了。不管你之前是不是搞过AI开发，只要熟悉Spring Boot，理论上就能用一套熟悉的依赖注入、自动装配和配置项，快速搭建出一个具备自主规划、工具调用能力的智能体Agent。

这篇文章我就围绕“使用Spring AI Alibaba构建智能体Agent”这条主线，从Agent的架构思路、核心概念、实际写代码到问题排查，完整走一遍。文中的示例项目是一个“订单查询Agent”，目标是让模型能够自己决定调用哪个数据库查询工具来回答用户问题。通过这个案例，我会把Spring AI Alibaba最关键的能力——Tool Calling（工具调用）——讲透，同时也会覆盖ChatClient用法、Prompt模板、模型配置等绕不开的实操细节。

1. Agent到底是什么，以及为什么用Spring AI Alibaba来实现

1.1 Agent和普通的“聊天机器人”差在哪

很多刚接触这个领域的同学，会把“接入了大模型API的聊天接口”误当成Agent。实际上两者有本质区别：普通聊天机器人只能“说”，不能“做”。你可以问它“杭州今天的天气怎么样”，它如果不知道，只能告诉你“抱歉，我无法实时获取天气信息”。而Agent不仅知道自己的知识边界，还能通过工具去补齐这个边界——它会自己决定去调用天气API，拿到结果之后再把答案整理给你。

打个比方：传统聊天机器人像一个只有嘴的客服，Agent则是一个有嘴、有手、有脑的完整办事员。它的大脑是大模型，负责理解意图、拆解任务、决定下一步干啥；它的手是各种工具（Tool），比如查数据库、调接口、发消息、操作文件；它的嘴则是最后一环的答案生成。这种“模型推理 + 工具调用 + 任务规划”的组合，才是Agent的完整形态。

1.2 Spring AI Alibaba在Java生态里的位置

Spring AI本身是Spring官方发起的AI应用框架项目，提供了对接各种大模型厂商的统一抽象层。Spring AI Alibaba则是阿里在Spring AI基础之上做的适配增强版本，专门用来对接阿里云的通义千问系列模型，同时继承和扩展了Spring AI的核心能力。

选择Spring AI Alibaba有几个非常实际的考量：

• 与Spring Boot无缝集成：不需要额外引入一堆乱七八糟的SDK，依赖注入、配置绑定、自动装配这些Spring老本行通通派上用场。
• 模型抽象统一：今天你用通义千问，明天想换成别的模型，改动成本被抽象层吞掉了大半。
• 内置了Agent开发所需的底层组件：比如Tool Calling机制、Prompt模板管理、ChatClient对话编排、输出解析器等，这些正是写Agent最核心的积木。
• 文档齐全且社区活跃：因为是国内团队维护，中文资料和issue反馈相对友好，遇到问题能较快找到解法。

如果说LangChain是Python圈的Agent全家桶，那么Spring AI Alibaba就是Java圈里最值得关注的Agent开发基础设施。它解决的核心问题是：不让Java开发者为了搞AI而被迫换技术栈。

1.3 本文示例项目的目标

为了把概念转成看得见摸得着的东西，我设计了一个“保温杯工厂订单查询Agent”。背景很简单：工厂有一套MySQL数据库，里面存着订单表，表里有订单号、产品名、数量、状态、下单日期等字段。用户的诉求是——能不能让AI直接用自然语言查这些数据？

• 用户问：“帮我查一下订单总量有多少。”
• Agent回答：先识别用户要查的是“订单总量”，然后调用指定的SQL查询工具，传入必要的表名和查询条件，拿到结果后组织成中文答案。

这个场景覆盖了Agent开发最典型的核心链路：意图理解、工具选择、工具参数生成、工具执行结果回填、最终答案生成。弄懂这一套，你就能举一反三，扩展到更多业务场景。

2. 构建前的架构拆分与关键组件选型

2.1 Agent的核心循环：模型-工具-反馈

无论用什么框架，Agent的底层运行逻辑都逃不出一个循环：模型决定行动 → 执行行动 → 返回结果 → 模型基于结果再决定下一步。

在实际代码中，这个循环通常不显式出现在我们的业务代码里，而是由Spring AI Alibaba框架替我们驱动。我们要做的，反而是两件事：

1. 提供给模型可调用的工具描述。
2. 定义好系统Prompt，让模型知道自己的职责边界。

从架构层面拆解，一个基于Spring AI Alibaba的Agent由五个模块组成：

这五个模块凑齐，一个最小可用的Agent就跑起来了。

2.2 Spring AI Alibaba的核心API：ChatClient

以前写Java调大模型接口，常见姿势是直接用对方SDK的请求对象，再手动处理响应字符串。Spring AI Alibaba把这个过程简化成了类似MyBatis写SQL、RestTemplate调接口的体验。

ChatClient就是整个交互链路的门面，它支持流式与非流式调用，支持拼接Prompt，也支持把Tool列表传给模型。实际写下来你会发现，这个API设计得比较顺手，有点“SQL到Java方法映射”的意思，声明式的味道很足。

2.3 Tool Calling是怎么回事

Tool Calling是Agent的灵魂。它并不神秘，本质上分三步走：

• 第一步，你把每个工具的描述、参数schema（JSON格式）发给大模型。
• 第二步，模型根据用户问题，判断需要调用哪个工具，并生成对应的参数JSON。注意，这时候模型还没真正执行你的工具，只是“申请调用”。
• 第三步，你收到模型的工具调用请求后，在本地执行真正的业务方法，再把执行结果回传给模型，模型结合结果生成给用户的最终回复。

所以Tool Calling就像：模型是个只会出主意的军师，真正动手打仗的是你的Java方法。它告诉军师“我有哪些兵可以用”，军师说“派炮兵连轰炸3号阵地”，于是你让炮兵连真去开炮，再把战果汇报给它。

Spring AI Alibaba里实现一个Tool，只需要在一门普通的Service或Component上，用@Tool注解标注方法即可。框架会把方法名、方法参数和注释自动转换成模型可理解的JSON Schema。

3. 新建工程与基础配置

3.1 依赖引入与工程结构

我用的是Spring Boot 3.2.x + Spring AI Alibaba 1.0.0版本组合，构建工具选择Maven。需要说明的是，Spring AI Alibaba的版本策略和Spring Cloud Alibaba比较像，会以start.aliyun.com作为默认的依赖管理地址。如果你用阿里云的初始化器生成工程，它会自动处理依赖坐标。

在pom.xml中，核心依赖如下：

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.4</version> <relativePath/> </parent> <dependencies> <dependency> <groupId>com.alibaba.cloud.ai</groupId> <artifactId>spring-ai-alibaba-starter</artifactId> <version>1.0.0</version> </dependency> <dependency> <groupId>com.alibaba.cloud.ai</groupId> <artifactId>spring-ai-alibaba-starter-tool-calling</artifactId> <version>1.0.0</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- 数据库相关 --> <dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>3.0.3</version> </dependency> </dependencies>

提示：如果你不是使用阿里云初始化的工程模板，而是手动搭建，务必要在工程的dependencyManagement里加入Spring AI Alibaba的BOM，否则版本号对不上，启动时会遇到一堆NoSuchMethodError。

3.2 application.yml配置详解

配置文件里需要配置三组核心内容：模型服务商地址、API Key、模型名称。我这里以通义千问为例，使用的模型是qwen-plus。

spring: ai: alibaba: # 使用兼容OpenAI协议的通义千问服务 base-url: https://dashscope.aliyuncs.com/compatible-mode/v1 api-key: ${DASHSCOPE_API_KEY} chat: client: # 可选，设置chat client的默认配置 observations-enabled: true datasource: url: jdbc:mysql://localhost:3306/agent_demo?useUnicode=true&characterEncoding=utf8 username: root password: 123456

这里要提醒一个关键点：Spring AI Alibaba默认走的是DashScope的OpenAI兼容模式，所以base-url必须是compatible-mode这个地址，不能填成纯DashScope原生的端点。如果你之前调过通义的SDK，容易在这里踩坑。

3.3 准备数据库表结构

为了让Agent有数据可查，我准备了一张简单的订单表。建表语句先贴出来，后面所有示例都是针对这张表查询的。

CREATE TABLE `orders` ( `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键', `order_no` varchar(64) DEFAULT NULL COMMENT '订单编号', `product_name` varchar(128) DEFAULT NULL COMMENT '产品名称', `quantity` int DEFAULT NULL COMMENT '数量', `status` tinyint DEFAULT NULL COMMENT '订单状态：1待生产，2生产中，3已完成', `created_at` datetime DEFAULT NULL COMMENT '下单时间', PRIMARY KEY (`id`) ) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8mb4;

然后塞几条测试数据，让Agent查询测试有东西可返回：

INSERT INTO `orders` (`order_no`, `product_name`, `quantity`, `status`, `created_at`) VALUES ('PO202405001', '304不锈钢保温杯', 2000, 1, '2024-05-01 10:00:00'), ('PO202405002', '陶瓷内胆保温杯', 1500, 2, '2024-05-02 11:30:00'), ('PO202405003', '儿童卡通保温杯', 800, 3, '2024-05-03 09:20:00'), ('PO202405004', '304不锈钢保温杯', 500, 1, '2024-05-04 16:45:00');

4. 从0到1实现订单查询Agent

4.1 先做一个最朴素的“对话接口”

在写Agent工具之前，按照渐进式开发的习惯，我建议先跑通最基础的问答链路：启动工程，能调通模型，再往上面盖Agent能力。

创建OrderAgentController，先暴露一个问最简单的对话接口：

@RestController @RequestMapping("/agent") public class OrderAgentController { @Resource private ChatClient chatClient; public OrderAgentController(ChatClient.Builder builder) { this.chatClient = builder.build(); } @GetMapping("/chat") public String chat(@RequestParam("message") String message) { return chatClient.prompt() .user(message) .call() .content(); } }

此时你去浏览器访问：

http://localhost:8080/agent/chat?message=你好

如果一切正常，会收到模型的友好回复。这个阶段的目的很简单：确认API Key有效、网络通、依赖装配无误。如果你在这一步都拿不到回复，先排查配置和网络环境，别急着往下写。

4.2 让Agent拥有查询工具：定义@Tool

接下来就是整个Agent的核心环节——写Tool。这里用MyBatis做数据访问，先定义Mapper接口：

@Mapper public interface OrderMapper { @Select("SELECT COUNT(*) FROM orders") long countOrders(); @Select("SELECT IFNULL(SUM(quantity), 0) FROM orders") long sumQuantity(); @Select("SELECT product_name, SUM(quantity) AS total_quantity FROM orders GROUP BY product_name") List<Map<String, Object>> groupByProduct(); @Select("SELECT * FROM orders WHERE status = #{status}") List<Map<String, Object>> selectByStatus(int status); }

然后创建OrderQueryTool类，每个方法上用@Tool注解描述功能。这里有个很重要的细节：注解的description一定要写得清晰、准确，因为它是模型决定是否调用该工具的唯一依据。

@Component public class OrderQueryTool { @Resource private OrderMapper orderMapper; @Tool(description = "查询订单总数量") public String countOrders() { return "订单总数：" + orderMapper.countOrders(); } @Tool(description = "查询所有订单的商品总件数") public String sumQuantity() { return "商品总件数：" + orderMapper.sumQuantity(); } @Tool(description = "按产品名称分组查询各产品的订单数量汇总") public List<Map<String, Object>> groupByProduct() { return orderMapper.groupByProduct(); } @Tool(description = "根据订单状态查询订单列表，状态值说明：1待生产，2生产中，3已完成") public List<Map<String, Object>> selectByStatus(int status) { return orderMapper.selectByStatus(status); } }

你可能会好奇，这些Tool不是要传给模型吗，模型怎么能自动找到这些方法？实际上Spring AI Alibaba在启动时会自动扫描容器中所有标注了@Tool的Bean，把它们的方法描述打包成一个functions列表，挂到每次模型请求的上下文中。模型在生成回复时，如果发现某个工具描述与用户问题匹配，就会在响应里返回一个特殊的toolCalls字段。

4.3 升级Agent对话接口：把Tool挂载上去

光定义好Tool还不够，得让ChatClient知道“手里有这些牌可用”。把Controller改成这样：

@RestController @RequestMapping("/agent") public class OrderAgentController { private final ChatClient chatClient; public OrderAgentController(ChatClient.Builder builder, OrderQueryTool orderQueryTool) { this.chatClient = builder .defaultTools(orderQueryTool) .build(); } @GetMapping("/chat") public String chat(@RequestParam("message") String message) { return chatClient.prompt() .user(message) .call() .content(); } }

注意我用的是defaultTools，这表示每次对话都会把OrderQueryTool里的所有方法暴露给模型。如果你有多个不同的工具集合，需要根据场景动态选择，可以用.prompt().tools(...)来指定当前这轮对话要启用哪些工具。

到了这一步，我再请求：

http://localhost:8080/agent/chat?message=一共有多少笔订单

模型会收到两个东西：用户问题和可调用工具的说明。它会自己判断“查订单总数”对应countOrders方法，于是生成一个工具调用请求。框架内部帮你执行该方法，把结果“订单总数：4”回传给模型，最后模型生成一句完整回答：“目前一共有4笔订单。”

这个过程看起来像魔法，底层其实是框架把工具的JSON Schema塞给了模型，模型又在一轮请求里多返回了一组“工具调用指令”。Spring AI Alibaba把这些都封装好了，你从外面看就是一个简单的方法调用，但内部已经完成了一轮Agent的关键循环。

4.4 加上系统Prompt让Agent更“懂事”

没有系统Prompt的Agent，像一个没有岗位说明书的员工，虽然手里有工具，但容易乱用、漏用，甚至给用户输出不准确的话。所以给Agent加“员工手册”是必要的。

把Controller再调整一下，定义一个系统Prompt模板：

@RestController @RequestMapping("/agent") public class OrderAgentController { private static final String SYSTEM_PROMPT = """ 你是一个工厂订单管理助手的智能化Agent。 你的职责是帮助用户查询和分析订单数据。 规则： 1. 只能使用提供的工具查询数据，不能编造数据。 2. 如果用户的问题涉及到订单总数、数量、状态、产品等，必须调用对应工具。 3. 回答要简洁、专业，使用中文。 """; private final ChatClient chatClient; public OrderAgentController(ChatClient.Builder builder, OrderQueryTool orderQueryTool) { this.chatClient = builder .defaultSystem(SYSTEM_PROMPT) .defaultTools(orderQueryTool) .build(); } @GetMapping("/chat") public String chat(@RequestParam("message") String message) { return chatClient.prompt() .user(message) .call() .content(); } }

这里值得多说一句：系统Prompt写得越具体，Agent的行为就越可控。比如“只能使用提供的工具查询数据，不能编造数据”这句话，就防止了模型在数据库查不到结果时强行编一个数字出来。这是我在实际项目中踩过大坑后总结的经验——有的模型在没有工具可用或工具返回值为空时，会尝试“脑补”答案，而这个规则能把行为钳制住。

5. 多轮对话与上下文记忆的实现

5.1 需求场景：用户不想每次重复描述

只用单轮问答接口，Agent没法记住之前聊了啥。真实业务里，用户大概率会连续问多句话，比如：

• 用户：“帮我查一下待生产的订单有哪些。”
• 用户：“他们一共多少件？”

第二句里的“他们”指代第一句说到的“待生产订单”。如果Agent没有记忆，模型拿到第二句时就懵了，因为它不知道上下文。

我先把这个问题简化，用Spring AI的Memory接口配置对话记忆：

@RestController @RequestMapping("/agent") public class OrderAgentController { private final ChatClient chatClient; private final ChatMemory chatMemory; public OrderAgentController(ChatClient.Builder builder, OrderQueryTool orderQueryTool) { this.chatMemory = new InMemoryChatMemory(); this.chatClient = builder .defaultSystem(SYSTEM_PROMPT) .defaultTools(orderQueryTool) .build(); } @PostMapping("/chat") public String chat(@RequestBody ChatRequest request) { return chatClient.prompt() .user(request.message()) .chatMemory(chatMemory) .conversationId(request.conversationId()) .call() .content(); } }

对话上下文是依托conversationId来隔离的，不同用户传不同的聊天会话ID，各自的上下文就不会串门。这里我用的是内存态Memory，适合学习阶段；生产环境一般会用Redis或数据库做持久化，Spring AI提供了一个ChatMemory接口，实现一个持久化版本也很快。

5.2 对话记忆和Tool冲突时的注意事项

加上了ChatMemory之后，有一个容易踩坑的地方：如果某个Tool执行时依赖上下文动态变化的参数，而模型并不一定能从历史里准确提取出来。例如你想让Agent记住“上次查了哪个产品的订单”，下一次用户直接说“那这个产品的总件数呢”，模型需要结合历史消息推断产品名——这很考验模型能力。

我在实测中觉得，这类复杂指代处理，光靠把历史消息一股脑塞给模型是不够的。更稳的手段是：在Tool方法里，不依赖模型传参，而是自己在Service层维护一个“当前查询上下文”。比如用户第一次问完“304不锈钢保温杯的订单有哪些”，代码里就把ProductName存到会话状态里，第二次问“总件数呢”，直接取会话状态补全查询条件。

这种方法虽然听起来没那么“智能”，但可靠性远高于让模型自己记住。毕竟Agent的第一原则是正确，不是炫技。

6. 从示例到生产力的升级路径

6.1 从单工具到多工具协同

订单查询Agent现在还只是“会查表”的水平。生产级别的Agent往往需要同时挂多个域的工具，比如订单查询、库存查询、物流查询、报表生成等。这时候每个工具类最好按领域拆开，一个域一个@Service，内部再细分@Tool方法。同时给工具的description起名也更讲究，要让模型能一眼区分“查订单”和“查库存”的区别。

6.2 引入RAG增强知识边界

如果Agent还要回答“保温杯的材质有哪些”“生产周期多长”这类不在数据库里的问题，就要靠RAG了。Spring AI Alibaba也提供了向量数据库和文档解析的抽象，通常做法是：把产品文档切块、向量化后存到DashVector或Redis向量库，然后注册一个“知识库查询”的Tool，让模型决定何时检索。

这么一来，Agent就有两个知识来源：结构化数据走SQL工具，非结构化文档走向量检索工具。两条腿走路，覆盖面就上来了。

6.3 增加任务编排与人工确认

再往上走，Agent还需要有“多步任务编排”和“人工确认”机制。比如用户说“帮我把第3号订单状态改一下，并且通知仓库那边备货”，这就涉及写操作了。写操作的Agent不能像查询一样直接执行，正确的姿势是：Agent生成一个操作计划，返回一个确认页面给用户，用户点了确认之后才真正执行。

这个场景里，Spring AI Alibaba支持把工具返回类型定义成结构化对象，由框架解析后走你的业务流程，而不是简单的字符串拼接。这类设计需要你从Agent架构层面提前规划好权限边界，建议在实体工具被调用前，先过一层“意图审批”逻辑。

7. 实战中的常见问题与排查技巧

7.1 模型始终不调用我定义的工具

这是最常遇到的问题。你Tool定义好了，用户也按预期问了问题，但模型就是不用工具，反而用自己的常识硬答。我通常按这个顺序排查：

1. 工具描述是否清晰：如果description含糊其辞，模型识别不到“该不该用”。比如“查询订单数量”和“统计商品总数量”如果区别不大，模型容易选错或干脆不选。
2. 模型能力是否足够：qwen-turbo和qwen-plus在Tool Calling上的稳定度有明显差距，如果是复杂场景，建议直接上qwen-plus或更强型号。
3. 系统Prompt是否限制了工具使用：某些Prompt里写了“请直接回答”，模型可能就不会走工具链路，需要调整措辞。
4. 工具类是否真的被扫描到：检查启动日志，如果没看到Tool相关注册信息，多半是依赖没引入全。

7.2 工具调用成功但结果回答异常

这类问题非常典型：我看日志，工具被调用了，返回了正确数据，但最终模型的回答还是错的。常见原因是工具返回的数据结构和模型理解之间有偏差。

排查办法是把工具返回结果尽量改成“人话”字符串，而不是一坨原始JSON。例如我示例里的countOrders方法返回“订单总数：4”，模型看到这句话就能直接组装答案；如果返回的是Map或对象，模型也能解析，但对小参数模型来说容易出现理解偏差，所以工具返回值尽量转成自然语言描述。

7.3 版本冲突导致启动失败

Spring AI Alibaba目前迭代速度较快，不同版本之间API可能有细微波动。我见过最多的报错是NoClassDefFoundError和NoSuchMethodError，十有八九是Spring AI Alibaba和Spring Boot、JDK版本没对齐。我实测下来这套组合是稳的：

如果遇到奇怪报错，先做减法，把自定义配置去掉，用最小配置启动，逐步加回依赖，很快就能定位是谁导致的冲突。

7.4 对话记忆越聊越乱

这是做多轮对话Agent时绕不开的体验问题。当上下文长了之后，ChatMemory会把全部历史消息发给模型，Token消耗变大，模型回答的焦点也开始漂移。尤其是用户中途切换了话题，模型容易把新话题和旧历史混在一起。

我的习惯是给Memory加一个“最近N条消息”的窗口，而不是无限累积。另外在关键节点上用Prompt要求模型“忽略与当前问题无关的历史信息”。虽然这不能100%解决焦点漂移，但实测下来能明显改善。

7.5 本地调试时想细看模型“怎么想的”

Spring AI Alibaba可以开启日志级别的调试信息，查看模型请求和响应payload。在application.yml里这样配置：

logging: level: com.alibaba.cloud.ai: DEBUG

开了之后，你能在日志里看到模型返回的toolCalls详情、每次调用的输入输出参数。对理解Agent决策过程非常有帮助，强烈建议刚开始做Agent开发时把日志调高观察几轮。

8. 我对Spring AI Alibaba构建Agent的实操感受

整套流程走下来，我的一个强烈感受是：Spring AI Alibaba把做Agent的门槛拉到了“会Spring Boot就能上手”的程度。比起之前在Java里裸调大模型API，省掉了太多繁文缛节。特别是@Tool注解这套设计，把“让模型使用你的方法”这件事变得非常顺手，不需要手工维护JSON Schema，方法签名变了，Tool说明自动跟着变，这个体验在开发调试时尤其舒服。

不过也要说句公道话，Spring AI Alibaba还处于快速演进期，版本之间的API变化确实偏快。所以如果你准备在企业项目里正式引入，建议锁死版本，不要把依赖写成latest或带SNAPSHOT的坐标，否则升级一次哭一次。另外生产环境一定要对Tool做权限管控，不是所有方法都适合暴露给模型，站在安全角度，给Agent的工具要尽量窄、尽量专用。

最后再分享一个悄悄摸出来的技巧：写工具description的时候，把“边界”也写进去。比如查询工具里写明“只能查询非脱敏字段”，这样就算模型收到一个涉及脱敏字段的问题，也不会往你的限制外钻。Agent的安全感，往往就是靠这些细节堆出来的。

如果你正准备在Java项目里落地Agent，或者正纠结选哪个框架，我的建议是直接动手拿Spring AI Alibaba写一个最简单的查询Agent。不要光看文档，亲手把“模型-工具-数据库”这条链路跑通了，你对Agent的理解会往上跳一大截。