都说 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 LayerJavaManus 的架构就是围绕这两件事展开的。清晰界定了问题后后面所有的代码设计都会顺理成章。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映射为integerLong映射为integer且带int64格式化标记ListString映射为array并嵌套 string 类型描述。这些映射关系如果不处理模型生成的参数类型在反序列化时很容易报错。3.3 工具执行与参数回填反序列化的正确姿势模型返回的响应里工具调用参数通常是一个 JSON 字符串。执行器拿到这个字符串后要先通过 Schema 校验一遍确认必填项都有、类型匹配再进行 JSON 反序列化为 Java 对象。这里我踩过一个典型的坑模型生成的 JSON 有时候会在字段名上大小写不规范比如把orderId生成成了orderid。解决办法是在反序列化时启用大小写不敏感的映射配置并在校验阶段兜底字段缺失时返回可读性强的错误信息而不是直接异常抛出。这个错误信息会作为工具执行结果回传给模型让模型自己修正参数这比中断整个 Agent 流程要好太多。工具本身的异常处理也要单独说。任何工具方法都可能抛异常但这个异常不能让整个 Agent 循环崩掉。JavaManus 的规则是工具异常统一被捕获包装成一个带有错误信息的结果消息返回给模型模型会看到类似工具执行失败原因订单号不存在这样的反馈然后它可以决定换一种方式完成任务。这种设计在真实场景里非常有用因为模型的容错能力远超你设置各种重试策略的精细度。4. 多轮对话里的编排逻辑从 Session 隔离到上下文管理工具调用只是单个动作Agent 的能力在于多个动作的组合和决策。这要求框架处理多轮对话的编排其中三个问题最关键会话隔离、上下文裁剪、以及任务完成判定。4.1 会话运行时每个任务一个独立的上下文沙箱用户不可能一次只跑一个任务也不可能所有请求共享一份上下文。JavaManus 为每个 Agent 任务创建一个运行时对象这个对象内部封装了消息列表、最近一次执行时间、迭代计数、以及可选的用户自定义状态。运行时对象 { 会话ID: 全局唯一 消息列表: ArrayListMessage 迭代次数: 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 工程化希望这篇文章能帮你少踩几个坑。
都说 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 LayerJavaManus 的架构就是围绕这两件事展开的。清晰界定了问题后后面所有的代码设计都会顺理成章。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映射为integerLong映射为integer且带int64格式化标记ListString映射为array并嵌套 string 类型描述。这些映射关系如果不处理模型生成的参数类型在反序列化时很容易报错。3.3 工具执行与参数回填反序列化的正确姿势模型返回的响应里工具调用参数通常是一个 JSON 字符串。执行器拿到这个字符串后要先通过 Schema 校验一遍确认必填项都有、类型匹配再进行 JSON 反序列化为 Java 对象。这里我踩过一个典型的坑模型生成的 JSON 有时候会在字段名上大小写不规范比如把orderId生成成了orderid。解决办法是在反序列化时启用大小写不敏感的映射配置并在校验阶段兜底字段缺失时返回可读性强的错误信息而不是直接异常抛出。这个错误信息会作为工具执行结果回传给模型让模型自己修正参数这比中断整个 Agent 流程要好太多。工具本身的异常处理也要单独说。任何工具方法都可能抛异常但这个异常不能让整个 Agent 循环崩掉。JavaManus 的规则是工具异常统一被捕获包装成一个带有错误信息的结果消息返回给模型模型会看到类似工具执行失败原因订单号不存在这样的反馈然后它可以决定换一种方式完成任务。这种设计在真实场景里非常有用因为模型的容错能力远超你设置各种重试策略的精细度。4. 多轮对话里的编排逻辑从 Session 隔离到上下文管理工具调用只是单个动作Agent 的能力在于多个动作的组合和决策。这要求框架处理多轮对话的编排其中三个问题最关键会话隔离、上下文裁剪、以及任务完成判定。4.1 会话运行时每个任务一个独立的上下文沙箱用户不可能一次只跑一个任务也不可能所有请求共享一份上下文。JavaManus 为每个 Agent 任务创建一个运行时对象这个对象内部封装了消息列表、最近一次执行时间、迭代计数、以及可选的用户自定义状态。运行时对象 { 会话ID: 全局唯一 消息列表: ArrayListMessage 迭代次数: 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 工程化希望这篇文章能帮你少踩几个坑。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
