做企业级 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 的取舍逻辑用生态换可控性我在技术选型时列过一张对比表核心是在“开发速度”和“生产可控性”之间做权衡。方案优势企业级隐患直接调 Python Agent 框架社区丰富、Demo 跑得快跨语言部署、链路追踪断档、内存管理不可控微服务包装 Python Agent语言解耦网络开销大、状态同步复杂、运维两套体系纯 Java 自研 Harness全链路统一、JVM 工具链现成需要自己补 Agent 框架缺失的轮子最后选了“纯 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 里是这样跑的接口层收到请求校验租户身份和基础参数。编排层创建一个 TaskInstance初始状态是 PENDING。调度器把 TaskInstance 分配给某个空闲的 AgentRuntime 实例。执行层开始跑 Agent 主循环把用户输入和系统提示词组成上下文调用 LLM Provider得到一次 Response。如果 Response 里有工具调用请求执行层去 ToolRegistry 里找对应的工具执行并把结果追加到上下文中。重复第 4 步直到模型输出最终答案或达到最大迭代次数。状态落库触发回调通知业务方。这个模型的灵感来自于对消息队列消费者的理解——任务不是阻塞等待模型返回而是像消息一样被消费、被推进。每个节点执行完都要持久化一次状态这样即便 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 { CompletableFutureLlmResponse 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 AgentToolTInput, TOutput { TOutput execute(TInput input); String toolName(); ClassTInput 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. 实操过程从搭建骨架到跑通第一个 Agent4.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 搭建一个最简单的 AgentRuntimeAgentRuntime 是执行层的核心类它负责跑 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 报表走定时任务汇总。说实话这些库没有一个是“必须”的核心逻辑都是自己写的。选型的唯一标准就是团队熟不熟——学习成本最低、排障最顺手的就是好选择。有一次我为了追求新技术引入了一个不常见的缓存客户端结果线上出问题时团队成员没人熟悉它的行为排查