写在前面

       2026年，AI Agent不再是Python的专属领地。Spring AI Alibaba 1.1.2.0的发布，让Java开发者可以用最熟悉的Spring Boot风格，像写普通Service一样写Agent。但很多Java同学还在观望——“Java做Agent是不是很复杂？”“是不是要学一堆新东西？”今天，我带你用天气查询Agent这个经典案例，从零开始，完整走一遍从依赖配置到生产级部署的全流程。全程只有代码、注解和Spring Boot——没有Python，没有陌生的框架。看完这篇文章，你就能在自己的Spring Boot项目里跑起来第一个Agent。

一、Spring AI Alibaba 1.1.2：Java Agent开发的“全家桶”

1.1 从“模型接入”到“智能体框架”的跃迁

自1.1.2.x版本起，Spring AI Alibaba已从单纯的“模型接入工具”升级为完整的智能体开发框架。其核心架构包含六大模块：智能体框架（Agent Framework）提供智能体生命周期管理、能力注册与调用机制。

2026年2月发布的1.1.2.0版本带来了两大核心升级：

• Agent Skills：ReactAgent集成Agent Skills，支持技能的渐进式披露——系统提示中只注入技能列表（name、description），模型需要时再调用read_skill加载完整内容

• 多智能体模式：Graph支持并行条件边、并行聚合策略（AllOf/AnyOf）、异步工具执行等增强

1.2 为什么Java开发者应该关注？

Spring AI Alibaba基于Spring AI构建，是阿里云通义系列模型及服务在Java AI应用开发领域的最佳实践。它提供高层次的AI API抽象与云原生基础设施集成方案，深度集成Spring Cloud Alibaba的微服务治理体系。

更关键的是：你不需要为了AI重写整个系统——Spring AI Alibaba可以无缝融入现有Spring Boot项目。

二、ReAct Agent：Agent的“思考-行动”循环

在写代码之前，先理解Agent的核心运行机制。Spring AI Alibaba的Agent基于业界最成熟的ReAct（Reasoning + Acting）框架。

ReAct的核心是一个循环：

Agent的四大核心组件：

• 大脑（大模型） ：负责思考、决策、规划

• 工具集：Agent可调用的所有能力（Function Calling）

• 记忆系统：短期记忆（当前会话）+ 长期记忆（跨会话）

• 规划器：复杂任务拆解、步骤优化、错误修正

我们用天气查询Agent来完整演示这套机制。

三、实战一：5分钟跑通你的第一个Agent（基础版）

3.1 添加核心依赖

xml

<dependencies>
    <!-- Spring AI Alibaba Agent Framework -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-agent-framework</artifactId>
        <version>1.1.2.0</version>
    </dependency>
    <!-- DashScope ChatModel 支持 -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
        <version>1.1.2.0</version>
    </dependency>
</dependencies>

3.2 定义天气工具

java

// 方式一：实现 BiFunction 接口
class WeatherTool implements BiFunction<String, ToolContext, String> {
    @Override
    public String apply(String city, ToolContext toolContext) {
        // 实际项目可调用真实天气API
        return city + "今天天气非常好！☀️ 气温25°C";
    }
}

// 方式二：使用 @Tool 注解（更简洁）
@Component
public class WeatherTools {
    @Tool(description = "查询指定城市的实时天气信息")
    public String getWeather(@ToolParam(description = "城市名称") String city) {
        // 调用真实天气API
        return city + "今天晴，气温25°C，湿度60%";
    }
}

3.3 构建并运行Agent

java

@Test
void testWeatherAgent() throws GraphRunnerException {
    // 1. 初始化 DashScope API
    DashScopeApi dashScopeApi = DashScopeApi.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .build();
    
    // 2. 创建 ChatModel
    ChatModel chatModel = DashScopeChatModel.builder()
        .dashScopeApi(dashScopeApi)
        .build();
    
    // 3. 包装工具
    ToolCallback weatherTool = FunctionToolCallback.builder("get_weather", new WeatherTool())
        .description("获取某个城市的天气")
        .inputType(String.class)
        .build();
    
    // 4. 构建 ReactAgent[reference:14]
    ReactAgent agent = ReactAgent.builder()
        .name("weather_agent")
        .model(chatModel)
        .tools(weatherTool)
        .systemPrompt("你是一个专业的天气预报助手")
        .saver(new MemorySaver())  // 内存版记忆
        .build();
    
    // 5. 调用 Agent[reference:15]
    AssistantMessage response = agent.call("上海今天天气怎么样？");
    System.out.println(response.getText());
    // 输出: 上海今天天气非常好！☀️ 气温25°C
}

核心步骤拆解：

步骤	作用
DashScopeApi配置	连接阿里云大模型服务
FunctionToolCallback	将Java方法包装为Agent可调用的工具
ReactAgent.builder()	用Builder模式快速构建Agent
MemorySaver	保存对话历史，支持多轮对话

仅需十几行代码，一个能思考、能调用工具的Agent就跑起来了。

四、实战二：生产级Agent的完整实现

基础版能跑通，但生产环境需要更多能力。下面展示一个生产级天气Agent的完整实现。

4.1 系统提示词设计（关键！）

系统提示词决定了Agent的行为模式。好的提示词应该包含：角色定位 + 工具说明 + 行为约束。

java

String SYSTEM_PROMPT = """
    你是一位擅长说**天气冷笑话/谐音梗**的专业天气预报员。
    
    你可以使用两个工具：
    - **get_weather_for_location**：用于获取指定地点的天气
    - **get_user_location**：用于获取用户当前所在位置
    
    如果用户询问天气，**必须先确认地点**。
    如果从问题中能判断出他们指的是**自己所在的地方**，
    就使用 **get_user_location** 工具获取他们的位置。
    
    回答格式要求：
    1. 先说天气状况
    2. 附上一个与天气相关的冷笑话
    3. 给出穿衣或出行建议
    """;

4.2 多工具协同 + 结构化输出

java

@Configuration
public class WeatherAgentConfig {
    
    @Bean
    public ReactAgent weatherAgent(ChatModel chatModel) {
        // 注册多个工具
        List<ToolCallback> tools = List.of(
            FunctionToolCallback.builder("get_weather", new WeatherTool())
                .description("查询指定城市的实时天气")
                .inputType(WeatherRequest.class)
                .build(),
            FunctionToolCallback.builder("get_user_location", new LocationTool())
                .description("获取用户当前所在城市")
                .inputType(Void.class)
                .build()
        );
        
        return ReactAgent.builder()
            .name("weather_assistant")
            .model(chatModel)
            .tools(tools.toArray(new ToolCallback[0]))
            .systemPrompt(SYSTEM_PROMPT)
            .saver(new RedisSaver(redisTemplate))  // 生产环境用Redis[reference:19]
            .build();
    }
}

// 结构化输入参数
public record WeatherRequest(String city, String date) {}

五、进阶：Agent Skills——让Agent“按需学习”

1.1.2.0版本最实用的新特性是Agent Skills。它解决了之前Agent“知道的太多”导致的上下文膨胀问题。

5.1 为什么需要Skills？

之前的Agent开发有个痛点：为了让Agent能处理各种任务，得把所有背景知识、工具说明都塞进系统提示里。结果上下文越来越长，模型容易分心，token消耗也居高不下。

Skills的思路很简单：先把技能目录给Agent，等它真正需要时再加载详细内容。

5.2 创建第一个Skill

text

skills/
└── weather-expert/
    ├── SKILL.md          # 必需：技能定义
    ├── references/       # 可选：参考资料
    └── scripts/          # 可选：执行脚本

SKILL.md格式：

markdown

---
name: weather-expert
description: 专业天气预报技能，包含气象知识、天气解读和预报服务
---

# 天气预报专家技能

## 功能说明
你是一位专业的气象预报员，能够：
1. 解读气象数据并提供准确的天气预测
2. 分析天气趋势并给出出行建议
3. 用通俗易懂的语言解释气象现象

## 使用方法
1. 当用户询问天气时，先确认地点
2. 调用 get_weather 工具获取数据
3. 结合气象知识解读数据
4. 给出实用建议

## 注意事项
- 72小时以上的预报仅供参考
- 极端天气要强调安全提示

5.3 在Agent中加载Skills

java

// 1. 注册Skill
SkillRegistry registry = FileSystemSkillRegistry.builder()
    .projectSkillsDirectory(System.getProperty("user.dir") + "/skills")
    .build();

// 2. 创建Skills Hook（自动注入read_skill工具）
SkillsAgentHook hook = SkillsAgentHook.builder()
    .skillRegistry(registry)
    .build();

// 3. 构建Agent
ReactAgent agent = ReactAgent.builder()
    .name("skills-agent")
    .model(chatModel)
    .saver(new MemorySaver())
    .hooks(List.of(hook))  // 注入Skills能力
    .build();

// 4. Agent自动发现skills目录下的所有Skill
agent.call("请介绍一下你有哪些技能？");
// Agent会先展示技能列表，需要时再加载详细内容

渐进式披露的工作流程：

六、生产环境部署的“避坑指南”

java

@Bean
public ChatMemory chatMemory(RedisConnectionFactory redisConnectionFactory) {
    return new RedisChatMemory(redisConnectionFactory);
}

@Bean
public ReactAgent agent(ChatModel chatModel, ChatMemory chatMemory) {
    return ReactAgent.builder()
        .model(chatModel)
        .saver(new RedisSaver(chatMemory))  // Redis持久化
        .build();
}

6.1 记忆持久化：从MemorySaver到RedisSaver

开发环境用MemorySaver没问题，但生产环境必须用RedisSaver——否则服务重启后所有对话历史都会丢失。

6.2 多实例部署的会话一致性

多实例部署后，会话可能分散在不同Pod，需要确保会话状态共享。使用Redis共享存储是标准方案。

6.3 可观测性与调试

Spring AI Alibaba Admin提供可视化的Agent开发、可观测性、评估和MCP管理能力。生产环境建议接入。

6.4 生产级部署架构

七、总结：Java开发者入局AI的最好时机

从本文的实战可以看到，用Spring AI Alibaba构建Agent并不复杂：

1. 依赖配置：添加两个starter，5分钟搞定

2. 工具定义：用@Tool注解或FunctionToolCallback，把Java方法变成Agent的工具

3. Agent构建：用Builder模式，十几行代码创建ReActAgent

4. 记忆管理：开发用MemorySaver，生产换RedisSaver

5. 技能扩展：用Agent Skills实现渐进式加载，控制Token成本

2026年，Java开发者不需要转Python就能构建生产级Agent。Spring AI Alibaba 1.1.2已经提供了从模型接入、Agent构建到云原生部署的端到端能力。

你的第一个Agent，就从今天开始。