在 AI Agent 工程化落地的讨论中，Python 生态往往占据主流位置。但对于许多企业而言，核心业务系统长期构建在 Java 技术栈之上。如何让 Agent 直接进入既有业务链路，而不是通过跨进程调用引入额外复杂度，成为现实问题。掘金上一篇关于 JavaManus 的技术文章，提供了一个以纯 Java 从零构建 Agent 框架的观察样本。
为什么 Java Agent 框架值得被重新审视
文章指出，Python 在 LangChain、LlamaIndex、AutoGPT 等方向已形成完整生态，但企业工程环境并不总是 Python 友好。如果业务主体是 Spring Boot 服务，把 Python Agent 嵌入其中，通常意味着跨进程调用、序列化开销以及运维链路变长。
JavaManus 的目标并不是复刻一个大型通用 Agent 平台，而是提供一个可扩展的 ReAct Agent 实现：能够接入 Spring Boot 应用，支持自定义工具，并兼容不同 LLM 提供商。项目基于 Spring AI 1.1.0 与 Spring Boot 3.4，默认使用火山引擎 Ark 作为 LLM 提供方，整体代码规模不到 30 个 Java 文件。
从架构上看，JavaManus 采用分层组合设计。外部通过 ManusController 暴露 SSE 接口，内部由 ManusAgent 装配工具，再向下继承至 ToolCallAgent、ReActAgent 和 BaseAgent。记忆模块、ChatModel 适配层与工具集合分别承担不同职责。文章强调，这种结构遵循“组合优于继承”的原则，替换模型或工具集时，不需要改动 Agent 核心逻辑。
ReAct 循环：从自动执行转向显式编排
JavaManus 的核心运行模式仍是经典的 ReAct，即推理与行动交替进行。模型先判断下一步行动，工具执行结果再回传给模型，成为后续推理依据。文章将这一过程拆分为 think 与 act 两个阶段。
在 think 阶段，系统会把 Memory 中的消息、系统提示词以及工具定义一起发给模型，并解析返回内容中的工具调用。这里的关键设计是关闭 Spring AI 的自动工具执行能力，即设置 internalToolExecutionEnabled 为 false。原因是框架需要自行控制工具执行时机，例如截断过长输出、触发事件，或在特殊工具出现时提前结束任务。
在 act 阶段，工具输出会作为 ToolResponseMessage 写回记忆。如果结果超过预设的 maxObserve，系统会只保留前 N 个字符，避免大文件读取等场景迅速消耗上下文窗口。对于 terminate 等特殊工具，Agent 会直接进入结束状态，而不是继续下一轮推理。
工具调用、记忆管理与工程边界
工具系统方面，JavaManus 复用了 Spring AI 的 ToolCallback 接口。所有工具最终返回纯文本，以降低工具与模型之间的交互复杂度。ToolCollection 负责根据工具名称查找并执行对应工具，未知工具会抛出 ToolError。
文章重点介绍了两个核心工具：
- StrReplaceEditor：支持 view、create、str_replace、insert、undo_edit 五种命令，是 Agent 修改代码和文件的主要入口。
- PythonExecute：通过 ProcessBuilder 启动独立 Python 进程，执行代码并带有超时保护，用于补足 Java 在数学计算、数据处理等场景中的协作需求。
记忆管理采用相对朴素的滑动窗口策略。Memory 本质上是一个带上限的消息列表，超过 maxMessages 后会丢弃最早的消息。文章认为，这种方式虽然简单，但足以避免长任务中上下文无限膨胀；若需要更复杂的长期记忆，可以进一步引入摘要或向量检索机制。
在模型适配层面，由于 Spring AI 官方尚未提供火山引擎 starter，JavaManus 自行实现了 ChatModel 和 EmbeddingModel。其核心工作是把 Spring AI 的 Prompt 转换为 Ark SDK 的 ChatCompletionRequest，再把响应转换回 ChatResponse，其中工具调用的双向映射是适配过程的关键部分。
对于 Java 技术团队而言，JavaManus 的意义不在于提供一个完成度极高的商业框架，而在于展示了 Agent 框架在 Java 生态中可以被拆解为哪些明确模块：状态控制、ReAct 循环、工具编排、记忆管理、模型适配与错误边界。相比直接引入外部 Python 服务，这种方式更贴近企业现有系统的部署方式，也更便于复用 Spring 生态的依赖注入、配置管理与测试体系。
当前 Agent 框架的竞争焦点正在从模型能力转向工程可控性。JavaManus 提供了一个小型但完整的案例：当 Agent 被放入真实业务系统时，真正需要解决的不是单点调用模型，而是如何把推理、工具、记忆与异常恢复组织成稳定可维护的代码结构。
原创文章，作者：点点，如若转载，请注明出处：https://www.dian8dian.com/dang-qi-ye-xi-tong-yu-jian-agent-javamanus-gei-chu-java
