LangChain4J中的工具鏈，你知道嗎？
作者：江南一點雨
大語言模型（LLM）除了生成文本，還可以通過工具調用觸發特定操作。該機制允許開發者為模型定義功能函數（如數學計算、API 調用等），當模型識別用戶需求需要外部工具輔助時，會在響應中表達調用意圖，開發者根據此意圖執行工具并將結果返回給模型。
咱們繼續來聊 langchain4j。
最近松哥和大伙聊的基本上都是大模型應用開發的入門知識，松哥這邊后面會開始做集團的知識庫，到時候再和大家分享一些項目中的實踐經驗。
一、Function Calling
大語言模型（LLM）除了生成文本，還可以通過工具調用觸發特定操作。該機制允許開發者為模型定義功能函數（如數學計算、API 調用等），當模型識別用戶需求需要外部工具輔助時，會在響應中表達調用意圖，開發者根據此意圖執行工具并將結果返回給模型。
特別是在一些涉及到數學運算的場景，大家知道大模型并不擅長于此，如果能夠直接調用我們自己的 API，就會方便很多。或者是一些涉及到內部 API 調用的場景，通過 Function Calling 就可以非常方便的實現。
1.1 三要素
- 名稱：明確的功能標識（如squareRoot）
- 描述：說明功能及適用場景（如"計算數的平方根"）
- 參數說明：每個參數的語義定義（如x表示待計算數值）
1.2 執行流程
通過工具調用機制，大模型突破了自身在實時性、準確性和功能擴展性方面的限制。
開發者需要重點掌握工具定義規范、執行流程編排和錯誤處理策略，結合 ReAct 等框架實現更智能的 AI 應用。最新技術如 LLMCompiler 的并行調用優化，以及 OpenManus 的任務分解機制，正在推動該領域向更高階的自主智能演進。
二、兩種方案
LangChain4j 中對于工具的調用提供了兩種不同的抽象層次。
2.1 Low-Level
Low-Level 直接使用 ChatLanguageModel 和 ToolSpecification API 來實現。Low-Level 具有如下一些特點：
- 完全控制：開發者需手動定義工具規格（ToolSpecification），包括工具名稱、描述、參數結構（JSON Schema）等。
- 靈活性強：適用于復雜場景，如第三方 API 集成或需要動態配置參數。
- 開發成本高：需編寫大量膠水代碼處理消息構建、工具執行及結果反饋。
適用場景：
- 需要精細控制工具邏輯（如參數校驗、錯誤處理）
- 集成非標準接口的外部服務
2.2 High-Level
High-Level 是通過 AI Services 和 @Tool 注解的 Java 方法High-Level 具有如下一些特點：
- 聲明式開發：使用 @Tool 注解自動生成工具規格，無需手動定義。
- 自動化流程：框架自動處理工具調用、結果注入和多輪對話管理。
- 代碼簡潔：隱藏底層復雜度，類似 Spring Data JPA 的 Repository 接口。
適用場景：
- 快速構建標準化工具（如內部業務 API）
- 需要與 Spring Boot 集成的項目
接下來我會逐一和大家介紹這兩種方案。
三、Low-Level
下面我們通過一個完整的天氣查詢案例，展示如何在 LangChain4j 中手動構造ToolSpecification并實現工具調用流程。
3.1 定義工具規格
3.1.1 手動定義
// 步驟1：手動構建天氣查詢工具規格
ToolSpecification weatherTool = ToolSpecification.builder()
.name("getWeather")
.description("返回指定城市明日天氣預報，當用戶詢問未來24小時天氣時調用")
.parameters(JsonObjectSchema.builder()
.addStringProperty("city", "需要查詢的城市名稱，如北京、London")
.addEnumProperty("unit", List.of("CELSIUS", "FAHRENHEIT"), "溫度單位，默認使用CELSIUS")
.required("city") // 顯式聲明必填參數
.build())
.build();
List<ToolSpecification> toolSpecifications = List.of(weatherTool);關鍵設計原則：
- 命名規范：getWeather采用動詞+名詞結構，明確功能定位
- 描述清晰：包含觸發條件（"當用戶詢問未來 24 小時天氣時調用"）
- 參數約束：
- 城市參數添加示例值增強可理解性
- 溫度單位使用枚舉類型約束取值范圍
- 通過 required() 顯式標記必填參數
3.1.2 注解定義
也可以利用注解工具自動定義這個規格，如下：
class WeatherTools {
@Tool("返回指定城市明日天氣預報，當用戶詢問未來24小時天氣時調用")
String getWeather(@P("需要查詢的城市名稱，如北京、London") String city, String temperatureUnit) {
return "2025-03-16深圳天氣：多云轉晴，氣溫18-25°C，濕度65%";
}
}
List<ToolSpecification> toolSpecifications = ToolSpecifications.toolSpecificationsFrom(WeatherTools.class);3.2 完整交互
步驟1：初始請求構建
// 步驟1：構造初始聊天請求
ChatRequest request = ChatRequest.builder()
.messages(UserMessage.from("2025年3月16日深圳的天氣如何？"))
.toolSpecifications(toolSpecifications)
.build();
// 發送請求并獲取響應
ChatResponse response = model.chat(request);
AiMessage aiMessage = response.aiMessage();此時若模型判斷需要調用工具，aiMessage.toolExecutionRequests()將包含：
{
"name": "getWeather",
"arguments": {"city": "深圳", "unit": "CELSIUS"}
}步驟2：工具執行與結果反饋
// 步驟2：執行工具邏輯（模擬實現）
if (aiMessage.hasToolExecutionRequests()) {
ToolExecutionRequest request = aiMessage.toolExecutionRequests().get(0);
Map<String, Object> args = parseJson(request.arguments());
// 模擬工具執行（實際應調用外部API）
String result = "2025-03-16深圳天氣：多云轉晴，氣溫18-25°C，濕度65%";
// 構造結果消息
ToolExecutionResultMessage resultMsg = ToolExecutionResultMessage.from(request, result);
// 構建二次請求
ChatRequest followupRequest = ChatRequest.builder()
.messages(List.of(
UserMessage.from("2025年3月16日深圳的天氣如何？"),
aiMessage,
resultMsg
))
.toolSpecifications(toolSpecifications)
.build();
// 獲取最終響應
ChatResponse finalResponse = model.chat(followupRequest);
System.out.println(finalResponse.aiMessage().text());
// 輸出："2025年3月16日深圳將有多云轉晴天氣，溫度范圍18-25攝氏度"
}3.3 技術要點
3.3.1 參數結構
JsonObjectSchema.builder()
.addStringProperty("city", "城市中文或英文名稱，如'New York'需轉換為'紐約'")
.addEnumProperty("unit", List.of("CELSIUS", "FAHRENHEIT"),
"單位轉換需求，如用戶特別說明華氏度時使用")
.build()- 類型校驗：通過addStringProperty/addEnumProperty確保參數合法性
- 語義增強：在描述中補充數據轉換規則（如英文城市名轉中文）
3.3.2 異常處理機制
try {
// 工具執行邏輯
} catch (InvalidCityException e) {
return ToolExecutionResultMessage.error(request, "城市名稱無效: " + e.getMessage());
} catch (ApiTimeoutException e) {
return ToolExecutionResultMessage.error(request, "天氣接口響應超時");
}- 錯誤碼規范：定義業務異常類型輔助模型理解
- 錯誤信息結構化：通過error()方法返回標準錯誤格式
3.3.3 多工具協作模式
// 添加多個工具規格
ToolSpecification airQualityTool = ToolSpecification.builder()
.name("getAirQuality")
.description("獲取城市空氣質量指數，當用戶詢問 PM2.5 或空氣質量時調用")
.parameters(/* 參數定義 */)
.build();
List<ToolSpecification> tools = List.of(weatherTool, airQualityTool);- 工具組合策略：天氣與空氣質量工具形成互補
- 調用優先級：通過描述中的觸發條件引導模型選擇
四、High-Level
4.1 核心機制
@Tool 注解驅動開發，主要是通過 Java 注解自動生成工具規格，無需手動定義 JSON Schema。
@Tool("計算兩個數之和")
public double add(@P("第一個數") int a,
@P(value = "第二個數", required = false) Integer b) {
return a + (b != null ? b : 0);
}自動生成效果：
{
"name": "add",
"description": "計算兩個數之和",
"parameters": {
"type": "object",
"properties": {
"a": {"type": "integer", "description": "第一個數"},
"b": {"type": "integer", "description": "第二個數"}
},
"required": ["a"]
}
}4.2 交互時序
4.3 代碼實踐
來看個具體的代碼案例吧，也是官方給的案例：
public class CalculatorDemo01 {
staticclass Calculator {
@Tool("計算字符串的長度")
int stringLength(String s) {
System.out.println("計算字符串的長度 s='" + s + "'");
return s.length();
}
@Tool("計算兩個數的和")
int add(int a, int b) {
System.out.println("計算兩個數的和 a=" + a + ", b=" + b);
return a + b;
}
@Tool("計算一個數的平方根")
double sqrt(int x) {
System.out.println("計算一個數的平方根 x=" + x);
return Math.sqrt(x);
}
}
public static void main(String[] args) {
ChatLanguageModel model = ZhipuAiChatModel.builder()
.apiKey(API_KEY)
.model("glm-4")
.temperature(0.6)
.maxToken(1024)
.maxRetries(1)
.callTimeout(Duration.ofSeconds(60))
.connectTimeout(Duration.ofSeconds(60))
.writeTimeout(Duration.ofSeconds(60))
.readTimeout(Duration.ofSeconds(60))
.build();
Assistant assistant = AiServices.builder(Assistant.class)
.chatLanguageModel(model)
.tools(new Calculator())
.chatMemory(MessageWindowChatMemory.withMaxMessages(10))
.build();
String question = "字符串 \"hello\" 和 \"world\" 長度總和的平方根是多少?";
String answer = assistant.chat(question);
System.out.println(answer);
}
}來看下執行結果：
圖片
上面代碼比較簡單，就不啰嗦解釋了。
注意，在 @Tool 注解中，包含觸發條件和數據來源。
4.4 注意事項
4.4.1 參數類型支持矩陣
參數類型 | 支持情況 | 示例 |
基本類型 | 完全支持（int, double） |
|
集合類型 | List/Set/Map |
|
嵌套POJO | 支持遞歸結構 |
|
枚舉 | 自動識別取值范圍 |
|
復雜參數處理：
@Description("用戶查詢條件")
class Query {
@Description("篩選狀態：ACTIVE/INACTIVE")
Status status;
@Description("返回結果數量限制")
@P(required = false)
Integer limit;
}
@Tool("查找用戶")
List<User> findUsers(Query query) { ... }4.4.2 動態工具配置
根據上下文動態加載工具。舉個例子。
下面是一個使用 ToolProvider 實現動態工具加載的完整示例，該示例模擬酒店預訂場景，根據用戶消息內容動態選擇工具：
場景描述
- 當用戶消息包含 "預定" 關鍵詞時，動態加載 預定查詢工具
- 當用戶消息包含 "天氣" 關鍵詞時，動態加載 天氣查詢工具
- 其他情況不加載任何工具
工具定義
// 預定查詢工具（靜態定義）
publicclass BookingTools {
@Tool("根據預定號查詢預定詳情，預定號格式為B-后接5位數字")
public String getBookingDetails(
@P("預定號，例如B-12345") String bookingNumber) {
// 模擬數據庫查詢
return"預定號: " + bookingNumber + ", 狀態: 已確認, 房型: 豪華套房";
}
}
publicclass WeatherTools {
@Tool("返回指定城市明日天氣預報，當用戶詢問未來24小時天氣時調用")
String getWeather(@P("需要查詢的城市名稱，如北京、London") String city, String temperatureUnit) {
return"2025-03-16深圳天氣：多云轉晴，氣溫18-25°C，濕度65%";
}
public static ToolExecutor getWeatherExecutor() {
return (request, memoryId) -> {
return"2023-10-15 天氣: 晴, 溫度20-25°C ";
};
}
}動態工具提供者
public class DynamicToolProvider implements ToolProvider {
@Override
public ToolProviderResult provideTools(ToolProviderRequest request) {
String userMessage = request.userMessage().singleText().toLowerCase();
Map<ToolSpecification, ToolExecutor> tools = new HashMap<>();
// 預定相關工具
if (userMessage.contains("預定")) {
// 通過反射獲取@Tool注解的方法規格
ToolSpecification bookingSpec = null;
try {
bookingSpec = ToolSpecifications.toolSpecificationFrom(
BookingTools.class.getDeclaredMethod("getBookingDetails", String.class)
);
} catch (NoSuchMethodException e) {
thrownew RuntimeException(e);
}
// 方法引用執行器
ToolExecutor bookingExecutor = (req, memId) -> {
return"bookingExecutor";
};
tools.put(bookingSpec, bookingExecutor);
}
// 天氣相關工具
if (userMessage.contains("天氣")) {
tools.put(
ToolSpecifications.toolSpecificationsFrom(WeatherTools.class).get(0),
WeatherTools.getWeatherExecutor()
);
}
return ToolProviderResult.builder()
.addAll(tools)
.build();
}
}AI 服務配置與使用
public class Demo01 {
// 1. 定義AI服務接口
interface TravelAssistant {
Result<String> handleRequest(String userMessage);
}
// 2. 配置AI服務
TravelAssistant assistant = AiServices.builder(TravelAssistant.class)
.chatLanguageModel(createOpenAiModel()) // 創建模型實例
.toolProvider(new DynamicToolProvider())
.build();
private ChatLanguageModel createOpenAiModel() {
ChatLanguageModel chatModel = ZhipuAiChatModel.builder()
.apiKey(API_KEY)
.model("glm-4")
.temperature(0.6)
.maxToken(1024)
.maxRetries(1)
.callTimeout(Duration.ofSeconds(60))
.connectTimeout(Duration.ofSeconds(60))
.writeTimeout(Duration.ofSeconds(60))
.readTimeout(Duration.ofSeconds(60))
.build();
return chatModel;
}
// 3. 測試不同場景
public static void main(String[] args) {
Demo01 demo01 = new Demo01();
// 案例1: 預定查詢
demo01.testRequest("我的預定號B-12345的狀態是什么？");
// 案例2: 天氣查詢
demo01.testRequest("今天巴黎的天氣如何？");
// 案例3: 普通咨詢
demo01.testRequest("酒店的早餐時間是幾點？");
}
private void testRequest(String message) {
Result<String> result = assistant.handleRequest(message);
System.out.println("用戶問題: " + message);
System.out.println("最終回答: " + result.content());
result.toolExecutions().forEach(exec ->
System.out.println("調用工具: " + exec.request().name() + ", 參數: " + exec.request().arguments())
);
System.out.println("-------------------");
}
}執行結果輸出
用戶問題: 我的預定號B-12345的狀態是什么？
最終回答: 根據查詢結果，您的預定號B-12345的狀態是bookingExecutor。如果您需要更詳細的預定詳情，請提供更多信息，我將盡力幫助您。
調用工具: getBookingDetails, 參數: {"arg0":"B-12345"}
-------------------
用戶問題: 今天巴黎的天氣如何？
最終回答: 根據我獲取的信息，巴黎今天的天氣是晴天，溫度在20-25°C之間。
調用工具: getWeather, 參數: {"arg0":"Paris","arg1":"today"}
-------------------
用戶問題: 酒店的早餐時間是幾點？
最終回答: 酒店的早餐時間通常根據酒店的規定而有所不同，但一般而言，大多數酒店的早餐時間可能在以下范圍內：
- 早上6:00至上午10:00
- 早上7:00至上午11:00
有些酒店可能提供更早或更晚的早餐服務，以適應不同客人的需求。如果您正在計劃前往某家酒店并想了解具體的早餐時間，建議您直接聯系酒店的前臺或查看官方網站上的信息，以獲取最準確的時間安排。
-------------------4.4.3 執行結果追蹤
獲取工具執行記錄：
Result<String> result = assistant.chat("查看訂單123狀態");
List<ToolExecution> executions = result.toolExecutions();
executions.forEach(exec -> {
System.out.println("調用工具: " + exec.request().name());
System.out.println("參數: " + exec.request().arguments());
System.out.println("結果: " + exec.result());
});4.4.4 異常處理
結構化錯誤反饋：
@Tool
String getStockPrice(String symbol) {
try {
return apiClient.fetchPrice(symbol);
} catch (InvalidSymbolException e) {
throw new ToolExecutionException("STOCK_SYMBOL_INVALID", e.getMessage());
}
}錯誤類型定義：
class ToolExecutionException extends RuntimeException {
private String errorCode;
public ToolExecutionException(String code, String message) {
super(message);
this.errorCode = code;
}
// Getters
}4.4.5 性能優化
緩存機制：
@Tool("查詢城市信息")
@Cacheable(value = "cityCache", key = "#cityName")
public CityInfo getCityInfo(String cityName) { ... }批量處理：
@Tool("批量查詢溫度")
public Map<String, Double> batchGetTemperatures(List<String> cities) { ... }4.5 VS REST API
維度 | 傳統REST API | LangChain4j工具API |
接口定義 | Swagger/OpenAPI | Java注解自動生成 |
參數校驗 | 手動實現 | 自動類型轉換+JSON Schema |
調用方式 | 顯式HTTP調用 | LLM動態決策調用 |
錯誤處理 | HTTP狀態碼 | 結構化異常消息反饋 |
協議耦合 | 強依賴HTTP | 與協議解耦 |
通過高階API，開發者可以快速將現有業務能力轉化為大語言模型可用的工具，顯著提升開發效率。結合動態工具配置和結果追蹤功能，能夠構建出高度智能化的對話系統。最新實踐顯示，采用該模式可使工具集成開發時間縮短約 60%。
五、方案對比
維度 | 低階API | 高階API |
靈活性 | 高（完全自定義） | 中（依賴框架自動生成邏輯） |
開發效率 | 低（需手動處理所有細節） | 高（注解驅動，減少重復代碼） |
適用階段 | 探索性開發、復雜集成 | 成熟業務場景、標準化工具 |
學習成本 | 高（需掌握 JSON Schema 等細節） | 低（通過注解簡化） |
六、最佳實踐
- 優先使用高階API快速驗證功能
- 需深度定制時切換至低階API
責任編輯：武曉燕
來源：
江南一點雨
