Java 搭建 AI Agent 核心原理与实战落地方案

步骤 2：配置 LLM 与核心组件

在 application.yml 中配置 OpenAI API 密钥（也可替换为通义千问、文心一言的密钥和接口地址）、Redis、MySQL 连接信息：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/order_db?useSSL=false&serverTimezone=UTC
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver
  redis:
    host: localhost
    port: 6379
    password: 
    database: 0
# LangChain4j 配置
langchain4j:
  openai:
    api-key: sk-your-openai-api-key
    model-name: gpt-4o
    temperature: 0.3 # 控制生成内容的确定性，越低越稳定

然后创建 LangChain4j 核心 Bean，用于初始化 LLM 客户端和 Agent 规划器：

import dev.langchain4j.agent.Agent;
import dev.langchain4j.agent.AgentExecutor;
import dev.langchain4j.agent.tool.Tool;
import dev.langchain4j.memory.chat.MessageWindowChatMemory;
import dev.langchain4j.model.openai.OpenAiChatModel;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class LangChain4jConfig {
    // 初始化 OpenAI 聊天模型
    @Bean
    public OpenAiChatModel openAiChatModel() {
        return OpenAiChatModel.builder()
                .apiKey("sk-your-openai-api-key")
                .modelName("gpt-4o")
                .temperature(0.3)
                .build();
    }

    // 初始化 Agent：注入模型、记忆、工具
    @Bean
    public AgentExecutor agentExecutor(OpenAiChatModel openAiChatModel, OrderTool orderTool, ExcelTool excelTool, EmailTool emailTool) {
        return AgentExecutor.builder()
                .agent(Agent.builder()
                        .chatModel(openAiChatModel)
                        .chatMemory(MessageWindowChatMemory.withMaxMessages(10)) // 保存最近 10 条会话信息
                        .tools(orderTool, excelTool, emailTool) // 注册可用工具
                        .build())
                .build();
    }
}

步骤 3：开发核心工具类（Agent 的'手脚'）

工具是 Agent 实现落地能力的关键，我们需要封装 3 个核心工具：订单数据查询工具、Excel 生成工具、邮件发送工具。每个工具都需要用 LangChain4j 的@Tool 注解标记，让 Agent 能识别并调用。

3.1 订单数据查询工具（OrderTool）

import dev.langchain4j.agent.tool.Tool;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;
import java.util.Map;

@Component
public class OrderTool {
    @Autowired
    private JdbcTemplate jdbcTemplate;

    /**
     * 查询指定时间范围内的订单统计数据
     * @param startDate 开始日期（格式：yyyy-MM-dd）
     * @param endDate 结束日期（格式：yyyy-MM-dd）
     * @return 统计数据：总销售额、订单数、Top3 热销商品
     */
    @Tool("查询指定时间范围内的订单统计数据，参数为开始日期和结束日期（格式：yyyy-MM-dd）")
    public Map<String, Object> queryOrderStatistic(String startDate, String endDate) {
        // 1. 查询总销售额和订单数
        String statSql = "SELECT SUM(amount) AS totalSales, COUNT(id) AS orderCount " +
                         "FROM order_table WHERE create_time BETWEEN ? AND ?";
        Map<String, Object> statMap = jdbcTemplate.queryForMap(statSql, startDate, endDate);

        // 2. 查询 Top3 热销商品
        String top3Sql = "SELECT product_name, SUM(sales_num) AS salesNum " +
                         "FROM order_item WHERE order_create_time BETWEEN ? AND ? " +
                         "GROUP BY product_name ORDER BY salesNum DESC LIMIT 3";
        statMap.put("top3Products", jdbcTemplate.queryForList(top3Sql, startDate, endDate));
        return statMap;
    }
}

3.2 Excel 生成工具（ExcelTool）

import com.alibaba.excel.EasyExcel;
import dev.langchain4j.agent.tool.Tool;
import org.springframework.stereotype.Component;
import java.io.File;
import java.util.List;
import java.util.Map;

@Component
public class ExcelTool {
    /**
     * 生成订单统计 Excel 报表
     * @param statData 统计数据（包含总销售额、订单数、Top3 热销商品）
     * @param filePath 生成文件路径（如：D:/order_stat.xlsx）
     * @return 文件路径
     */
    @Tool("生成订单统计 Excel 报表，参数为统计数据和文件保存路径")
    public String generateOrderExcel(Map<String, Object> statData, String filePath) {
        // 构建 Excel 数据列表
        List<Map<String, Object>> excelData = List.of(
            Map.of("统计项", "总销售额", "数值", statData.get("totalSales")),
            Map.of("统计项", "订单数", "数值", statData.get("orderCount")),
            Map.of("统计项", "Top3 热销商品", "数值", statData.get("top3Products"))
        );
        // 生成 Excel
        EasyExcel.write(filePath).sheet("订单统计").doWrite(excelData);
        return "Excel 报表生成成功，路径：" + filePath;
    }
}

3.3 邮件发送工具（EmailTool）

import dev.langchain4j.agent.tool.Tool;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.mail.SimpleMailMessage;
import org.springframework.mail.javamail.JavaMailSender;
import org.springframework.stereotype.Component;

@Component
public class EmailTool {
    @Autowired
    private JavaMailSender mailSender;

    /**
     * 发送邮件（带附件）
     * @param to 收件人邮箱
     * @param subject 邮件主题
     * @param text 邮件内容
     * @param filePath 附件路径（如：D:/order_stat.xlsx）
     * @return 发送结果
     */
    @Tool("发送带附件的邮件，参数为收件人邮箱、主题、内容、附件路径")
    public String sendEmailWithAttachment(String to, String subject, String text, String filePath) {
        try {
            SimpleMailMessage message = new SimpleMailMessage();
            message.setFrom("[email protected]");
            message.setTo(to);
            message.setSubject(subject);
            message.setText(text);
            // 此处简化，实际带附件需使用 MimeMessage
            mailSender.send(message);
            return "邮件发送成功，收件人：" + to;
        } catch (Exception e) {
            return "邮件发送失败：" + e.getMessage();
        }
    }
}

步骤 4：开发控制层，接收用户指令并触发 Agent

import dev.langchain4j.agent.AgentExecutor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/ai-agent")
public class AgentController {
    @Autowired
    private AgentExecutor agentExecutor;

    /**
     * 接收用户自然语言指令，触发 AI Agent 执行任务
     * @param request 包含用户指令的请求体
     * @return Agent 执行结果
     */
    @PostMapping("/execute")
    public String executeTask(@RequestBody AgentRequest request) {
        // 调用 Agent 执行任务，返回结果
        return agentExecutor.execute(request.getInstruction());
    }

    // 内部静态类：请求体封装
    public static class AgentRequest {
        private String instruction; // getter、setter
        public String getInstruction() { return instruction; }
        public void setInstruction(String instruction) { this.instruction = instruction; }
    }
}

步骤 5：测试验证

启动项目后，通过 Postman 发送 POST 请求到 http://localhost:8080/ai-agent/execute，请求体为：

{
  "instruction": "统计 2025 年 5 月 1 日至 5 月 31 日的订单数据，包含总销售额、订单数、Top3 热销商品，生成 Excel 报表保存到 D:/202505_order_stat.xlsx，然后发送到 [email protected] 邮箱，邮件主题为 2025 年 5 月订单统计"
}

正常情况下，Agent 会自动执行以下步骤：

1. 调用 OrderTool 查询指定时间范围的订单数据；
2. 调用 ExcelTool 生成报表；
3. 调用 EmailTool 发送带附件的邮件；
4. 返回执行结果（包含报表路径、邮件发送状态）。

Java AI Agent 的优化技巧（企业级落地关键）

上面的实战案例实现了基础功能，要落地到生产环境，还需要做好以下优化：

1. 指令解析优化：增加参数校验与格式标准化

用户输入的自然语言可能存在歧义（如日期格式不明确），可在工具调用前增加拦截器，对关键参数（如日期、邮箱、文件路径）进行校验，若参数缺失或格式错误，Agent 主动询问用户补充，避免执行失败。

2. 异常处理优化：增加重试机制与降级策略

工具调用可能出现异常（如数据库连接超时、邮件服务不可用），可通过 Spring Retry 实现重试机制；对于非核心工具（如邮件发送），可设置降级策略（如失败后记录日志，后续手动补发），避免单个步骤失败导致整个任务终止。

3. 性能优化：异步执行与任务拆分

对于复杂任务（如多维度数据统计 + 多文件生成），可通过 CompletableFuture 实现异步执行，并行调用多个工具；同时将大任务拆分为小步骤，通过 Redis 记录每个步骤的执行状态，支持断点续跑（如某步骤失败，修复后可从该步骤继续执行，无需重新开始）。

4. 安全优化：工具权限控制与指令过滤

生产环境中，需对 Agent 的工具调用权限进行控制（如普通用户无法调用删除数据的工具）；同时增加指令过滤机制，拒绝恶意指令（如'删除数据库所有数据'），避免安全风险。

总结与展望

用 Java 搭建 AI Agent，核心是借助 LangChain4j 将 LLM 的'规划能力'与 Java 的'企业级落地能力'结合，通过工具封装实现各类业务场景的适配。从实战案例能看出，Java 开发者无需学习全新技术栈，基于现有 Spring 生态就能快速上手。

未来，Java AI Agent 的落地场景会更加丰富：如企业内部的智能运维 Agent（自动排查系统故障）、电商领域的智能客服 Agent（自主处理订单咨询与售后）、金融领域的风险控制 Agent（实时监测交易风险）。