1. 为什么我要用纯 Java 去啃 Agent Harness 这块硬骨头第一次听到“Agent Harness”这个词很多人脑子里冒出来的第一反应是 Python。原因很简单过去两年几乎所有关于智能体编排、工具调用、多轮推理的示例代码默认语言都是 Python生态里现成的库一抓一大把。我在项目立项的时候也犹豫过是不是顺着大流走用 Python 快速搭一个原型出来先跑通再说但真正把需求摊开来看之后我放弃了这条路。BizBuddy 这个平台的定位不是“跑个 Demo 看看效果”而是要塞进企业已有的业务系统里和现有的权限体系、审计日志、消息队列、定时任务、监控告警这些东西长在一起。企业里跑着的核心服务绝大多数是 Java 写的运维团队熟悉 JVM 的调优和排障安全团队对 Java 生态的依赖扫描和漏洞治理有成熟流程。如果我硬塞一个 Python 运行时进去等于凭空多出一套需要单独维护、单独监控、单独做安全合规的技术栈。这个隐性成本远比“Python 写起来快”那点收益要大。所以 BizBuddy 的核心约束从一开始就定死了纯 Java 实现不引入任何非 JVM 的运行时依赖。这里的“纯 Java”不是指不能用第三方库而是指整个 Agent Harness 的调度、推理循环、工具注册、状态管理、并发控制全部跑在 JVM 上用 Java 语言和 JVM 生态的组件来完成。这个决定带来的取舍贯穿了整个项目后面每一节我都会具体讲。先说说 Agent Harness 到底是个什么东西免得后面聊得太抽象。你可以把它理解成智能体的“操作系统内核”。一个智能体要干活需要几件事接收任务、规划步骤、调用工具、观察结果、决定下一步、直到任务完成或者放弃。Harness 就是把这套循环管起来的那层框架。它不负责“智能”本身——智能来自背后的大模型——它负责的是把模型的输出变成可执行的动作把动作的结果喂回给模型并且在中间加上超时、重试、限流、审计、权限校验这些企业级必须有的东西。BizBuddy 要解决的核心问题是让业务团队能够用自然语言描述一个任务平台自动拆解成若干步骤调用企业内部已有的 API、数据库查询、文件处理等能力最终把结果交付出来。听起来和市面上很多“智能体平台”差不多但企业级这三个字意味着完全不同的要求一次工具调用失败不能把整个任务搞崩敏感操作必须走审批每一步都要留痕可追溯并发上来之后不能把下游系统打挂。这些才是真正花时间的地方。这篇文章我会把 BizBuddy 从设计到落地的关键取舍讲清楚包括为什么选 Java、Harness 的循环怎么设计、工具注册怎么做、状态和并发怎么管、企业级的安全和审计怎么嵌进去。如果你也在做类似的事情或者正在纠结技术选型希望这些踩过的坑能帮你少走点弯路。2. 把 Agent 循环拆开看Harness 到底管哪几件事2.1 一次任务执行的完整生命周期在动手写代码之前我花了大概两周时间把“一个任务从进入到结束”的全过程画在了白板上。这个动作看起来笨但极其重要。因为 Agent Harness 最容易出问题的地方不是某个单点功能没实现而是状态在多个环节之间传递时丢了或者串了。一个任务在 BizBuddy 里的生命周期大致是这样的用户提交任务描述Harness 创建一个 TaskContext里面装着任务 ID、用户身份、权限范围、超时预算、已用步数、对话历史、中间产物。然后进入主循环每一轮做四件事把当前上下文和可用工具列表发给模型模型返回一个动作调用某个工具或者给出最终答案Harness 校验这个动作是否合法、是否有权限、是否超出预算合法就执行把结果写回上下文进入下一轮。直到模型给出最终答案或者触发终止条件步数耗尽、超时、连续失败。这里有个关键设计点Harness 不信任模型的任何输出。模型说“我要调用删除用户接口”Harness 不会直接执行而是先过一遍策略引擎。策略引擎检查这个用户有没有删除权限、这个操作是不是在高危名单里、当前任务是不是已经超过了允许的步数。只有全部通过才真正执行。这个“不信任”原则是企业级和玩具级的分水岭。2.2 为什么循环控制不能交给模型自己很多人做 Agent 的第一版喜欢让模型自己决定“我还要不要继续”。模型说“我完成了”循环就结束。这个做法在 Demo 里没问题在生产里是灾难。原因有三个。第一模型会“幻觉完成”。它可能只做了一半就自信地说任务搞定了尤其是任务步骤比较多的时候。第二模型没有成本概念。它不知道每次调用工具都要花钱、花时间、占用下游资源可能会无休止地重试。第三模型无法感知外部约束。比如下游系统已经限流了模型还在那儿一个劲地调。所以 BizBuddy 把循环的终止权牢牢握在 Harness 手里。模型可以“建议”结束但最终是否结束由 Harness 根据预算、步数、错误率来判断。具体来说每个任务创建时会带一个maxSteps和deadline每轮循环开始前检查超了就强制终止并返回当前已有的中间结果。这个设计让任务执行变得可预测运维团队能算出最坏情况下一个任务会占用多少资源。2.3 上下文窗口的取舍全量塞进去还是做摘要Agent 循环里最容易被低估的问题是上下文管理。每一轮都要把历史发给模型历史越长token 消耗越大而且模型在超长上下文里的表现会下降。BizBuddy 一开始的做法是“全量保留”结果跑复杂任务时 token 成本高得吓人而且模型开始忽略早期的关键指令。后来改成了分层策略。最近 N 轮对话完整保留更早的历史做摘要压缩只保留关键决策和中间产物的引用。中间产物本身不塞进上下文而是存在外部存储里上下文里只放一个句柄模型需要时再通过工具去取。这个改动让单任务的 token 消耗降了大概六成而且模型的表现反而更稳定了。这里有个实操心得摘要压缩不要用另一个模型调用去做成本高且不稳定。我们用的是规则化的摘要——保留每轮的工具名、关键参数、结果状态码丢掉冗长的原始返回。对模型来说知道“查了订单表返回成功有 3 条记录”比看到完整的 JSON 更有用。3. 纯 Java 技术栈的选型每一层为什么这么定3.1 运行时与并发模型的选择既然定了纯 Java接下来就是具体选型。运行时用标准 JDK版本跟着企业现有基线走不追最新。并发模型这块我纠结了一阵最终选了虚拟线程加结构化并发的思路但做了降级兼容——如果运行环境不支持就退回线程池。为什么是虚拟线程因为 Agent 任务的本质是大量 IO 等待等模型返回、等工具执行、等数据库查询。传统线程池在这种场景下要么开太大导致内存爆要么开太小导致吞吐上不去。虚拟线程让每个任务可以独占一个“轻量线程”写代码时是同步阻塞的风格心智负担小底层却能支撑很高的并发。这对 Harness 这种“每个任务一个执行流”的模型特别合适。但这里有个坑虚拟线程不是银弹。如果工具执行里有 synchronized 块或者用了 ThreadLocal 做重活虚拟线程的优势会被抵消甚至出现“钉住”问题。所以 BizBuddy 在工具执行层强制要求不允许在工具实现里用 synchronized共享状态一律走无锁结构或者显式的锁对象。这条规矩写进了工具开发规范里。3.2 工具注册与发现机制工具是 Agent 的手脚。BizBuddy 里一个“工具”就是一个可以被模型调用的能力单元比如“查询订单”“发送通知”“生成报表”。工具注册机制我设计成了注解加注册中心的模式。开发者写一个工具类加上BizTool注解声明工具名、描述、参数 schema。平台启动时扫描这些注解把工具元信息注册到中心的 ToolRegistry 里。模型看到的工具列表就是从 ToolRegistry 里按当前用户权限过滤出来的。这个过滤很关键——不同角色的用户能用的工具不一样财务能用的工具和客服能用的工具必须隔离。工具的描述文本description是给模型看的直接决定模型会不会正确调用。我在这上面踩过坑一开始描述写得太简略模型经常选错工具。后来定了个规矩每个工具的描述必须包含三要素——这个工具做什么、什么场景下用、参数怎么填。写清楚之后工具选择的准确率明显上来了。3.3 模型接入层的抽象模型接入这块BizBuddy 没有绑定任何一家。抽象出了一个ModelClient接口核心方法就是“给一段消息历史返回一个动作”。不同模型厂商的差异——请求格式、流式返回、function calling 的字段名——全部在各自的实现类里消化掉。这样做的好处是企业可以根据成本、合规、效果在不同任务上选不同的模型。比如简单的意图识别用小模型复杂的规划用大模型。Harness 层完全不关心背后是谁只认ModelClient接口。这个抽象也让测试变得容易写个假的 ModelClient 返回预设动作就能把整个循环跑起来做单元测试不用真的去调模型。层次选型核心理由运行时标准 JDK跟随企业基线降低运维成本并发虚拟线程 结构化并发IO 密集场景吞吐高代码风格简单工具注册注解 注册中心声明式权限过滤方便模型接入接口抽象 多实现不绑定厂商便于测试和切换状态存储关系库 对象存储事务可靠中间产物不占库4. 企业级能力怎么嵌进 Harness 的骨架里4.1 权限校验为什么必须放在工具执行前企业环境里权限是红线。BizBuddy 的权限模型分两层一层是“用户能不能用这个工具”另一层是“这次调用的参数是否越界”。第一层在工具注册中心过滤时解决第二层必须在执行前实时校验。举个例子一个“查询客户信息”的工具客服角色可以用但只能查自己负责的客户。这个“只能查自己的”约束光靠工具列表过滤是做不到的必须在执行时拿到当前用户身份和请求参数做一次数据级的校验。BizBuddy 把这层校验做成了可插拔的ToolGuard接口每个工具可以挂自己的守卫逻辑。守卫不通过直接返回拒绝模型收到拒绝后可以选择换个方式或者放弃。注意权限校验一定要在工具真正执行之前完成不能先执行再检查。有些团队图省事先调了接口再判断结果该不该给模型看这是很危险的因为副作用已经产生了。4.2 审计日志要记到什么粒度审计这块我的原则是“宁可多记不可漏记”。BizBuddy 对每一次工具调用都记一条审计记录包含任务 ID、用户、工具名、参数摘要、执行结果状态、耗时、模型给出的调用理由。参数摘要不是完整参数敏感字段要脱敏但结构要保留方便事后追溯。为什么连“模型给出的调用理由”都要记因为在排查问题时经常需要回答“模型当时为什么这么决策”。有了理由字段复盘时能看出是模型理解错了还是工具描述有歧义还是上下文丢了关键信息。这个字段在早期排障阶段帮了大忙。审计日志的存储用的是追加写的关系表不做更新和删除。查询走独立的只读副本避免影响主流程。日志量大的时候按任务 ID 分片保证单任务的所有记录能快速捞出来。4.3 限流、熔断与降级在 Harness 层的统一处理下游系统是有限的Agent 的调用欲望是无限的。BizBuddy 在 Harness 层统一做了限流和熔断而不是让每个工具自己实现。每个工具可以配置自己的 QPS 上限和并发上限Harness 在执行前检查令牌桶超了就排队或者直接拒绝。熔断的逻辑是某个工具连续失败达到阈值短时间内直接拒绝所有调用给下游喘息时间。模型收到“该工具暂时不可用”的反馈后可以选择走备用路径或者告知用户稍后再试。这套机制让整个平台在下游抖动时不会雪崩这是企业级和 Demo 级的又一个分水岭。降级策略也做在了 Harness 层。比如某个任务配置了“主模型不可用时切备用模型”这个切换逻辑不需要工具或业务代码关心Harness 在调用模型失败时自动走备用。这种横切关注点集中在 Harness 里业务开发者就不用重复造轮子。5. 状态管理与并发控制最容易翻车的地方5.1 TaskContext 的设计与不可变性TaskContext 是整个 Harness 里最核心的数据结构也是最容易出并发问题的地方。我的做法是TaskContext 本身尽量不可变每次状态变更产生一个新的快照。这样多个线程读同一个上下文时不会互相干扰也不需要加锁。具体实现上TaskContext 里放的是不可变集合和值对象。每轮循环结束时基于旧上下文生成新上下文写回任务的状态存储。这个“写回”是带版本号的乐观锁版本对不上就重试。这样即使同一个任务被意外并发处理也能保证状态不会错乱。这个设计有个代价内存里会短暂存在多个上下文快照。但实测下来单个上下文的大小是可控的因为中间产物存在外部这点内存开销换来的是并发安全非常值。5.2 长任务的断点续跑怎么做企业里的任务经常是长任务跑几分钟甚至几十分钟。如果中途服务重启任务不能就这么丢了。BizBuddy 的做法是每轮循环结束都把上下文持久化任务状态标记为“进行中”。服务重启后扫描所有“进行中”的任务从最后一次持久化的上下文恢复继续跑。这里有个细节恢复时不能盲目重跑上一轮的工具调用因为那个调用可能已经产生了副作用。所以上下文里会记录“上一轮动作是否已提交”。如果已提交恢复时直接进入下一轮如果未提交才重新执行。这个“提交标记”是断点续跑正确性的关键少了它就会出现重复下单、重复发通知这类事故。5.3 并发任务之间的资源隔离多个任务同时跑的时候资源隔离很重要。BizBuddy 给每个任务分配了独立的预算——步数预算、时间预算、token 预算。一个任务把预算耗光不会影响别的任务。工具层面的限流是全局的但任务层面的预算是独立的。另外任务之间共享的只有只读的工具元信息和模型客户端其他都是隔离的。这样设计的好处是一个任务出问题比如陷入死循环最多耗光自己的预算然后被终止不会拖垮整个平台。运维团队可以放心地让平台跑大量并发任务不用担心某个坏任务把系统搞挂。问题场景处理方式关键点服务重启从持久化上下文恢复检查动作提交标记避免重复副作用任务死循环预算耗尽强制终止步数、时间、token 三重预算并发状态冲突乐观锁 版本号版本不匹配则重试下游抖动熔断 降级集中在 Harness 层处理6. 实测中暴露的问题与我的应对6.1 模型工具选择准确率不够的排查过程上线初期遇到的最头疼的问题是模型经常选错工具。明明该调“查询订单”它去调了“查询物流”。排查过程分了三步。第一步看审计日志里的调用理由。发现模型对两个工具的区别理解模糊因为它们的描述写得太像了。第二步把工具描述拿出来对比果然“查询订单”写的是“查询订单信息”“查询物流”写的是“查询物流信息”对模型来说几乎没区别。第三步重写描述明确各自的适用场景和参数差异比如“查询订单”强调“根据订单号查订单状态和金额”“查询物流”强调“根据订单号查配送进度和承运方”。改完之后准确率上来了但还没到理想状态。后来又加了一招在系统提示里明确告诉模型“如果不确定用哪个工具先调用一个通用的查询工具确认”。这个兜底策略进一步降低了误调用。6.2 上下文膨胀导致成本失控的修复前面提过上下文全量保留的问题。具体表现是一个跑了二十多轮的任务token 消耗是预期的好几倍而且模型开始“忘事”——早期的关键约束被淹没了。修复方案是分层上下文加外部存储。实现时有个坑摘要压缩的规则一开始写得太激进把一些模型后续需要的细节也压掉了导致任务质量下降。后来调整了规则保留“决策类”信息做了什么选择、为什么压缩“数据类”信息具体的返回内容只留句柄。这个平衡点找了挺久最后是靠对比不同压缩策略下的任务成功率定下来的。6.3 工具执行超时引发的连锁反应有个工具是调外部接口的平时响应很快但偶尔会卡住几十秒。一开始 Harness 没有对工具执行设超时结果一个卡住的任务占着线程不放并发一上来线程池就满了整个平台响应变慢。修复是给每个工具调用加超时超时后中断执行并返回失败。但这里有个细节中断不等于副作用没发生。外部接口可能已经收到了请求只是响应慢。所以超时后的处理要谨慎对于非幂等的操作超时后不能简单重试要标记为“状态未知”让模型决定是查询确认还是放弃。这个“状态未知”的处理逻辑是踩了坑之后才补上的。实操建议所有对外部系统有副作用的工具都要考虑超时和重试的语义。幂等操作可以安全重试非幂等操作必须走“查询确认”路径。这个判断应该在工具元信息里声明让 Harness 自动处理。7. 我对这套架构后续演进的一些想法BizBuddy 跑到现在核心循环和治理能力已经比较稳了。回头看纯 Java 这个决定虽然让初期开发慢了一些但在企业落地阶段省了太多事。运维不用学新东西安全扫描能覆盖性能调优有现成经验这些都是实打实的收益。如果让我给正在做类似事情的人一句建议那就是先把 Harness 的治理能力想清楚再动手写循环。很多人一上来就急着让 Agent 跑起来结果跑通之后发现权限、审计、限流、断点续跑这些全得推倒重来。这些能力不是加在旁边的插件而是长在循环骨架里的后补的代价很大。工具描述的质量怎么强调都不过分。它看起来是文档工作实际上直接决定 Agent 的智商上限。我现在的做法是每加一个工具都要找人实际测几轮看模型能不能正确选、正确填参数不达标就改描述改到达标为止。至于后续我在考虑把工具的组合能力再往上提一层让常用的工具序列能沉淀成“技能”模型可以直接调技能而不是一步步拼工具。这样能进一步降低 token 消耗和出错概率。不过这是下一步的事了当前这套骨架已经能撑住企业里的实际使用。