Java 智能体开发：3 个常见误区与正确学习路径

✅ 正确示范：先理解底层，再用框架

import com.fasterxml.jackson.databind.ObjectMapper;
import okhttp3.*;
import java.io.IOException;
import java.util.*;

/**
 * LLM 客户端基础实现
 * 理解 LLM 调用的核心原理后再使用框架
 */
public class LLMClient {
    private static final String API_URL = "https://api.openai.com/v1/chat/completions";
    private final String apiKey;
    private final OkHttpClient httpClient;
    private final ObjectMapper objectMapper;

    public LLMClient(String apiKey) {
        this.apiKey = apiKey;
        this.httpClient = new OkHttpClient();
        this.objectMapper = new ObjectMapper();
    }

    /**
     * 基础聊天完成请求
     * 理解参数含义：temperature、max_tokens 等
     */
    public String chat(String userMessage, String systemPrompt) throws IOException {
        // 构建请求体 - 理解消息格式
        Map<String, Object> requestBody = new HashMap<>();
        requestBody.put("model", "gpt-3.5-turbo");

        List<Map<String, String>> messages = new ArrayList<>();
        messages.add(Map.of("role", "system", "content", systemPrompt));
        messages.add(Map.of("role", "user", "content", userMessage));
        requestBody.put("messages", messages);

        // 理解参数作用
        requestBody.put("temperature", 0.7);      // 控制随机性
        requestBody.put("max_tokens", 2000);      // 控制输出长度
        requestBody.put("top_p", 1.0);            // 核采样

        // 发送请求 - 理解 HTTP 通信
        Request request = new Request.Builder()
                .url(API_URL)
                .addHeader("Authorization", "Bearer " + apiKey)
                .addHeader("Content-Type", "application/json")
                .post(RequestBody.create(objectMapper.writeValueAsString(requestBody), MediaType.parse("application/json")))
                .build();

        try (Response response = httpClient.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                throw new IOException("API 调用失败：" + response.code());
            }
            String responseBody = response.body().string();
            return parseResponse(responseBody);
        }
    }

    /**
     * 流式响应 - 理解 Server-Sent Events
     */
    public void chatStream(String userMessage, StreamCallback callback) {
        // 流式请求实现
        // 理解 SSE 协议和流式处理
    }

    private String parseResponse(String responseBody) throws IOException {
        Map<String, Object> response = objectMapper.readValue(responseBody, Map.class);
        List<Map<String, Object>> choices = (List<Map<String, Object>>) response.get("choices");
        Map<String, Object> message = (Map<String, Object>) choices.get(0).get("message");
        return (String) message.get("content");
    }

    @FunctionalInterface
    public interface StreamCallback {
        void onChunk(String chunk);
    }
}

import java.util.*;

/**
 * 记忆管理基础实现
 * 理解 Agent 的记忆机制
 */
public class MemoryManager {
    // 对话历史
    private final List<Map<String, String>> conversationHistory = new ArrayList<>();
    // 长期记忆存储
    private final Map<String, Object> longTermMemory = new HashMap<>();
    // 记忆重要性评估
    private final int maxHistorySize = 50;

    /**
     * 添加消息到历史
     * 理解 Token 限制和上下文窗口管理
     */
    public void addMessage(String role, String content) {
        Map<String, String> message = Map.of("role", role, "content", content);
        conversationHistory.add(message);

        // 管理历史长度 - 滑动窗口策略
        if (conversationHistory.size() > maxHistorySize) {
            int removeCount = conversationHistory.size() - maxHistorySize;
            for (int i = 0; i < removeCount; i++) {
                conversationHistory.remove(0);
            }
        }
    }

    /**
     * 构建上下文 - 理解提示词工程
     */
    public List<Map<String, String>> buildContext(String systemPrompt) {
        List<Map<String, String>> context = new ArrayList<>();
        // 系统提示词
        context.add(Map.of("role", "system", "content", systemPrompt));

        // 添加长期记忆中的关键信息
        String memoryContext = buildMemoryContext();
        if (!memoryContext.isEmpty()) {
            context.add(Map.of("role", "system", "content", "重要背景信息：" + memoryContext));
        }

        // 对话历史
        context.addAll(conversationHistory);
        return context;
    }

    /**
     * 记忆检索 - 理解向量检索原理
     */
    public List<String> retrieveRelevantMemory(String query, int topK) {
        // 简化版：基于关键词匹配
        // 实际应该使用向量相似度检索
        List<String> relevant = new ArrayList<>();
        // TODO: 实现向量检索
        return relevant;
    }

    private String buildMemoryContext() {
        StringBuilder sb = new StringBuilder();
        longTermMemory.forEach((key, value) -> {
            sb.append(key).append(": ").append(value).append("; ");
        });
        return sb.toString();
    }

    public void saveToLongTermMemory(String key, Object value) {
        longTermMemory.put(key, value);
    }
}

1.4 学习路径对比

误区二：忽视 Java 特性，照搬 Python 方案

2.1 误区表现

很多教程和示例都是 Python 写的，Java 开发者容易直接照搬，忽略了 Java 的语言特性和生态差异。

2.2 常见错误对比

2.3 典型错误案例

❌ 错误 1：字符串拼接 JSON

// 错误：像 Python 一样直接拼接字符串
public class BadJsonHandler {
    public String buildPrompt(String name, int age) {
        // Python 风格的字符串格式化
        return "你好 " + name + "，你今年 " + age + " 岁了";
        // 问题：没有类型安全，容易出错
    }

    public String parseResponse(String jsonStr) {
        // 手动解析 JSON
        int start = jsonStr.indexOf("\"content\": \"") + 11;
        int end = jsonStr.indexOf("\"", start);
        return jsonStr.substring(start, end);
        // 问题：脆弱、易错、难以维护
    }
}

✅ 正确 1：使用 Java 类型系统

import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.Builder;
import lombok.Data;
import lombok.extern.slf4j.Slf4j;

/**
 * Java 风格的类型安全实现
 */
@Slf4j
public class GoodJsonHandler {
    private final ObjectMapper objectMapper = new ObjectMapper();

    /**
     * 使用强类型对象
     */
    @Data
    @Builder
    public static class ChatRequest {
        @JsonProperty("model")
        private String model;
        @JsonProperty("messages")
        private List<Message> messages;
        @JsonProperty("temperature")
        private Double temperature;
        @JsonProperty("max_tokens")
        private Integer maxTokens;
    }

    @Data
    @Builder
    public static class Message {
        @JsonProperty("role")
        private String role;
        @JsonProperty("content")
        private String content;
    }

    @Data
    public static class ChatResponse {
        @JsonProperty("id")
        private String id;
        @JsonProperty("choices")
        private List<Choice> choices;
        @JsonProperty("usage")
        private Usage usage;

        @Data
        public static class Choice {
            @JsonProperty("index")
            private Integer index;
            @JsonProperty("message")
            private Message message;
            @JsonProperty("finish_reason")
            private String finishReason;
        }

        @Data
        public static class Usage {
            @JsonProperty("prompt_tokens")
            private Integer promptTokens;
            @JsonProperty("completion_tokens")
            private Integer completionTokens;
            @JsonProperty("total_tokens")
            private Integer totalTokens;
        }
    }
}

/**
 * 使用 Record 模式（Java 16+）
 */
public record UserInfo(String name, int age) {}

/**
 * 类型安全的 Prompt 构建
 */
public String buildPrompt(UserInfo user) {
    return String.format("你好 %s，你今年 %d 岁了", user.name(), user.age());
}

/**
 * 类型安全的 JSON 序列化
 */
public String serializeRequest(ChatRequest request) {
    try {
        return objectMapper.writeValueAsString(request);
    } catch (JsonProcessingException e) {
        log.error("JSON 序列化失败", e);
        throw new RuntimeException("请求构建失败", e);
    }
}

/**
 * 类型安全的 JSON 反序列化
 */
public ChatResponse parseResponse(String jsonStr) {
    try {
        return objectMapper.readValue(jsonStr, ChatResponse.class);
    } catch (JsonProcessingException e) {
        log.error("JSON 反序列化失败：{}", jsonStr, e);
        throw new RuntimeException("响应解析失败", e);
    }
}

/**
 * 使用 Java 的 Optional 处理可能为空的值
 */
public String safeExtractContent(ChatResponse response) {
    return Optional.ofNullable(response)
            .map(ChatResponse::getChoices)
            .filter(choices -> !choices.isEmpty())
            .map(choices -> choices.get(0))
            .map(Choice::getMessage)
            .map(Message::getContent)
            .orElse("无法获取响应内容");
}

❌ 错误 2：同步阻塞调用

// 错误：像 Python 一样同步调用
public class BadAsyncHandler {
    public void handleMultipleRequests(List<String> prompts) {
        for (String prompt : prompts) {
            // 同步调用，阻塞等待
            String response = callLLM(prompt);
            System.out.println(response);
        }
        // 问题：性能差，无法利用 Java 并发优势
    }

    private String callLLM(String prompt) {
        // 同步 HTTP 调用
        return "response";
    }
}

✅ 正确 2：使用 Java 响应式编程

import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import reactor.core.scheduler.Schedulers;
import lombok.extern.slf4j.Slf4j;
import java.util.List;

/**
 * Java 风格的响应式异步处理
 */
@Slf4j
public class GoodAsyncHandler {
    private final LLMClient llmClient;

    public GoodAsyncHandler(LLMClient llmClient) {
        this.llmClient = llmClient;
    }

    /**
     * 使用 Project Reactor 处理并发请求
     */
    public Flux<String> handleMultipleRequestsReactive(List<String> prompts) {
        return Flux.fromIterable(prompts)
                .flatMap(prompt -> Mono.fromCallable(() -> llmClient.chat(prompt, "你是一个助手"))
                        .subscribeOn(Schedulers.boundedElastic())
                        .doOnError(e -> log.error("处理失败：{}", prompt, e))
                        .onErrorReturn("处理失败"))
                .doOnNext(response -> log.info("收到响应"));
    }

    /**
     * 使用 Virtual Thread（Java 21+）
     */
    public void handleMultipleRequestsVirtualThreads(List<String> prompts) throws Exception {
        try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
            List<Future<String>> futures = prompts.stream()
                    .map(prompt -> executor.submit(() -> llmClient.chat(prompt, "你是一个助手")))
                    .toList();
            for (Future<String> future : futures) {
                try {
                    String response = future.get();
                    log.info("响应：{}", response);
                } catch (Exception e) {
                    log.error("获取响应失败", e);
                }
            }
        }
    }

    /**
     * 使用 CompletableFuture（Java 8+）
     */
    public CompletableFuture<List<String>> handleMultipleRequestsAsync(List<String> prompts) {
        List<CompletableFuture<String>> futures = prompts.stream()
                .map(prompt -> CompletableFuture.supplyAsync(() -> llmClient.chat(prompt, "你是一个助手"), Executors.newVirtualThreadPerTaskExecutor()))
                .toList();
        return CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
                .thenApply(v -> futures.stream().map(CompletableFuture::join).toList());
    }

    /**
     * 带限流的并发控制
     */
    public Flux<String> handleWithRateLimit(List<String> prompts, int ratePerSecond) {
        return Flux.fromIterable(prompts)
                .delayElements(Duration.ofMillis(1000 / ratePerSecond))
                .flatMap(prompt -> Mono.fromCallable(() -> llmClient.chat(prompt, "助手"))
                        .timeout(Duration.ofSeconds(30))
                        .retry(2)
                        .onErrorReturn("超时"));
    }
}

2.4 Java vs Python Agent 开发对比

误区三：重功能轻工程，缺乏生产思维

3.1 误区表现

很多开发者只关注 Agent"能不能用"，忽略了生产环境必需的稳定性、可观测性、安全性等工程问题。

3.2 生产级 Agent 要求

3.3 生产级 Agent 实现

import io.micrometer.core.instrument.*;
import io.micrometer.core.instrument.binder.jvm.JvmMemoryMetrics;
import io.micrometer.prometheus.PrometheusConfig;
import io.micrometer.prometheus.PrometheusMeterRegistry;
import lombok.extern.slf4j.Slf4j;
import org.springframework.retry.annotation.Backoff;
import org.springframework.retry.annotation.Retryable;
import org.springframework.stereotype.Component;
import reactor.core.publisher.Mono;
import java.time.Duration;
import java.util.concurrent.*;

/**
 * 生产级 Agent 实现
 * 包含监控、重试、限流、缓存等生产特性
 */
@Slf4j
@Component
public class ProductionAgent {
    // 监控指标
    private final MeterRegistry meterRegistry;
    private final Counter requestCounter;
    private final Counter errorCounter;
    private final Timer responseTimer;
    private final Gauge cacheHitRate;

    // 限流器
    private final RateLimiter rateLimiter;
    // 缓存
    private final Cache<String, String> responseCache;
    // 断路器
    private final CircuitBreaker circuitBreaker;
    private final LLMClient llmClient;

    public ProductionAgent(LLMClient llmClient) {
        this.llmClient = llmClient;

        // 初始化监控
        this.meterRegistry = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);
        this.requestCounter = Counter.builder("agent.requests.total").description("总请求数").register(meterRegistry);
        this.errorCounter = Counter.builder("agent.errors.total").description("错误数").register(meterRegistry);
        this.responseTimer = Timer.builder("agent.response.time").description("响应时间").publishPercentiles(0.5, 0.95, 0.99).register(meterRegistry);

        // 初始化限流
        this.rateLimiter = RateLimiter.create(10.0); // 每秒 10 个请求

        // 初始化缓存
        this.responseCache = Caffeine.newBuilder()
                .maximumSize(1000)
                .expireAfterWrite(Duration.ofMinutes(10))
                .recordStats()
                .build();
        this.cacheHitRate = Gauge.builder("agent.cache.hit.rate", responseCache, cache -> {
            var stats = cache.stats();
            return stats.hitCount() / (double) (stats.hitCount() + stats.missCount());
        }).register(meterRegistry);

        // 初始化断路器
        this.circuitBreaker = CircuitBreaker.ofDefaults("llm-service");
        circuitBreaker.getEventPublisher().onStateTransition(event -> log.info("断路器状态变更：{}", event));
    }

    /**
     * 生产级聊天方法
     * 包含完整的监控、限流、重试、缓存
     */
    @Retryable(value = {LLMException.class}, maxAttempts = 3, backoff = @Backoff(delay = 1000, multiplier = 2))
    public Mono<AgentResponse> chat(AgentRequest request) {
        requestCounter.increment();
        return Mono.fromCallable(() -> {
            // 检查断路器
            if (!circuitBreaker.tryAcquirePermission()) {
                throw new LLMException("服务暂时不可用，请稍后重试");
            }

            // 限流检查
            if (!rateLimiter.tryAcquire(Duration.ofSeconds(5))) {
                throw new LLMException("请求过多，请稍后重试");
            }

            // 检查缓存
            String cacheKey = buildCacheKey(request);
            String cachedResponse = responseCache.getIfPresent(cacheKey);
            if (cachedResponse != null) {
                log.debug("缓存命中：{}", cacheKey);
                return AgentResponse.builder().content(cachedResponse).cached(true).build();
            }

            // 记录开始时间
            long startTime = System.nanoTime();
            Timer.Sample sample = Timer.start(meterRegistry);
            try {
                // 调用 LLM
                String response = llmClient.chat(request.getMessage(), request.getSystemPrompt());

                // 成功时更新断路器
                circuitBreaker.onSuccess(0, TimeUnit.NANOSECONDS);

                // 缓存响应
                if (request.isCacheable()) {
                    responseCache.put(cacheKey, response);
                }

                // 记录指标
                sample.stop(responseTimer);
                log.info("请求成功，耗时：{}ms", TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - startTime));
                return AgentResponse.builder().content(response).cached(false).tokens(estimateTokens(request.getMessage(), response)).build();
            } catch (Exception e) {
                // 失败时记录断路器
                circuitBreaker.onError(0, TimeUnit.NANOSECONDS, e);
                errorCounter.increment();
                log.error("LLM 调用失败", e);
                throw new LLMException("LLM 调用失败", e);
            }
        }).subscribeOn(Schedulers.boundedElastic());
    }

    /**
     * 批量处理优化
     */
    public Flux<AgentResponse> chatBatch(List<AgentRequest> requests) {
        return Flux.fromIterable(requests)
                .flatMap(request -> chat(request).timeout(Duration.ofSeconds(30))
                        .onErrorResume(e -> Mono.just(AgentResponse.builder().content("处理超时或失败").error(e.getMessage()).build())));
    }

    /**
     * 流式响应
     */
    public Flux<String> chatStream(AgentRequest request) {
        requestCounter.increment();
        return Flux.create(sink -> {
            llmClient.chatStream(request.getMessage(), chunk -> {
                sink.next(chunk);
            }, sink::error, sink::complete);
        });
    }

    /**
     * 安全检查 - 过滤敏感信息
     */
    private void sanitizeInput(AgentRequest request) {
        String message = request.getMessage();
        // 检测敏感信息
        if (containsSensitiveInfo(message)) {
            log.warn("检测到敏感信息，已过滤");
            request.setMessage(filterSensitiveInfo(message));
        }
        // 检测注入攻击
        if (detectPromptInjection(message)) {
            log.warn("检测到提示词注入尝试");
            throw new SecurityException("检测到异常输入");
        }
    }

    private String buildCacheKey(AgentRequest request) {
        return request.getSystemPrompt() + ":" + request.getMessage();
    }

    private boolean containsSensitiveInfo(String text) {
        // 简化的敏感信息检测
        return text.matches(".*\\d{15,19}.*") || // 可能是身份证
               text.matches(".*\\d{11}.*");     // 可能是手机号
    }

    private String filterSensitiveInfo(String text) {
        return text.replaceAll("\\d{15,19}", "***").replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2");
    }

    private boolean detectPromptInjection(String text) {
        // 检测常见的提示词注入模式
        String[] injectionPatterns = {"忽略以上指令", "ignore previous instructions", "forget everything", "新的指令"};
        String lowerText = text.toLowerCase();
        for (String pattern : injectionPatterns) {
            if (lowerText.contains(pattern.toLowerCase())) {
                return true;
            }
        }
        return false;
    }

    private int estimateTokens(String input, String output) {
        // 简单估算：约 4 字符=1token
        return (input.length() + output.length()) / 4;
    }

    /**
     * 获取监控指标
     */
    public String getMetrics() {
        return ((PrometheusMeterRegistry) meterRegistry).scrape();
    }
}

import lombok.Builder;
import lombok.Data;

/**
 * Agent 请求数据结构
 */
@Data
@Builder
public class AgentRequest {
    private String message;
    private String systemPrompt;
    @Builder.Default
    private boolean cacheable = true;
    private String userId;
    private String sessionId;
    private Map<String, Object> metadata;
}

import lombok.Builder;
import lombok.Data;

/**
 * Agent 响应数据结构
 */
@Data
@Builder
public class AgentResponse {
    private String content;
    private boolean cached;
    private Integer tokens;
    private String error;
    private Map<String, Object> metadata;
}

3.4 配置管理

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import lombok.Data;

/**
 * Agent 配置管理
 */
@Data
@Configuration
@ConfigurationProperties(prefix = "agent")
public class AgentConfig {
    /**
     * LLM 配置
     */
    private LLMConfig llm = new LLMConfig();

    /**
     * 缓存配置
     */
    private CacheConfig cache = new CacheConfig();

    /**
     * 限流配置
     */
    private RateLimitConfig rateLimit = new RateLimitConfig();

    /**
     * 重试配置
     */
    private RetryConfig retry = new RetryConfig();

    @Data
    public static class LLMConfig {
        private String apiKey;
        private String baseUrl = "https://api.openai.com/v1";
        private String model = "gpt-3.5-turbo";
        private Double temperature = 0.7;
        private Integer maxTokens = 2000;
        private Duration timeout = Duration.ofSeconds(30);
    }

    @Data
    public static class CacheConfig {
        private Integer maxSize = 1000;
        private Duration expireAfterWrite = Duration.ofMinutes(10);
        private Boolean enabled = true;
    }

    @Data
    public static class RateLimitConfig {
        private Double permitsPerSecond = 10.0;
        private Boolean enabled = true;
    }

    @Data
    public static class RetryConfig {
        private Integer maxAttempts = 3;
        private Long delay = 1000L;
        private Double multiplier = 2.0;
    }
}

# application.yml 配置示例
agent:
  llm:
    api-key: ${LLM_API_KEY}
    base-url: https://api.openai.com/v1
    model: gpt-3.5-turbo
    temperature: 0.7
    max-tokens: 2000
    timeout: 30s
  cache:
    max-size: 1000
    expire-after-write: 10m
    enabled: true
  rate-limit:
    permits-per-second: 10
    enabled: true
  retry:
    max-attempts: 3
    delay: 1000
    multiplier: 2.0
# 监控配置
management:
  endpoints:
    web:
      exposure:
        include: health, metrics, prometheus
  metrics:
    export:
      prometheus:
        enabled: true

总结：正确的 Java 智能体学习路径

4.1 学习路线图

第 1 阶段：基础夯实（2-3 周）

• 第 1 周：LLM 基础概念 & API 调用原理、Prompt 工程基础
• 第 2 周：记忆机制实现、工具调用原理
• 第 3 周：Java 特性运用、响应式编程入门

第 2 阶段：框架学习（2-3 周）

• 第 4 周：LangChain4j 框架、Spring AI 框架
• 第 5 周：向量数据库集成、RAG 模式实现
• 第 6 周：Agent 框架对比选型与定制

第 3 阶段：工程实践（3-4 周）

• 第 7 周：监控与可观测性、错误处理与重试
• 第 8 周：性能优化、缓存与限流
• 第 9 周：安全性加固、测试与部署

第 4 阶段：项目实战（4 周+）

• 第 10-13 周：构建完整应用、持续优化迭代

4.2 核心要点总结

4.3 推荐学习资源

/**
 * 学习资源清单
 */
public class LearningResources {
    public static class Frameworks {
        // Java Agent 框架
        public static final String langChain4j = "https://docs.langchain4j.dev/";
        public static final String springAI = "https://spring.io/projects/spring-ai";
        public static final String dashscope = "https://github.com/aliyun/dashscope-java-sdk";
    }

    public static class Tools {
        // 开发工具
        public static final String idea = "IntelliJ IDEA + GitHub Copilot";
        public static final String postman = "Postman - API 调试";
        public static final String wireshark = "Wireshark - 网络抓包";
    }

    public static class Practice {
        // 实践平台
        public static final String openai = "OpenAI API 文档";
        public static final String huggingface = "Hugging Face 模型库";
        public static final String kaggle = "Kaggle 竞赛平台";
    }

    public static class Reading {
        // 推荐阅读
        public static final String[] books = {
            "《Building Agents with LLMs》",
            "《Prompt Engineering Guide》",
            "《Reactive Programming in Java》"
        };
    }
}

结语

Java 智能体开发是一项融合 AI 技术和 Java 工程能力的综合性工作。避免这三大误区，按照科学的学习路径循序渐进，你一定能在 Java + AI 的交叉领域找到自己的位置。

记住：先理解原理，再使用工具；先关注工程，再追求功能；先稳定可靠，再性能优化。