Java企业级Agent Harness平台设计与落地实践

讲真，这两年聊 Agent 的人特别多，但真正能在企业里落地的很少。我在团队里做了个纯 Java 的 Agent Harness 平台，代号 BizBuddy。所谓 Harness，不是说它又一个聊天机器人框，也不是把某个 Python 编排框架搬到 Java 上来。它更像一个 Agent 的“驾驶舱”和“运行底座”：负责把大模型、企业存量系统、人的审批、审计日志全部串起来，让智能体能稳定、可控地替代一部分固定流程。今天这篇文章就把 BizBuddy 的设计取舍拆开来讲，重点不是炫技，而是那些你在选型文档里看不到的坑和手感。

先说结论：如果你的团队也是以 Java 为主，想在企业里做 Agent 落地，又不想被某个框架的抽象绑死，完全可以自己搭一个精简 Harness。别怕“重复造轮子”，关键是知道自己要造哪几个轮子。下面会从项目背景、整体架构、核心实现、落地取舍、踩坑记录五个方面展开，适合正在做企业级 AI 应用的 Java 工程师参考。

1. 为什么要做 Harness：Agent 缺的不是模型，而是骨架

1.1 我们的起点：一堆脚本和没人敢接手的“智能体”

事情要从一次内部需求说起。那段时间业务方频繁提同一类诉求：能不能用自然语言查订单状态、改工单、发起审批流程，而不是每天在多个后台系统里来回点。我们最初的做法很直接，把大模型接进来，给每个场景写一个 Prompt 模板，再在 Controller 里硬编码调用一些 Service。做了两三个 demo，效果还行，但问题很快就暴露了：模型输出一不稳定，整个流程就崩；工具逻辑和 Prompt 混在一起，加一个新场景要复制一大段代码；最要命的是，没人能说清楚 Agent 刚才调了哪个接口、花了多少钱、为什么这么干。这样的情况，业务方根本不敢把权限放出来。

后来我们意识到，真正缺的不是“又聪明一点的模型”，而是一个能承载 Agent 运行、编排工具、记录过程、控制权限的平台。当时也调研了几个现成的开源方案，Spring AI、LangChain4j 也看过，可用性不错，但放到我们的企业环境里还是有点别扭：我们的服务要接内部统一登录、要走公司现有的审计通道、要接一堆老系统的 HTTP 接口，这些“脏活”还是要自己写。与其在一个框架的边界内到处打补丁，不如自己抽出一个足够小而稳的运行时内核，于是 BizBuddy 立项了。

1.2 Harness 到底是个什么东西

先把这个概念掰开。如果按功能拆，一个完整的 Agent 应用可以分成四层：模型层、智能体层、工具层、平台层。市面上大量开源框架主要解决模型层和智能体层，它们帮你定义 Agent、Chain、Tool 这些抽象，让你快速搭一个 Agent 应用，但不太关心运行时的稳定性、可观测性、权限和多人协作。Harness 强调的恰恰是后两块：它是一个“能一直跑”的底座。

打个比方，框架像是给你一套乐高积木，你能拼出各种 Agent；Harness 则更像实验室里的操作台，它规定了你在哪个区域做实验、废液倒哪里、实验结果记录在哪本册子上。BizBuddy 的定位就是操作台，而不是某个具体的积木套装。我们内部也有业务开发者基于它做“查单助手”、“工单处理专员”，但这些都只是平台上跑的一个 Agent 配置加一组工具。

1.3 适合谁、不适合谁

如果你所在团队是 Python 技术栈，那很多内容不需要参考 Java 实现；如果你们只是想做一个几十个并发用户的内部小工具，也完全没必要搞一套 Harness，直接用现成框架就行。BizBuddy 这套思路适合的场景是：并发量上百、有权限和审计要求、Agent 要调用很多内部系统、需要灰度发布和故障回滚的企业环境。说白了，就是 Agent 要变成“企业正式员工”，而不是“临时实习生”的时候，Harness 的价值才体现出来。

2. 整体架构：BizBuddy 的五个核心模块

设计 BizBuddy 时，我没有把它做成一个大而全的中间件。核心思路是“最小主体 + 可扩展点”。整个系统可以划分为：模型网关、工具注册中心、任务调度引擎、记忆管理、安全审计与回放。下面分别讲每个模块的职责和关键抽象。

2.1 核心概念：Task、Session、Context

在代码里，最上层的是 AgentTask。一个 Task 代表一次用户请求，比如“查一下 A 客户最近的订单状态”。连接多个 Task 的是一次 Session，也就是一段持续对话，Session 里会维护历史上下文。每个 Task 执行时会创建 AgentContext，它有点像 Servlet 里的 RequestContext，存放当前会话的用户信息、工具列表、已经执行过的步骤、可用的内存存储等。

这三个抽象分开是有原因的。Task 和 Session 分离是为了应对一个现实问题：用户可能在一天内发起多个任务，但每个任务又长又独立。比如一个 Agent 在处理“批量生成对账报告”时，用户又发来一个“查询流程进度”的消息，这两者不能互相打架。Context 则保证了每个任务里的状态都是隔离的，不会出现多个任务共用变量导致数据串掉的情况。这一点在下面的 Java 实现中尤为重要，因为平台是并发执行任务的。

public record AgentTask( String taskId, String sessionId, String userId, String input, Instant createdAt ) {} public final class AgentContext { private final String taskId; private final String sessionId; private final String userId; private final Deque<AgentStep> steps; private final ToolRegistry toolRegistry; private final MemoryBlock memory; }

2.2 模块职责一览

这些模块之间的关系是：用户请求进入 PlanExecutor，PlanExecutor 在循环中调用 ModelGateway 获取模型决策，模型决定要调用哪个工具，然后 PlanExecutor 从 ToolRegistry 拿到对应的 ToolAdapter 去执行真实业务调用，执行完毕后写回 MemoryManager，再继续下一次模型决策。整个循环中间产生的关键事件，都会被 SecurityAudit 记录下来。

2.3 为什么坚持纯 Java

这是个被反复问的问题。从技术上，大模型相关的生态确实 Python 更丰富，但企业落地不只有模型调用这么一件事。我们的存量系统是 Java 的，注册中心、配置中心、监控系统、链路追踪都是 Java 体系的。如果引入一个 Python 侧 Agent 服务，首先要解决跨语言调用、独立部署、两套监控的问题，这已经足够把一个项目拖垮。

纯 Java 的另一层考虑是运行时可控。Java 的虚拟线程、并发工具、强类型系统，非常适合做这种状态机加工具调用的活。我们用 Java 17 + Spring Boot 3 起步，核心模块不依赖 Spring，只在接入层用 Boot 的自动配置。这样既保留了纯 Java 的可测试性，也能让团队里的老 Java 工程师快速上手。虚拟线程对 Agent 这种大量 IO 等待型任务非常友好，后面会细说。

3. 核心实现：从一个任务进入到最终输出

3.1 Agent 主循环与状态机

BizBuddy 的执行核心是一个状态机，而不是传统的“调用链”。状态枚举大致是：PENDING、PLANNING、TOOL_CALLING、TOOL_WAITING、OBSERVING、COMPLETED、FAILED、TERMINATED。任务的流转逻辑很简单：先解析用户意图，然后用模型生成计划或直接指定要调用的工具，接着进入工具调用阶段，拿到结果后再回到 PLANNING，直到模型认为不需要调用工具，任务就进入 COMPLETED。

这里有几个细节直接决定了体验。一是整体迭代次数必须限制，我们默认 20 步，防止模型抽风无限循环。二是每一个工具调用都有独立的超时时间，工具整体超时默认 30 秒，特殊工具可配置到 5 分钟。三是状态迁移必须判空和幂等，同一个 taskId 的并发回调不能导致状态错乱。这几个约束看着简单，但如果没有状态机做约束，很容易在调试时发现 Agent 已经“精神分裂”。

public enum AgentState { PENDING, PLANNING, TOOL_CALLING, OBSERVING, COMPLETED, FAILED, TERMINATED }

主循环类似这样：拿到用户输入 → 判断是否需要调用工具 → 如果需要，从决策结果中解析出 toolName 和 parameters → 找到 ToolAdapter 调用 → 把观察结果拼进 messages → 继续循环。在 Java 里，我习惯用一个受控的 while 循环加状态记录器，而不是用递归，因为递归在超长上下文或高并发下很容易出问题，而且排查栈也费劲。

3.2 ToolRegistry：把企业系统变成 Agent 的工具

这是企业级 Harness 里最重要的一部分。Agent 能不能干实事，完全取决于工具注册和调用链路是否靠谱。我们用注解加自定义描述的方式定义工具。使用者只需在一个类中写一个方法，打上@AgentTool(name = "queryOrderById", description = "根据订单ID查询订单基本信息")，参数对象用 Java Bean 描述，框架会自动生成 JSON Schema 供模型读取。

真实世界里的工具往往不是 REST API 那么干净。有的是老系统暴露的 SOAP 接口，有的是需要先调用 token 接口拿临时凭证的，有的是要传文件流处理的。为了隔离这些差异，ToolAdapter 做一个适配层，把 ToolInvocationRequest 转成外部系统能理解的调用，再把返回结果统一包装成ToolResult。内部会做异常捕获、超时重试、结果截断。结果截断特别重要，否则一个大查询返回几万行数据，一次模型调用直接让 token 费用爆表。

public interface ToolAdapter { ToolDescriptor descriptor(); boolean supports(ToolInvocationRequest request); ToolResult invoke(ToolInvocationRequest request); }

3.3 ModelGateway：不能让模型供应商绑死平台

我们并不绑定某一个具体模型。ModelGateway 抽象出 ModelClient 接口，支持同步补全、流式补全、Function Calling 三种模式。底层默认实现的是 OpenAI 兼容协议，对接国内几个云厂商模型时只需要改 baseUrl 和鉴权参数。这样做的好处是：一个 Agent 在灰度阶段可以用便宜的小模型验证链路，正式上线切到更强的模型，只改配置即可。

在处理模型输出时，必须做防御式解析。模型返回的 function call 参数不一定合法 JSON，经常是多一个逗号、少一个引号。我们先用 Jackson 解析，解析失败就进入“自纠错”流程，把原始字符串交给一个轻量模型修正，同时计入一次重试。这里不能粗暴重试 3 次，因为每次都烧 token，通常一次修复足够。

3.4 MemoryManager：记忆不只是聊天记录

在很多框架里，Memory 就等于聊天记录的数组，但企业 Agent 的“记忆”要更复杂。至少有三类：会话历史、业务状态、长期事实。会话历史好理解，业务状态指比如“当前正在处理的订单 ID”、“已经发送过的审批通知”，长期事实则比如用户的常用供应商列表、部门审批链。我把这些统一放进 MemoryBlock，每个 Agent 通过 Key-Value 写入。序列化统一用 JSON，因为 Java 对象直接存内存容易出现版本升级后反序列化失败的问题。

上下文压缩也是 MemoryManager 要管的。一个任务执行 20 步，每步都带上之前所有工具结果，很快就超过模型上下文窗口。我们在每次模型调用前检查 token 估算，超过阈值就把较早的消息做摘要。摘要消息本身也是一次模型调用，因此要设置成本上限。宁可让 Agent“忘掉”一些旧细节，也不能让上下文超限导致任务中断。

3.5 可观测性设计：每一步都可以回放

没有日志和追踪，对一个 B 端 Agent 来说等于没有质量。BizBuddy 里每个 Task 执行都会生成一个 Trace，包含多个 Span，每个 Span 对应一次模型调用或一次工具调用。关键日志要记录：模型请求的输入输出（脱敏后）、工具的参数和返回摘要、耗时、token 消耗、错误堆栈。

这里特别强调脱敏。有些查询业务会传入用户名、手机号、合同金额，这些字段如果在日志里明文出现，就是合规事故。我们实现了一个字段级脱敏器，在日志写出去之前根据敏感字段配置进行掩码处理，比如手机号只显示后四位。除此之外，审计事件单独落入独立的审计表，不与应用业务日志混在一起，便于安全团队抽查。

4. 企业级落地中的关键取舍

4.1 同步执行还是异步事件流

Agent 任务很可能耗时几十秒甚至几分钟。如果做成同步 HTTP 接口，网关超时和用户体验都会出问题。我们最终选择了异步事件流的方式：用户提交任务后，立即返回 taskId；前端通过 Server-Sent Events 或 WebSocket 订阅任务状态变化；任务每完成一个步骤，就推一个事件给前端。

看起来增加了一些复杂度，但这个取舍换来了两个实际收益：一是用户可以感知到 Agent“正在干什么”，而不是干等；二是平台在任务执行过程中能随时终止或人工介入。对企业场景来说，允许用户随时停止失控任务非常重要。

4.2 状态存储：内存态和持久态之间怎么权衡

一开始我们天真地想：所有状态放内存，既快又简单。结果一次发布重启，几百个进行中的任务全部丢失，群里被业务方连环提问。后来改成“先持久化，再执行”的策略，任何状态迁移都会写入 Redis，任务的关键节点记录到关系型数据库。Redis 主要存当前执行状态和上下文快照，关系库存任务元数据、执行历史、审计事件。

这个改动带来的额外工作不多，但收益很明显。任务执行到一半系统重启，下次启动后可以强制标记为“中断”，而不是让用户认为任务还在跑。如果 Agent 本身具备恢复能力，还可以从最近一个安全节点重试。

4.3 插件化边界：哪些扩展点要开放

做平台的人都容易犯一个毛病：什么都想做成 SPI，结果一大堆抽象反而把自己套住。BizBuddy 只开放了四个扩展点：ToolAdapter、ModelClient、MemoryStorage、EventListener。规则引擎、流程编排、拖拽画板、多租户商城这类功能统统不在核心范围内。理由很简单：扩展点越多，测试矩阵越大，团队学习成本越高。一个企业级工具的价值，不在于它能做所有事，而在于它把核心事做得足够稳、足够透明。

4.4 模型调用与并发治理

大模型接口和其他后端服务有一个显著区别：它可能很慢，而且对并发十分敏感。如果 Agent 在一次执行中需要连续做 10 次模型调用，那么 50 个并发用户就会给模型网关带来 500 个并发请求，很容易触发限流。所以我们用信号量限制每个 Agent 实例的最大并发模型调用数，并给每次模型请求设置超时。服务端返回 429 或超时后，采用指数退避重试，而不是固定间隔重试。

同时，在模型网关前加了一层熔断器。某个模型服务连续 5 次失败就熔断 30 秒，这期间任务直接失败并抛出清晰提示，而不是让所有任务都排队等待慢请求超时。这样单个模型故障不会拖垮整个平台。

5. 实战排查：我踩过的坑和一些技巧

5.1 模型“能对话但不会调工具”：参数 Schema 的坑

我自己遇到过最诡异的问题：模型明明能正常聊天，但一到 function calling 就频繁漏参、传错类型。后来排查发现，问题不是模型太傻，而是工具注册信息太糟糕。我一开始把参数定义成嵌套对象，字段名也和内部编码一致，模型根本猜不到每个字段是干什么的。

解决办法是尽量让工具参数扁平化、语义化，给每个参数写清楚“示例值”，并把参数个数控制在 5 个以内。比如不要传"customerId": "8492034"，而是传"customerNo": "V000188"。这种微调对准确率提升很大。如果模型还不稳定，就在调用前加一层参数校验，不合法就不送进工具执行。

5.2 工具调用死循环和重试风暴

Agent 在工具调用失败后会尝试自己修正，这是好事，但也可能变成灾难。最典型的是：数据库查询超时，工具返回“timeout”，模型不但不道歉，反而又构造了一个类似请求，再次调用，连续重试 10 次，把后端数据源打挂。我们把单次 Agent 循环的最大工具调用次数设定为 8 次，同时工具返回体里附带了可机器读取的错误类型，比如RETRYABLE和FATAL。模型看到 FATAL 时，应该停止补救并直接向用户说明失败原因，而不是继续尝试。

5.3 虚拟线程下的连接池保险丝

Java 21 虚拟线程很香，但别把所有任务都往上放。在一次压测中我们发现，工具执行大量阻塞型 JDBC 调用时，虚拟线程虽然本身几乎没有成本，但底层数据库连接池却被吃满了。原因很直接：虚拟线程数量可以很高，JDBC 连接数却有限。于是我们在工具执行层做了一个全局并发闸门，一次允许的工具调用并发数不超过配置值，默认是 20。这样既保留了异步编排的流程，又不会把下游资源打爆。

5.4 长任务的上下文泄漏

有段时间老有任务“突然开始胡说八道”，日志里显示模型每一轮都把之前所有工具结果原样传给模型，token 数一路上涨。追问下来才发现，MemoryManager 的压缩只对“会话历史”生效，却漏了“业务状态”里的长对象。比如某步骤把一个 200 KB 的报表对象写进 MemoryBlock，之后每一步都带上它。解决思路是对 MemoryBlock 的 Value 也做规模上限，超过阈值时自动转换为摘要引用，需要完整数据时再通过专门的工具去取。

5.5 测试与模拟：先减少真实模型调用

我们内部维护了一个MockModelClient，可以按配置返回固定的工具调用序列。大多数链路测试根本不连真实模型，而是模拟模型“决定调用 X 工具”以及“最终不再调用工具”的两种典型分支。只有到了联调阶段才切到真实模型。这么做每年能省不少 token 费用，而且跑回归测试也快，不至于每次都在 API 调用上排队。

6. 个人经验：起步别做太满

按我目前的使用体验，BizBuddy 最有价值的模块是 ToolRegistry 和 SecurityAudit，其次是状态机和 MemoryManager。如果你也想在企业里做 Agent Harness，我建议先别急着把模型网关、数据中心、工作流编排都集成齐。找一个真实场景，比如“查询订单进度”或“生成周报”，先把任务状态机和工具注册打通，让 Agent 能在真实系统里跑一遍闭环，再逐步加可观测性和记忆管理。

还有一个很实用的小技巧：在设计阶段就把“步骤记录”当成第一等公民。很多 Agent 项目跑着跑着就变成了黑盒，等出了问题，只能靠截图问用户“刚才发生了什么”。如果早早在工具调用层把每步参数、响应、耗时落盘，后续不管是排查、优化还是给管理层展示 RoI，都会轻松很多。BizBuddy 现在内部有个“任务回放”页面，能看到某个任务每一步的模型思考摘要、工具调用的入参和出参，对推进企业落地的说服力远超一堆指标图表。