LangChain4j 工具调用实战

你有没有遇到过这种场景：

• 用户问 AI："帮我查下今天上海的天气"
  
• AI 回答："抱歉，我无法获取实时信息。"
  

问题的核心是：AI 没有工具。就像给你一双手脚，让你去盖房子，你也做不到。但如果给你一套工具箱，情况就完全不同了。
今天我们就来给 AI 装上一套工具箱，让它能够从博客园实时获取最新技术文章。
什么是工具调用？

简单来说，工具调用就是让 AI 能够"借用"外部能力。
这些能力包括但不限于：

• 联网搜索
  
• 调用第三方 API
  
• 读写文件
  
• 查询数据库
  
• 执行代码
  

但有一个关键点要特别注意：
工具调用 不是 AI 自己去执行这些工具，而是 AI 说"我需要调用 XX 工具"，真正执行的是我们的应用程序。
流程是这样的：

1. 用户提问 → AI 分析意图 → AI 决定调用工具
2. → 我们的程序执行工具 → 把结果返回给 AI → AI 继续回答

复制代码

要实现的目标

让 AI 能够查询博客园用户的最新文章，并提取这些信息：

• 文章标题
  
• 文章链接
  
• 发布日期
  
• 摘要内容
  
• 阅读数、评论数、推荐数
  

实现方案：用 Jsoup 抓取博客园页面，把数据整理后返回给 AI。
快速了解流程

完整流程其实很简单：

• 用户提问 → 2. AI 分析意图 → 3. AI 决定调用工具 → 4. 程序执行工具 → 5. 结果返回给 AI → 6. AI 整理后回复用户
  

核心就是：AI 不直接调用工具，而是告诉我们的程序"我需要调用这个工具"，程序执行完后把结果给 AI，AI 再基于结果回答用户。

想看详细的调用链路？文章最后有完整的时序图，包你一看就懂。

动手实现（四步搞定）

步骤 1：引入依赖

先在 pom.xml 中加入 Jsoup（网页爬虫库）：

1. <dependency>
2.     <groupId>org.jsoup</groupId>
3.     jsoup</artifactId>
4.     <version>1.20.1</version>
5. </dependency>

复制代码

步骤 2：编写工具类

在 tools 包下创建一个工具类，用 @Tool 注解告诉 LangChain4j："这是一个工具"。
⚠️ 重点：工具描述一定要写清楚，AI 能否正确调用工具全看这个描述！

1. /**
2. * 博客园文章搜索工具
3. * 用于从博客园抓取用户的最新文章信息
4. *
5. * @author BNTang
6. */
7. @Slf4j
8. public class CnblogsArticleTool {
10.     /**
11.      * 从指定用户的博客园主页获取最新的技术文章列表。
12.      * 支持提取文章标题、链接、发布日期、摘要、阅读数、评论数和推荐数等信息。
13.      *
14.      * @param input 博客园用户名或URL，可选地附加"|N"来限制结果数量
15.      * @return 技术文章列表的JSON格式，包含详细信息，若失败则返回错误信息
16.      */
17.     @Tool(name = "cnblogsSearch", value = """
18.             从博客园获取最新文章。输入可以是：
19.             - 博客园用户名（例如：'someUser'）
20.             - 完整的个人主页URL（例如：'https://www.cnblogs.com/someUser/'）
21.             可选择性地附加'|N'来限制结果数量，例如：'someUser|5'。
22.             返回包含标题、链接、日期、摘要、阅读数、评论数、推荐数的JSON数组。
23.             """
24.     )
25.     public String searchCnblogsArticles(@P(value = "用户名或URL（可选地附加|限制数量）") String input) {
26.         if (input == null || input.trim().isEmpty()) {
27.             return "{"error":"Empty input"}";
28.         }
30.         String[] parts = input.trim().split("\\|", 2);
31.         String target = parts[0].trim();
32.         int limit = 10;
33.         if (parts.length == 2) {
34.             try {
35.                 limit = Math.max(1, Math.min(100, Integer.parseInt(parts[1].trim())));
36.             } catch (NumberFormatException ignored) { /* keep default */ }
37.         }
39.         String url;
40.         if (target.startsWith("http://") || target.startsWith("https://")) {
41.             url = target;
42.         } else {
43.             url = "https://www.cnblogs.com/" + target + "/";
44.         }
46.         Document doc = fetchDocumentWithRetries(url, 3, 8000);
47.         if (doc == null) {
48.             return "{"error":"Failed to fetch or parse page"}";
49.         }
51.         // 选择博客文章的主容器
52.         Elements dayElements = doc.select(".day");
54.         List results = new ArrayList<>();
56.         for (Element dayEl : dayElements) {
57.             if (results.size() >= limit) {
58.                 break;
59.             }
61.             // 提取标题和链接
62.             Element titleEl = dayEl.selectFirst(".postTitle a, .postTitle2");
63.             if (titleEl == null) {
64.                 continue;
65.             }
67.             String title = titleEl.text().trim();
68.             // 移除"[置顶]"标记
69.             title = title.replaceAll("^\\[置顶]\\s*", "");
71.             String href = titleEl.absUrl("href");
72.             if (href.isEmpty()) {
73.                 href = titleEl.attr("href").trim();
74.             }
76.             // 去重检查
77.             boolean seen = false;
78.             for (ArticleInfo r : results) {
79.                 if (r.url.equals(href)) {
80.                     seen = true;
81.                     break;
82.                 }
83.             }
84.             if (seen) {
85.                 continue;
86.             }
88.             // 提取日期
89.             String date = "";
90.             Element dateEl = dayEl.selectFirst(".dayTitle a");
91.             if (dateEl != null) {
92.                 date = dateEl.text().trim();
93.             }
95.             // 提取摘要
96.             String summary = "";
97.             Element summaryEl = dayEl.selectFirst(".c_b_p_desc, .postCon");
98.             if (summaryEl != null) {
99.                 summary = summaryEl.text().trim();
100.                 // 移除"阅读全文"链接文本
101.                 summary = summary.replaceAll("阅读全文$", "").trim();
102.                 // 限制摘要长度
103.                 if (summary.length() > 200) {
104.                     summary = summary.substring(0, 200) + "...";
105.                 }
106.             }
108.             // 提取统计信息
109.             String viewCount = "0";
110.             String commentCount = "0";
111.             String diggCount = "0";
113.             Element postDesc = dayEl.selectFirst(".postDesc");
114.             if (postDesc != null) {
115.                 Element viewEl = postDesc.selectFirst(".post-view-count");
116.                 if (viewEl != null) {
117.                     viewCount = extractNumber(viewEl.text());
118.                 }
120.                 Element commentEl = postDesc.selectFirst(".post-comment-count");
121.                 if (commentEl != null) {
122.                     commentCount = extractNumber(commentEl.text());
123.                 }
125.                 Element diggEl = postDesc.selectFirst(".post-digg-count");
126.                 if (diggEl != null) {
127.                     diggCount = extractNumber(diggEl.text());
128.                 }
129.             }
131.             if (!title.isEmpty() && !href.isEmpty()) {
132.                 results.add(new ArticleInfo(title, href, date, summary, viewCount, commentCount, diggCount));
133.             }
134.         }
136.         if (results.isEmpty()) {
137.             return "{"message":"未找到文章。"}";
138.         }
140.         StringBuilder sb = new StringBuilder();
141.         sb.append("[");
142.         for (int i = 0; i < results.size(); i++) {
143.             ArticleInfo article = results.get(i);
144.             sb.append("{");
145.             sb.append(""title":").append(jsonEscape(article.title)).append(",");
146.             sb.append(""url":").append(jsonEscape(article.url)).append(",");
147.             sb.append(""date":").append(jsonEscape(article.date)).append(",");
148.             sb.append(""summary":").append(jsonEscape(article.summary)).append(",");
149.             sb.append(""viewCount":").append(article.viewCount).append(",");
150.             sb.append(""commentCount":").append(article.commentCount).append(",");
151.             sb.append(""diggCount":").append(article.diggCount);
152.             sb.append("}");
153.             if (i < results.size() - 1) {
154.                 sb.append(",");
155.             }
156.         }
157.         sb.append("]");
158.         return sb.toString();
159.     }
161.     /**
162.      * 带重试机制获取网页文档
163.      *
164.      * @param url         目标URL
165.      * @param maxAttempts 最大尝试次数
166.      * @param timeoutMs   超时时间（毫秒）
167.      * @return Jsoup文档对象，失败返回null
168.      */
169.     private Document fetchDocumentWithRetries(String url, int maxAttempts, int timeoutMs) {
170.         String userAgent = "Mozilla/5.0 (compatible; Bot/1.0; +https://example.com/bot)";
171.         int attempt = 0;
172.         while (attempt < maxAttempts) {
173.             attempt++;
174.             try {
175.                 return Jsoup.connect(url)
176.                         .userAgent(userAgent)
177.                         .timeout(timeoutMs)
178.                         .referrer("https://www.google.com")
179.                         .get();
180.             } catch (IOException e) {
181.                 log.warn("第{}次尝试获取 {} 失败: {}", attempt, url, e.getMessage());
182.                 try {
183.                     Thread.sleep(500L * attempt);
184.                 } catch (InterruptedException ignored) {
185.                     Thread.currentThread().interrupt();
186.                     break;
187.                 }
188.             }
189.         }
190.         log.error("所有尝试均失败，无法获取 {}", url);
191.         return null;
192.     }
194.     /**
195.      * 从文本中提取数字
196.      *
197.      * @param text 包含数字的文本，如"阅读(123)"
198.      * @return 提取的数字字符串
199.      */
200.     private String extractNumber(String text) {
201.         if (text == null) {
202.             return "0";
203.         }
204.         text = text.replaceAll("[^0-9]", "");
205.         return text.isEmpty() ? "0" : text;
206.     }
208.     /**
209.      * JSON字符串转义
210.      *
211.      * @param s 待转义的字符串
212.      * @return 转义后的JSON字符串
213.      */
214.     private String jsonEscape(String s) {
215.         if (s == null) {
216.             return """";
217.         }
218.         String escaped = s.replace("\", "\\\")
219.                 .replace(""", "\\"")
220.                 .replace("\n", "\\n")
221.                 .replace("\r", "\\r");
222.         return """ + escaped + """;
223.     }
225.     /**
226.      * 文章信息类
227.      */
228.     private static class ArticleInfo {
229.         String title;
230.         String url;
231.         String date;
232.         String summary;
233.         String viewCount;
234.         String commentCount;
235.         String diggCount;
237.         ArticleInfo(String title, String url, String date, String summary,
238.                     String viewCount, String commentCount, String diggCount) {
239.             this.title = title;
240.             this.url = url;
241.             this.date = date;
242.             this.summary = summary;
243.             this.viewCount = viewCount;
244.             this.commentCount = commentCount;
245.             this.diggCount = diggCount;
246.         }
247.     }
248. }

复制代码

核心逻辑：

• 解析用户输入（支持用户名或 URL）
  
• 用 Jsoup 抓取博客园页面
  
• 用 CSS 选择器提取文章信息
  
• 返回 JSON 格式的结果
  

步骤 3：把工具绑定到 AI Service

1. public AiCodeHelperService aiCodeHelperService() {
2.     ChatMemory chatMemory = MessageWindowChatMemory.withMaxMessages(10);
4.     return AiServices.builder(AiCodeHelperService.class)
5.             .chatModel(qwenChatModel)
6.             .chatMemory(chatMemory)
7.             .contentRetriever(contentRetriever)
8.             .tools(new CnblogsArticleTool())  // ← 绑定工具
9.             .build();
10. }

复制代码

步骤 4：测试一下

写个单元测试：

1. @Test
2. void chatWithTools() {
3.     String result = aiCodeHelperService.chat(
4.         "帮我查下博客园用户 BNTang 的最新文章"
5.     );
6.     System.out.println(result);
7. }

复制代码

关键来了，在工具方法里打断点，Debug 运行：

你会看到断点真的停下来了！

这说明 AI 真的调用了我们的工具！
工具把数据返回给 AI 后，AI 会整理成自然语言：

在 Debug 模式下，你还能看到 AI Service 加载了工具：

以及工具的完整调用链路：

完美运行！
工具定义的两种方式

前面用的是声明式定义（注解），LangChain4j 也支持编程式定义：

简单场景用声明式，需要动态创建工具用编程式。
还能做更多

除了搜索，工具调用还能实现这些功能：

• 读写本地文件
  
• 生成 PDF 报告
  
• 执行 Shell 命令
  
• 生成图表
  
• 调用企业内部 API
  

更棒的是：这些工具不一定都要自己写，可以通过 MCP（Model Context Protocol）协议直接用别人开发好的工具。
完整的调用链路

如果想深入理解工具调用的每一步，看这个时序图就对了：
sequenceDiagram      autonumber      participant U2 as
来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！