纯Java构建企业级AI Agent Harness平台：从架构设计到踩坑实战

做企业级 AI Agent 的人，大概都有过这种感觉：模型选型一堆、工具调用一堆、会话状态一团乱麻，最后发现真正难的不是让大模型“开口说话”，而是给这群 Agent 搭一个能稳定、可控、可追溯的“窝”。这个窝，就是 Harness——承载 Agent 运行的基础设施。BizBuddy 这个项目，就是我用纯 Java 折腾出来的一个 Harness 平台，给企业场景下的 Agent 提供统一的运行环境、编排调度和治理能力。

为什么强调“纯 Java”？因为走到企业级这一步，你会发现生态比炫技重要得多。团队里全是 Java 工程师，现有业务系统是 Spring Boot 那一套，安全、审计、监控、配置中心全是围绕 JVM 生态建的——这种情况下硬塞一个 Python 技术的 Agent 框架，等于给自己造了个跨语言的运维噩梦。我最初也试过给 Python 方案做微服务包装，但治理成本实在太高，最后还是决定用 Java 从零搭一个 Harness，把 Agent 生命周期管理、任务编排、工具注册、会话持久化全部收敛进一套代码里。这篇文章就是我把 BizBuddy 从概念到落地过程中的完整设计笔记，包括关键模块的实现思路、做过的取舍，以及几个真实踩过的坑。

这个东西适合谁？两种人最该看：一种是想在现有 Java 技术栈里引入 Agent 能力，但又被各种 Python 方案劝退的团队；另一种是已经在用 Agent，但觉得“单点跑 Demo 没问题，一上生产就失控”的同行。我不会只给你一堆概念，而是把我觉得值得抄作业的代码结构和配置方案都摆出来，配合踩坑记录，尽量让你绕开我走过的弯路。

1. 整体设计思路：先想清楚 Harness 和 Agent 的分工

1.1 Agent Harness 到底解决什么问题

先要把概念收敛一下。Agent 本身是“会思考的调用者”——它接收任务，拆解任务，调用工具，根据结果决定下一步动作。但单个 Agent 在企业级场景里几乎不能直接暴露给业务方，因为没人能保证它的行为稳定、可重试、可审计、可限流。Harness 的定位就是这中间的一层：Agent 只负责“决策”，Harness 负责“让决策安全地发生”。

具体拆开，BizBuddy 做了这几件事：

• 生命周期管理：Agent 实例的创建、预热、暂停、销毁，全部由 Harness 统一控制，不允许业务代码里 new 一个 Agent 就跑。
• 任务编排：把“用户说一句话”变成“一个可跟踪的任务”，任务里有节点、有状态、有超时、有重试。
• 工具治理：Agent 能调用哪些工具，由 Harness 的注册中心说了算，而不是让模型自己瞎编函数名。
• 状态持久化：多轮对话和长流程任务的中间状态，落到存储里，服务重启不丢上下文。

打个比方，Agent 像是一位能力很强的员工，Harness 则是这家公司的管理制度和工作台。没有 Workbench，员工能力再强也用不安全——你不知道他今天会干什么、干了什么、干到一半跑了怎么办。BizBuddy 就是给 Agent 配套的这套 Workbench。

1.2 纯 Java 的取舍逻辑：用生态换可控性

我在技术选型时列过一张对比表，核心是在“开发速度”和“生产可控性”之间做权衡。

最后选了“纯 Java 自研”，核心原因是：AI 应用最大的不确定性在模型输出，而不在编程语言。既然模型输出的解析和兜底是必须自己写的，那语言本身的生态优势就能把其余部分填平。Java 这边的超时控制、熔断限流（比如 Resilio 类的库）、配置管理、监控埋点，都是几十年沉淀下来的成熟方案，直接搬进 Harness 里就能用。

更重要的是团队心智。招一个懂 LangChain 的 Python 工程师容易，但让整个 Java 后端团队学会维护一套 Python Agent 服务，成本远超预期。纯 Java 方案意味着：所有后端工程师都能 review Agent 编排代码，所有已有监控告警体系都能无缝接入，所有安全审计规范都沿用现有流程。这是纯 Java 最大的红利——它不是技术上最激进的，却是组织上最平滑的。

1.3 适用范围与目标读者

BizBuddy 不是要做成大而全的 PaaS 平台，它更偏向一个“企业内部的 Agent 运行底座”。它适用的场景包括：智能客服工单助手、内部知识库问答机器人、定时数据分析和报表生成 Agent、IT 运维自动化助手等。这些场景有一个共同点：流程相对稳定、需要对接企业内部系统、对安全审计有明确要求。

如果说你的场景是“让 Agent 自由探索开放式问题，结果对不对无所谓”，那 Harness 的治理能力反而是束缚。但企业场景里，结果正确性和过程可追溯性永远排在第一位。所以这篇文章更适合那些正在把 Agent 从 Demo 推向生产环境的团队。

2. 架构设计：模块拆分与任务运行机制

2.1 核心分层：从 API 到模型调用

BizBuddy 整体分成四层，每层职责单一，层与层之间只通过接口通信：

• 接口层：对业务方暴露 HTTP/消息队列接口，统一接收任务请求，不做业务逻辑。
• 编排层：负责把任务请求解析为 DAG 或状态机，决定 Agent 按什么顺序执行哪些节点，以及节点间数据如何传递。
• 执行层：真正调用模型、执行工具、解析输出。这一层也是 Harness 的核心，后面会重点展开。
• 治理层：横切关注点，包括权限校验、限流、审计日志、监控指标、配置管理等。

分层的好处是边界清晰。我最开始也犯过把所有逻辑塞进一个 Service 的错，结果改动任何一块都要回归全部功能。后来按这四层重构后，编排层的逻辑可以单测，执行层的模型调用故障不会污染编排状态，治理层的策略调整也能独立发布。

2.2 运行时模型：一个任务的生命周期

一个任务在 BizBuddy 里是这样跑的：

1. 接口层收到请求，校验租户身份和基础参数。
2. 编排层创建一个 TaskInstance，初始状态是 PENDING。
3. 调度器把 TaskInstance 分配给某个空闲的 AgentRuntime 实例。
4. 执行层开始跑 Agent 主循环：把用户输入和系统提示词组成上下文，调用 LLM Provider，得到一次 Response。
5. 如果 Response 里有工具调用请求，执行层去 ToolRegistry 里找对应的工具，执行并把结果追加到上下文中。
6. 重复第 4 步，直到模型输出最终答案，或达到最大迭代次数。
7. 状态落库，触发回调通知业务方。

这个模型的灵感来自于对消息队列消费者的理解——任务不是阻塞等待模型返回，而是像消息一样被消费、被推进。每个节点执行完都要持久化一次状态，这样即便 JVM 崩溃，重启后也能从最近的状态快照继续，而不是全部重来。

关于任务状态的代码示意：

public enum TaskState { PENDING, RUNNING, WAITING_TOOL, COMPLETED, FAILED, TIMEOUT }

这里有一个我强烈建议处理的细节：把 WAITING_TOOL 单独列出来。因为工具调用往往是耗时操作（HTTP 请求、数据库查询、文件处理），如果不和 RUNNING 区分开，超时控制和监控告警会失准——你分不清 Agent 是在思考还是卡在工具调用上。

2.3 上下文管理：让 Agent 记住“它刚才在干什么”

上下文管理会在一个长任务里被反复使用。Agent 的多轮决策本质上就是在和上下文对话——模型靠历史信息判断下一步动作。BizBuddy 没有用无限拼接历史消息的“笨办法”，而是做了有损压缩和结构化记忆：

• 短期上下文：当前任务节点内的模型往返消息，保留原始格式。
• 长期记忆：关键结论、已完成的工具调用结果摘要、用户偏好等，存入向量库或 KV 存储。
• 上下文窗口监控：实时计算 token 占用，接近模型上限时自动触发摘要压缩策略。

有人会问，为什么不用 LangChain 那套记忆模块？因为企业内部的数据往往不在“对话历史”里，而在业务系统里——比如工单状态、客户信息。BizBuddy 的记忆设计更接近“工作记忆”，它会主动去业务系统拉取当前任务需要的数据，拼进上下文，而不是仅仅记住“上次说了什么”。

这个机制在纯 Java 里实现其实不难，核心是一个 ContextWindow 类，内部维护消息列表和 token 估算器。每次新增消息时都会触发估算，超过阈值就调用摘要器，把早期消息压缩成一条 Summary。这个过程对业务方完全透明。

3. 核心模块设计与实现要点

3.1 LLM Provider 网关：把“换模型”变成配置项

企业级平台绝不能把模型写死在代码里。BizBuddy 做了一个 LLM Provider 抽象层，所有模型接入都通过它。这样，业务方可以在配置中心指定当前任务用哪个模型、哪个版本，甚至按流量切分不同的模型。

核心接口设计如下：

public interface LlmProvider { CompletableFuture<LlmResponse> chatAsync(LlmRequest request); String providerName(); }

不同模型服务商各自实现这个接口，内部再去做协议适配。目前我接入了 OpenAI 兼容协议、国产模型服务、内部自研模型三套 Provider，切换只需要改一行配置。

这里要重点说超时和重试。LLM 调用的延迟分布很不稳定，有时候 5 秒返回，有时候 60 秒没动静。BizBuddy 对 Provider 做了三档超时控制：

• 首字节超时（比如 15 秒）：超过后直接断掉，判定为故障。
• 整体超时（比如 60 秒）：超过后终止任务，进入回调逻辑。
• 流式空闲超时（比如 30 秒）：流式输出中间停留过久，同样终止。

重试策略也不是无脑重试。对于鉴权错误（401/403）直接抛错不重试；对于限流错误（429）做指数退避，最多重试 3 次；对于超时错误只重试一次，因为重试第二次往往同样超时。

3.2 Tool 体系：类型安全的工具注册与参数校验

Agent 本身不直接执行操作，它只能“请求”执行操作——这个请求会转成 Tool 调用。BizBuddy 的 Tool 体系设计上参考了类反射框架的思路：每个工具是一个 Java Bean，通过注解和泛型定义自己的输入输出结构。

public interface AgentTool<TInput, TOutput> { TOutput execute(TInput input); String toolName(); Class<TInput> inputType(); }

这样设计的好处是：工具的参数校验可以在 Java 层完成，不必把类型安全寄托在模型的 JSON 输出上。模型返回一个 tool_call 后，BizBuddy 会根据 inputType 做 JSON 反序列化，如果字段缺失或类型不对，会直接把解析错误回传给模型，让模型自己纠正——而不是让工具层抛异常。

工具注册中心维护了一个全量工具清单，包含租户可见性配置。某个租户能用哪些工具、每日调用配额是多少，都由治理层控制。每次工具调用都会记录审计日志：谁在什么时间调了哪个工具、参数是什么、返回值是什么。这一点在企业落地时几乎是刚需——出了事故可以回溯，合规审计也有据可查。

我实测过，工具数量超过 30 个以后，模型的选择准确率会明显下降。解决办法是在系统提示词里做工具分组摘要，而不是把所有工具描述一次性全塞进去。比如先把“工单查询”“工单创建”“工单修改”归为“工单操作组”，只描述组的功能和关键字段，等模型决定要用哪个组时，再下发组内的详细工具列表。

3.3 会话管理：多租户隔离与状态持久化

BizBuddy 的会话设计和普通聊天机器人不一样——它不仅要记住聊了什么，还要记住任务执行到哪一步了。会话状态我分成三层：

• Meta 层：会话 ID、租户 ID、创建时间、关联业务对象 ID。
• Context 层：模型消息历史、上下文摘要、当前任务 DAG 节点位置。
• Data 层：Agent 从各业务系统拉取的数据快照。

这三层分开存储。Meta 存在关系型数据库，Context 存在 Redis（支持 TTL 自动清理），Data 层因为可能很大，通常放在对象存储或独立缓存里。为什么分开？因为三者的访问频率和一致性要求完全不一样。Meta 需要强一致，Context 允许秒级延迟，Data 层只要最终一致就行。

多租户隔离是硬性的，不能等出问题再补。我在架构上直接让每个租户拥有独立的 Context 命名空间，Redis key 都带租户前缀，数据库表也有 tenant_id 分片字段。工具调用权限按租户维度绑定，模型调用配额按租户维度统计。

3.4 安全与审计：企业级硬门槛

现在做 AI 应用，安全问题不能等上线后再补救。BizBuddy 在安全这块做了五件事：

• Prompt 注入防护：对所有外部输入做注入模式检测，一旦命中高置信度的攻击模式，直接终止任务并告警。
• 工具调用白名单：模型只能调用注册中心里已授权的工具，硬编码的拒绝策略优先于任何模型意图。
• 敏感信息脱敏：日志输出和链路追踪里自动过滤手机号、身份证号、密钥等字段，防止通过调试日志泄露。
• 审计日志：任务全生命周期留痕，包括模型输入输出摘要（不存全文，只存 hash 和关键片段）、工具调用明细、操作人信息。
• KMS 密钥管理：所有模型服务的 API Key 不落磁盘明文，统一走密钥管理服务解密。

有一条经验值得单独说：审计日志不要把完整模型输入输出都存下来，既占空间又有泄露风险。我最后的设计是存“结构化字段 + 内容 hash”，原始内容只保留 7 天，过期自动清理。这样既满足追溯需求，又把隐私风险降到最低。

4. 实操过程：从搭建骨架到跑通第一个 Agent

4.1 项目搭建与模块命名

BizBuddy 是标准的多模块 Maven 工程，模块划分如下：

bizbuddy-parent ├── bizbuddy-api // 对外接口定义 ├── bizbuddy-core // 编排、执行、运行时核心 ├── bizbuddy-provider // LLM Provider 实现 ├── bizbuddy-tools // 内置工具集 ├── bizbuddy-admin // 管理端接口与任务监控 └── bizbuddy-common // 通用工具、上下文模型、审计组件

这样做的好处是依赖关系清晰。业务方只需要依赖 bizbuddy-api，不必关心核心实现；新增一个工具只需要在 bizbuddy-tools 里加类，不影响其他模块。我第一次搭的时候图省事把所有代码塞在一个模块里，结果工具类增加后编译时间直线上升，拆分模块后不仅编译快了，代码 review 也轻松很多。

4.2 搭建一个最简单的 AgentRuntime

AgentRuntime 是执行层的核心类，它负责跑 Agent 主循环。简化版实现思路如下：

public class AgentRuntime { private final LlmGateway llmGateway; private final ToolRegistry toolRegistry; private final int maxIterations = 10; public TaskResult execute(Task task) { ContextWindow context = task.getContext(); for (int i = 0; i < maxIterations; i++) { LlmResponse response = llmGateway.chat(context.toMessages()); if (response.hasToolCalls()) { for (ToolCall call : response.getToolCalls()) { AgentTool<?, ?> tool = toolRegistry.get(call.getName()); Object result = tool.execute(parseArguments(call)); context.appendToolResult(call, result); } } else { return TaskResult.completed(response.getContent()); } } return TaskResult.maxIterationsExceeded(); } }

这个主循环就是 Agent 的最小内核。后面的复杂设计——并行工具调用、条件跳转、人工审批节点——本质上都是在扩展这个循环。我建议新手先把这个跑通，再慢慢加功能。一上来就搞复杂的编排框架，很容易陷入抽象过度。

跑第一个 Agent 时，推荐先接入一个简单的本地模拟 Provider，返回固定 JSON，避免模型网络问题干扰调试。等主循环稳定了，再切换真实模型服务。

4.3 配置热更新：上生产环境的第一关

BizBuddy 的配置管理借助了配置中心的思路，运行参数全部外置，支持推送生效。我把配置分成三类：

• 静态配置：应用启动参数，如端口、连接池大小。
• 动态配置：模型参数、开关、阈值，支持热更新。
• 租户配置：每个租户单独一份，如模型配额、可用工具列表。

动态配置里最有价值的是“模型参数热更新”——比如线上发现某模型回答质量下降，运维可以直接把 prompt 模板里的某个版本号切掉，无须重启服务。这个能力在故障处理时极其顺手。

不要把所有配置塞一个文件里。我的经验是：按模块拆分，模块自己监听自己需要的配置，避免一处变更导致全部 Bean 刷新。一开始我图省事用了一个全局配置类，结果每次改动都会触发大量 Bean 重建，后来按模块拆分后稳定多了。

4.4 可观测性建设：从链路追踪到 Token 计费

Agent 应用的可观测性和普通接口完全不同。普通接口看 QPS、P99 就够，Agent 任务还需要看：任务走到哪个节点了、模型推理占了多少时间、工具调用占了多少时间、Token 烧了多少、哪个环节失败率最高。

BizBuddy 在关键路径上埋了以下几类指标：

• 任务指标：任务总量、成功率、失败率、平均轮次、平均时长。
• 模型指标：每次调用的延迟、Token 消耗、超时次数、重试次数。
• 工具指标：调用量、错误率、平均耗时。
• 业务流程指标：任务到达哪个节点后开始大量流失，哪个工具最容易被模型误选。

链路追踪采用标准 trace 范式，一个任务 = 一个 trace，每次模型调用和工具调用 = 一个 span。瀑布图一看就能定位：是模型响应慢，还是工具执行慢，还是编排逻辑卡住了。

Token 计费要单独说。企业内部用 Agent 必然涉及成本分摊，BizBuddy 对每次模型调用都记录了模型名、输入 token 数、输出 token 数、租户 ID、任务 ID，汇总后就是一个完整的成本账单。没有这一步，老板问“这套系统一个月烧多少钱，哪个部门烧得最多”的时候，你只能哑口无言。

4.5 用虚拟线程重构并发执行

Java 21 的虚拟线程对 Agent 执行模型是很大的利好。Agent 主循环天然是阻塞式的——等模型返回、等工具调用结果——如果用传统线程池，高并发下很快就把线程池耗尽了。我最初用固定大小线程池，压测时 20 个并发就把资源占满，后来切换到虚拟线程，每个任务一个虚拟线程，数量轻松上去，资源开销却小得多。

切换方法很简单，核心改动是把线程池换成：

ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();

这不代表所有地方都能无脑换。虚拟线程适合 IO 密集，不适合 CPU 密集。工具调用里如果包含大量计算任务，还是应该丢到独立的工作线程池去跑。还有一个注意点：虚拟线程不能和 synchronized 混用太多，否则会出现线程钉扎（pinned）问题。我在写工具调用时尽量用 ReentrantLock 或原子类替代 synchronized，实测性能明显更好。

5. 踩坑实录与排查技巧

5.1 模型输出 JSON 格式不稳定

这是做 Agent 平台遇到最高频的问题。模型返回的 tool_call 参数偶尔会是非法 JSON，或者字段名悄悄变了。刚上线的时候我直接让 Jackson 反序列化，经常抛异常。

解决方案分两层：

• 解析层做容错：先走严格模式，失败后走宽松模式（允许未闭合引号、乱序字段），再失败就把原始输出回传模型，让它自己修正。
• 定义层做约束：在工具定义里把枚举字段列全，减少模型自由发挥的空间。

这条规则适用于任何“模型输出不能稳定遵循格式”的场景，核心思想是宽容处理和反馈纠错，而不是指望模型永不犯错。

5.2 流式输出缓冲区 OOM

做流式输出的时候，我把所有文本块先塞进内存再统一返回，结果高并发下出现内存溢出。原因是流式交互里每个任务至少攒了几百个小文本块，同时在线用户一多，内存直接爆了。

后来改成背压式传递：模型流式吐出的每个文本块，直接推给下游响应器，不在 Harness 层做聚合缓存。只在需要完整内容做处理时（比如摘要生成），才显式开启收集模式。

5.3 工具执行超时没兜底，导致任务挂死

有一段时间线上偶尔出现任务卡住的现象，查了很久才定位到：某个工具调用外部系统 API，没有设置超时，对方服务假死时连接一直挂着，导致整个任务停在那里。后面给工具调用统一加了超时控制和线程中断机制，任何工具执行超过配置时间都会被强制终止，并记录超时异常。这条处理对生产系统至关重要——工具执行是最不可控的环节，外部系统随时可能出问题，必须有兜底。

5.4 JVM GC 停顿导致模型响应超时误判

还有一个比较隐蔽的问题：GC 长停顿会导致模型调用计时超时，触发重试。但其实是服务端自己停顿了，不是模型服务故障。

解决办法是把超时判断的计时器放在独立监控线程上，统计业务耗时和真实耗时两个维度。如果真实耗时远大于业务耗时，说明可能是 GC 或调度延迟，这类超时不计入模型故障率，也不触发重试。

5.5 会话并发提交的竞态问题

当同一个会话同时来了两个用户请求时，两个任务同时读写上下文，会导致状态覆盖。现在做了一层会话级锁：同一个 sessionId 的任务在编排层排队执行，不同会话的任务可以并行。这个坑上线前自测很难发现，多用户真实使用后才会暴露。建议在架构设计阶段就把会话并发模型想清楚。

6. 工具选型：聊一聊几个核心依赖

最后说说用到的关键库和选型理由。

• HTTP 客户端：模型调用和大部分工具调用都是 HTTP 交互，选择了成熟度高、支持 HTTP/2 和连接池的 OkHttp。需要流式响应时，OkHttp 的 SSE 支持也很完善。
• JSON 处理：Jackson 依然是 Java 生态里最稳的选择。除了基本序列化，我还用它的 JsonNode 做了模型输出的容错解析，配合自定义 DeserializationProblemHandler 效果很好。
• 任务调度：需要定时触发 Agent 任务的场景，我引入了轻量级的任务调度框架，支持 cron 表达式和分布式锁。
• 配置管理：早期用 Spring Cloud Config 那一套，后来觉得对 Agent 场景过重，直接换了轻量配置中心，推送能力够用且部署简单。
• 可观测性：OpenTelemetry 协议统一收集链路数据，标准 trace 格式直接对接现有监控系统。指标导出用 Prometheus 协议，Cost 报表走定时任务汇总。

说实话这些库没有一个是“必须”的，核心逻辑都是自己写的。选型的唯一标准就是团队熟不熟——学习成本最低、排障最顺手的就是好选择。有一次我为了追求新技术引入了一个不常见的缓存客户端，结果线上出问题时团队成员没人熟悉它的行为，排查