Java智能体AI Agent开发中常见误区与避坑指南

// 错误：直接使用LangChain4j，不知其所以然
@Service
public class BadAgentService {

    @Inject
    ChatLanguageModel model;

    public String chat(String message) {
        // 只会调用API，不理解背后的原理
        return model.generate(message);
        // 问题：Prompt怎么优化？失败怎么办？成本如何控制？
    }
}

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");

        // 理解角色系统：system/user/assistant
        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) {
            // 保留最近的N条消息
            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);
    }
}

// 错误：像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);
        // 问题：脆弱、易错、难以维护
    }
}

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("无法获取响应内容");
    }
}

// 错误：像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";
    }
}

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) {
        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()
                ).exceptionally(e -> {
                    log.error("请求失败: {}", prompt, e);
                    return "默认响应";
                }))
                .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("超时")
                );
    }
}

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;
}

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

/**
 * 学习资源清单
 */
public class LearningResources {

    public static class Frameworks {
        // Java Agent框架
        String langChain4j = "https://docs.langchain4j.dev/";
        String springAI = "https://spring.io/projects/spring-ai";
        String dashscope = "https://github.com/aliyun/dashscope-java-sdk";
    }

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

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

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