🌐 LangChain4j AI Agent 开发实战指南（Java 工程师专属 · 从零到生产）

文档定位：面向有 Java 基础的开发者，聚焦 AI Agent 核心开发流程，拒绝“玩具级 demo”，提供可落地的工程化方案
技术栈：LangChain4j 0.28.0 + Spring Boot 3.2 + OpenAI API（兼容国产模型）
核心理念：Agent = Tools（工具） + Reasoning（推理） + Memory（记忆） + Action（执行）

---

📌 一、为什么选择 LangChain4j？（vs Python 版）

维度	LangChain4j (Java)	LangChain (Python)	Java 工程师优势
工程化	✅ 强类型、编译检查、IDE 深度支持	⚠️ 动态类型、运行时错误多	重构安全、大型项目可控
生态整合	✅ 无缝对接 Spring Boot/Cloud	⚠️ 需额外胶水代码	企业级微服务天然适配
部署运维	✅ JVM 生态（监控/链路追踪）	⚠️ 需容器化隔离	与现有 Java 系统零摩擦
性能	✅ 异步非阻塞（Project Reactor）	⚠️ GIL 限制	高并发场景优势显著

💡 关键认知：
LangChain4j 不是 LangChain 的简单移植，而是为 JVM 生态深度重构的 AI 应用框架

---

🛠️ 二、环境准备（5 分钟快速启动）

1. Maven 依赖（pom.xml）

<properties>
    <langchain4j.version>0.28.0</langchain4j.version>
    <spring.boot.version>3.2.5</spring.boot.version>
</properties>

<dependencies>
    <!-- 核心框架 -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j</artifactId>
        <version>${langchain4j.version}</version>
    </dependency>
    
    <!-- OpenAI 模型（替换为国产模型见第7节） -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-open-ai</artifactId>
        <version>${langchain4j.version}</version>
    </dependency>
    
    <!-- Spring Boot 集成（生产必备） -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-spring-boot-starter</artifactId>
        <version>${langchain4j.version}</version>
    </dependency>
    
    <!-- 内存存储（生产替换为 Redis） -->
    <dependency>
        <groupId>dev.langchain4j</groupId>
        <artifactId>langchain4j-core</artifactId>
        <version>${langchain4j.version}</version>
    </dependency>
    
    <!-- 工具类：JSON 处理 -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
    </dependency>
</dependencies>

2. 配置文件（application.yml）

langchain4j:
  openai:
    api-key: ${OPENAI_API_KEY} # 环境变量注入（安全！）
    base-url: https://api.openai.com/v1
    chat-model:
      model-name: "gpt-4o-mini" # 生产建议：gpt-4o / 国产模型
      temperature: 0.3
      max-tokens: 1000
  # 内存对话存储（生产替换为 RedisStore）
  store:
    type: in-memory

🔒 安全提示：

• 严禁将 API Key 写入代码！使用环境变量/配置中心
• 生产环境建议：API 网关限流 + 模型调用审计日志

---

🧠 三、核心概念速览（Agent 开发基石）

概念	LangChain4j 实现	作用	代码类比
Model	ChatLanguageModel	大模型客户端	RestTemplate
Prompt	PromptTemplate	指令模板	@Query 注解
Tool	@Tool 注解方法	Agent 可调用能力	@Service 方法
Memory	ChatMemory	对话历史管理	HttpSession
Agent	AiService / AgentExecutor	智能体核心	@Controller
Chain	Chain 接口	工作流编排	Stream 流水线

---

💡 四、实战 Demo：智能客服 Agent（完整可运行）

场景需求

开发一个电商客服 Agent，支持：
✅ 查询订单状态（调用内部 API）
✅ 计算优惠（数学工具）
✅ 记忆用户偏好（对话历史）
✅ 拒绝敏感问题（安全护栏）

步骤 1：定义 Tools（工具层）

import dev.langchain4j.service.tool.Tool;
import org.springframework.stereotype.Component;

import java.util.HashMap;
import java.util.Map;

@Component
public class CustomerServiceTools {
    
    // 模拟订单数据库（生产替换为 FeignClient）
    private final Map<String, Map<String, Object>> orders = new HashMap<>() {{
        put("ORD1001", Map.of("status", "已发货", "amount", 299.0));
        put("ORD1002", Map.of("status", "待支付", "amount", 89.5));
    }};
    
    @Tool("查询订单状态，参数：订单号（如 ORD1001）")
    public String checkOrderStatus(String orderId) {
        if (!orders.containsKey(orderId)) {
            return "订单号不存在，请确认后重试";
        }
        Map<String, Object> order = orders.get(orderId);
        return String.format("订单 %s 状态：%s，金额：%.2f元", 
            orderId, order.get("status"), order.get("amount"));
    }
    
    @Tool("计算订单优惠后价格，参数：原价, 折扣率（0-1）")
    public String calculateDiscount(double originalPrice, double discountRate) {
        if (discountRate < 0 || discountRate > 1) {
            return "折扣率必须在0-1之间";
        }
        double finalPrice = originalPrice * discountRate;
        return String.format("原价 %.2f元，%.0f折后价格：%.2f元", 
            originalPrice, discountRate * 10, finalPrice);
    }
    
    @Tool("安全审核：检测用户问题是否含敏感词（政治/辱骂等）")
    public boolean isQuestionSafe(String question) {
        String[] sensitiveWords = {"政治", "骂人", "违法"};
        for (String word : sensitiveWords) {
            if (question.contains(word)) {
                return false;
            }
        }
        return true;
    }
}

步骤 2：构建 Agent（智能体层）

import dev.langchain4j.memory.chat.MessageWindowChatMemory;
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.service.AiServices;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.V;
import org.springframework.stereotype.Service;

@Service
public class CustomerServiceAgent {
    
    private final AiService agent;
    
    // 依赖注入（Spring 管理）
    public CustomerServiceAgent(
            ChatLanguageModel model,
            CustomerServiceTools tools) {
        
        // 创建带记忆的 Agent
        this.agent = AiServices.builder(AiService.class)
                .chatLanguageModel(model)
                .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) // 保留最近10轮对话
                .tools(tools) // 注入工具
                .systemMessageProvider(userId -> 
                    "你是一名专业电商客服「小福」，语气亲切。" +
                    "规则：1. 仅回答电商相关问题 2. 拒绝敏感问题 3. 用中文简洁回复")
                .build();
    }
    
    // Agent 接口定义（声明式编程）
    public interface AiService {
        @UserMessage("用户问题：{{question}}")
        String chat(@V("question") String question);
    }
    
    // 对外服务方法
    public String handleQuery(String userId, String question) {
        // 安全前置检查（生产建议：独立 Filter）
        if (!new CustomerServiceTools().isQuestionSafe(question)) {
            return "您的问题涉及敏感内容，我无法回答。如有其他购物问题，我很乐意帮助您！";
        }
        return agent.chat(question);
    }
}

步骤 3：Controller 层（REST API）

import org.springframework.web.bind.annotation.*;
import jakarta.servlet.http.HttpSession;

@RestController
@RequestMapping("/api/agent")
public class AgentController {
    
    private final CustomerServiceAgent agent;
    
    public AgentController(CustomerServiceAgent agent) {
        this.agent = agent;
    }
    
    @PostMapping("/chat")
    public String chat(
            @RequestParam String question,
            HttpSession session) {
        
        // 从 Session 获取用户ID（生产替换为 JWT）
        String userId = session.getId();
        
        // 调用 Agent
        return agent.handleQuery(userId, question);
    }
}

步骤 4：启动类（Spring Boot）

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class AgentApplication {
    public static void main(String[] args) {
        SpringApplication.run(AgentApplication.class, args);
        System.out.println("✅ AI Agent 服务已启动！访问: http://localhost:8080/api/agent/chat?question=订单ORD1001状态");
    }
}

---

🌟 五、关键能力深度解析

1. Tool 定义最佳实践

@Tool("查询实时天气，参数：城市名（中文）")
public WeatherResponse getWeather(@ToolArgument("city") String city) {
    // 生产：调用天气 API（带熔断/重试）
    return weatherClient.query(city); 
}

// 复杂参数：使用 DTO（LangChain4j 自动 JSON 序列化）
@Tool("创建订单")
public OrderResponse createOrder(@ToolArgument("order") CreateOrderRequest request) {
    // request 包含：productId, quantity, address...
}

2. 记忆管理（生产级方案）

// 替换内存存储为 Redis（支持分布式）
@Bean
public ChatMemoryStore chatMemoryStore(RedisTemplate<String, Object> redis) {
    return new RedisChatMemoryStore(redis, "agent:memory:");
}

// 按用户隔离记忆
@Bean
public ChatMemory chatMemory(ChatMemoryStore store, @Value("#{userId}") String userId) {
    return MessageWindowChatMemory.builder()
            .id(userId) // 用户ID作为记忆Key
            .maxMessages(20)
            .chatMemoryStore(store)
            .build();
}

3. 安全与审计（企业必备）

// 自定义 Prompt 拦截器
@Component
public class SecurityPromptInterceptor implements PromptInterceptor {
    @Override
    public Prompt transform(Prompt prompt) {
        // 注入安全指令到系统消息
        String safeSystemMessage = prompt.systemMessage() + 
            "\n【安全规则】禁止生成违法/歧视/虚假信息，涉及医疗/金融需声明'请咨询专业人士'";
        return Prompt.from(safeSystemMessage, prompt.userMessage());
    }
}

// 调用审计日志
@Aspect
@Component
public class AgentAuditAspect {
    @AfterReturning(pointcut = "execution(* *.chat(..))", returning = "result")
    public void logAudit(JoinPoint jp, Object result) {
        String question = jp.getArgs()[0].toString();
        log.info("AUDIT|user:{}|question:{}|response:{}", 
            getUserId(), question, result);
    }
}

---

🌍 六、国产模型无缝替换（适配中国场景）

方案 1：通义千问（阿里云）

langchain4j:
  dashscope: # 通义实验室
    api-key: ${DASHSCOPE_API_KEY}
    chat-model:
      model-name: "qwen-max" # qwen-plus / qwen-turbo

// 无需改代码！仅替换配置
@Bean
public ChatLanguageModel chatModel() {
    return DashscopeChatModel.builder()
            .apiKey(apiKey)
            .modelName("qwen-max")
            .build();
}

方案 2：其他模型支持

模型厂商	依赖坐标	配置前缀
讯飞星火	langchain4j-spark	spark
百度文心	langchain4j-ernie	ernie
智谱 GLM	langchain4j-zhipu-ai	zhipu-ai
Ollama 本地	langchain4j-ollama	ollama

💡 统一抽象：所有模型实现 ChatLanguageModel 接口，业务代码零修改切换模型

---

🚀 七、生产环境 Checklist

类别	关键项	工具/方案
安全	API Key 管理	配置中心（Apollo/Nacos）+ KMS
性能	模型调用限流	Resilience4j + Sentinel
可观测	调用链追踪	SkyWalking + MDC 日志
成本	Token 消耗监控	自定义 Metrics（Micrometer）
合规	敏感词过滤	腾讯云内容安全 API
灾备	模型降级策略	本地小模型（TinyLlama）兜底

---

💎 八、总结与进阶路线

核心心法

🔹 Agent 不是“调大模型”，而是“设计工具+约束推理”
🔹 80% 价值来自 Tools 设计，20% 来自 Prompt 优化
🔹 生产环境：安全 > 成本 > 效果

进阶学习路径

推荐资源

• 📚 官方文档：https://docs.langchain4j.dev（必读！）
• 🌐 示例仓库：github.com/langchain4j/langchain4j-examples
• 📰 中文社区：LangChain4j 中文文档（GitHub 搜索）
• 🎥 实战视频：B 站搜索“LangChain4j 企业级实践”

---

最后赠言（来自一线架构师）：
“我曾用 3 天为物流系统开发 Agent：

• Tools：对接 WMS（库存查询）、TMS（运单跟踪）
• 效果：客服人力下降 40%，用户满意度↑25%
  关键不是技术多炫酷，而是精准解决业务痛点。
  从今天起，用 LangChain4j 为你的系统装上‘智能大脑’！”

✅ 立即行动：

git clone https://github.com/langchain4j/langchain4j-examples.git
cd spring-boot-example
mvn spring-boot:run
# 访问 http://localhost:8080/swagger-ui.html 测试你的第一个 Agent！

（注：本文档基于 LangChain4j 0.28.0 编写，API 可能随版本迭代调整，请以官方文档为准。生产环境务必进行安全与性能测试！）