纯Java打造企业级Agent Harness：BizBuddy架构设计与工程实践

1. 为什么我要用纯 Java 造一个 Agent Harness

1.1 从一个真实的痛点说起

去年下半年，我所在的团队接了一个内部效率工具的需求。背景很简单：公司内部有好几个业务系统，客服、运营、数据分析的同事每天要在这些系统之间来回切换，重复执行一些固定流程，比如查订单、拉报表、生成周报、批量发通知。大家一开始想的是接一个大模型接口，写个脚本把流程串起来就完事了。真动手才发现，事情远没有这么简单。

一个能跑通的 Demo 和一个能上生产的 Agent 平台，中间隔着的不是模型能力，而是工程化。模型调用只是最外面那一层，底下要处理的东西包括：会话状态怎么存、工具怎么注册和发现、多轮对话的上下文怎么裁剪、失败重试怎么做、权限怎么隔离、审计日志怎么落、并发上来之后怎么限流、不同业务方怎么接入自己的工具。这些东西，才是真正决定一个 Agent 平台能不能在企业里活下来的关键。

我当时给这个平台起了个名字叫BizBuddy，定位很明确：一个面向企业内部业务场景的 Agent Harness（智能体承载框架）。所谓 Harness，你可以理解成"马具"——模型是那匹马，能力很强但方向不定，Harness 就是套在它身上、让它能被人驾驭、能拉着车稳定跑起来的那套东西。它不负责训练模型，也不负责做模型本身，它负责的是把模型、工具、记忆、权限、观测这些零件组装成一个可运维、可扩展、可审计的系统。

1.2 为什么坚持"纯 Java"

这是整个项目里被问得最多的一个问题。现在做 Agent 相关的东西，Python 生态几乎是默认选项，LangChain、LlamaIndex 这些框架成熟度摆在那里，为什么还要用 Java 从头造？

我的理由有三条，都是被现实逼出来的。

第一，企业存量系统绝大多数是 Java。我们要对接的订单系统、权限中心、消息网关、报表服务，全是 Spring Boot 写的。如果 Agent 平台用 Python 写，那每一次工具调用都要跨语言、跨进程、跨网络，中间多一层序列化和网络开销不说，运维上还要维护两套技术栈、两套发布流程、两套监控。对于一个人力有限的小团队，这是实打实的负担。

第二，Java 的并发和稳定性模型更适合长驻服务。Agent 平台本质上是一个长时间运行的服务，要处理大量并发的会话、要管理连接池、要做优雅停机、要做线程隔离。JVM 在这方面的成熟度、可观测性工具链、以及团队已有的排障经验，都是现成的资产。Python 的 GIL 在高并发 IO 场景下虽然影响没那么大，但真到了要精细控制线程池、要做背压的时候，Java 的这套东西用起来更顺手。

第三，类型系统带来的可维护性。Agent 平台里到处都是结构化数据：工具的参数 schema、模型的返回结构、会话的状态机。用强类型语言写，编译期就能挡掉一大批低级错误，IDE 的补全和重构也好用得多。项目做到后期，代码量上来了，这一点带来的收益非常明显。

当然，纯 Java 也有代价。最大的代价是生态。Python 那边现成的 prompt 模板库、向量库客户端、各种模型的 SDK，Java 这边要么没有，要么质量参差不齐。所以 BizBuddy 里相当一部分工作，是在补这些基础设施。这也是为什么这个项目值得写一篇总结——踩过的坑足够多。

1.3 这个平台到底解决了什么问题

说人话，BizBuddy 让业务方可以这样用：写一个 Java 类，加上一个注解，声明这个类是一个"工具"，说明它的名字、描述、参数；然后在配置里注册这个工具属于哪个 Agent；业务同事在聊天界面里用自然语言描述需求，Agent 自己决定调哪个工具、传什么参数、拿到结果之后怎么组织语言回复。

举个具体例子。运营同事想查"上周华东区退货率最高的三个品类"。以前的做法是：找数据同学写 SQL，等半天，拿到结果再自己整理。有了 BizBuddy 之后，运营直接在对话框里输入这句话，Agent 会识别出这需要调用"报表查询工具"，自动把自然语言转成结构化查询参数，调用后端接口，拿到数据后再用自然语言总结成一段话返回。整个过程几秒钟。

这个例子里，模型负责的是"理解意图"和"组织语言"，真正的数据查询还是走原来的后端接口，权限、数据口径、审计全都没变。这就是 Harness 的价值：它不替代企业已有的系统，它是在已有系统之上加了一层自然语言的交互入口。

适合谁来参考这篇内容？如果你正在做企业内部工具、正在评估要不要自建 Agent 平台、或者单纯好奇"一个生产级 Agent 系统到底要考虑哪些东西"，那这篇应该对你有用。我会尽量把设计取舍讲透，而不是只贴代码。

2. 整体架构设计与关键取舍

2.1 分层设计：把"会变的"和"不变的"分开

BizBuddy 的整体架构我分了四层，从下往上依次是：模型接入层、核心运行时层、工具与能力层、接入层。这个分层不是拍脑袋定的，而是遵循一个原则：把容易变化的部分隔离出去，让核心逻辑保持稳定。

模型接入层负责屏蔽不同模型提供方的差异。今天用这家，明天可能换那家，接口协议、返回格式、流式方式都不一样。这一层定义一个统一的ModelClient接口，上层只认这个接口，具体实现可以是任何一家。这样换模型的时候，改动被限制在这一层里。

核心运行时层是整个平台的心脏，包含会话管理、Agent 调度、工具调用编排、上下文管理、记忆存储。这一层是纯业务逻辑，不依赖任何具体的模型或工具，是测试覆盖的重点。

工具与能力层是业务方接入的地方。每个工具就是一个普通的 Java 类，通过注解声明元信息，运行时通过反射扫描注册。业务方不需要懂 Agent 的内部机制，只要按约定写好工具就行。

接入层负责对外暴露能力，可以是 HTTP 接口、WebSocket、消息队列消费者，甚至是一个定时任务。这一层很薄，主要是协议转换和鉴权。

提示：分层的关键不是层数多，而是依赖方向单一。上层可以依赖下层，下层绝不能反向依赖上层。我在代码评审时会把这条当作硬性红线，一旦发现下层 import 了上层的类，直接打回。

2.2 为什么不用现成的 Agent 框架

这个问题我在立项时认真评估过。当时看了几个主流的 Java Agent 框架，也考虑过用 Python 框架加一层 Java 网关的方案。最后决定自研，核心原因是控制力。

现成框架的问题在于，它们为了通用性做了大量抽象，这些抽象在你需求简单的时候是助力，需求一复杂就变成阻力。比如上下文管理，框架给你一个默认策略，但企业场景里不同 Agent 的上下文策略可能完全不同：客服 Agent 需要保留完整对话历史，报表 Agent 只需要保留最近一轮，代码助手 Agent 需要保留文件内容。要改这些，就得深入框架内部，改着改着就变成了"框架的二次开发"，还不如自己写。

另一个原因是可观测性。企业里跑的东西，出问题必须能查。现成框架的日志和埋点往往不够细，或者格式不符合公司已有的监控体系。自研的话，从第一天就可以把 traceId、会话 ID、工具调用耗时这些关键信息按公司规范打出来，接入现有监控几乎零成本。

当然，自研不是没有代价。最大的代价是时间。一个能用的框架，别人可能一周就搭起来了，我们花了将近两个月才把核心跑通。但这两个月里，每一行代码我们都清楚它在干什么，后面加功能、排故障的时候，这个"清楚"省下的时间远超当初多花的。

2.3 核心数据模型：会话、消息、工具调用

整个平台的数据模型其实就三个核心实体，理解了它们，整个系统就理解了一大半。

会话（Session）是一次完整交互的容器。它有一个唯一 ID，有创建时间、最后活跃时间、所属用户、所属 Agent 类型。会话是有生命周期的，长时间不活跃会被归档或清理。会话里存的是消息列表和状态。

消息（Message）是会话里的基本单位，分三种角色：用户消息、助手消息、工具消息。用户消息是输入，助手消息是模型的输出（可能包含工具调用请求），工具消息是工具执行的结果。这三者按时间顺序排列，构成对话历史。

工具调用（ToolCall）是助手消息里的一种特殊内容。当模型决定调用工具时，它输出的不是纯文本，而是一个结构化的调用请求，包含工具名和参数。平台解析这个请求，执行对应工具，把结果作为工具消息追加到历史里，然后再把更新后的历史发给模型，让它继续。

这三个实体的关系可以用一句话概括：一个会话包含多条消息，助手消息里可能包含多个工具调用，工具调用的结果又变成新的消息。整个 Agent 的运行，就是这个循环不断转下去，直到模型输出一条不含工具调用的纯文本消息为止。

2.4 状态管理：内存、Redis 还是数据库

会话状态存哪里，是个必须早做决定的问题。我评估了三种方案。

纯内存最简单，一个ConcurrentHashMap就搞定，读写快，没有外部依赖。问题是服务重启状态就没了，多实例部署也没法共享。适合单机 Demo，不适合生产。

纯数据库最稳，状态持久化，重启不丢，多实例共享。问题是每次读写都要走数据库，高频对话场景下数据库压力大，而且对话历史这种数据，读写模式是"写多读也多"，关系型数据库不一定是最优解。

最后我选的是内存加 Redis 的混合方案。活跃会话的状态放在内存里，读写走本地，快；同时异步写一份到 Redis，用于故障恢复和多实例共享。会话结束或超时后，完整历史归档到数据库，用于审计和后续分析。

这个方案的关键在于一致性。内存和 Redis 之间是异步同步，理论上存在短暂不一致。我的处理是：以内存为准，Redis 只作为恢复源。如果服务崩溃重启，从 Redis 加载最近的状态，可能丢失最后几条消息，但不会导致状态错乱。对于企业内部工具，这个一致性级别是够的，如果换成金融交易场景，那就得换成同步写加事务。

注意：状态管理这块，千万不要一上来就追求"完美一致"。先想清楚业务能容忍多大的不一致，再选方案。很多团队在这里过度设计，最后系统复杂得没人敢改。

3. 核心模块的实操细节

3.1 模型接入层：如何优雅地屏蔽差异

模型接入层的核心是一个接口和一组实现。接口定义得很简单：

public interface ModelClient { ModelResponse chat(ModelRequest request); void chatStream(ModelRequest request, StreamCallback callback); }

ModelRequest里封装了消息列表、工具定义、温度、最大 token 这些参数。ModelResponse里封装了模型返回的文本、工具调用请求、token 用量。所有具体模型的差异，都被这两个类吃掉了。

实现层里，我踩过最大的坑是流式响应和工具调用的兼容。有些模型在流式模式下，工具调用的参数是分片返回的，你需要自己拼接。比如一个工具调用，参数是{"city": "上海"}，流式返回可能是{"ci、ty": "上、海"}这样分三次来的。如果不处理，解析就会失败。

我的做法是在流式回调里维护一个缓冲区，按工具调用的 index 分组，每个 index 维护一个参数片段列表，等流结束时再统一拼接解析。这个逻辑不复杂，但如果不注意，线上就会出现"偶尔工具调用失败"的诡异问题，而且很难复现。

另一个坑是超时和重试。模型接口偶尔会慢，偶尔会返回 5xx。我的策略是：连接超时设短一点（比如 5 秒），读超时设长一点（比如 60 秒，因为模型生成确实慢）；重试只对幂等的请求做，而且最多重试两次，重试之间加指数退避。这里要特别注意，带工具调用的请求不要轻易重试，因为模型可能已经"决定"要调工具了，重试可能导致重复调用。

3.2 工具注册：注解加反射的取舍

工具注册我用的是注解加反射的方案。业务方这样写：

@AgentTool(name = "queryOrder", description = "根据订单号查询订单详情") public class QueryOrderTool { @ToolParam(name = "orderId", description = "订单号", required = true) private String orderId; public ToolResult execute() { // 调用后端订单服务 return ToolResult.success(orderService.query(orderId)); } }

启动时，平台扫描所有带@AgentTool的类，解析出工具名、描述、参数 schema，注册到一个全局的ToolRegistry里。运行时，模型返回工具调用请求，平台从 registry 里找到对应的工具类，用反射创建实例、注入参数、执行方法。

这个方案的好处是接入成本极低，业务方不用继承任何基类，不用实现任何接口，加个注解就行。坏处是反射有性能开销，而且编译期检查弱。参数名写错了，编译不报错，运行时才炸。

为了弥补这个缺点，我加了一个启动期校验：扫描到工具类之后，检查参数 schema 是否合法、必填参数是否有默认值、工具名是否重复。有问题直接在启动时抛异常，不让服务带病上线。这个校验帮我挡掉过好几次低级错误。

实操心得：反射方案一定要配启动期校验。宁可启动失败，也不要运行时才发现问题。生产环境的启动失败是可控的，运行时的偶发失败是灾难。

3.3 上下文管理：裁剪策略决定成本和质量

上下文管理是 Agent 平台里最容易被低估、又最影响效果和成本的模块。模型有上下文窗口限制，对话轮次多了，历史消息必须裁剪。怎么裁，直接决定了 Agent 的"记性"和每次调用的 token 成本。

我实现了三种策略，可以按 Agent 配置。

滑动窗口最简单：只保留最近 N 轮对话。优点是实现简单、成本可控；缺点是会丢失早期的重要信息。适合那种"每轮独立"的场景，比如查询类 Agent。

摘要压缩复杂一些：当历史超过阈值时，调用模型把早期对话压缩成一段摘要，摘要加最近几轮一起发给模型。优点是保留了长期信息；缺点是压缩本身要花一次模型调用，有额外成本和延迟。适合长对话场景，比如客服。

关键信息提取最复杂：从历史里提取出结构化的事实（比如用户 ID、订单号、偏好），单独存储，每次请求时把这些事实作为系统提示的一部分注入。优点是信息密度高、token 省；缺点是需要额外的提取逻辑，而且提取可能出错。适合信息密集的场景，比如多轮填表。

实际用下来，我的建议是默认用滑动窗口，特殊场景再上摘要。关键信息提取虽然理论上最优，但工程复杂度高，除非场景真的需要，否则不划算。

3.4 工具调用的编排：串行、并行还是混合

一轮对话里，模型可能一次返回多个工具调用。这些调用怎么执行，是个需要仔细设计的问题。

最简单的是串行：一个一个执行，前一个的结果作为后一个的输入。适合有依赖关系的调用，比如先查用户 ID，再根据 ID 查订单。缺点是慢，N 个调用就是 N 倍时间。

并行快，多个调用同时执行。适合无依赖的调用，比如同时查三个不同城市的天气。但并行有风险：如果工具之间有隐式依赖，或者共享资源，并行可能出问题。

我的方案是默认串行，允许工具声明自己可以并行。工具类上加一个@AgentTool(parallelizable = true)的标记，平台看到这个标记，就把多个可并行的调用放到线程池里跑。这样既保证了默认安全，又给了优化空间。

这里有个细节要注意：并行执行的结果顺序。模型返回的工具调用是有顺序的，并行执行完，结果必须按原顺序组装回消息里，否则模型会困惑。我的做法是给每个调用分配一个 index，结果按 index 排序后再组装。

3.5 权限与审计：企业场景的硬要求

企业内部工具，权限和审计是绕不过去的。BizBuddy 在这块的设计原则是：权限校验在工具执行前，审计日志在工具执行后。

权限校验分两层。第一层是用户级：这个用户有没有权限使用这个 Agent。第二层是工具级：这个 Agent 有没有权限调用这个工具，以及这个用户通过这个 Agent 调用这个工具时，数据范围是什么。第二层是关键，因为同一个工具，不同用户能查的数据范围可能不同。

我的实现是给工具加一个@ToolPermission注解，声明需要的权限码。执行前，平台从当前会话里取出用户身份，调用公司的权限中心校验。校验不通过，直接返回错误，不执行工具。

审计日志记录每一次工具调用：谁、什么时候、通过哪个 Agent、调用了哪个工具、参数是什么、结果状态如何、耗时多少。这些日志异步写到审计系统，不阻塞主流程。参数里如果有敏感信息，比如身份证号、手机号，要在写日志前脱敏。

注意：审计日志的脱敏一定要在写入前做，不能指望下游系统脱敏。下游系统可能有很多个，你控制不了每一个。敏感信息一旦落盘，就是合规风险。

4. 常见问题与排查实录

4.1 模型"幻觉"调用不存在的工具

这是上线初期最常见的问题。模型有时候会"编"一个工具名出来，比如实际工具叫queryOrder，它返回getOrder。平台找不到这个工具，就会报错。

排查思路：先看模型返回的原始内容，确认工具名到底是什么。如果确实是模型编的，说明工具描述不够清晰，或者工具太多导致模型混淆。

解决方法有三个层次。第一，优化工具描述，让名字和描述更明确，减少歧义。第二，减少单次暴露的工具数量，如果一个 Agent 挂了 20 个工具，模型很容易选错，可以按场景拆分 Agent。第三，加一层容错，工具找不到时，不直接报错，而是返回一条"工具不存在，可用工具列表如下"的消息给模型，让它重新选择。第三层是兜底，前两层才是根本。

4.2 工具调用参数解析失败

模型返回的参数是 JSON 字符串，有时候格式不合法，比如多了个逗号、少了引号、或者类型不对（该是数字的给了字符串）。解析失败，工具就没法执行。

我的处理是宽松解析加类型转换。JSON 解析用宽松模式，允许一些常见的不规范写法。解析出来之后，按工具声明的参数类型做转换，字符串转数字、数字转字符串都支持。转换失败才报错。

另外，参数校验要给出明确的错误信息。不要只说"参数错误"，要说"参数 orderId 期望是字符串，实际收到的是数组"。明确的错误信息，模型看到之后往往能自己纠正，重新发起调用。

4.3 会话状态丢失或错乱

这个问题比较隐蔽，通常出现在多实例部署或者服务重启之后。表现是：用户发现 Agent"失忆"了，或者回复的内容对不上之前的对话。

排查思路：先确认会话状态存在哪里，内存还是 Redis。如果是内存，多实例部署时请求被负载均衡打到不同实例，状态自然对不上。如果是 Redis，检查 key 的过期时间设置，以及序列化反序列化是否正常。

我的经验是，会话状态一定要有版本号。每次更新状态，版本号加一。读取时如果发现版本号比预期低，说明状态是旧的，要么拒绝使用，要么触发重新加载。这个机制能挡掉大部分状态错乱问题。

4.4 高并发下的性能瓶颈

压测的时候发现，并发一上来，响应时间飙升。用工具分析，瓶颈通常在两个地方：模型调用和工具执行。

模型调用是外部依赖，你控制不了它的速度，能做的是连接池复用和合理的超时设置。连接池要够大，但也不能无限大，否则会把模型服务打挂。超时要设，但不能太短，否则正常的长回复会被误杀。

工具执行如果是 IO 密集的，用线程池隔离，避免一个慢工具拖垮整个平台。线程池的大小要按工具类型分别设置，查询类工具可以大一点，写操作类工具要小一点，避免并发写导致数据问题。

4.5 常见问题速查表

5. 一些踩坑之后的经验总结

5.1 关于"纯 Java"这件事的再思考

项目做完回头看，纯 Java 这个选择是对的，但代价确实比预想的大。最大的代价不是写代码本身，而是生态缺失带来的隐性成本。比如做一个向量检索，Python 那边几行代码的事，Java 这边要自己封装客户端、处理连接、做序列化，工作量翻了好几倍。

所以我的建议是：如果你的团队 Java 底子厚、存量系统多，纯 Java 值得；如果团队更熟 Python、存量系统少，没必要为了"统一技术栈"硬上 Java。技术选型要看团队的实际能力，不要被"纯"这个字绑架。

5.2 关于 Agent 平台的边界

做这个项目最大的收获，是搞清楚了 Agent 平台不该做什么。它不该替代业务系统，不该承担核心交易逻辑，不该做模型训练。它的定位就是一层"自然语言交互层"，把已有的能力用更自然的方式暴露给用户。

想清楚这个边界之后，很多设计决策就顺了。比如工具执行失败，平台不该自己重试业务逻辑，而应该把失败信息返回给模型，让模型决定怎么办。再比如数据权限，平台不该自己维护一套权限体系，而应该复用公司已有的权限中心。

5.3 关于可观测性

上线之后，可观测性的重要性远超我的预期。Agent 系统的不确定性比传统系统高得多，同样的输入，模型可能给出不同的输出，工具可能因为各种原因失败。没有足够的日志和埋点，出了问题根本无从下手。

我的做法是每个环节都打点：模型调用打了、工具调用打了、上下文裁剪打了、状态读写打了。日志里带上 traceId，一次请求的所有日志能串起来。这些埋点在开发阶段看起来是负担，上线之后是救命的。

5.4 最后分享一个小技巧

如果你也在做类似的平台，我强烈建议先做一个"最小可观测闭环"：一个最简单的 Agent，一个最简单的工具，一套完整的日志。先让这个闭环跑通，再往上加功能。不要一上来就设计大而全的架构，那样很容易陷入"设计三个月，写代码三天，改架构三个月"的循环。

BizBuddy 的第一版，核心代码不到两千行，但日志、埋点、错误处理一样不少。正是这个"小但完整"的底子，让后面加功能变得很顺。这个经验，我觉得比任何架构图都值钱。