LangChain4j实战：构建Java智能代理系统

1. LangChain4j实战项目概述

最近在Java生态中探索AI应用开发时，发现LangChain4j这个框架特别适合构建智能代理(Agent)系统。作为一个专为Java设计的AI集成框架，它让开发者能够轻松地将大语言模型(LLM)能力整合到现有Java应用中。今天我就来分享一个完整的Agent应用搭建过程，从环境准备到核心功能实现，手把手带你走通全流程。

这个实战项目适合以下人群：

• 有Java基础想切入AI开发的工程师
• 需要快速构建企业级AI代理的团队
• 希望了解LangChain4j核心特性的技术决策者

我们将构建一个具备对话记忆、工具调用和复杂推理能力的智能代理，最终实现的效果包括：

• 多轮对话上下文保持
• 外部API工具集成
• 自动化任务分解与执行
• 结构化数据提取

2. 环境准备与项目初始化

2.1 基础环境配置

首先确保你的开发环境满足以下要求：

• JDK 17或更高版本（LangChain4j需要Java模块系统支持）
• Maven 3.8+或Gradle 7.x
• 可用的LLM API访问权限（推荐OpenAI或本地部署的Ollama）

创建Maven项目时，需要添加LangChain4j核心依赖：

xml复制<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j</artifactId>
    <version>0.25.0</version>
</dependency>

根据你要集成的LLM服务，选择对应的适配器依赖。以OpenAI为例：

xml复制<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai</artifactId>
    <version>0.25.0</version>
</dependency>

2.2 配置LLM连接

在application.properties或yaml中配置API密钥和模型参数：

yaml复制langchain4j.open-ai.chat-model.api-key=${OPENAI_API_KEY}
langchain4j.open-ai.chat-model.model-name=gpt-3.5-turbo
langchain4j.open-ai.chat-model.temperature=0.7
langchain4j.open-ai.chat-model.max-tokens=500

提示：生产环境建议通过环境变量注入敏感信息，不要硬编码在配置文件中

3. 核心Agent架构设计

3.1 Agent基础组件

LangChain4j的Agent由以下几个核心部分组成：

1. ChatModel - 底层的大语言模型实例
2. Memory - 对话状态和上下文存储器
3. Tools - 代理可调用的外部能力
4. Orchestrator - 控制流程的执行引擎

典型的初始化代码如下：

java复制OpenAiChatModel chatModel = OpenAiChatModel.builder()
    .apiKey(apiKey)
    .modelName("gpt-4")
    .build();

ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10);

Agent agent = Agent.builder()
    .chatModel(chatModel)
    .chatMemory(memory)
    .tools(new CalculatorTool(), new WeatherTool())
    .build();

3.2 工具(Tool)开发指南

工具是Agent扩展能力的关键。创建一个工具需要：

1. 定义工具接口
2. 实现具体功能
3. 添加描述注解

示例：开发一个查询股票价格的工具

java复制interface StockService {
    @Tool("获取指定股票的当前价格")
    double getStockPrice(@P("股票代码，例如：AAPL") String symbol);
}

class YahooFinanceStockService implements StockService {
    @Override
    public double getStockPrice(String symbol) {
        // 实现实际的API调用逻辑
        return yahooFinanceClient.getQuote(symbol).getPrice();
    }
}

注意事项：工具方法必须包含清晰的@Tool和@P注解，这些描述会被LLM用来理解工具用途

4. 高级功能实现

4.1 对话记忆管理

有效的记忆管理是多轮对话的基础。LangChain4j提供了多种记忆实现：

java复制// 基于窗口的记忆（保留最近N条消息）
ChatMemory memory = MessageWindowChatMemory.withMaxMessages(10);

// 基于Token计数的记忆
ChatMemory memory = TokenWindowChatMemory.withMaxTokens(1000, new OpenAiTokenizer());

// 持久化记忆（需要集成外部存储）
ChatMemory memory = PersistentChatMemory.builder()
    .store(redisChatMemoryStore)
    .build();

记忆的常见使用模式：

java复制String sessionId = "user123";
memory.add(sessionId, UserMessage.userMessage("我想订北京到上海的机票"));
AgentResponse response = agent.execute(sessionId, memory);
memory.add(sessionId, AiMessage.aiMessage(response.text()));

4.2 复杂任务分解

Agent的核心能力是将复杂任务分解为可执行的子任务。通过Chain of Thought提示工程技术，我们可以实现这一过程：

java复制String prompt = """
    你是一个旅行规划助手。用户说：{{message}}
    请按以下步骤处理：
    1. 识别用户意图
    2. 提取关键参数（时间、地点、预算等）
    3. 规划需要调用的工具序列
    4. 执行并汇总结果
    """;

Agent agent = Agent.builder()
    .promptTemplate(prompt)
    // ...其他配置
    .build();

5. 生产环境注意事项

5.1 性能优化技巧

1. 批量处理：对多个用户请求进行批量化处理

   java复制List<AgentResponse> responses = agent.batchExecute(requests);
   

2. 缓存策略：对工具调用结果进行缓存

   java复制agent = agent.withToolCache(Caffeine.newBuilder()
       .maximumSize(1000)
       .expireAfterWrite(5, TimeUnit.MINUTES)
       .build());
   

3. 流式响应：处理长耗时任务时提供渐进式反馈

   java复制agent.streamingExecute(request, new StreamingResponseHandler() {
       @Override
       public void onNext(String token) {
           // 处理流式token
       }
   });
   

5.2 监控与调试

集成OpenTelemetry进行分布式追踪：

xml复制<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-opentelemetry</artifactId>
    <version>0.25.0</version>
</dependency>

配置追踪器：

java复制OpenTelemetry openTelemetry = // 初始化OpenTelemetry
Agent agent = Agent.builder()
    .tracer(new OpenTelemetryTracer(openTelemetry))
    .build();

6. 完整示例：客服Agent实现

下面是一个电商客服Agent的完整实现：

java复制public class CustomerServiceAgent {
    
    private final Agent agent;
    
    public CustomerServiceAgent() {
        ChatModel chatModel = OpenAiChatModel.withApiKey(apiKey);
        
        ChatMemory memory = PersistentChatMemory.builder()
            .store(new RedisChatMemoryStore())
            .maxMessages(20)
            .build();
            
        List<Tool> tools = Arrays.asList(
            new OrderLookupTool(),
            new RefundTool(),
            new ProductCatalogTool()
        );
        
        this.agent = Agent.builder()
            .chatModel(chatModel)
            .chatMemory(memory)
            .tools(tools)
            .promptTemplate(new CustomerServicePrompt())
            .build();
    }
    
    public String handleRequest(String sessionId, String userInput) {
        memory.add(sessionId, UserMessage.userMessage(userInput));
        AgentResponse response = agent.execute(sessionId, memory);
        memory.add(sessionId, AiMessage.aiMessage(response.text()));
        return response.text();
    }
}

关键组件说明：

• OrderLookupTool：查询订单状态的工具
• RefundTool：处理退款申请的工具
• ProductCatalogTool：商品信息查询工具
• CustomerServicePrompt：包含客服专用指令的提示模板

7. 常见问题排查

7.1 工具调用失败

症状：Agent无法正确识别或调用工具

解决方案：

1. 检查工具方法的@Tool注解描述是否清晰
2. 验证工具方法参数是否有@P注解描述
3. 测试工具方法能否独立运行

7.2 记忆丢失问题

症状：对话上下文无法保持

解决方案：

1. 检查记忆存储是否配置正确
2. 确保每次交互使用相同的sessionId
3. 验证记忆存储后端（如Redis）是否可用

7.3 响应质量下降

症状：Agent回答变得不相关或不准确

解决方案：

1. 调整提示工程模板
2. 检查记忆窗口大小是否合适
3. 监控LLM API的速率限制和配额

在实际项目中，我发现合理设置temperature参数对结果质量影响很大。对于需要确定答案的任务，建议设置为0.3-0.5；对于创意性任务，可以提高到0.7-1.0。同时，及时清理记忆中的无关信息也能显著提升长期对话的稳定性。