企业官网建设流程全解析

先说结论：标题里提到的“从零用 Java 构建 AI Agent 框架”，我没法真去把整套源码贴出来，毕竟那需要几万行代码。但基于这个标题背后要解决的问题——为什么要用 Java 写 Agent、Agent 框架的核心到底在管什么、以及怎么在 JVM 生态里落地上手——我可以把一套可复现的设计思路和关键实现细节拆开讲透。

这两年 AI Agent 的概念火得不行，但市面上绝大多数框架都是 Python 写的。Java 开发者想搞 Agent，要么被迫切到 Python 生态，要么只能在一个不太匹配的运行时里硬凑。我们团队当时接手一个企业级场景，要求把 Agent 能力嵌入到已有的 Java 微服务体系里，同时又不想引入跨语言的调度复杂度——JavaManus 就是在这个背景下从零设计的。这篇文章我会围绕这套框架设计的几个核心决策点展开：为什么用 Java、Agent 的能力模型怎么定义、工具调用与任务执行链路怎么拆、上下文管理和记忆怎么做，以及我们踩过的那些坑。适合想用 JVM 技术栈落地 Agent 的团队参考，也适合对 Agent 底层机制感兴趣的读者。

1. 整体架构设计与思路拆解

1.1 为什么偏要用 Java 写 Agent 框架

先聊一个最容易被杠的问题：现在做大模型应用，Python 明显更顺手，生态也更丰富，为什么还要用 Java 重新造轮子？

我给出的答案是：要看你的 Agent 最终要跑在哪。

如果你只是做研究和原型验证，Python 确实无可挑剔，langchain、llama-index这些库把大部分琐碎工作都封装好了。但一旦 Agent 要进入企业生产环境，事情就变了。Java 的杀手锏在于它的运行时稳定性和生态纵深。我们当时面临的情况很典型：Agent 需要实时读取内部系统的订单数据，需要调用一组很老的 SOAP 接口，还要把分析结果写进 Oracle 数据库。这些能力 Python 也能做，但我们的技术团队本身全是 Java 背景，与其用 Python 重写一遍接口对接逻辑，不如直接在 JVM 里做原生集成。

另一个被低估的点是 Java 的并发模型在 Agent 场景下的适用性。Agent 的执行天然是“多路探索”的：一个任务要被拆成多个子任务，若干工具调用可能需要并行执行，同时不同 Agent 实例之间还可能有协作。Java 的虚拟线程在 JDK 21 中正式落地之后，这种高并发的任务调度变得极其轻量，一个 JVM 里跑几千个虚拟线程毫无压力。这是 Python 的 GIL 模型下需要费很大力气才能达到的效果。

第三点则是运维的维度。Agent 系统一旦上线，就需要日志记录、指标监控、优雅停机、配置热更新这些能力。Java 生态里这些东西沉淀了二十多年，拿来即用。与其等 Agent 相关的 Python 运维设施慢慢成熟，不如用一套已经很成熟的运行时去承载新的业务逻辑。

1.2 Agent 框架的核心：那不是聊天，那是干活

说个很多人对 Agent 的误会。很多人觉得 Agent 就是把大模型的对话接口包一层，加上工具调用就算完事。但实际上，Agent 真正复杂的不是“对话”，而是“干活”——也就是把一个目标转化为一系列可执行、可观测、可回滚的操作。

一个合格的 Agent 框架，我认为至少要解决四个基本问题：

目标拆解。用户给一个笼统的指令，比如“帮我分析过去三个月各区域销售额的波动原因”，Agent 首先得把它拆成一个可以执行的计划。这跟人解决问题的思路是一样的：先明确分析维度、再确定数据来源、再选择分析方法，最后组织输出。

工具调度。拆解出的计划要落地，就必须调用外部工具——查数据库、调接口、跑脚本、写文件。工具可能是本地方法，也可能是远程服务，Agent 要能识别哪个工具适合当前子任务，用什么样的参数去调用，以及如果调用失败怎么重试。

状态跟踪。Agent 的执行不是一次请求就完事的，它往往需要多轮迭代。每一轮执行到了什么状态、还差什么信息、哪些中间结果对后续步骤有用，都要被持续追踪。否则，Agent 就像个失忆的人，每次决策都缺上下文。

结果验证。大模型生成的结论不一定对。工具调用的返回值也可能是脏数据。框架需要在 Agent 的内部增加验证环节，确保每一步执行的结果是可信的，然后再进入下一步。

这些需求被汇总起来，就构成了我设计中所谓的 Agent Core——一个独立于具体大模型的服务编排层。模型可以换，工具可以增删，但这个 Core 必须是稳定的。

1.3 基于 JavaManus 的整体分层模型

基于上面的思路，我们在设计 JavaManus 时把整个框架分为四层。这里直接给出我们最后定型的分层结构，你可以把它当作一个抽象的参考架构。

这个分层是照着“依赖往里收、能力往外放”的原则设计的。接入层只是入口，不承载业务逻辑；编排层处理 Agent 的核心生命周期；能力层负责把各种外部依赖封装成统一的工具接口；模型层则让上层完全不感知底层是 GPT、Claude 还是国产模型。

我见过很多团队做 Agent 时犯的一个错误是：把逻辑全塞进 Controller 或者 Service 里，刚开始能跑，但一加新工具就到处改代码，一换模型就崩。分层的意义在于，每个组件只关心自己那一层的事情，上层不需要关心下层的实现细节。比如接入层收到 HTTP 请求，只需要把任务丢给编排层，不用关心这个任务最终是调用哪个模型、执行哪些工具。

2. 核心细节解析与实操要点

2.1 Agent 的能力模型：从 Prompt 到结构化指令

Agent 的核心实体是一个“智能体”，它跟一个普通的 HTTP 接口的最大区别在于：它需要理解目标，并自主决定怎么完成目标。这个“自主决定”的过程，在工程上其实就是一套结构化的指令和上下文传递机制。

我们在 JavaManus 里定义了 AgentTask 和 AgentStep 两个核心模型。

AgentTask代表一次完整的任务生命周期。包含任务 ID、目标描述、初始上下文、状态、执行计划引用。这里最重要的就是goal字段——它承载用户输入的原始的、模糊的目标，同时还有一版经过解析器提炼出的formattedGoal，其中提取了关键任务类型、目标实体、预期产出。

AgentStep代表一步具体动作。它包含：该步骤的输入参数、要调用的工具名、预期产出描述、依赖的上一步 ID（用于构建 DAG）、执行状态、以及可选的失败降级策略。正是因为有了步骤这个细粒度的抽象，Agent 的执行轨迹才变得可观测，也能在失败时精准定位到具体哪个环节出了问题。

在 Prompt 构造上，我们采用了一套“结构化指令 + 工具描述注入 + 历史摘要”的组合拳。工具描述不是把方法的注释搬上去，而是让模型能读懂“什么场景用什么工具、参数怎么传”。这里我直接放一段我们工具描述的标准格式，已经算是一个模板：

{ "toolName": "query_sales_data", "description": "查询指定时间段内各区域的销售额数据。适用场景：用户询问销售趋势、区域对比、业绩达成率。", "params": { "startDate": "yyyy-MM-dd 格式的起始日期", "endDate": "yyyy-MM-dd 格式的结束日期", "region": "可选，区域名称，不填则查询全区域" }, "returns": "包含日期、区域、销售额字段的 JSON 数组" }

这里有个容易被忽视的细节：工具描述的清晰度，直接影响模型选工具的正确率。我们做过 AB 测试，描述里明确写了“适用场景”之后，工具选择的准确率从 72% 提升到了 89%。原因很简单——大模型的工具选择本质上是语义匹配，你给的场景线索越多，匹配越准。

2.2 上下文与记忆管理：别让 Agent 变“金鱼”

Agent 跟普通程序的一个显著区别是：它需要记忆。但这种记忆又跟传统数据库的持久化不一样。Agent 的记忆包含三个层次——工作内存、短期记忆、长期记忆。

工作内存对应一次任务执行过程中的全部上下文。比如当前任务目标、已完成的步骤和结果、工具返回的中间数据。这部分生命周期最短，任务结束即释放。

短期记忆对应最近几次任务的关键信息。比如用户偏好的输出格式、上次任务中哪些工具执行失败过。这层记忆可以存在本地缓存里，TTL 设置成几个小时或一天。

长期记忆则是 Agent 跨会话沉淀的可复用知识。例如某个用户经常查询华东区域的数据，长期记忆就把“华东区域”设为该用户的默认过滤条件；再比如某类业务的处理逻辑较复杂、有特殊路径，长期记忆就保存这些经验提示，在之后的同类任务里注入。

JavaManus 里用MemoryStore接口来抽象这三类记忆。工作内存就是一个HashMap，短期记忆用了 Caffeine 缓存，长期记忆则存进了向量数据库。但存储本身不是重点，重点是“怎么检索和注入”。

直接说我们的做法吧。在每次 Agent 准备执行任务之前，编排层会把用户的profile和与当前任务语义相关的历史经验取出来，拼装到系统提示里。做法并不复杂，但要控制注入量。经验太多了，Prompt 就会膨胀，模型注意力会被稀释。我们一般限制每次最多注入 5 条记忆，超过的部分宁可丢弃，也不要把 Prompt 搞成一锅粥。

有一个很典型的坑：把记忆检索做成了“全量检索”。听起来合理，但如果向量库里已有上千条历史记录，每次任务执行前都来一次全量相似度计算，响应延迟根本扛不住。我们后来改成“先粗筛、再精排”：先用关键词过滤掉完全无关的记忆，只对候选集做向量相似度计算。实测响应时间从 800ms 降到了 120ms。这个优化逻辑其实跟搜索引擎的原理是一样的，回忆一下倒排索引的思路就通了。

2.3 工具注册与动态发现机制

工具是 Agent 的“手脚”。在 JavaManus 的设计里，工具不是写死在代码里的if-else分支，而是一套可插拔的注册机制。我们定义了一个Tool接口，所有工具都必须实现它：

public interface Tool { String getName(); String getDescription(); Map<String, Object> getParameterSchema(); ToolResult execute(Map<String, Object> params); }

这里比较关键的是getParameterSchema()。它返回的是一个 JSON Schema——描述这个工具接受什么参数、参数类型是什么、哪些是必填的。为什么这么做？因为 Agent 的决策是由大模型驱动的，模型需要“看”到这个工具的参数签名，才知道怎么传参。Java 方法签名没法直接被模型读取，所以必须通过 Schema 做一层桥接。

在工具加载上，我们用了 Spring Boot 的自动装配机制——所有实现Tool接口的 Bean 会在容器初始化时被自动扫描，并注册到ToolRegistry。这带来的好处是：新增一个工具，只需要写一个类、实现对应接口、加注解，不需要修改任何已有代码。工具的可插拔性让 Agent 的能力可以无限扩展——query_sales_data、generate_report、send_email，每加一个工具，就是给 Agent 加了一只手。

你可能想问：工具太多了模型选不准怎么办？这就是ToolRegistry的另一个职责——按需注入。不是把所有工具的描述一股脑丢给模型，而是根据任务的语义，只把最相关的前 N 个工具描述注入到 Prompt 里。这一步用 TF-IDF 关键词匹配就能做到，成本低但效果明显。可以把这理解成“让模型的范围从几百个工具缩小到几个候选”，决策准确性自然就上来了。

2.4 多模型适配层：别把自己绑死在一家供应商

现在的大模型市场已经非常多元了，今天用得好好的模型，明天可能价格调整，也可能某个新模型在特定任务上表现更好。如果你的 Agent 框架跟某一家的 SDK 深度绑定，替换成本会非常高。

所以我们抽象了LLMProvider接口。它非常薄，只做三件事：同步/流式生成、Token 统计、模型名与配置解析。

流式输出这一点值得重点说说。Agent 的有些任务是长耗时的——比如分析几百条数据并生成报告，如果等整个模型推理完才输出，用户端会一直“转圈”，体验很糟。JavaManus 里通过StreamingResponse的方式把模型的输出一点一点推给前端。在技术上，我们用 Spring WebFlux 的Flux来做响应式流推送，后端实时把模型生成的 Token 转发给前端；同时，编排层会额外跑一个订阅任务，把这些流式 Token 累积起来，等完整结果出来后继续做下游处理和工具调度。这样既保证了交互的实时性，又不丢失完整的结果语义。

实际上实现多模型接入并不需要魔法。每个模型厂商的接口无非是：输入消息列表、返回文本结果。我们的适配器核心逻辑就是做一个格式转换——把厂商格式转成统一的LLMRequest，再把响应转回统一的LLMResponse。如果某天想换一家模型，只需写一个新的适配器类，在配置里切换一下。我这里给一个可能的配置片段：

java: manus: llm: provider: openai-compatible base-url: http://localhost:9997/v1 model-name: qwen-plus temperature: 0.3 max-tokens: 4096

这个配置的关键是openai-compatible——很多开源模型和云厂商都提供 OpenAI 兼容接口，所以写一个通用的 OpenAI 兼容适配器，就等于打通了市面上绝大多数模型服务。

3. 实操过程与核心环节实现

3.1 过一遍完整链路：从任务输入到结果返回

纸上谈兵讲了半天，我们把一条完整链路走一遍，你就知道这些模块是怎么协作的了。假设一个用户请求是：“生成 2024 年 Q4 华东区的销售分析报告”。

第一步，接入层的 Controller 收到这个请求，包装成一个AgentTask对象，丢给编排层的AgentScheduler。编排层会根据任务的复杂度，决定使用什么样的执行计划策略。由于这里有一个明确的“生成报告”动词和一个“销售数据”对象，可以走预定义流程模板。

第二步，AgentScheduler从ToolRegistry里检索与当前任务相关的工具。正常情况下会命中query_sales_data和generate_report两个工具。随后，执行计划会被构建成一个简单 DAG——先查数据，后生成报告。

第三步，进入实际的执行循环。第一步调用query_sales_data，传入 startDate、endDate 和 region。参数不是凭空生成的，而是AgentCore在调用模型时，把工具的描述注入 Prompt，然后让模型返回结构化的ToolCall指令，再由框架解析执行。翻译成人话就是：大模型“决定”了该用什么参数，框架负责“执行”这个调用。

第四步，工具调用完成后，返回的销售数据会被写回工作内存。AgentCore把数据和当前状态一并传给模型，询问下一步该怎么做。模型通常会回答“数据已获取，开始生成报告”。随后generate_report工具被执行，把数据渲染成一份标准化的 Markdown 或 PDF 报告。

第五步，报告生成完成后，框架将最终结果返回给调用端。整条链路看下来就五个环节，但每个环节都涉及状态流转、上下文更新和异常处理。为了完整呈现这个链路，我给你梳理一个时序表：

接入层 -> 编排层: 提交任务，包含目标描述 编排层 -> 工具注册中心: 检索可用工具 编排层 -> 决策引擎: 规划执行步骤，构建 DAG 执行引擎 -> 大模型: 注入上下文和工具描述，请求决策 大模型 -> 执行引擎: 返回工具调用指令 执行引擎 -> 工具实例: 执行调用，获取结果 执行引擎 -> 大模型: 注入工具结果，请求下一步 大模型 -> 执行引擎: 返回最终回复 / 下一个工具调用 执行引擎 -> 输出适配器: 格式化结果 输出适配器 -> 接入层: 返回最终响应

3.2 Java 流式处理在执行引擎中的落地

Agent 的执行过程本质上是一连串数据处理流的串联。数据从工具 A 流出，进入模型 A 的上下文，模型的输出又成为工具 B 的输入。如果每一次交互都靠阻塞式的调用，不仅性能差，代码也会写得像回调地狱。

JavaManus 里我们对这个问题的解法是引入响应式编程范式，核心基于 Project Reactor。每个 AgentStep 的执行结果会被封装成一个Mono<ToolResult>，多个步骤之间的数据流转通过flatMap串联。比如“先查数据再生成报告”这个链路，用代码表达出来长这样：

public Mono<ToolResult> executePlan(AgentTask task) { return Mono.just(task) .flatMap(this::planSteps) .flatMap(dag -> executeDag(dag, task.getContext())) .onErrorResume(e -> Mono.just(ToolResult.failure(e.getMessage()))); } private Mono<List<AgentStep>> planSteps(AgentTask task) { // 调用模型生成步骤列表，或匹配预定义流程模板 } private Mono<ToolResult> executeDag(List<AgentStep> dag, Context ctx) { // 逐个执行步骤，每步结果写入 ctx }

这里面有个重要的细节：为什么不用普通的CompletableFuture或者ExecutorService？

原因是错误传播。Agent 的步骤之间是有依赖关系的，如果步骤二依赖步骤一的输出，而步骤一执行失败了，步骤二再跑就没有意义。CompletableFuture确实也能做编排，但处理“几步中有一步失败、其余该怎么办”的逻辑非常繁琐。而 Reactor 的onErrorResume、mergeWith这些组合子能让我们更清晰地表达这类分支逻辑。尤其当 DAG 复杂起来之后，响应式的声明式写法明显更整洁。

3.3 可观测性：追踪一次任务的全链路轨迹

Agent 系统跟普通后端系统最大的不同是：它的执行路径不是预先写死的，而是模型每次实时决定的。这就意味着同样的输入，两次执行可能走完全不同的工具调用路径。如果你没有一套全链路追踪机制，排查问题时基本等于盲人摸象。

我们在 JavaManus 里定义了ExecutionTrace数据结构。这次任务里的每一步——模型怎么思考、选择了什么工具、传了什么参数、工具返回了什么结果、耗时多少——都会被记录。这些数据有三个用途：一是实时的任务状态展示，二是问题定位，三是 Prompt 调优的参考。

实现上我们借用了 OpenTelemetry 的 span 概念。一个任务是一个 root span，每执行一个步骤就创建一个 child span。span 上挂的 attribute 包括工具名、参数摘要、模型名、token 消耗。所有 span 最终被汇入一套可观测后端进行查询和分析。

这套体系上线后，我们发现了一个特别有意思的现象：很多“Agent 执行结果不对”的问题，根因并不是模型选择错误，而是框架在工具结果传递过程中出现了数据截断。比如模型返回了 2000 个字符的结果，但工具上下文只保留了前 500 字符。没有 trace 的话，这类问题极难定位。而一旦有了完整的轨迹，问题一眼就能看出来。

3.4 项目落地需要避开的性能陷阱

说几个我们在压测中真正遇到的性能问题，以及对应的解决方案。

第一个陷阱是 Token 计算带来的性能负担。每次调用大模型前，框架都要估算当前上下文的 Token 数，决定是否触发摘要压缩。如果用官方 SDK 自带的 tokenizer，几十次调用下来 CPU 开销很可观。我们的优化方式是：在上线前做一次校准，统计模型在常见上下文长度下的 token 消耗，拟合一个粗略的“字符数 × 系数”预估公式。虽然不精确，但足够用于触发阈值判断。精确统计只保留在最终计费日志阶段。

第二个陷阱是工具调用的网络开销。Agent 在工具之间切换时，频繁建立新的 HTTP 连接会产生很大的连接池压力。我们统一把所有远程工具调用收敛到一个HttpClientManager，复用底层连接池，并针对不同工具设置合理的connectTimeout和readTimeout。刚开始图省事，所有工具共用一个超时时间，结果有一个慢接口把整个 Agent 的任务周期拖到超时，最后一次性拆开配置，问题就没了。

第三个陷阱是上下文压缩策略的执行时机。如果不做压缩，长对话场景下 Prompt 会越来越大，响应越来越慢；但压缩过头，模型又会丢失重要信息。我们最终采用了“双阈值”方案：当上下文总长度超过上限的 70% 时触发压缩，但要求压缩后的摘要至少保留原始信息的 40%。这个阈值不是拍脑袋定的，是在压测里反复调出来的一个平衡点。

4. 常见问题与排查技巧实录

4.1 工具调用循环与终止条件控制

Agent 用着用着容易进入一个死循环：模型反复决定调用某个工具，每次调用结果都类似，但迟迟不给出最终答案。这种情况在复杂任务里非常常见，本质上是模型的“任务完成判断”出了问题。

我们的解法是加入一个“最大迭代次数”的硬限制，把默认值设在 8 步。超过这个步数，强制让模型进入总结模式，把当前已有信息整合成最终回复。同时在系统提示里加一句硬约束：当你认为当前信息已经足够满足用户目标时，直接输出最终答案，不需要继续调用工具。句话说，模型确实有这个“收尾能力”，只是需要有人给它一个明确的信号。

另外还有一个隐蔽的坑：模型调用了工具，但工具返回的结果是空数据或错误信息，而模型又把这段错误信息当成正常上下文继续下一步推理。所以我们在工具执行层加了一个验证逻辑——工具返回之后，先检查结果是否包含明确的错误标志。有错就直接走失败路径，不让脏数据污染后续推理。

4.2 并发安全与执行环境隔离

Agent 的多实例并发执行时，最怕的是上下文串线。用户 A 的任务上下文跑到了用户 B 的任务里——这在多租户场景下是严重事故。

我们使用“每任务一个上下文”的原则：AgentContext是在任务创建时实例化的，所有步骤共享同一个引用，但它的归属严格限定在当前任务内部，绝对不允许有任何静态变量存储任务状态。

你可能觉得这是常识，但实际踩过坑：最初版本的ToolRegistry里有一个缓存 Map 保存“最近一次工具调用结果”，本意是想做结果复用，结果测试的时候发现两个任务之间发生了数据交叉。改动的方案也很直接——把结果缓存改成 per-task 的局部变量。这个坑记忆很深，也让我对“Agent 是状态化还是无状态化”有了新的认识。理想中 Agent 是无状态的，但现实是为了性能一定会引入缓存，这时就务必把缓存的隔离性和生命周期想清楚。

4.3 模型“犯糊涂”时的兜底策略

模型毕竟是概率系统，它有时候会生成格式完全不对的输出——比如工具调用的参数缺了必填项，或者返回了不存在的工具名。这类问题无法通过“更聪明的 Prompt”完全消除，必须靠框架兜底。

我们的策略很简单，三层兜底：

第一层，工具调用参数校验。如果模型返回的ToolCall在ToolRegistry里找不到对应工具，或者参数格式不合法，直接把这次调用标记为失败，并给模型回传错误信息：“该工具不存在或参数格式错误，请重新决策”。模型收到错误信息后，通常会修正决策。

第二层，重试机制。定义一个重试次数上限——默认 3 次。每次重试时，把上一次错误的详细原因追加到上下文里，让模型带着反馈重新决策。可以这样理解：模型一开始可能因为上下文不清而犯错，但给了纠错反馈之后，它其实能做出正确的判断。

第三层，人工接管兜底。如果重试后仍失败，或者用户任务的置信度一直低于阈值，就把任务标记为NEED_HUMAN_REVIEW，推到审批队列。这一步在企业场景里特别重要——Agent 不是用来完全替代人的，它越界时，必须有一个人能拉得住缰绳。

4.4 问题排查速查表

把我们从真实故障里总结出的排查经验整理成一张表，遇到问题时可以按图索骥：

最后分享一个“非技术”的建议：Agent 框架的调试，别只盯日志。把模型每一步的完整输入输出存下来，生成一份可读的 trace 报告，配合任务失败时的上下文回溯，排查效率会提升很多。尤其是在模型决策路径不稳定的情况下，trace 比日志信息有价值得多。

个人做下来的体会是：Java 写 Agent 框架并非逆流而上，反而在某些场景里是一种务实的选择。它没有 Python 那么轻巧，但当你需要把 Agent 嵌入到企业级系统里时，JVM 的稳定性和生态纵深会变成实实在在的优势。核心不在于语言，在于你把 Agent 的骨架搭得多稳、多利于维护。JavaManus 这套设计的思路，希望能给你提供了一个可以参考的起点。