Spring AI 实战：Agent 基础搭建与核心能力解析

小马爱打代码

660人浏览 · 2026-01-30 10:23:45

小马爱打代码 · 2026-01-30 10:23:45 发布

通过之前的学习，我们已经掌握了 Spring AI 的核心模块（对话、Embedding、RAG）实战技巧。随着 AI 技术的演进，AI 已成为从 “信息提供者” 升级为 “任务执行者” 的关键方向。本文作为 Spring AI 系列的 Agent 入门篇，将先带你理解 AI Agent 的核心概念与特点，再通过 Spring AI 构建基础版 Agent 案例，帮你快速入门这一前沿技术。

一、AI Agent 核心概念与核心特点

1. 什么是 AI Agent？
Agent 是一类由大语言模型、工具组件、任务编排层及运行时服务共同构建的智能程序，其核心机制是通过循环调用大语言模型的认知与推理能力
在这里插入图片描述

大语言模型堪称 “身怀强大认知能力却缺乏执行能力的天才”，而 Agent 则是通过软件工程的方法论，将其封装为可独立完成特定任务的自动化软件系统。

比如你说 “帮我整理本周工作周报”，大模型可能只能告诉你 “你需要提供工作内容、统计数据、总结成果”，而 AI Agent 会自动扫描你的邮件、提取会议纪要、统计项目进度，最终生成完整的周报文档。

2. AI Agent 的核心特点
自主性：无需人工持续干预，设定目标后可自主推进任务，比如智能扫地机器人按预设时间自动打扫。
智能规划：能将复杂目标拆解为可执行的子任务，比如规划旅行时，会拆解为查机票、订酒店、规划景点路线等步骤。
适应性：可根据环境变化调整策略，比如预订高铁票时发现目标车次售罄，会自动推荐备选车次。
记忆能力：具备短期记忆（对话上下文）和长期记忆（持久化存储），能记住历史交互信息，比如记住你偏好的出行时间、座位类型。

3. AI Agent 分类
从架构层面划分，Agent 可分为两大类型：人工流程编排类（Workflow Agent）与自主规划类（Autonomous Agent）。
人工流程编排类（Workflow Agent）：指通过预定义的代码执行路径，协调大语言模型（LLM）与各类工具协同工作的系统。
自主规划类（Autonomous Agent）：指由大语言模型（LLM）动态指导自身执行流程与工具调用策略，实现任务执行方式自主决策的系统。

无论是人工流程编排类还是自主规划类智能体，其底层均构建于增强型大语言模型（Augmented LLM）之上，核心依托检索增强、工具增强与记忆增强三大能力体系实现功能拓展。

二、Agent 的核心架构

Agent 的自主执行能力，依托推理引擎、指令、记忆、工具四大核心组件的协同运作，四者各司其职、层层衔接，共同构成完整的智能执行链路。
在这里插入图片描述

1. 推理引擎（LLM）

目前绝大多数 Agent 均以多模态大语言模型（如 GPT-4、Claude、通义千问）为核心推理引擎。大模型的价值远不止文字生成，更关键是赋予 Agent 核心认知能力

2. 指令

指令即系统提示词(System Prompt)或上下文工程(Context Engineering)，其核心作用是定义 Agent 的核心目标与行为边界，为推理引擎提供明确的执行准则。

3. 记忆（Memory）

没有记忆的 Agent 如同 “一次性交互工具”，无法沉淀历史信息、适配长期需求。Agent 的记忆系统通常分为短期记忆和长期记忆两类，各司其职：

4. 工具（Tools）

工具就像是 Agent 的“手脚”，Agent通过工具来执行任务、获取信息或完成操作。随着生态系统的成熟，工具的使用方式也在不断变得更加标准化。

三、Agent 是如何工作的？

举个例子，当你对 Agent 说 “帮我订一张明天去杭州的高铁票”，它会一步步完成整个任务：

1. 意图解析：明确你要订高铁票，还会考虑是否需要同步发邮件通知你行程信息。

2. 行动流程规划：

先确认两个关键信息：现在的时间、你当前所在的城市（比如上海）。

连接 12306 系统，筛选出 “上午发车、二等座” 的车次。

挑出最合适的一趟（比如 G7531，8:15 发车），先问你是否确认预订。

等你确认后，自动操作订票，再整理出一份行程明细。

3. 执行与结果反馈：告诉你结果：“已为您预订 G7531 次列车（8:15 上海虹桥→9:20 杭州东），行程详情：xxx”。

4. 异常策略调整：要是碰到没票或者时间不合适的情况，它会自己换个条件重新查，再给你新的选择。

这种 “定目标 → 看情况 → 去执行 → 看反馈 → 再调整” 的循环流程，正是 Agent 的核心运行逻辑。

在这里插入图片描述

四、Spring AI 构建基础版 AI Agent：任务规划助手

（一）案例目标
搭建一个简单的任务规划 Agent，用户输入复杂任务（如 “准备周末家庭野餐”），Agent 会自动拆解为具体子任务，无需手动干预，适配入门级 Agent 核心能力。

（二）技术选型
在这里插入图片描述

（三）项目初始化与配置
1. 创建 Spring Boot 项目
项目名称：SpringAIAgentDemo
JDK 版本：17
Spring Boot 版本：3.5.3
核心依赖：Spring Web、Spring AI 智普 AI Starter、Lombok

2. 配置 pom.xml 依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.example</groupId>
        <artifactId>Weiz-SpringAI-Agent</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </parent>
    <artifactId>Weiz-SpringAI-Agent-QuickStart</artifactId>
    <name>Weiz-SpringAI-Agent-QuickStart</name>
    <description>Weiz-SpringAI-Agent-QuickStart</description>

    <properties>
        <java.version>17</java.version>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-zhipuai</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-client-chat</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

3. 配置 application.properties

# 应用基础配置
spring.application.name=SpringAIAgentDemo
server.port=8084
# 智普 AI 配置
spring.ai.zhipuai.api-key=你的智普 AI API Key
spring.ai.zhipuai.base-url=https://open.bigmodel.cn/api/paas
spring.ai.zhipuai.chat.options.model=GLM-4-Flash
# 日志配置（便于调试）
logging.level.org.springframework.ai=INFO
logging.level.com.example=DEBUG

（四）核心开发：构建任务规划 Agent
1. 编写 Agent 核心服务
创建com.example.weizspringai.service.TripPlanningAgentService 类，封装Agent 的行程规划与任务拆解能力：

package com.example.weizspringai.service;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
@Service
public class TripPlanningAgentService {

    @Autowired
    private ChatClient chatClient;

    /**
     * Agent 核心能力：接收出行需求，生成完整行程规划
     *
     * @param tripDemand 用户出行需求（包含时间、地点、偏好等）
     * @return 完整行程规划（按天/按时段拆分）
     */
    public String planTrip(String tripDemand) {
        // 定义 Agent 行为规则：引导大模型完成行程规划
        String systemPrompt = """
                你是一个专业的智能行程规划 Agent，核心职责是根据用户出行需求，生成完整、可执行的行程方案，规则如下：
                1. 先拆解需求核心要素：出行时间、目的地、人数、偏好（景点类型、饮食、交通方式）、禁忌；
                2. 行程按天拆分，每天按时间段（上午/下午/晚上）规划，包含景点、交通、餐饮、停留时长；
                3. 景点选择贴合用户偏好，餐饮适配饮食禁忌，交通路线合理（避免绕路）；
                4. 补充实用提示（如景点开放时间、预约要求、穿搭建议）；
                5. 语言简洁明了，结构清晰，便于用户直接参考执行。
                """;

        StringBuilder response = new StringBuilder();
        try {
            // 调用大模型完成行程规划（模拟 Agent 自主规划能力）
            return chatClient.prompt()
                    .system(systemPrompt)
                    .user("请根据以下出行需求生成完整行程规划：" + tripDemand)
                    .call()
                    .content();
        }catch (Exception e) {
            System.out.println("调用AI模型失败"+e.getMessage());
            return "调用AI模型失败"+e.getMessage();
        }
    }
}

2. 编写 Controller 提供接口
创建com.example.weizspringai.controller.AgentController 类，提供 HTTP 接口供测试：

package com.example.weizspringai.controller;

import com.example.weizspringai.service.TripPlanningAgentService;
import lombok.RequiredArgsConstructor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;

@RestController
@RequestMapping("/agent/trip")
@RequiredArgsConstructor
public class AgentController {

    @Autowired
    private TripPlanningAgentService tripPlanningAgentService;

    /**
     * 行程规划接口：接收出行需求，返回完整行程方案
     */
    @GetMapping("/plan")
    public Map<String, String> planTrip(@RequestParam("demand") String demand) {
        String tripPlan = tripPlanningAgentService.planTrip(demand);
        return Map.of(
                "userDemand", demand,
                "tripPlan", tripPlan,
                "agentType", "智能行程规划 Agent"
        );
    }
}

（五）系统测试与验证
测试 1：规划 “周末两天北京短途游”

访问http://localhost:8084/agent/trip/plan?demand=周末两天北京短途游，2人，偏好人文景点，不吃辣，交通以地铁为主，响应结果：

{
  "userDemand": "周末两天北京短途游，2人，偏好人文景点，不吃辣，交通以地铁为主",
  "tripPlan": "### 北京周末两天短途游行程规划\n\n#### 第一天：历史文化体验\n\n**上午**\n- **9:00-10:30**：**天安门广场**\n  - 景点：参观毛主席纪念堂（需提前预约），游览天安门广场。\n  - 交通：地铁1号线天安门东站下车。\n  - 餐饮建议：附近有王府井小吃街，可品尝京味小吃，但请注意避免辣食。\n\n- **10:45-12:00**：**故宫博物院**\n  - 景点：参观故宫，了解中国古代皇家文化。\n  - 交通：步行至故宫东华门，乘坐地铁1号线或2号线至天安门东站。\n  - 餐饮建议：故宫附近有“故宫角楼餐厅”，提供不辣的宫廷小吃。\n\n**下午**\n- **12:30-14:00**：午餐\n  - 餐饮建议：选择“老北京炸酱面”或“豆汁儿”等不辣的北京特色美食。\n\n- **14:30-16:00**：**南锣鼓巷**\n  - 景点：游览南锣鼓巷，体验老北京胡同文化。\n  - 交通：步行或乘坐地铁8号线南锣鼓巷站下车。\n\n- **16:15-17:30**：**什刹海**\n  - 景点：参观后海、前海，感受北京古都的宁静。\n  - 交通：步行从南锣鼓巷前往什刹海。\n\n**晚上**\n- **18:00-19:30**：晚餐\n  - 餐饮建议：选择“全聚德”烤鸭或其他不辣的北京菜馆。\n\n- **20:00-21:30**：**王府井步行街**\n  - 景点：逛王府井步行街，体验北京现代都市风貌。\n  - 交通：步行或乘坐地铁1号线王府井站下车。\n\n#### 第二天：艺术与休闲\n\n**上午**\n- **9:00-10:30**：**国家大剧院**\n  - 景点：参观国家大剧院，欣赏建筑艺术。\n  - 交通：地铁1号线天安门东站下车，步行至国家大剧院。\n\n- **11:00-12:00**：**中央美术学院美术馆**\n  - 景点：参观美术馆，感受艺术氛围。\n  - 交通：步行至中央美术学院美术馆。\n\n**下午**\n- **12:30-14:00**：午餐\n  - 餐饮建议：选择“京味斋”等提供不辣的北京菜馆。\n\n- **14:30-16:00**：**798艺术区**\n  - 景点：游览798艺术区，感受现代艺术气息。\n  - 交通：乘坐地铁6号线至东四十条站，步行至798艺术区。\n\n**晚上**\n- **18:00-19:30**：晚餐\n  - 餐饮建议：选择“西四老馆”等不辣的北京特色餐厅。\n\n- **20:00-21:30**：**后海酒吧街**\n  - 景点：在酒吧街享受夜晚的休闲时光。\n  - 交通：乘坐地铁6号线至南锣鼓巷站，步行至后海酒吧街。\n\n### 实用提示\n- **预约**：故宫、毛主席纪念堂等景点需提前预约。\n- **穿搭建议**：根据天气情况，建议穿着舒适、便于行走的服装。\n- **交通**：以地铁为主，部分景点间步行可达，避免高峰期拥堵。\n\n希望这份行程规划能帮助您享受愉快的北京周末之旅！",
  "agentType": "智能行程规划 Agent"
}

测试 2：规划 “单日西安历史文化游”

访问 http://localhost:8084/agent/trip/plan?demand=单日西安历史文化游，1人，喜欢古建筑，素食主义者，希望行程宽松，响应结果：

{
  "userDemand": "单日西安历史文化游，1人，喜欢古建筑，素食主义者，希望行程宽松",
  "tripPlan": "### 西安历史文化单日游行程规划\n\n#### 出行日期：[请填写具体日期]\n#### 人数：1人\n#### 偏好：\n- 景点类型：古建筑\n- 饮食：素食\n- 交通方式：步行为主，公共交通辅助\n\n#### 禁忌：\n- 无特殊禁忌\n\n### 行程安排\n\n#### 上午：\n- **08:00 - 09:00**：**早餐** - 在回民街品尝素食早餐，如素食肉夹馍、豆腐脑等。\n- **09:30 - 11:30**：**陕西历史博物馆** - 参观古建筑，了解陕西历史文化。建议提前在线预约门票，博物馆内可自备午餐。\n- **停留时长**：1.5小时\n\n#### 下午：\n- **12:00 - 13:00**：**午餐** - 在博物馆附近的素食餐厅用餐，如“素满园”。\n- **13:30 - 15:30**：**大雁塔** - 参观唐代著名佛塔，周围有多个古建筑群，适合悠闲漫步。\n- **停留时长**：1.5小时\n\n#### 晚上：\n- **16:00 - 17:30**：**小雁塔** - 参观另一座唐代古塔，欣赏周边夜景。\n- **18:00 - 19:00**：**晚餐** - 在大雁塔附近选择一家素食餐厅，如“素食园”。\n- **停留时长**：1小时\n\n#### 实用提示：\n- **陕西历史博物馆**：建议提前一天预约，开放时间为9:00-17:00，16:00停止入场。\n- **素食餐厅**：西安有众多素食餐厅，可根据个人口味选择。\n- **穿搭建议**：建议穿着舒适，以休闲装为主，适合步行。\n- **交通**：步行为主，如需公共交通，可使用西安公交或地铁，注意查看路线和时间表。\n\n### 行程总结\n本行程以参观古建筑为主，结合素食饮食，适合喜欢悠闲游览的素食主义者。行程安排宽松，让游客能够充分感受西安的历史文化氛围。",
  "agentType": "智能行程规划 Agent"
}

（六）测试结果分析
从上面的测试结果可以看到：智能行程规划 Agent 具备完整的核心能力，接收用户需求后无需人工干预即可自动拆解并完成行程规划，覆盖景点、交通、餐饮、实用提示等全要素且贴合人文景点、素食、地铁出行等用户偏好，时间安排合理、步骤清晰可直接落地执行，还能根据人数、饮食禁忌、交通偏好等不同需求灵活调整行程细节，充分满足 “宽松”“不赶时间” 等实际使用场景。

五、Agent 核心逻辑总结

本案例通过 Spring AI 快速搭建了基础版智能行程规划 Agent，核心逻辑如下：

定义 Agent 行为规则：通过系统提示词明确 Agent 的核心任务（行程规划）和输出标准（结构清晰、贴合偏好）；
借助大模型实现智能规划：利用 GLM-4-Flash 的推理与拆解能力，将模糊的出行需求转化为具体行程；
提供简洁交互接口：通过 HTTP 接口接收用户需求，返回标准化、可执行的行程结果。

这个基础版 Agent 虽未涉及工具调用、记忆存储等高级能力，但已体现 AI Agent 的核心价值 —— 将 “模糊需求” 转化为 “明确方案”，为后续复杂 Agent 开发奠定基础。