五分钟构建天气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 网关。

有两个细节很重要：

第二步：把工具注册成 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

天气只是入门例子。真正有价值的是把同一套模式迁移到业务系统：

生产化清单

但要注意，企业级 Agent 不应该一开始就追求“大而全”。更稳的路径是：先做单工具、单场景、只读查询；再加多工具编排；最后再考虑写操作、审批、人机协同和审计。

生产落地检查清单

上线前至少检查这些点：

如果这些点没做，Demo 越顺，生产越危险。因为 Agent 一旦接入真实系统，就不再只是“聊天窗口”，而是一个会替用户触发系统能力的入口。

总结

用 Spring AI Alibaba 构建第一个天气智能体，核心步骤其实只有四个：添加依赖、创建天气工具、注册 ToolCallback、组装 ReactAgent。

真正值得记住的是这个模式：

自然语言问题 → 模型判断 → 工具调用 → 外部结果 → 最终回答

这个链路跑通之后，天气只是最小样例。你可以把它迁移到订单、库存、知识库、工单、审批等真实业务场景。对于 Java 后端团队来说，Spring AI Alibaba 的价值在于：它把 AI Agent 的实验性玩法，尽量拉回到熟悉的 Spring 工程模型里，让你可以用已有的工程治理方式去管理一个会调用工具的智能体。