都说 2025 年是 AI Agent 元年，各种框架层出不穷。我的一位老同事前段时间接了个内部项目，要在一套成熟的 Java 微服务体系里嵌入一个能自主完成多步任务的 AI 助手，选型时发现市面上的 Agent 框架要么重、要么绑定特定大模型服务商，要么跟 Java 生态的融合度差得让人抓狂。他折腾了几天后跑来找我吐槽，我干脆自己动手，从零实现了一个轻量级 Java Agent 框架。
这个框架后来就是大家看到的 JavaManus。它不是什么面向 C 端的 App，也不是一个包打天下的低代码平台，而是一个专注解决 Java 后端服务里接入 AI 自主代理能力的基础框架。核心解决三件事：怎么把大模型的能力抽象成 Java 接口、怎么让 Agent 自主决定调用哪些工具、以及怎么让这些工具调用过程可控、不炸掉你现有的业务系统。如果你正在给公司现有系统加 AI 能力，或者对 Agent 的底层工作机制好奇，这篇文章正好可以给你省掉不少弯路的成本。
我在设计这个框架的时候给自己定了三个原则：轻量到能塞进任何现有 Spring Boot 项目里；对模型服务商的 SDK 依赖隔离到"换厂商不改业务代码"；Agent 执行过程必须可观测、可中断、可控制。下面我会从整体架构、核心模块、踩坑实录三个层面展开，把 JavaManus 的设计思路和实现细节一次说透。
1. 为什么在 Java 生态里自研 Agent 框架：先厘清问题边界
先聊聊背景。大语言模型本身只负责"生成文本"，但 Agent 要的是"感知 - 决策 - 行动 - 反馈"的闭环。这个闭环需要大量工程化基础设施：外部工具怎么注册、函数参数怎么校验、模型返回的调用指令怎么解析、多轮对话的历史上下文怎么管理、工具调用的异常怎么处理、并发请求怎么隔离。这些都不属于模型能力，而是应用框架的职责。
在市面方案里，Python 生态的 Agent 框架确实成熟，但 Java 团队集成起来要么走跨语言 RPC，要么自己维护一套 Python 服务，运维成本直接翻倍。我当时的处境很典型：服务端全是 Java，基础设施是内部私有化部署，大模型走统一的网关接入，要求所有 AI 能力必须在 JVM 内闭环。所以与其硬套 Python 方案，不如写一个 Java 原生框架。
JavaManus 这个名字听起来像某个开源项目的变体，但对我而言它更是一个工程代号。它的定位不是 RAG（检索增强生成）那种知识库问答工具，也不是简单的请求转发中间层，而是在 ReAct 思维链范式之上实现的一个可编程的 Agent 执行引擎。所谓 ReAct 就是一种交替"思考 - 行动"的决策模式：Agent 先观察当前状态，思考下一步该做什么，然后调用工具，再把工具结果反馈给模型，继续下一轮思考，直到任务结束。
这个范式在 Java 里落地，本质上是两件事的工程化：
- 一个能循环处理模型请求和工具调用的运行时执行器（Runtime Executor）
- 一套把 Java 方法安全暴露给模型调用的工具抽象层（Tool Abstraction Layer）
JavaManus 的架构就是围绕这两件事展开的。清晰界定了问题后，后面所有的代码设计都会顺理成章。
2. 总体架构拆解：核心模块与执行数据流
JavaManus 由几个核心模块组成，每个模块的边界在设计时反复推敲过：消息抽象、模型网关、工具注册中心、规划器/执行器、记忆存储。它们之间的关系不是简单的一条流水线，而是一套可插拔的协作机制。
2.1 消息抽象：Agent 与外界沟通的统一语言
Agent 内部流转的数据，不只包括你给模型说的话，还包括工具调用指令、工具返回结果、系统提示词等。JavaManus 没有直接用字符串拼 Prompt，而是定义了一套统一消息模型。这套模型模仿了业界主流对话接口的结构：role 区分消息角色，content 存文本内容，toolCalls 和 toolCallId 承载工具调用双向关联。
设计上有一个关键取舍：消息类型应该开放还是封闭。我选择了封闭式基类加可选扩展字段的方式。也就是说，核心消息只包含必要字段，任何自定义数据都放进 attachments 扩展字段。这样做的好处是序列化稳定、跨模型网关传输不丢信息，坏处是如果你要加特别复杂的消息形态，会感觉约束略多。但这种约束在工程上其实是好事，它逼着调用方把逻辑显式化，而不是塞进一个万能 Map 里。
2.2 模型网关抽象：换模型服务商不换业务代码
JavaManus 的模型调用层没有绑死任何一家 SDK，而是定义了一个聊天模型接口，统一封装消息列表输入、模型参数、工具定义列表，由网关实现完成"Java 对象到大模型 API 请求参数"的映射。
刚开始我倾向于直接用某个云厂商的 HTTP 接口，但后来发现不同厂商接口差异巨大：有的走 OpenAI 兼容协议，有的自己定义了一套流式格式，还有一个私有化部署的产品只支持 SSE 流式输出非标准事件类型。如果业务代码直接依赖某一家，将来切换就直接重写一层。所以模型网关的职责很纯粹：把内部消息结构翻译成目标模型的 HTTP JSON 请求，再把返回的响应解析为内部消息。
为了让这套抽象不过度设计，我只定义了两个核心方法：流式对话和标准对话。流式返回通过回调接口逐段推送内容，标准对话则阻塞式拿到完整结果。
2.3 工具注册中心：把 Java 方法变成模型可用的函数
这是 JavaManus 最核心的模块。它的工作包含两部分：发现工具和描述工具。
发现工具的思路参考了很多 Spring 框架的理念，做了一个轻量级注解扫描器。你在任意 Spring Bean 的方法上标注自定义注解，框架在启动时扫描所有候选类，把这些方法注册进一个工具表。每一个注册的工具都会自动生成一份 JSON Schema 描述文件，包含方法名、参数名、参数类型、必填项、方法用途说明。模型在决定调用什么工具时，它真正看到的不是 Java 代码，而是这份 JSON Schema。
描述工具的难点在于参数枚举。比如有一个参数是"排序字段"，可选项是时间、价格、销量，如果你在代码里写死了枚举，模型就只能靠猜。JavaManus 的做法是支持工具方法上用注解显式声明每个参数的取值范围和描述，然后由注册中心把这些信息合并进 Schema。这样模型生成的参数天然能落到你代码预期范围内。
2.4 规划器与执行器：一个循环里完成 ReAct 决策
我不太喜欢把 Agent 架构画成一堆复杂组件的拼接图。真正跑起来的核心其实是一个循环：把消息列表传给模型，模型返回一个回复，如果回复里带了工具调用指令，就执行工具，把执行结果作为新的消息追加进列表，然后带着更新后的完整消息列表再请求模型。如此往复。这个循环拆成两个组件是因为职责不同：规划器负责和模型交互，推断下一步动作；执行器负责真正跑工具方法，处理异常，把结果标准化回传给规划器。
循环次数不能是无限的。JavaManus 有一个最大迭代次数的硬限制，默认设置为 20 次，防止模型在一个问题上反复横跳浪费 Token。同时每一轮的完整消息列表会保存到一个内存存储里，便于随时审计这个 Agent 到底经历了什么"思考过程"。
3. 工具调用的完整生命周期：注解扫描、Schema 生成与参数回填
工具调用是 Agent 框架里工程细节最密集的部分。模型说它要调用某个函数，你的系统得按图索骥地执行对应方法，再把方法返回值翻译回模型能看懂的消息。听起来简单，实际落地全是坑。下面拆开说。
3.1 注解定义与扫描机制
先看工具方法长什么样。一个工具方法就是一个普通 Java 方法，只是加了注解。例如：
@Component public class OrderTools { @AgentTool(name = "query_order_by_id", description = "根据订单号查询订单基本信息，返回包含状态、金额、收件人字段的对象") public OrderInfo queryOrderById(@ToolParam(description = "订单号，例如 20250101001") String orderId) { // 走内部 RPC 查询订单，这里省略实现 return orderService.queryById(orderId); } }关键在于框架如何发现它。JavaManus 在启动时通过 Spring 容器的getBeansWithAnnotation能力拿到所有包含工具方法的 Bean，再反射遍历其方法，筛选出标了注解的方法。这一步需要处理不少细节：方法参数名默认是arg0这类无意义名字，必须用注解里的参数名覆盖；方法重载要小心，同一类里两个同名方法会导致工具注册冲突；工具方法不应该有超过 6 个参数，否则模型生成精确参数的难度会急剧上升。
为了提升参数 Schema 的质量，我在注解里支持了必填项、可选项、示例值等字段。模型拿到示例值后，生成参数的格式正确率会有明显提升。
3.2 JSON Schema 的生成：让模型真正看懂你的函数
模型接口里的 tools 参数要求的是 JSON 数组，结构大概是：
[ { "type": "function", "function": { "name": "query_order_by_id", "description": "根据订单号查询订单基本信息", "parameters": { "type": "object", "properties": { "orderId": { "type": "string", "description": "订单号，例如 20250101001" } }, "required": ["orderId"] } } } ]JavaManus 在工具注册后，会为每个工具方法维护一个 Schema 对象。这个对象由框架在注册阶段生成，不会每个请求都动态反射，这样大大降低了请求链路的开销。生成的逻辑说白了就是把注解描述翻译成 JSON 结构，但有一个细节必须处理：Java 类型到 JSON Schema 类型的映射。比如Integer映射为"integer"，Long映射为"integer"且带int64格式化标记，List<String>映射为"array"并嵌套 string 类型描述。这些映射关系如果不处理，模型生成的参数类型在反序列化时很容易报错。
3.3 工具执行与参数回填：反序列化的正确姿势
模型返回的响应里，工具调用参数通常是一个 JSON 字符串。执行器拿到这个字符串后，要先通过 Schema 校验一遍，确认必填项都有、类型匹配，再进行 JSON 反序列化为 Java 对象。这里我踩过一个典型的坑：模型生成的 JSON 有时候会在字段名上大小写不规范，比如把orderId生成成了orderid。解决办法是在反序列化时启用大小写不敏感的映射配置，并在校验阶段兜底：字段缺失时返回可读性强的错误信息，而不是直接异常抛出。这个错误信息会作为工具执行结果回传给模型，让模型自己修正参数，这比中断整个 Agent 流程要好太多。
工具本身的异常处理也要单独说。任何工具方法都可能抛异常，但这个异常不能让整个 Agent 循环崩掉。JavaManus 的规则是：工具异常统一被捕获，包装成一个带有错误信息的结果消息返回给模型，模型会看到类似"工具执行失败，原因：订单号不存在"这样的反馈，然后它可以决定换一种方式完成任务。这种设计在真实场景里非常有用，因为模型的容错能力远超你设置各种重试策略的精细度。
4. 多轮对话里的编排逻辑：从 Session 隔离到上下文管理
工具调用只是单个动作，Agent 的能力在于多个动作的组合和决策。这要求框架处理多轮对话的编排，其中三个问题最关键：会话隔离、上下文裁剪、以及任务完成判定。
4.1 会话运行时：每个任务一个独立的上下文沙箱
用户不可能一次只跑一个任务，也不可能所有请求共享一份上下文。JavaManus 为每个 Agent 任务创建一个运行时对象，这个对象内部封装了消息列表、最近一次执行时间、迭代计数、以及可选的用户自定义状态。
运行时对象 { 会话ID: 全局唯一 消息列表: ArrayList<Message> 迭代次数: int 当前状态: RUNNING / WAITING_TOOL / FINISHED / ERROR 分配内存: 本次调用产生的临时对象 }Session 隔离不仅是业务需要，还是安全需要。如果一个任务里的工具调用结果能被另一个任务引用，那模型生成的内容就有可能串味。Session 层把这种风险物理隔断了，同时支持在任务结束后手动或自动释放。
4.2 上下文裁剪策略：不能被历史消息拖垮
Agent 循环的代价在于消息列表越来越长。每轮工具调用结果都要追加到列表里，然后下轮请求原样发给模型，Token 消耗很快。实践中你会发现，超过十轮后，模型生成内容的关联度反而下降，因为无效噪音太多。JavaManus 提供了一套策略接口，默认实现是所有消息全量发送，但建议生产环境替换为按 Token 上限裁剪的实现。裁剪策略我总结出三种有效模式：
- 保留系统提示词和最近的 N 条消息，丢弃中间历史
- 将工具调用结果做摘要，替换为压缩后的文本再放入消息列表
- 分离关键事实存储区，模型请求里只携带当前任务必需的事实，而不是所有流水账
说实话，第三种模式效果最好，但实现成本也最高。它需要你定义一个字段提取器，把单调的消息流中"对任务有决定性影响的信息"抽取出来持久化。JavaManus 当前默认实现是前两种策略的组合，够用但不完美，后续版本会继续演进。
4.3 任务完成判定：什么时候算是做完了
这个判定听起来容易，实现起来很难。模型自己说"任务完成"不一定真完成了；工具返回了数据不代表模型正确使用了数据。JavaManus 的判定模型有三层：
第一层是模型主动发起终止标志，即模型在回复里明确说明"已完成"。第二层是硬性边界，比如迭代次数耗尽、用户主动中断。第三层是业务状态校验，需要开发者注册一个回调，检查最终回复是否符合某种期望。比如一个订票 Agent，最终回复说"已订票成功"，但订单系统里并没有新增订单，那这个完成就是虚假的。业务校验回调就是为了拦截这种情况。
三层判定之间的优先级也很关键：业务校验优先于模型自述，模型自述优先于硬性边界。这能最大限度防止模型幻觉被当成正确结果落库。
5. 工程化落地中的几个典型坑：并发、超时与模型返回格式
框架从原型到勉强可用，再到能稳定跑在业务环境里，中间经历了大量问题。下面几个坑是最常见的，如果你也要写类似框架，可以提前规避。
5.1 并发调用下的线程模型冲突
一开始我偷懒，直接用虚拟线程或者普通线程池在服务层并发调用模型和工具。结果测试环境跑得欢，一上生产就出现工具注册表被并发写坏的问题。原因很直接：工具注册是启动时一次性的，但工具调用参数解析时用到了一个共享的 Schema 缓存对象，这个对象没有做线程安全隔离。
解决方式很简单：把 Schema 缓存设计为不可变对象，每次请求使用一个全新的执行上下文去引用它，而不是直接修改共享对象。修改之后再压测，并发 500 的请求量下没再出现过参数解析错乱。这里有个经验：Agent 框架里共享对象越少越好，宁可多造几个对象，也不要为了省一点内存去共用可变状态。
5.2 模型返回非标准工具调用格式
不同模型返回的工具调用格式真是千人千面。有的模型会在回复文本里混入一个代码块标注的 JSON，而不是走标准的 tool_calls 字段；有的模型会返回一个格式完全正确但函数名不在注册表里的调用；还有个别模型偶尔会返回空 tool_calls，但文本里明明说"我现在调用工具查询订单"。
JavaManus 的兜底方案是在解析层设置了多级解析链：先标准解析，再宽松解析，再到启发式正则提取。如果多级解析全部失败，就把原始文本作为普通回复返回给上层。最后一种情况其实是最保险的兜底，因为模型可以再输出一轮尝试，而框架不会因为解析异常中断整个任务。
5.3 超时问题：模型慢和工具慢要分开设限
很多初次设计 Agent 框架的人，只给模型调用设了超时，却忽略工具调用也可能卡死。一个查询工具如果依赖的下游 RPC 慢，就可能卡住整个循环。JavaManus 把超时拆成两级：模型调用超时和工具调用超时，工具超时又拆成连接超时和读超时。工具箱里对那些可能长时间运行的工具，统一要求开发者显式标注预估耗时，超时后执行器会发错误消息给模型，模型会选择重试或走替代方案。
这个设计在业务里带来的直接收益是：一个工具挂了，Agent 还能自我纠偏走别的路径，而不是整个任务报废。
6. 实践效果与后续演进：JavaManus 还能往哪走
框架在当初的项目里跑了快四个月，最典型的使用场景是内部工单助手。它对接了订单查询、库存校验、物流跟踪、客户备注提取四个内部工具，Agent 可以根据用户一句自然语言描述，自主决定查询顺序，并且自动组合不同工具的结果。效果最直观的是"物流正常为什么客户说没收到"这种问题，模型会先查物流单号，再看库存发货状态，然后查客户备注里是否有延迟信息，最终给出真正可疑的解释。这个任务如果用规则引擎写，分支组合能把你绕晕。
在性能上，一次包含 3 个工具调用的完整任务，纯框架耗时约 80 至 150 毫秒，大部分时间其实是模型响应耗时。JavaManus 本体的性能开销已经压到了很低。
后续演进我有几个方向想持续推进：
- 支持工具调用过程中的人工审批节点，让高风险操作必须经过人工确认
- 增加更完善的记忆持久化策略，打通任务之间的长期记忆
- 做一个可视化的 Agent 轨迹回放面板，方便调试复杂的工具调用链
JavaManus 这套框架本质上是一场关于"如何把大模型能力工程化"的实践。它的设计理念就是把复杂性收敛在框架层，让上层业务只关注工具定义和结果处理。对 Java 团队来说，与其接一个笨重的跨语言框架，不如在 JVM 内自建这套机制，成本低且可控性强。如果你也在做类似的 Agent 工程化，希望这篇文章能帮你少踩几个坑。
