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