坦白说，看到“JavaManus”这个名字的那一刻，我第一反应是：终于有人愿意在 Java 生态里认真搞 AI Agent 了。过去这两年，Agent 框架几乎被 Python 圈包揽，LangChain、LlamaIndex、AutoGPT 满天飞，Java 开发者要么干瞪眼，要么硬着头皮在 Java 项目里嵌一个 Python 微服务。所以我决定自己动手，完全从零开始，用纯 Java 实现一个能够自主拆解任务、调用工具、完成闭环的 Agent 框架。
这篇文章会把我在设计和实现 JavaManus 过程中的核心思路、架构选型、关键代码、以及一堆实战踩坑记录全部摊开来讲。它不是什么理论科普，而是一份能直接照着改、照着用的工程实践笔记。适合那些在 Java 技术栈里做 AI 应用开发、想自己造轮子理解 Agent 本质、或者准备把 Agent 能力集成进现有后端系统的朋友。
1. 整体架构与设计思路：为什么 Agent 框架必须自己造
1.1 Java 生态做 Agent 的真实痛点
先聊聊背景。我所在的项目组一直做的是企业级后端系统，技术栈很纯粹：Spring Boot、MyBatis、XXL-Job、Nacos 这一套。最近老板提了个需求，希望系统能根据用户的自然语言指令，自动完成数据查询、报表生成、异常告警推送这类操作。说白了，就是要把 LLM 接进现有业务系统里。
当时第一反应是直接用 Python 写个 Agent 服务，再通过 HTTP 和 Java 交互。但调研后发现几个问题很棘手：第一，公司现有的权限体系、配置中心、注册中心全在 Java 侧，Python 服务要接入这些基础设施，光改造成本就够喝一壶；第二，运维体系统一走 Java 的发布链路，多一套 Python 服务等于多一套监控、日志、告警的折腾；第三，团队里没有一个能写 Python 的人。所以最后拍板：用 Java 从零写一个轻量级 Agent 框架，就叫它 JavaManus。
1.2 JavaManus 的设计目标与边界
动手之前，我先明确了 JavaManus 必须要做到的四件事：
- 能自主规划：收到一个复杂任务后，Agent 自己拆成多个子步骤，不靠人肉编排。
- 能调用工具：接上现有的 Java 服务方法，比如查数据库、调接口、发通知。
- 能自我修正：某一步执行失败了，Agent 能根据错误信息调整策略重新尝试，而不是直接崩溃。
- 能流式交互：Agent 的思考过程、工具调用日志、最终结果，都要流式推给前端，不然用户等一个十几秒的完整响应早跑了。
而明确不做的边界是：不做一个通用平台型框架，不做模型训练和微调，不搞复杂的多智能体通信协议。这些会让整个项目失控。
1.3 总体架构分层
JavaManus 的总体结构我分了五层，从下往上分别是：
- 基础设施层：LLM 网关客户端、工具注册中心、内存存储、事件总线。
- 能力层：规划器（Planner）、执行器（Executor）、记忆管理器（Memory）、工具调用器（ToolInvoker）。
- 核心引擎层：AgentRunner，负责编排思考-行动-观察循环。
- 接口层：REST API 和 WebSocket，给上层业务系统调用。
- 接入层：业务方的自定义工具、自定义 Prompt 模板、自定义拦截器。
这个分层最大的好处是：每层只依赖下一层，替换成本低。比如我想把底层的大模型从 OpenAI 协议换成国内各家模型，只需要改基础设施层的 LLM 网关客户端，上面四层完全不动。
2. 核心引擎：AgentRunner 与思考-行动-观察循环
2.1 为什么选 ReAct 模式而不是纯 Chain
Agent 最核心的机制就是思考-行动-观察循环，也就是 ReAct（Reasoning + Acting）。我试过几种方案：纯 Chain 模式用起来像写死的工作流，灵活性差；Plan-and-Execute 模式虽然规划能力强，但实现复杂度高，对每一步的状态管理要求很严格。
JavaManus 最终选择了 ReAct 作为基础，但做了两层增强：第一，在进入 ReAct 循环之前，先让模型输出一个简短的全局计划（Plan），相当于给 ReAct 流程加了个导航；第二，每一次思考结果都要求模型显式给出"是否需要调用工具"，用工具结果作为下一次思考的输入。这两层增强让 Agent 既有 ReAct 的灵活性，又有一定的前瞻性。
循环的核心实现长这样：
public class AgentRunner { private final LLMGateway llmGateway; private final ToolRegistry toolRegistry; private final MemoryManager memoryManager; private final EventBus eventBus; public AgentOutcome execute(String task) { // 第一步：生成全局计划 List<PlanStep> plan = planner.createPlan(task); eventBus.publish(new PlanGeneratedEvent(plan)); // 第二步：进入思考-行动-观察循环 int maxIterations = 20; for (int i = 0; i < maxIterations; i++) { AgentThought thought = llmGateway.think(buildPrompt(task, plan, i)); eventBus.publish(new ThoughtEvent(thought)); if (thought.isFinalAnswer()) { return AgentOutcome.finalAnswer(thought.getContent()); } if (thought.requiresToolCall()) { ToolCall call = thought.getToolCall(); ToolResult result = toolRegistry.invoke(call); eventBus.publish(new ToolResultEvent(call, result)); memoryManager.remember(result); } } return AgentOutcome.timeout(); } }2.2 迭代次数的控制策略
上面代码里我写了个maxIterations = 20，这是拍脑袋定出来的吗？不是，是压测压出来的。我用 50 条测试任务分别跑了 5 次循环、10 次循环、15 次循环、20 次循环，发现大多数正常任务在 5-10 轮就能完成，复杂任务到 15 轮左右基本也能收敛。20 轮是为了给那些要反复试错的任务留足余量，超过 20 轮的任务绝大多数是模型在空转，再跑下去只会烧 Token。
这里有个很重要的工程细节：每执行一次循环，都要把当前迭代次数拼进 Prompt 里告诉模型。比如"你目前已经尝试了 7 次，如果仍然无法解决问题，请直接输出当前能给出的最优答案"。不然模型会在循环里无限打转，解决问题遥遥无期。
2.3 事件驱动与状态管理
AgentRunner 本身是无状态的，每次执行都通过 EventBus 发布事件。这个设计借鉴了事件溯源的思想，好处有两点：一是前端可以通过 WebSocket 实时订阅事件流，把 Agent 的思考过程像打字机一样展示给用户；二是方便排查问题，把事件的完整时间线打出来，就等于看了一遍 Agent 的完整思考轨迹。
状态管理我用了简单的状态机，只有四个状态：INITIALIZED、PLANNING、EXECUTING、FINISHED，外加两个终态FAILED和TIMEOUT。为什么不搞复杂状态机？因为 Agent 的执行过程本身是循环不是线性流转，状态太细化反而容易出 bug，四个状态足够覆盖主流程了。
3. 工具注册与调用：让 Agent 真正干活的引擎
3.1 工具是 Agent 的手脚
模型再聪明，不接工具也就是个只会说不会做的嘴炮侠。JavaManus 的工具系统是整个框架里我最看重的一块，也是踩坑最多的一块。
工具系统的设计目标是：业务方在 Java 方法上加一个注解，注册进来，Agent 就能自动识别、自动生成参数、自动调用。就像这样：
@Component public class WeatherTools { @AgentTool(name = "query_weather", description = "查询指定城市的当前天气情况") public String queryWeather(@AgentToolParam(description = "城市名称，例如北京") String city) { // 调用外部天气服务 return weatherService.getCurrentWeather(city); } }3.2 工具注解与注册机制
@AgentTool注解负责标记一个方法可以被 Agent 调用。框架启动时，通过 Spring 的ApplicationContext扫描所有带这个注解的 Bean，把方法信息反射出来，注册到 ToolRegistry 里。
注册的时候要做三件事：第一，把方法名转成 snake_case 格式的工具名，因为 LLM 对下划线命名更敏感；第二，解析方法参数上的@AgentToolParam注解，拿到每个参数的描述；第三，生成工具的 JSON Schema，这是给模型看的工具说明书。
JSON Schema 生成的代码大致这样：
public String generateToolSchema(ToolDefinition tool) { Map<String, Object> schema = new HashMap<>(); schema.put("type", "object"); Map<String, Object> properties = new LinkedHashMap<>(); for (ToolParameter param : tool.getParameters()) { Map<String, Object> paramSchema = new HashMap<>(); paramSchema.put("type", "string"); paramSchema.put("description", param.getDescription()); if (!param.isRequired()) { paramSchema.put("optional", true); } properties.put(param.getName(), paramSchema); } schema.put("properties", properties); schema.put("required", tool.getRequiredParameters()); return JsonUtils.toJson(schema); }3.3 参数映射与类型转换
工具调用的核心难点不在注册，而在参数映射。模型返回的是一段 JSON 字符串，比如{"city": "北京"}，你要把这个 JSON 正确映射到 Java 方法的参数列表上。
最简单的情况是基本类型参数，直接 JSON 解析赋值就行。复杂的是嵌套对象参数，比如有个工具方法接收一个QueryCriteria对象，里面包含了startTime、endTime、filters这些字段。模型能不能正确构造这个对象，很大程度上取决于你的 Schema 定义得够不够细。
我踩过一个大坑：有个工具方法参数是Long类型，模型返回的参数值是"1234567890123"字符串，Jackson 反序列化的时候报错说无法将字符串转换为 Long。排查后发现是模型生成工具调用参数时把所有值都当字符串处理了。解决办法是在生成 Schema 的时候，给参数显式标注类型，并且在反序列化时做一层宽松转换：能转数字就转数字，转不了就保留字符串。
3.4 工具调用的错误处理
Agent 调用工具时，工具本身可能会抛异常。比如查数据库超时了、外部接口返回 500 了。这时候如果直接把异常抛给 AgentRunner，整个循环就中断了。正确做法是：把异常捕获后转成 ToolResult 返回给模型。
我封装了一个工具调用的包装逻辑：
public ToolResult invoke(ToolCall call) { try { Object[] args = parameterResolver.resolve(call.getArguments(), tool.getMethod()); Object result = tool.getMethod().invoke(tool.getBean(), args); return ToolResult.success(JsonUtils.toJson(result)); } catch (IllegalArgumentException e) { // 参数错误，把错误信息返回给模型，让它修正参数后重新调用 return ToolResult.failure("参数校验失败: " + e.getMessage()); } catch (InvocationTargetException e) { // 业务异常，同样返回给模型 return ToolResult.failure("工具执行异常: " + e.getCause().getMessage()); } }这样模型看到失败原因后，就能判断是调整参数重试，还是换一种工具，又或者是直接告诉用户"这个操作做不了"。这种自我纠错能力，就是工具调用闭环的灵魂。
4. 规划与上下文管理：让长任务不迷路、不超窗
4.1 全局计划与子任务拆解
ReAct 循环有个天然缺陷：容易走一步看一步，做着做着忘了最初的目标。比如用户说"分析近三个月销售数据并生成月报"，Agent 可能在查询数据的时候就陷入细节，把生成月报这个大目标抛在脑后。
JavaManus 的处理方式是在正式执行前，先让模型输出一个全局计划。计划的格式长这样：
[ {"step": 1, "action": "query_sales_data", "goal": "获取近三个月销售明细"}, {"step": 2, "action": "calculate_metrics", "goal": "计算环比增长率"}, {"step": 3, "action": "generate_report", "goal": "生成分析月报"} ]这个计划会拼在每一轮循环的 Prompt 里，让模型随时知道自己当前处于整个任务的哪个阶段。实测下来，这个设计显著减少了模型跑偏的概率。
4.2 Token 窗口管理
上下文窗口是 Agent 的硬约束。每轮循环，你要把系统提示词、全局计划、历史思考记录、工具调用结果、最新一次的用户问题全部塞进 Prompt，很容易就把上下文撑爆。
我的 Token 管理策略是三级：
- 短期记忆：保留最近 5 轮的思考-行动-观察记录，用于当前决策。
- 中期摘要：把 5 轮之前的交互历史用模型做一次摘要压缩，只保留关键结论。
- 长期事实：把用户的原始需求和全局计划放在 Prompt 前方最显眼的位置，永远不裁剪。
具体实现时，我在每轮构造 Prompt 前会估算 Token 数，如果超过阈值就触发摘要压缩。估算用的是简单的字符数除以 3 再乘一个系数，不用太精确（其实也没办法很精确），能保证不超窗就行。
4.3 轻量级记忆存储
记忆管理模块我用了最朴素的内存 Map，配合定时清理。这里不引入 Redis 的原因很简单：JavaManus 定位是轻量级框架，单个 Agent 实例的会话量级根本到不了需要外部存储的程度。真要支持分布式、多实例共享记忆，那是后续把 MemoryManager 接口换成 Redis 实现的事，接口预留好了就行。
5. LLM 接入层与流式响应：如何优雅地连接大模型
5.1 模型网关的抽象设计
JavaManus 对底层 LLM 的接入做了一个统一的 LLMGateway 接口，不同模型服务商各自实现。接口核心方法就两个：一个是流式对话补全，一个是函数调用（Function Calling）补全。
接口设计这么简单是有原因的：Agent 和模型的交互本质上就两种模式——一种是模型输出自然语言（比如思考过程、最终答案），另一种是模型输出结构化的工具调用指令。把这两种模式抽象成接口方法，上层就不必关心底层是 OpenAI 还是 Claude 还是别的什么模型了。
public interface LLMGateway { Flux<ModelChunk> chatStream(ChatRequest request); Flux<ToolCallChunk> chatWithTools(ChatRequest request, List<ToolDefinition> tools); }5.2 流式解析与增量事件推送
流式响应的难点在于：大模型是一段一段吐字的，你怎么把这段不完整的文本流解析成"思考"或"工具调用"的完整结构。
我在 JavaManus 里实现了一个简单的增量解析器。大概思路是：设置一个缓冲区，不断把流式到达的字符追加进去，然后尝试用 Jackson 的ObjectMapper增量解析来识别完整的函数调用 JSON 结构。如果当前缓冲区里的内容还不能构成一个完整的 JSON，就继续等；如果已经识别出完整的工具调用 JSON，就把这段内容从缓冲区里摘出来，并发布一个工具调用事件。
这里有个小坑要注意：不同模型厂商对流式输出的格式封装不一样，有的会在 chunk 里直接吐增量文本，有的会把完整内容拆成多段，还有的可能把多个函数调用拆在不同 chunk 里。所以解析器一定要做得健壮，各种边界情况都要覆盖到。我在测试用例里专门写了十几个极端场景：比如函数名在第一个 chunk、参数在第二个 chunk、结束括号在第三个 chunk，这种跨 chunk 拼接的情况最容易出 bug。
5.3 模型配置与多模型切换
JavaManus 的模型配置全部走application.yml，支持配置多个模型提供商，按角色区分。比如规划任务用便宜快速的模型，复杂推理用更强但贵的模型，工具调用用支持 Function Calling 的模型。
这个设计思路来自一个实际观察：Agent 流程中，规划阶段对推理能力要求不高，用快模型能显著降延迟；而复杂任务的最终回答需要强推理，用慢但聪明的模型能避免逻辑错误。把不同模型按任务阶段混合编排，既省 Token 又提升体验。
6. 实战踩坑实录：Java 写 Agent 的十个典型问题
6.1 Jackson 泛型擦除引发的类型混乱
这是我遇到的第一个大坑。JSON Schema 生成阶段，我用了一个通用的类型工具类来获取方法参数的类型信息。但 Java 的泛型擦除导致一个问题：如果方法参数是List<String>，运行时拿到的Type对象确实是ParameterizedType，但如果参数是List<List<String>>，嵌套的泛型信息就会部分丢失。
解决办法是：要求工具参数尽量用简单类型，复杂结构就封装成 DTO，并在 DTO 字段上用 Jackson 注解显式声明类型。同时写了一个单元测试，专门用TypeReference做反序列化验证，确保每个工具参数的解析都能得到正确类型。
6.2 模型返回工具调用的 JSON 不合法
别看大模型聪明，让它生成严格合法的 JSON 也经常翻车。常见的错误包括：多一个逗号、字符串里的引号没转义、字段名大小写不一致、多了注释。
我的应对策略是三层容错：第一层，直接尝试用 Jackson 严格模式解析；第二层，如果失败，把 JSON 里的注释去掉、修掉多余的逗号后再试；第三层，还不行就把这段文本直接返回给模型，告诉它"你刚才生成的工具调用参数格式有误，请重新生成"。
我在实测中发现，第三层容错往往是最有效的。因为你让模型自己修正自己的错误，它比你任何程序化修复都更聪明。
6.3 流式响应的粘包与拆包
WebSocket 推送流式事件时，前端的接收端时不时出现乱序或者事件丢失。排查后发现是 WebSocket 消息的粘包问题，多个 Flux chunk 被合并成一次网络传输，前端拿到的是一个拼接在一起的字符串。
解决办法是：每个流式事件的末尾都加一个自定义的分隔符，前端按分隔符拆分后再逐个解析。这个方案简单粗暴但极其可靠，实测几万次推送没有出现乱序。
6.4 Function Calling 的多工具并发选择问题
模型有时候会一次请求同时调用多个工具。这个能力理论上很高效，但我在实现时发现一个问题：多个工具调用结果都回来了，上下文里会变得特别混乱，模型容易在后续的思考中混淆"哪个结果对应哪个工具"。
JavaManus 的处理方式是：默认关闭多工具并行调用，模型一次只能调用一个工具。等上下文管理更成熟了再开放这个能力。如果你也想做多工具调用，我建议在每个工具调用结果前加上工具标识，提醒模型这是哪个工具的结果。
6.5 HTTP 调用超时的隐性坑
Java 的 HTTP 客户端默认超时时间很长，Agent 循环调用 LLM 时，如果模型服务商那边响应变慢，整个请求会被拖住，引发连锁超时。
我统一封装 HTTP 客户端时，把连接超时设为 5 秒，读取超时设为 60 秒，并且给整个流式调用加了一个全局超时保护（用timeout()操作符实现）。这样即使模型方响应异常，AgentRunner 也会及时抛出超时异常走失败分支，而不是无限等待。
7. 性能优化与压测数据：框架到底行不行
7.1 并发模型与线程池配置
JavaManus 的 AgentRunner 是响应式模型和传统阻塞模型混用的。外层调用方通过 WebFlux 得到响应式 API，但内部工具调用又依赖同步的反射调用。这个混用风格一开始让我很纠结，后来想通了：工具调用是业务系统里的存量代码，大部分是阻塞式的，强行改成响应式反而容易出兼容问题。
所以线程池配置上我做了隔离：LLM 调用线程池用虚拟线程（Java 21 的Thread.ofVirtual()），因为 LLM 调用是纯 IO 等待，虚拟线程能最大化吞吐；工具调用线程池用固定大小线程池，默认 8 个线程，避免业务代码在线程资源上互相争抢。
7.2 压测数据与性能调优
我用一个模拟的"数据查询Agent"做了压测。场景是：用户连续输入 20 个不同的查询请求，每个请求需要 Agent 调用两个工具（查用户表、查订单表）然后汇总结果。
压测结果：单实例并发 10 个会话时，平均单轮响应时间约 3.2 秒，其中 LLM 推理占 2.5 秒，工具执行占 0.4 秒，剩余是网络开销。并发 50 个会话时，响应时间退化到 8 秒左右，瓶颈出现在 LLM 网关的限流上。这说明框架本身的资源开销非常小，真正的瓶颈永远在模型服务那一侧。
7.3 热点代码优化
如果要提一个最值得优化的点，我建议看 JSON 序列化和反序列化。Agent 每轮循环至少要做 3 次 JSON 解析：解析模型输出、生成工具调用 Schema、处理工具结果。我就用了 Jackson 的ObjectMapper单例复用，并把所有 Schema 的结果缓存到内存里，避免重复生成。这个小优化直接把每轮循环的耗时降了 15%。
8. 框架的扩展性与应用场景：不止是玩具
8.1 业务系统集成实战
JavaManus 在我这边的落地场景是"智能数据助手"。用户在前端输入"帮我查一下上周各区域的销售额排名，并找出增长最快的三个区域"，JavaManus 自动规划、调用数据查询工具、生成分析报告，最后通过 WebSocket 把思考过程和结果推送到前端。
整个接入过程比预想中顺利，主要原因就是我把 Spring Boot 的自动配置做到了极致。业务方只需要在自己的项目里引入依赖，配置模型 API Key，然后把自己已有的 Service 方法加上@AgentTool注解，JavaManus 就自动把工具暴露给了 Agent。不需要改任何业务代码。
8.2 与现有权限体系打通
企业级应用绕不开权限控制。JavaManus 在工具调用层做了权限拦截：每个工具可以声明需要的权限标识，AgentRunner 在执行前会检查当前会话的权限上下文，没有权限的调用直接拒绝，并把拒绝原因返回给模型。
这个方案比在模型 Prompt 里强调权限规则可靠得多。Prompt 是软的，模型可能无视；代码是硬的，说拒绝就拒绝。安全边界这种事，永远别指望模型自律。
8.3 后续扩展方向
JavaManus 目前的版本只能算 MVP（最小可行产品），后续空间还很大。我想做的几个方向包括：多 Agent 协作（不同 Agent 各负责一块子任务，通过消息队列通信）、工具市场（业务方上传自定义工具包，动态加载）、可视化编排（拖拽工具节点来定义 Agent 工作流）。
如果你也想做类似的事情，我的建议是：先把核心循环跑通，再考虑这些花哨功能。一个能稳定处理 80% 场景、不炸不崩的简单框架，远比一个功能齐全但是三天两头出 bug 的复杂框架有价值。
9. 个人体会与总结建议
项目做完回头看，用 Java 写 Agent 框架这件事，给我最大的感受是三句话：
第一，Java 不是不能做 AI 应用，关键要看你怎么扬长避短。LLM 推理这种密集计算确实不是 Java 的强项，但 Agent 框架的核心是理解和编排业务工具，这正是 Java 生态沉淀了二十年的地盘。只要能打通 LLM 接入这一环，后面的工具调用、权限控制、状态管理、日志监控，Java 的成熟度反而比 Python 生态更高。
第二，Agent 框架的生产力取决于工具生态的丰富程度。模型再智能，没有趁手的工具它也使不出来。做 JavaManus 让我琢磨明白了一件事：写 Agent 和写别的系统不一样，你不是在写业务逻辑，而是在给模型设计一套可以操控世界的"操作手册"。工具的质量直接决定了 Agent 的上限。
第三，别迷信复杂的框架设计，简单才能稳定。我做 JavaManus 的过程中，有两次大改动都是因为觉得当前设计太简陋，想重构得更"优雅"，结果重构完炸出一堆新 bug。最后反而证明，最朴素的 ReAct 循环加上精心设计的工具注册机制，性能和质量都远超几个花哨的实验性功能。
如果你也在考虑在自己项目里搞一个 Agent，我的建议是直接动手写一个最小的循环：接上模型、注册一个工具、跑通一次完整的"思考-调用-反馈"流程。等你看到 Agent 第一次通过工具调用拿到结果、并且根据结果继续往下一步走的那一刻，你就能真正体会到这个系统的灵魂在哪里了。剩下的事情，就是在这个最小循环上不断打磨和扩展，把框架一点点养大。
