先交代一下背景这个项目不是某个大厂实验室的作品是我们团队在业务里被逼出来的。我们一直在做 Java 后端的 SaaS 业务这两年陆陆续续接了好几个 AI 场景从客服工单自动处理到运营报表的自然语言查询每个场景都绕不开“让模型自己调用工具、自己决定下一步怎么做”这个核心能力。市场上的选择不少但真正能无缝嵌进 Java 25 Spring Boot 4 这套业务技术栈、还支持响应式流式传输的几乎没有。所以最后我们决定自己写一个写完之后发现它完全能沉淀成一个独立框架就开源了。这篇文章不会讲太多高大上的架构理念重点是把我们从立项、设计内核、踩坑到开源发布的真实过程记录下来。适合两类人看一类是想在 Java 生态里搞 AI Agent 却不知道怎么下手的后端工程师另一类是已经在做 Agent 框架、但被响应式编程和模型调用的各种边界问题折磨得够呛的人。希望我踩过的坑能帮你少走一段弯路。1. 为什么非要在 Java 生态里做 Agent 框架一个缺口的观察与决策过程1.1 起项目之前我们面对了什么你可能也遇到过这种状况业务方天天说“接入 AI”但你打开需求一看无非是几件事——让模型根据用户问题决定调用哪个接口、把多轮对话的上下文管好、最后把结果以流式的方式推给前端。这些事在 Python 生态里已经有 LangGraph 或 CrewAI 这样的成熟选择但在 Java 生态里尤其是我们这种以 Spring Boot 为核心、服务已经跑了两三年的团队情况完全不同。我们不是不能用 Python 写个独立服务而是不想为了一个 Agent 场景引入一整套异构技术栈。这个判断基于几个非常现实的理由运维体系不统一。公司内部的服务注册、监控告警、日志采集全都在 Java/Spring 这条链路上Python 服务进生产意味着要把监控链路再铺一套。客户对部署形态有要求。不少客户要求私有化部署他们已有的运维人员只熟悉 Java 应用服务器或者容器编排多一种语言就是多一份交付成本。模型 SDK 大多有 Java 客户端但不少供应商的 Java 客户端并不是响应式风格的。我们需要在自己的框架里统一掉这个差异而不是让业务代码到处适配。团队里能写高质量 Java 的人远比能写 Python 的人多。框架跑在 Java 里后续维护和扩展的阻力最小。说白了选择 Java 不是因为 Java 比 Python 更“适合”做 Agent而是因为 Java 是我们生产环境里唯一合理的落盘点。框架只有落在团队真正用得上、维护得起的地方才有生命力。1.2 为什么没有直接选 LangChain4j 或 Spring AI这个决策我们认真评估过不是拍脑袋。简单说LangChain4j 和 Spring AI 都是优秀的基础工具库但它们解决的是“大模型怎么接进来”的问题而不是“Agent 在生产环境里怎么跑得稳”的问题。我们拉了一张表来对比需求能力维度我们需要的LangChain4j/Spring AI 现状我们的决策流式响应从 Agent 全链路思考、工具执行、输出支持 SSE 流式推送更多是单次模型调用的流式返回自建事件流模型编排控制精确控制工具调用轮数、并行步骤、条件分支提供链式或简单的循环能力复杂分支要手写内核提供 planner 和 executor 接口响应式融合与 Spring WebFlux 的背压、异步调度无缝衔接偏传统 Servlet 阻塞模型用 Reactor 类型做核心原语生产可观测每个 Agent 回合都有事件日志和指标多数要靠外部集成框架里定义标准 AgentEvent私有化部署尽量少的外部中间件依赖部分能力依赖 LangSmith 等服务内置可插拔 tracing 接口我知道你会问自己造轮子不累吗其实我们的想法是累也要控制轮子的半径。我们不做“什么都有”的全家桶只做 Agent 运行时里最刚性、最容易被写坏的那部分循环控制、工具协议、记忆管理、事件流。模型接入、向量数据库这些都定义成 SPI 接口让社区和业务自己去接。所以这个框架的核心依赖非常克制就是 Reactor 和 Spring 的自动配置那一套。1.3 目标定位只解决 Agent 运行时的三个核心问题项目启动前我们开过几次会最后把范围收敛到三件事Agent 循环控制。模型输出结果后框架要决定是继续调用工具还是结束任务每一轮的上下文都要正确传递。工具调用的协议与执行。让模型能够按照我们暴露的 JSON Schema 去调用 Java 方法同时让 Java 开发者可以用注解轻松暴露工具。记忆与上下文管理。自动把多轮对话里的消息压缩、裁剪避免上下文膨胀导致模型行为漂移。这三件事解决好了业务方接入时只需要写自己的工具类和提示词循环和记忆这些脏活全部交给框架。事实证明这三个点也正好是后来社区贡献者最感兴趣的部分。很多人不是不想用 Agent而是不敢写循环控制和记忆压缩怕写错。框架把这两块做成默认能力恰好切中了他们的实际痛点。2. 框架的内核结构响应式执行链、编排器与工具协议2.1 顶层执行模型WebFlux 的入口一路通到 Agent 循环我们的框架对外暴露的第一个核心类叫AgentRuntime它的入口方法是这样的public interface AgentRuntime { FluxAgentEvent stream(AgentRequest request); MonoAgentResult execute(AgentRequest request); }stream方法面向 WebFlux Controller可以直接把事件流桥接成 SSE 响应execute则是把事件流累积成单个结果对象方便同步调用场景。两个入口底层共享同一套执行管道。整个执行链路的核心思想是“一次 Agent 回合就是一个 Reactor 数据流”。我用简化的方式描述一下public FluxAgentEvent stream(AgentRequest request) { return Flux.defer(() - runLoop(request, 0)) .contextWrite(ctx - ctx.put(AGENT_CONTEXT, new ConversationContext())); } private FluxAgentEvent runLoop(AgentRequest request, int round) { return Mono.just(round) .filter(r - r maxRounds.get()) .flatMapMany(r - encodeContext(request)) // 1. 把上下文编码为模型消息 .flatMap(messages - planner.plan(messages)) // 2. 调用模型得到决策 .flatMapMany(plan - dispatchSteps(request, plan)) // 3. 按决策执行工具或结束 .concatWith(Mono.defer(() - runLoop(request, round 1))); }上面这段不是完整代码但你可以看到循环的本质每执行完一轮框架就把新产生的工具结果追加回上下文然后递归进入下一轮。递归在这里是有业务含义的Agent 本来就是多轮决策的过程每一轮依赖上一轮的结果。为了防止递归失控我们有一个LoopGuard组件它同时检查三件事总轮数是否超过maxRounds默认 4 轮可配置最近两轮的工具调用是否完全重复相同工具、相同参数整个上下文是否触达 token 预算红线这三道闸门我们在后面踩坑部分会展开讲现在先记在心理上。2.2 编排器如何把“并行工具调用”和“顺序依赖”统一掉模型在一次决策里可能想同时调用多个工具例如同时查订单状态和查物流轨迹也可能要求“先查库存如果不足再查补货计划”。这两种语义差别很大不能用同一个执行模板硬套。所以我们定义了三种步骤原语SequentialStep按顺序执行前一个工具的结果可以作为后一个工具的参数。ParallelStep并行执行多个工具所有结果同时回收。ConditionalStep根据前置条件表达式决定走哪个分支。在响应式世界里并行天然对应Flux.merge顺序天然对应concatMap。我给大家看一眼编排器的核心调度逻辑FluxAgentEvent dispatchSteps(AgentTask task, Plan plan) { if (plan.steps().isEmpty()) { return Flux.just(AgentEvent.finished(task)); } FluxToolResult results Flux.fromIterable(plan.steps()) .flatMap(step - { if (step instanceof ParallelStep p) { return Flux.fromIterable(p.steps()) .flatMap(s - executor.execute(task.context(), s)) .collectList() .map(list - mergeResults(list)); } return executor.execute(task.context(), step) .concatMap(result - result.isFailure() ? handleFailure(result) : Flux.just(result)); }); return results.map(result - AgentEvent.toolResult(task, result)) .doOnNext(event - task.context().append(event)); }这里有一个关键设计工具结果的回写不是零散完成的而是在一个步骤完成后再统一append到对话上下文。为什么要这样做因为模型对上下文的解读是有顺序依赖的。如果你把并行工具的结果按完成时间先后无序写进上下文模型可能会误判“先返回的就是先发生的”这会让多工具并行场景下的推理质量大幅下降。统一回收再统一写入虽然有一些延迟但保证了上下文里的执行时序与真实世界一致。这一点我们在踩坑部分还会再提。2.3 虚拟线程与响应式并不是二选一聊聊 Java 25 和 Spring Boot 4 在这个项目里的价值。有人说响应式编程和虚拟线程是互斥的我们实践下来并不完全是这样。它们解决的其实是不同层面的问题虚拟线程让阻塞代码变得廉价响应式让 IO 密集管道具备背压控制。两者完全可以分工合作。我们在项目里的具体分工是这样的HTTP 层用 WebFlux面向大量客户端 SSE 连接背压语义天然匹配。Agent 编排层用 Reactor 的Mono/Flux保证工具的并发、顺序、超时控制都符合声明式模型。模型 SDK 调用和一些遗留的 JDBC 组件仍然使用虚拟线程。Java 25 对虚拟线程的支持已经非常成熟我们用它包了一层VirtualThreadExecutor专门处理那些没法改造成响应式的阻塞调用。这里我要特意说明一个细节。很多人以为把Schedulers.parallel()扔给阻塞代码就能完美适配其实不是。响应式管道的线程亲和性非常重要尤其是当你在 WebFlux 的 Netty 线程上执行了阻塞调用整个 EventLoop 线程组会被拖垮。我们的经验是给阻塞模型调用单独配置一个基于虚拟线程的调度器在Schedulers.fromExecutorService包一层然后通过统一工厂获取避免散落在业务代码里的自定义线程池。这一套组合下来既保留了响应式流式返回的优势又大大降低了全部响应式改造的工程量。如果你们团队对响应式没那么熟我建议也可以采用同样的混合策略而不是一上来就要求所有代码都是非阻塞的。3. 工具调用与记忆设计的取舍两种避免“自嗨”的设计约束3.1 工具协议为什么固定在 JSON Schema 而不是走简单反射Agent 框架里最难做的不是循环而是工具协议。模型不了解你的 Java 方法它只知道一段 JSON 文本。如何让模型准确知道你有哪些工具、每个工具参数长什么样以及什么时候不该调用某个工具这是决定框架好不好用的分水岭。我们的做法很简单用注解声明工具运行时自动推导 JSON Schema。AgentTool(name create_ticket, description 创建一条用户工单需要提供用户ID和问题描述) public ToolResult createTicket( ToolParam(description 用户唯一标识) String userId, ToolParam(description 问题描述不超过500字) String message) { return ticketService.create(userId, message); }框架在扫描到这个注解后会生成类似这样的 JSON Schema 给模型{ type: function, function: { name: create_ticket, description: 创建一条用户工单需要提供用户ID和问题描述, parameters: { type: object, properties: { userId: {type: string}, message: {type: string} }, required: [userId, message] } } }看到这里你可能会问为什么不直接用反射去枚举方法参数类型就行原因是模型的工具调用准确率很大程度依赖描述文本的质量不只是类型。一个参数叫message问题是它到底填什么如果不给描述模型经常会把用户原始问题原封不动塞进去或者凭空捏造。所以我们强制要求每个AgentTool和ToolParam都必须写描述框架在启动时校验缺失就报错启动失败。这个设计一开始被团队同事吐槽“太啰嗦”但实际跑起来效果立竿见影工具选择的准确率从 70% 左右稳定到 90% 以上。模型真的非常依赖文字描述来理解调用边界这点怎么强调都不过分。还有一个我们后期补上的细节是工具描述里要写清楚“什么时候不调用”。比如某个工具是删除数据的如果你只写“删除订单”模型可能在用户说“取消订单”时就调用它而取消和删除在业务语义里是完全不同的操作。我们现在的做法是在描述里补充条件性说明例如“仅当用户明确要求删除或作废订单时调用如果是取消订单请调用 cancel_order”。别小看这句话它能把误调用率降一个量级。3.2 响应式工具执行与副作用补偿工具方法本身的返回值可能是同步的也可能是异步的。我们设计了一个统一的ToolExecutor适配层public interface ToolExecutor { MonoToolResult execute(ToolInvocation invocation); default FluxString stream(ToolInvocation invocation) { return execute(invocation).map(ToolResult::content); } }同步方法内部会被包装成Mono.fromCallable再投到我们前面说的虚拟线程调度器上执行如果工具返回了Publisher类型框架会直接桥接成响应式流。这样业务开发者根本不必关心自己写的是同步还是异步框架统一处理调用耗时、超时和取消。这里必须提一下“副作用补偿”这个坑。Agent 调用工具不等于普通 API 请求它可能在对话进行到一半时已经执行了一次写操作但用户随后中断了对话。比如模型先调用了“创建订单草稿”然后又调用了“发送提醒短信”结果用户中途关了页面SSE 连接断了。这时候短信已经发出了但订单草稿可能根本没保存两边不一致。我们的处理方式是约定一套补偿接口每个工具都可以实现AgentToolCompensator在 Agent 会话异常终止时框架会主动调用已执行工具的补偿逻辑。但老实说这个能力到现在也只是做得“可用”并没有覆盖所有业务场景。我的建议是如果你们的工具里有明显的副作用操作不要在 Agent 里让它自动执行而是让模型生成“待确认动作列表”由业务系统在执行前做一个人工确认这种模式稳妥得多。3.3 记忆层窗口与摘要两种实现并存的理由记忆是 Agent 框架里最容易做“重”也最容易做“空”的部分。很多框架一上来就给你接向量数据库、搞语义检索但我们认为大部分业务场景的第一需求根本不是“长期记忆”而是“别让上下文爆掉”。所以我们做了两个实现共用一个MemoryStrategy接口WindowMemory固定保留最近 N 轮对话。优点是简单、成本低、行为可预期缺点是会把早期关键信息扔掉。适用于客服工单这类对话轮次短、关键信息集中在最近的场景。SummarizeMemory当窗口超过预算时把前面的对话摘要成一段自然语言再和最近对话一起送入模型。优点是信息浓缩、可控上下文窗口缺点是摘要本身有压缩损耗且摘要过程会额外产生一次模型调用增加延迟和费用。我自己在项目里的建议是默认先用WindowMemory只有当对话长度明显超过模型上下文一半时再去考虑SummarizeMemory。不要一上来就上向量库那个是把问题复杂化了。向量库适合的是“在几十万条历史记录里找相似案例”的场景而绝大多数 Agent 只需要“记得刚才发生了什么”。顺带说一个取舍细节记忆层不是把消息简单拼一起就完事。我们在 context 里维护了三个分区系统指令区、对话历史区、工具回写区。工具回写区可以在每轮结束时做裁剪因为有些工具返回的 JSON 特别长但真正有用的可能只有其中两个字段。如果任它堆积很快就把模型上下文撑爆。我们提供ToolResultTrimmer接口允许每个工具自定义“保存到上下文的净值”这个功能是后期社区反馈最多、加得也最值的一个扩展点。4. 高频踩坑记录背压、阻塞调用与 Agent 死循环的实战修复4.1 坑一并行工具结果回写顺序错乱模型误判业务时序这个 Bug 是我们的测试环境先炸出来的。当时场景是“查询订单并发查询物流”两个工具都很快但网络抖动导致物流查询先返回订单查询后返回。结果框架把先返回的结果先写进上下文模型读到的是“物流轨迹在前、订单状态在后”它推理时居然认为订单是在物流之后创建的给出了一堆莫名其妙的回答。这个问题的根源不是模型蠢而是我们违反了时序一致性原则。修复方式我们在 2.2 节已经提到了就是把同一个步骤里的多个并行工具结果collectList收集齐了再统一写回。这样虽然牺牲了一点等待时间但换来的是上下文里的逻辑时序永远正确。我额外说一个容易被人忽略的细节统一写回时工具结果在上下文里的顺序也要固定。不能每次执行完按返回顺序排要按工具在步骤里的声明顺序排。否则即使你是统一写回的两次运行之间顺序可能不一样模型还是会困惑。我们在ParallelStep里为每个工具挂了index字段写回前按index排序这个逻辑写进单元测试里之后再也没有复发过。4.2 坑二Java HTTP Client 的同步阻塞混进 Netty 线程这是我们踩过最隐蔽的一个性能坑跟大家详细复盘一下。我们一开始接入大模型供应商 SDK 时用的是 JDK 自带的HttpClient。它在单次调用上千毫秒的场景下性能没什么问题问题出在放进了flatMap之后。Agent 编排天然是并发很高的一个 WebFlux 应用可能同时跑几十个 Agent 会话每个会话每轮要调多次模型。如果你在flatMap里直接放一个同步阻塞调用它会在 Reactor 的 Netty 线程上占用时间。刚开始流量不大看不出来等压测一上来你会发现整个应用的吞吐断崖式下跌因为 Netty 的 EventLoop 线程被阻塞调用占满了。我们用BlockHound这个库做了检测第一时间就把问题定位了。修复方案就是前面说的把同步阻塞调用包装到专门的虚拟线程调度器里。private final Scheduler virtualScheduler Schedulers.fromExecutorService( Executors.newVirtualThreadPerTaskExecutor(), llm-blocking); public MonoString callModel(String payload) { return Mono.fromCallable(() - syncClient.call(payload)) .subscribeOn(virtualScheduler); }这里还有第二个坑虚拟线程调度器不能一开到底。因为Schedulers.fromExecutorService创建的调度器默认会缓存线程如果你给每个请求都新建一个执行器线程数会不受控制地膨胀。我们用了一个静态共享的ExecutorService配合固定上限的线程池保证高并发下虚拟线程资源可控。4.3 坑三Agent 死循环的暴力防止我们的三层闸门是怎么设计的模型在工具调用场景里偶尔会“魔怔”比如查询物流失败后它反复调用同一个查询接口每次换一点参数但换汤不换药。如果没有循环上限这个请求会一直打到你后端把下游接口打爆。我们的第一层闸门是轮数上限这个不用多说第二层闸门是累计 token 上限上下文总量超过预算就直接终止第三层闸门是最有特色的——重复行为检测。我们在LoopGuard里维护一个最近三轮的工具调用指纹列表指纹由“工具名 参数 HashMap 去掉时间戳后的序列化结果”生成。如果连续三轮指纹完全一致我们直接中断 Agent返回一个特殊的事件给调用方“检测到模型重复调用相同工具已终止本次任务”。说一个小教训指纹计算不能直接拿原始参数序列化因为大多数业务参数里都带timestamp、requestId这类会变化的字段。你要是连这些都算进去重复行为永远检测不到。我们把这种情况做成注解属性比如ToolParam(ignoreInFingerprint true)框架计算指纹时会跳过标注字段。这个细节也是被生产环境教育出来的。4.4 坑四SSE 流式输出与事务一致性不可兼得时怎么选还有一类坑不是代码层面的而是产品层面。当我们把 Agent 结果以 SSE 流式推给前端时对话是逐字显示的。如果 Agent 中间执行了一个“扣减库存”的操作用户看到一半觉得不对关掉了页面。此时库存已经扣了但没有生成订单。我们一开始的方案是记录补偿事件在连接断开时自动回滚。但在一次真实客户对接中我们发现自动补偿比不补偿更危险——因为补偿可能发生在扣减成功之后、用户又点了确认的那几毫秒窗口里结果把有效扣减回滚了。后来我们改成“写操作一律等 Agent 全部执行完成由前端点击确认按钮触发提交”。即 Agent 只生成操作方案业务系统按方案执行不在 Agent 内部做最终写操作。这个经验可能只适合部分业务但值得所有做 Agent 工具调用的人思考Agent 的职责是决策和推理不是执行不可逆操作。把不可逆操作留给业务流程确认才能避免很多在分布式环境里解释不清的问题。5. 开源发布复盘模块布局、文档策略与社区冷启动5.1 仓库结构与 Maven 模块怎么切才合理开源最怕的是把内部代码原封不动扔出来。我们花了几周时间把内部项目拆成适合开源的结构最后定了五个 Maven 模块├── agent-api // 公共接口和注解依赖最少 ├── agent-core // 内核实现包含 AgentRuntime、编排器、LoopGuard ├── agent-spring-boot-starter// Spring Boot 自动配置让用户一个依赖引入全部功能 ├── agent-adapters // 模型接入适配层OpenAI、通义等不同实现 └── agent-samples // 示例工程每个场景一个子目录agent-api是我们认为最关键的模块。它只包含接口、注解和事件模型不依赖任何框架和网络库。这样第三方用户可以只依赖agent-api就能实现自己的运行时或者在自己的框架里嵌这套协议。发布到 Maven Central 的过程这里也顺带说一句你需要先配好 GPG 签名、Sonatype 的账号、POM 里的 SCM 坐标。我们第一次发布因为忘记在 POM 里声明licenses和scm被中央仓库拒了好几次。后来把发布流程写成了 GitHub Actions workflow每次提交 tag 自动触发省心很多。5.2 文档策略示例比 API 文档重要十倍开源项目冷启动阶段最大的敌人不是代码质量而是“用户看不懂怎么从零跑起来”。我们犯过的错误是前期把大量时间花在 Javadoc 上结果 README 里的一步到位示例写得不够细导致第一波用户进来以后不知道怎么和 Spring Boot 4 应用集成。后来我们把agent-samples里的第一个示例精简成 60 行以内能跑通的完整工程并且把运行步骤写在 README 最前面引入依赖、写一个Configuration注册工具、在 Controller 里调用runtime.stream()、启动应用。配一张完整的 SSE 返回截图。第二个被验证有效的事情是“错误信息友好化”。框架解析模型返回的非法 JSON 时我们不只抛异常而是把原始模型输出片段、当前上下文轮次、工具列表一并打包进异常信息。这样用户看到报错至少知道往哪儿查不会一头雾水地在 issue 里打转。开源项目的内容里这一点投入产出比极高强烈建议所有做框架的人参考。5.3 社区冷启动的一些个人体感我不打算晒 star 数或下载量那种数据意义不大而且每个项目情况不一样。我更想说的是开源一个 Java 框架你收到的第一批反馈往往不是赞美而是功能需求。你就当这是社区给你开的产品评审会认真对待比申诉和辩论更有价值。我们在发布后的第一周收到的最有价值反馈是“希望能支持自定义的模型响应解析器”。因为我们内置的解析只针对 OpenAI 风格的 function call 格式而社区用户用的模型五花八门有的一开始就把工具调用直接以 JSON 写在 assistant 消息里格式完全不一样。这个反馈让我们意识到框架的模型适配层必须留出足够宽的扩展点而不是绑死在一种协议上。另一个体感是文档里要明确“什么情况不推荐使用这个框架”。我们写了一段如果你的场景只是单轮问答、不需要工具调用、不需要流式输出那么直接用 HTTP 客户端调模型的官方 API 就行别引入 Agent 框架增加复杂度。这段话表面上是劝退用户实际上让真正需要框架的用户对你建立了信任。最后说一下我们接下来想做的事。Roadmap 上排了三件事一是支持更多模型厂商的 function calling 协议二是把记忆层扩展成可以接向量数据库的 SPI三是一些更细致的可观测性指标比如每个工具调用耗时、失败率、平均轮数。这些功能能不能落地很大程度上取决于社区反馈的优先级排序我们欢迎感兴趣的人参与讨论或提 PR。回看整个过程我最大的感受是在一个成熟的技术栈里做“新东西”最难的不是把新东西写出来而是让新东西和老生态不打架。Java 25 的虚拟线程、Spring Boot 4 的响应式底座、大模型 SDK 的阻塞调用这三者原本并不天然兼容但通过合理的分层设计它们完全可以成为一套顺手的生产工具。开源只是开始后续的路还长设计和维护中的坑还得继续填。
