夜雨聆风AI锋行 · Spring AI Alibaba 实战
五分钟构建天气AI智能体
从 0 到可运行 Demo：让 AI 助手真的会调用天气工具，而不是凭空编答案。
封面图
你有没有遇到过这种场景：产品经理说“我们先做一个简单的 AI 助手吧，能查天气就行”，但真正落到代码里，马上就会卡在几个问题上：模型怎么接入？工具函数怎么暴露给大模型？大模型什么时候会主动调用工具？调用结果又怎么回到最终回答里？
这篇文章不绕概念，直接用 Spring AI Alibaba 做一个最小可运行的天气智能体。目标很明确：用户问“杭州今天适合带伞吗”，智能体不是凭空编答案，而是调用我们注册的 get_weather 工具，再组织成人能看懂的回复。
先看最终效果
我们要实现的链路很简单：
调用链路
用户输入一句自然语言问题后，ReactAgent 会把问题交给大模型判断。如果问题需要外部信息，大模型会选择调用 get_weather 工具；工具返回结构化天气数据；最后模型基于工具结果生成中文回答。
示例交互可以是这样：
User: 杭州今天适合带伞吗？
Agent: 杭州今天小雨，气温 18~23℃，建议带伞，通勤路上注意湿滑。注意，这里的关键不是“天气查询”本身，而是让模型学会走工具调用这条路径。只要这个模式跑通，后面可以把天气工具换成订单查询、库存查询、工单创建、知识库检索，业务价值就出来了。
准备环境
官方快速开始里给出的基础要求是：JDK 17+、Maven 3.8+，并准备一个大模型供应商的 API Key。使用 DashScope 时，通常通过环境变量注入：
export AI_DASHSCOPE_API_KEY=你的百炼APIKey新建一个 Spring Boot 项目后，核心依赖可以先保持最小化。以 Spring AI Alibaba 1.1.2.x 为例：
<dependencies>
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-agent-framework</artifactId>
<version>1.1.2.0</version>
</dependency>
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
<version>1.1.2.0</version>
</dependency>
</dependencies>如果你是在企业项目里落地，建议把版本号收敛到父工程的 dependencyManagement 中，不要让每个微服务自己散落维护。
第一步：定义天气工具
AI Agent 真正有用，靠的不是“更会聊天”，而是“能调用系统能力”。在 Spring AI / Spring AI Alibaba 的语境里，工具就是暴露给模型的函数能力。
先写一个最小天气工具：
import org.springframework.ai.chat.model.ToolContext;
import org.springframework.ai.tool.annotation.ToolParam;
import java.util.Map;
import java.util.function.BiFunction;
public class WeatherTool implements BiFunction<String, ToolContext, String> {
private static final Map<String, String> MOCK_WEATHER = Map.of(
"杭州", "小雨，18~23℃，东北风 2 级",
"上海", "多云，20~25℃，空气质量良好",
"北京", "晴，16~27℃，午后紫外线较强"
);
@Override
public String apply(
@ToolParam(description = "城市名称，例如：杭州、上海、北京") String city,
ToolContext context) {
return MOCK_WEATHER.getOrDefault(city, city + " 暂无实时天气，建议稍后重试");
}
}这里为了五分钟跑通，用了内存 Map 模拟天气接口。生产环境里可以替换成高德、和风天气、内部气象服务，或者公司已有的 HTTP 网关。
有两个细节很重要：
ToolParam 不是注释摆设，它会影响模型抽取参数的质量。第二步：把工具注册成 ToolCallback
工具类本身只是 Java 函数，还需要包装成模型可识别的 ToolCallback：
import org.springframework.ai.tool.ToolCallback;
import org.springframework.ai.tool.function.FunctionToolCallback;
ToolCallback weatherTool = FunctionToolCallback
.builder("get_weather", new WeatherTool())
.description("根据城市名称查询天气，适用于用户询问气温、下雨、是否带伞等问题")
.inputType(String.class)
.build();这里的描述建议写得业务化一点，不要只写“查询天气”。比如“是否带伞”“气温”“下雨”这些词，会帮助模型把用户问题和工具能力匹配起来。
很多工具调用失败，并不是框架问题，而是工具描述写得过于抽象：模型看不懂你这个工具什么时候该用。
第三步：创建 ChatModel
接下来创建模型对象。官方示例里使用 DashScopeChatModel：
import com.alibaba.cloud.ai.dashscope.api.DashScopeApi;
import com.alibaba.cloud.ai.dashscope.chat.DashScopeChatModel;
import org.springframework.ai.chat.model.ChatModel;
DashScopeApi dashScopeApi = DashScopeApi.builder()
.apiKey(System.getenv("AI_DASHSCOPE_API_KEY"))
.build();
ChatModel chatModel = DashScopeChatModel.builder()
.dashScopeApi(dashScopeApi)
.build();生产里不要把 API Key 写死在代码或配置仓库里。更推荐走环境变量、K8s Secret、配置中心密文能力，至少要做到不同环境隔离。
第四步：创建 ReactAgent
现在把模型、工具和提示词组装到 ReactAgent 里：
import com.alibaba.cloud.ai.graph.agent.ReactAgent;
import com.alibaba.cloud.ai.graph.agent.Agent;
import com.alibaba.cloud.ai.graph.checkpoint.savers.MemorySaver;
import org.springframework.ai.chat.messages.AssistantMessage;
ReactAgent agent = ReactAgent.builder()
.name("weather_agent")
.model(chatModel)
.tools(weatherTool)
.systemPrompt("""
你是一个天气助手。
当用户询问天气、温度、下雨、出行建议、是否带伞时，必须优先调用 get_weather 工具。
回答要简洁、具体，给出可执行建议。
如果工具返回暂无数据，要明确说明无法获得实时天气，不要编造。
""")
.saver(new MemorySaver())
.build();
AssistantMessage response = agent.call("杭州今天适合带伞吗？");
System.out.println(response.getText());到这里，一个最小天气智能体就完成了。
为什么建议先用 ReactAgent
Spring AI Alibaba Agent Framework 的定位不是只封一层 Chat API，而是为了开发 Agentic、Workflow、Multi-Agent 应用。对于第一个 Demo，我建议先用 ReactAgent，因为它刚好覆盖 Agent 最核心的闭环：
架构拆解
这个闭环比“直接问模型”更接近真实业务系统。企业里的 AI 助手通常不是只会聊天，而是要能查订单、查库存、查物流、开工单、写审批、调知识库。
五分钟 Demo 最容易踩的坑
第一，API Key 没注入成功。
很多同学启动项目后只看到鉴权失败，却忘了 IDE、终端、容器里的环境变量不是同一个作用域。建议启动时打印一个脱敏检查日志，例如只判断变量是否存在，不打印原值。
第二，工具描述过短。
如果工具只写 Get weather，模型可能不知道“要不要带伞”也应该调用它。工具描述要覆盖用户可能使用的自然语言表达。
第三，系统提示词太软。
如果提示词只是“你是一个助手”，模型可能凭常识回答天气。对于外部实时信息，要明确要求“必须优先调用工具，不要编造”。
第四，工具返回值太随意。
Demo 阶段返回字符串没问题，生产环境最好返回结构化 JSON，例如城市、天气、最高温、最低温、风力、更新时间、数据源。这样模型更容易稳定生成结论。
第五，没有兜底策略。
外部天气接口超时、限流、城市不存在都很常见。工具层要返回可解释错误，Agent 层要把错误翻译成人话，而不是直接抛异常给用户。
改成真实天气接口时怎么设计
五分钟 Demo 用 Map 足够，但真实项目可以按下面方式演进：
public record WeatherResult(
String city,
String weather,
String temperatureRange,
String wind,
String updateTime,
String source
) {}工具返回 JSON 后，再让模型总结：
{
"city": "杭州",
"weather": "小雨",
"temperatureRange": "18~23℃",
"wind": "东北风2级",
"updateTime": "2026-05-18 08:00",
"source": "internal-weather-service"
}生产里还建议加三层保护：
从天气 Agent 扩展到企业业务 Agent
天气只是入门例子。真正有价值的是把同一套模式迁移到业务系统：
生产化清单
get_weather 换成 query_order_status，就变成订单助手。search_knowledge_base，就变成内部知识库问答。create_ticket，就变成客服工单助手。query_inventory，就变成供应链库存助手。但要注意，企业级 Agent 不应该一开始就追求“大而全”。更稳的路径是：先做单工具、单场景、只读查询；再加多工具编排；最后再考虑写操作、审批、人机协同和审计。
生产落地检查清单
上线前至少检查这些点：
如果这些点没做，Demo 越顺，生产越危险。因为 Agent 一旦接入真实系统，就不再只是“聊天窗口”，而是一个会替用户触发系统能力的入口。
总结
用 Spring AI Alibaba 构建第一个天气智能体，核心步骤其实只有四个：添加依赖、创建天气工具、注册 ToolCallback、组装 ReactAgent。
真正值得记住的是这个模式：
自然语言问题 → 模型判断 → 工具调用 → 外部结果 → 最终回答这个链路跑通之后，天气只是最小样例。你可以把它迁移到订单、库存、知识库、工单、审批等真实业务场景。对于 Java 后端团队来说，Spring AI Alibaba 的价值在于：它把 AI Agent 的实验性玩法，尽量拉回到熟悉的 Spring 工程模型里，让你可以用已有的工程治理方式去管理一个会调用工具的智能体。
