Java大模型开发入门 (12/15)：Agent实战 - 打造能调用外部API的智能助手

前言

在上一篇文章中，我们成功地为AI应用装上了“四肢”，构建了一个能使用本地计算器工具的初级智能体（Agent）。它不再只是一个“知道分子”，更是一个能做简单计算的“行动派”。

然而，它的“行动”范围还局限在我们的Java程序内部。真正的智能助手需要能够与广阔的外部世界进行信息交互。今天，我们将拆除这堵墙，把难度和实用性都提升一个台阶：我们将赋予Agent调用外部REST API的能力。

我们将封装一个能查询实时天气预报的API作为新工具，打造一个能理解“明天上海天气怎么样？”这类自然语言，并给出实时、准确答案的智能助手。

第一步：选择并分析外部API

为了方便学习，我们选择一个免费、稳定且无需API Key的公共天气API：Open-Meteo。

我们将使用它的天气预报API，其基本用法如下：

• 请求URL: https://api.open-meteo.com/v1/forecast
• 请求参数:
  • latitude: 纬度 (e.g., 31.2323)
  • longitude: 经度 (e.g., 121.4692)
  • daily: 需要查询的每日数据，比如weather_code,temperature_2m_max (天气代码, 最高温度)
  • timezone: 时区 (e.g., Asia/Shanghai)

一个有趣的挑战是，这个API需要经纬度，而用户通常只会提供城市名。我们正好可以利用这一点来检验我们Agent的“智力”——LLM本身具备将城市名转换为经纬度的常识知识！

第二步：创建天气工具 (WeatherTools)

我们将创建一个新的工具类，负责调用天气API。

1. 添加spring-boot-starter-web依赖
   如果你的项目中还没有RestTemplate，请确保pom.xml中包含spring-boot-starter-web，它会自动配置RestTemplate等Web客户端。

2. 创建WeatherTools类
   在service包下创建WeatherTools.java。

   package com.example.aidemoapp.service;import dev.langchain4j.agent.tool.Tool;
   import lombok.RequiredArgsConstructor;
   import org.springframework.stereotype.Component;
   import org.springframework.web.client.RestTemplate;import java.util.Map;@Component
   @RequiredArgsConstructor
   public class WeatherTools {private final RestTemplate restTemplate = new RestTemplate();@Tool("""Gets the current weather forecast for a given latitude and longitude.It's important to use this tool ONLY when user asks about weather.""")public String getWeatherForecast(double latitude, double longitude) {System.out.printf("Tool executed: getWeatherForecast(lat=%.4f, lon=%.4f)%n", latitude, longitude);String apiUrl = String.format("https://api.open-meteo.com/v1/forecast?latitude=%.4f&longitude=%.4f&daily=weather_code,temperature_2m_max,temperature_2m_min&timezone=Asia/Shanghai",latitude, longitude);try {// 使用RestTemplate调用API// 我们期望返回一个Map结构的JSON对象Map<String, Object> response = restTemplate.getForObject(apiUrl, Map.class);if (response != null && response.containsKey("daily")) {Map<String, Object> dailyData = (Map<String, Object>) response.get("daily");// 简单地提取第一天的数据作为“当前”预报double maxTemp = ((java.util.List<Double>) dailyData.get("temperature_2m_max")).get(0);double minTemp = ((java.util.List<Double>) dailyData.get("temperature_2m_min")).get(0);return String.format("The weather forecast is: min temperature %.1f°C, max temperature %.1f°C.", minTemp, maxTemp);}return "Could not retrieve weather data.";} catch (Exception e) {System.err.println("Error calling weather API: " + e.getMessage());return "Error: Unable to get weather forecast.";}}
   }
   

   代码解析：

   • @Tool注解中的描述非常关键，它告诉LLM这个工具是干什么的，以及何时应该使用它。
   • 我们定义了latitude和longitude两个参数，把“城市名转经纬度”这个推理任务留给了LLM。
   • 内部使用RestTemplate来执行HTTP GET请求。
   • 我们对返回的JSON进行了简单的解析，提取出最高和最低温度，并格式化成一个人类可读的字符串返回。在生产环境中，你会使用更健壮的DTO类来做JSON映射。

第三步：升级我们的Agent，赋予它多种工具

一个Agent可以拥有一个“工具箱”，里面放着各种工具。我们只需在创建AiService时，把所有工具都提供给它。

1. 修改config/LangChain4jConfig.java
   找到agentAssistant的Bean定义，将新的WeatherTools也注入进去。

   // LangChain4jConfig.java// ... 其他Bean的定义 ...
   import com.example.aidemoapp.service.AgentAssistant;
   import com.example.aidemoapp.service.CalculatorTools;
   import com.example.aidemoapp.service.WeatherTools; // 引入新工具// ...@Configuration
   public class LangChain4jConfig {// ... 其他已有的Bean ...// 修改Agent服务接口Bean@Beanpublic AgentAssistant agentAssistant(ChatModel chatLanguageModel, CalculatorTools calculatorTools,WeatherTools weatherTools) { // 注入新工具return AiServices.builder(AgentAssistant.class).chatModel(chatLanguageModel).tools(calculatorTools, weatherTools) // <-- 关键步骤：将所有工具都注册进去.build();}
   }
   

   现在，我们的agentAssistant同时拥有了计算器和天气查询两种能力！

第四步：进行综合测试

1. 启动或重启你的Spring Boot应用。

2. 测试计算能力
   请求URL: http://localhost:8080/api/agent/chat?query=What is 3 plus14?
   Agent应该能正确调用CalculatorTools（你可能需要先为它添加一个乘法工具！）并给出答案。

3. 测试天气查询能力
   请求URL: http://localhost:8080/api/agent/chat?query=明天上海天气怎么样？
   现在，见证奇迹的时刻到了！

   • LLM思考：“用户在问上海的天气。我有一个getWeatherForecast工具，但它需要经纬度。我知道巴黎的经纬度大约是31.2304,121.4737。”
   • 后台日志：你会看到类似 TTool executed: getWeatherForecast(lat=31.2304, lon=121.4737) 的打印。
   • 最终回答：你会收到一个类似 "明天上海的天气预报显示，最低气温为23.2°C，最高气温为30.1°C。" 的实时回答。

4. 测试无工具任务
   请求URL: http://localhost:8080/api/agent/chat?query=Tell me a story about a brave knight.
   Agent会发现这个问题不需要任何工具，于是直接使用gpt-4o-mini的创作能力来回答你。

总结

今天，我们成功地将AI Agent的能力从程序内部延伸到了广阔的互联网世界。通过封装一个调用外部API的工具，我们的AI助手变得前所未有的实用。

我们学到了：

• 如何将一个调用外部API的Java方法封装成一个@Tool。
• LLM的强大推理能力，它能根据自然语言自主推断出调用工具所需的精确参数（如经纬度）。
• 如何为一个Agent配置一个包含多种不同能力的“工具箱”。

我们的AI应用开发之旅已经走过了很长的路，从最初的简单API调用，到RAG，再到现在的多功能Agent。我们一直在使用功能强大的LangChain4j框架。但是，Spring官方也推出了自己的AI框架——Spring AI。它和LangChain4j有什么异同？它能为我们带来什么新的便利？

---

源码获取

本文中所有实战代码均已同步更新至Gitee仓库。建议您git pull拉取最新代码，对照本文进行学习。

• Gitee仓库地址: https://gitee.com/chaocloud/springboot-langchain4j-demo.git

---

下一篇预告：
《Java大模型开发入门 (13/15)：拥抱官方标准 - Spring AI框架入门与实践》—— 我们将探索由Spring官方团队打造的AI框架Spring AI，了解它的设计哲学，并用它来实现我们之前已经很熟悉的功能，看看它能为Spring开发者带来怎样“原汁原味”的开发体验。