Java 使用 LangChain4j 构建 AI 智能体实战

一、大模型与智能体对比

大模型：优势在知识问答和文本生成；劣势在处理实时信息、精确计算或访问个性化工具时存在局限。

智能体可以让大模型调用个性化工具 (智能体 ~= 工具 + 大模型)。例如，大模型可以英文翻译；而智能体可以英文翻译后调用个性化工具/专业工具进行润色，保存到数据库等一系列自主规划、个性化规划的应用。

二、智能体示例

官方文档：

• https://docs.langchain4j.dev/intro/
• https://docs.langchain4j.dev/tutorials/spring-boot-integration/

LangChain4j 实现智能体中：一个 agent 可以包含若干@AiService；一个@AiService 可以包含若干@Tool；一个@Tool 可以包含若干工具类操作，比如 CURD、调用第三方 API、调用 http 接口，与缓存 redis/HDFS 等等交互。

注意：AiService 也可以作为其他 AiService 的@Tool

步骤：

1. 定义工具（Tools）。工具可以是任何东西：网页搜索、外部 API 调用、或执行一段特定代码等。
2. 使用 AiServices 来组装智能体，将工具和模型结合起来。
3. 新建 controller 控制器进行调用返回。

1、定义工具 tools

工具 1：用户 CURD

package com.ai.LangChain4j.agent;
import dev.langchain4j.agent.tool.Tool;
import dev.langchain4j.agent.tool.P;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Component;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;

@Component
public class AiUserTool {
    @Autowired
    private UserService userService;

    // 通过@P 注解为参数添加描述信息
    @Tool("新增用户服务")
    public void addUser(@P("用户名称") String name, @P("用户年龄") String age, @P("用户性别") String sex) {
        User user = new User(null, name, age, sex);
        userService.addUser(user);
    }

    @Tool("根据用户名查询用户完整信息")
    public User findUser(@P("用户名称") String name) {
        return userService.findUser(name);
    }

    @Async
    @Tool("异步查询")
    public CompletableFuture<User> getUserAsync(String userId) {
        return CompletableFuture.supplyAsync(() -> userService.findById(userId));
    }
}

工具 2：翻译

package com.ai.LangChain4j;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.spring.AiService;

@AiService
public interface TranslatorService {
    @SystemMessage("你是一位翻译助手")
    @UserMessage("请将以下句子翻译成英文：{{message}}")
    String chat(String message);
}

工具 3：数值计算

@Component
public class MyCalculatorTool {
    @Tool("用于计算两个数字的加法、减法、乘法和除法")
    public double calculate(double a, double b, String operator) {
        switch (operator) {
            case "+": return a + b;
            case "-": return a - b;
            case "*": return a * b;
            case "/":
                if (b == 0) throw new IllegalArgumentException("除数不能为零");
                return a / b;
            default: throw new IllegalArgumentException("不支持的操作符：" + operator);
        }
    }
}

工具 4：日期格式化

package com.ai.LangChain4j.agent;
import dev.langchain4j.agent.tool.Tool;
import org.springframework.stereotype.Component;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

@Component
public class DateTimeTool {
    @Tool("获取当前时间，返回格式为 yyyy-MM-dd HH:mm:ss")
    public String getCurrentDateTime() {
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
        String time = LocalDateTime.now().format(formatter);
        return time;
    }
}

工具 5：调用第三方 API

package com.ai.LangChain4j.agent;
import org.springframework.stereotype.Component;
import dev.langchain4j.agent.tool.Tool;
import org.springframework.web.client.RestTemplate;
import java.util.Map;

@Component
public class MyWebSearchTool {
    private final RestTemplate restTemplate = new RestTemplate();

    @Tool("在互联网上搜索实时信息，可以调用公开平台的 api 查询信息，例如当前新闻、天气等")
    public String searchWeb(String query) {
        // 为了演示，我们返回一个固定的字符串，实际中应该调用真实的搜索 API
        return "根据搜索查询'" + query + "'，这里是模拟的搜索结果：xxxxxxxxx";
    }
}

2、使用 AiServices 来组装智能体，将工具和模型结合起来

定义一个 AiService：

package com.ai.LangChain4j.agent;
import dev.langchain4j.service.spring.AiService;

@AiService
public interface MyAssistantService {
    String chat(String userMessage);
}

给 AI Service 绑定工具：使用 AiServices 的话，就设置 tools 就行了，之后它的实现类自动管理 tool 的调用。

package com.ai.LangChain4j.agent;
import dev.langchain4j.memory.ChatMemory;
import dev.langchain4j.memory.chat.MessageWindowChatMemory;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import dev.langchain4j.memory.chat.TokenWindowChatMemory;
import java.time.Duration;

@Configuration
public class MyAgentConfiguration {
    // 配置带工具的 AI 服务
    @Bean
    public MyAssistantService assistant(MyCalculatorTool calculatorTool, MyWebSearchTool webSearchTool, AiUserTool aiUserTool, BookingTools bookingTools) {
        ChatMemory chatMemory = MessageWindowChatMemory.withMaxMessages(20);
        return AiServices.builder(MyAssistantService.class)
                .chatModel(OpenAiChatModel.builder()
                        .baseUrl(baseUrl)
                        .apiKey(apiKey)
                        .modelName(modelName)
                        // 使用的模型名称
                        // .maxTokens(1000) // 单次回答的最大 token 数
                        .logRequests(logRequests) // 记录请求日志
                        .logResponses(logResponses) // 记录响应日志
                        .returnThinking(false) // 是否返回 AI 的思考过程
                        // .customHeaders(map)
                        // 超时配置优化
                        .timeout(Duration.ofMinutes(5)) // 长文本处理设置较长超时
                        .temperature(0.1) // 降低随机性，使工具调用更稳定（0-1，越高越随机）
                        .build())
                .tools(calculatorTool, webSearchTool, aiUserTool, bookingTools) // 给 AI Service 绑定工具
                .chatMemory(chatMemory) // 记忆功能概述 记忆对话功能允许 AI 记住之前的对话内容，实现上下文连贯的对话体验。LangChain4j 提供了多种记忆存储方式，包括内存存储、Redis 存储等。
                .build();
    }

    @Value("${langchain4j.open-ai.chat-model.api-key}")
    private String apiKey;

    @Value("${langchain4j.open-ai.chat-model.base-url}")
    private String baseUrl;

    @Value("${langchain4j.open-ai.chat-model.model-name}")
    private String modelName;

    @Value("${langchain4j.open-ai.chat-model.log-requests}")
    private Boolean logRequests;

    @Value("${langchain4j.open-ai.chat-model.log-responses}")
    private Boolean logResponses;
}

3、新建 controller 控制器进行调用返回

package com.ai.LangChain4j.agent;
import com.ai.LangChain4j.CalculatorTool;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.service.AiServices;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/agent")
public class MyAgentController {
    @Autowired
    private MyAssistantService myAssistantService;

    @Autowired
    private ChatModel chatModel;

    /**
     * 定义工具、组装智能体、集成 Spring Boot，并添加记忆功能
     *
     * @param message
     * @return
     */
    @GetMapping("/chat")
    public String assistantchat(String message) {
        return myAssistantService.chat(message);
    }
}

三、AiService 也可以作为其他 AiService 的@Tool

interface RouterAgent {
    @dev.langchain4j.service.UserMessage("""
        Analyze the following user request and categorize it as 'legal', 'medical' or 'technical', then forward the request as it is to the corresponding expert provided as a tool. Finally return the answer that you received from the expert without any modification. The user request is: '{{it}}'.
        """)
    String askToExpert(String request);
}

interface MedicalExpert {
    @dev.langchain4j.service.UserMessage("""
        You are a medical expert. Analyze the following user request under a medical point of view and provide the best possible answer. The user request is {{it}}.
        """)
    @Tool("A medical expert")
    String medicalRequest(String request);
}

interface LegalExpert {
    @dev.langchain4j.service.UserMessage("""
        You are a legal expert. Analyze the following user request under a legal point of view and provide the best possible answer. The user request is {{it}}.
        """)
    @Tool("A legal expert")
    String legalRequest(String request);
}

interface TechnicalExpert {
    @dev.langchain4j.service.UserMessage("""
        You are a technical expert. Analyze the following user request under a technical point of view and provide the best possible answer. The user request is {{it}}.
        """)
    @Tool("A technical expert")
    String technicalRequest(String request);
}

MedicalExpert medicalExpert = AiServices.builder(MedicalExpert.class)
        .chatModel(model)
        .build();
LegalExpert legalExpert = AiServices.builder(LegalExpert.class)
        .chatModel(model)
        .build();
TechnicalExpert technicalExpert = AiServices.builder(TechnicalExpert.class)
        .chatModel(model)
        .build();
RouterAgent routerAgent = AiServices.builder(RouterAgent.class)
        .chatModel(model)
        .tools(medicalExpert, legalExpert, technicalExpert)
        .build();
routerAgent.askToExpert("I broke my leg what should do");

注意：RouterAgent 可以使用 3 个 AiService 作为 tool。 注：agent 不能使用 chat memory

四、访问执行过的 Tools

需要使用 Result：

interface Assistant {
    Result<String> chat(String userMessage);
}
Result<String> result = assistant.chat("Cancel my booking 123-456");
String answer = result.content();
List<ToolExecution> toolExecutions = result.toolExecutions();
ToolExecution toolExecution = toolExecutions.get(0);
ToolExecutionRequest request = toolExecution.request();
String resultText = toolExecution.result(); // tool execution result as text
Object resultObject = toolExecution.resultObject(); // actual value returned by the tool

流式输出场景下：

interface Assistant {
    TokenStream chat(String message);
}
TokenStream tokenStream = assistant.chat("Cancel my booking");
tokenStream
        .onToolExecuted((ToolExecution toolExecution) -> System.out.println(toolExecution))
        .onPartialResponse(...)
        .onCompleteResponse(...)
        .onError(...)
        .start();

五、处理 Tool 异常

1、处理 tool 参数异常

方法一：抛出异常

Assistant assistant = AiServices.builder(Assistant.class)
        .chatModel(chatModel)
        .tools(tools)
        .toolArgumentsErrorHandler((error, errorContext) -> {
            throw MyCustomException(error);
        })
        .build();
try {
    assistant.chat(...);
} catch (MyCustomException e) {
    // handle e
}

方法二：给 LLM 返回一个 text 消息

Assistant assistant = AiServices.builder(Assistant.class)
        .chatModel(chatModel)
        .tools(tools)
        .toolArgumentsErrorHandler((error, errorContext) -> ToolErrorHandlerResult.text("Something is wrong with tool arguments: " + error.getMessage()))
        .build();

2、处理 tool 运行时异常

注：同上，也可以抛出异常或给 LLM 返回一个 text 消息

Assistant assistant = AiServices.builder(Assistant.class)
        .chatModel(chatModel)
        .tools(tools)
        .toolExecutionErrorHandler((error, errorContext) -> ToolErrorHandlerResult.text("Something is wrong with tool execution: " + error.getMessage()))
        .build();