很多人一开始做 AI Agent以为难在“让模型答对”真正落到企业级才发现难的是“让 Agent 在业务系统里稳定、可控、可审计地跑起来”。BizBuddy 就是基于这个痛点用纯 Java 从零搭出来的一套企业级 Agent Harness 平台。这个标题里每一个词都不是白给的纯 Java 意味着技术栈选择有明确取舍企业级意味着要对权限、审计、稳定性、成本负责而 Harness 这个词强调的是“运行环境”而不是“应用框架”。这篇文章主要面向两类读者一类是正在用 Java 技术栈做 AI 应用的后端工程师另一类是准备在企业内部落地 Agent 平台、但被各种 Python 系方案劝退的架构师。我会把 BizBuddy 的核心设计、关键代码、选择理由和踩坑过程全部分享出来包括那些光看 Demo 永远学不到的生产教训。1. 先搞清楚Agent Harness 到底在解决什么问题1.1 Agent 不是“多轮调接口”单次 LLM 调用是“问答”Agent 是“干活”。它有一个感知-决策-行动-观察的闭环模型决定调哪个工具、传什么参数工具返回结果模型带着结果继续决策直到得出最终答案。这个循环看上去简单一旦放进企业内部就需要回答几个普通 API 不会回答的问题工具调用的副作用怎么回滚模型把参数传错怎么办每个环节审计记录放哪一次任务跑到一半超时算谁的打个比方普通 LLM API 调用相当于你请了个顾问聊完就散场Agent 相当于你雇了个临时员工他要干很多事还要对结果负责。Harness 就是这家公司的“规章制度和人资系统”规定他什么时候能干什么、干错了怎么处理、每一步都留痕。1.2 Harness 和 Framework 是两回事我一直不把 BizBuddy 叫 Agent Framework因为框架决定的是“你的代码怎么写”而 Harness 决定的是“你的 Agent 怎么活”。举个具体的例子市面上一些 Python 系编排框架给你一堆编排好的类和方法让你能快速拼出一个 Agent而 Harness 更像你给攀岩者系的那根安全绳——你自己决定攀爬路线但安全绳决定了跌落时谁能接住你、怎么接。所以 BizBuddy 的重点不在“让开发者更快写出 Agent”而在“让 Agent 在长时间运行中不失控”。它管的是生命周期、状态持久化、工具的权限边界、全链路可观测、流量控制和审计日志。业务代码是 Agent 自己的事BizBuddy 只提供跑道和安全网。1.3 “企业级”这三个字的分量我见过不少团队做 Agent 做成 Demo 很容易一周就能跑通“帮我查库存并下单”但一上生产就散架。企业级意味着权限一个 Agent 能调哪些工具按租户、角色、甚至按单次会话动态授权。审计谁能看到 Agent 做了什么模型读了哪些数据工具改了哪条记录全部可回溯。稳定性单个模型服务商抖动不能拖垮整个流程限流、熔断、降级是标配。成本Token 花在哪儿、每个会话花多少钱、哪个工具最烧钱得有账可算。这些问题和“模型聪明不聪明”没有直接关系但决定了你做的 Agent 到底是个玩具还是生产力工具。BizBuddy 的设计就是把这些企业级命题从“事后补”变成“事前内建”。2. 为什么非要用纯 Java2.1 现实约束Agent 要接的遗产系统全是 Java做技术选型先看要落的土壤。我们企业里的核心系统——用户中心、订单、财务、权限——清一色是 Java 技术栈。Agent 的价值在于能调这些内部系统如果 Agent 平台用 Python 写就得在中间横一个远程调用网关每个工具都要做一层语言边界的序列化和鉴权开发和部署成本直接翻倍。反过来用纯 Java 写 Harness工具就是普通的 Java 方法加上一个注解Agent 可以直接复用现有的依赖注入容器、配置体系、监控埋点甚至同一个进程里就能调内部服务。这是最朴素的理由也是最有分量的理由。2.2 类型系统和 Schema 的一致性Function Calling让模型调用工具的核心是把工具的调用协议以 JSON Schema 形式暴露给模型。Python 这类动态语言也能做但 Java 的类型系统在这个场景有明显优势方法签名天然就是 Schema一个 Java Record 加上字段校验注解就能稳定生成严格的参数结构。模型返回的参数经过反序列化后类型错误在边界上就能被拦下来不会在工具内部炸出莫名其妙的类型转换异常。我用过的动态语言方案参数校验基本靠手写模型一旦给出多一个字段少一个字段就要在代码里到处防御。Java 这边用反射加主流的 JSON 序列化库边界上的解析和校验一次搞定这节省的调试时间不是一星半点。2.3 JVM 的并发与资源模型企业级 Agent 平台是一台“对话和动作的流量引擎”一个运行中的 Agent 实例本质上是一个异步状态机。JVM 的虚拟线程让大规模并发 Agent 会话成为可能——一个会话一个虚拟线程挂起等待模型响应时不占平台线程单机轻松维持几千路会话。加上成熟的线程池、内存管理、监控体系底子比脚本语言厚实得多。老实说Java 在 AI 生态上确实吃亏本地模型推理、向量计算的库都不如 Python 丰富。但 Agent Harness 的大部分任务只是调用远程模型 API、编排逻辑、调内部服务并不需要在本地跑神经网络。真需要本地向量化时起一个 Python sidecar 做专门服务把嵌入计算外包出去完全不影响主链路。这个取舍我后面会专门讲。2.4 选择 Java 的代价清单没有哪个选择是没有代价的。纯 Java 换来的稳定性和集成度也买了几个实实在在的痛点代价说明缓解方式AI 生态工具少分析、评估、调参工具不如 Python主链路保持纯 Java分析类工作放 sidecar样板代码多模型协议适配、Schema 生成需要不少基础设施代码建好抽象层新模型接入只写一个适配器社区示例少网上鲜有“Java 做 Agent 平台”的完整方案内部沉淀最佳实践文档化部署体积大JVM 启动慢、镜像大生产环境常驻进程滚动发布代替冷启动这个表格里的每一项都是我们实际踩过之后总结的。选了 Java就接受它的脾气想办法把短处隔离在核心链路之外。3. 核心抽象Agent、Tool、Memory、EventBus3.1 四件套的职责边界BizBuddy 有四个核心抽象。Agent准确说是 AgentExecutor负责跑模型交互循环Tool 是所有可被模型调用的能力入口Memory 管理上下文EventBus 把生命周期中的关键时刻广播给外围系统。这四个东西边界必须清晰不然就会长成一个大泥球。先说 AgentExecutor。它只管一件事把消息列表交给模型、解析响应、决定继续还是终止。它心里没有业务逻辑不知道“查库存”是什么只负责循环。Tool 是一个统一接口内部可以是一个 Java 方法、一个 HTTP 封装、一个 SQL 查询器但对外只暴露两样东西描述自己“什么时候该用”的 Schema和接收参数执行的入口。Memory 分两层短期记忆就是当前会话的消息窗口长期记忆是会话结束后沉淀下来的摘要和向量索引。EventBus 则把每个环节的钩子交给外部——工具调用前做权限校验调用后做审计落库Agent 回合结束做指标上报。所有横切功能都挂在钩子上而不是写死在主循环里。3.2 Tool 注册中心与模型协议的桥接层这是 BizBuddy 里最核心的一块。设计目标是业务同学写一个方法加个注解这个方法就能被任意模型厂商的 Agent 正确调用不需要关心各家协议的差别。Tool(name queryOrderStatus, description 根据订单号查询订单当前状态适合在用户询问订单进度时调用, params Param(name orderId, type string, required true, description 订单号格式如 ORD-2025-0001)) public String queryOrderStatus(OrderQuery query) { // 内部逻辑调订单服务、做权限校验、脱敏后返回 return orderService.queryShortStatus(query.orderId()); }开发者写的是“带注解的普通方法”BizBuddy 在启动时扫描注册容器里的 Bean反射解析注解生成统一的 FunctionSchema再通过厂商适配层翻译成各家协议。今天接的是某一家的工具格式明天换另一家业务方法一行不改。这个桥接层的价值在真实项目里被反复验证模型厂商的协议改版、参数约束调整都只需要改适配器业务工具全部豁免。反过来如果让业务方直接手写各家 JSON Schema一次协议升级就能让几百个工具同时失效。3.3 编排引擎确定性优先智能让位很多场景不需要模型自己发散思考。比如“订单退款”流程顺序是固定的校验资格、冻结库存、发起退款、通知客户中间一步失败整体回滚。这种流程如果全交给模型自由发挥等于把可靠性交给了掷骰子。BizBuddy 的编排引擎允许用声明式 DSL 定义这种确定流程节点能力复用 Tool流程控制由系统保证。Workflow refundWorkflow Workflow.of(refundOrder) .node(validateNode, validateEligibility) .node(freezeStockNode, freezeStock) .node(refundProcNode, performRefund) .node(notifyNode, notifyCustomer) .onFailure(fallbackNode, notifyOpsManualReview) .enableHumanInTheLoop(performRefund, BEFORE_EXECUTION);这里最值得说的是 Human-in-the-loop涉及资金、数据删除等高危节点流程走到之前会暂停状态落库把审批请求推送给人工。审批通过后流程从暂停点继续不会从头再来。这个能力在 Demo 里没人重视在真实业务里却是上线的硬门槛。没有人工审批环节业务部门根本不可能同意让 Agent 动财务系统。4. 企业级硬指标可观测、安全、稳定性4.1 全链路 Trace一个 Agent 会话一次追踪Agent 调用链很长用户请求 → 多次模型调用 → 多个工具执行 → 内部系统调用。传统按接口维度的日志在这里完全失效你必须把“一次 Agent 会话”当成一条完整的事务来追踪。实现上BizBuddy 为每次会话生成 traceId存放在会话上下文通过日志 MDC 贯穿全程。每次模型调用和工具执行都打印结构化 JSON 日志字段包括 traceId、会话编号、回合序号、模型名、耗时、Token 用量、工具名、入参摘要敏感字段脱敏。我在生产上遇到问题基本只要用 traceId 从日志平台捞一次全链路就能复现 Agent 当时的视角。上线第一天就要盯这些指标我整理成了速查表指标定义警线参考会话完成率跑到终态成功/失败/超时的会话占比低于 95% 要查状态卡死工具调用成功率工具执行无异常占比低于 90% 查协议和权限单会话 Token 成本模型输入输出 token 折算金额异常增长大概率是上下文膨胀平均决策轮数每个会话平均 Agent 循环次数超过 8 轮要审视 Prompt 和工具边界工具出参拒收率模型参数校验失败的次数占比持续高于 5% 说明工具 Schema 写得不清楚4.2 状态持久化与断点恢复企业级 Agent 不能把命挂在内存里。Session 状态、消息窗口、工具中间结果都要能落库。BizBuddy 把每一个 Agent 会话建模成可持久化的状态机每进入一个新的决策回合快照写一次数据库。这样带来的好处很直接进程重启会话不丢、审批暂停后能恢复、甚至可以把线上会话原封不动搬到测试环境回放。这里有个坑要提醒落库的粒度不能太细也不能太粗。每个工具调用都落库写放大严重只落最终答案又无法断点恢复。BizBuddy 的折中是“回合级快照 事件流水”每回合落一条快照工具调用过程以追加事件的形式写流水恢复时用快照加上后续事件重建现场。实测在单机每秒上千会话的压力下这个策略的写入开销可以忽略。4.3 安全设计密钥、越权、SSRF 一个都不能少Agent 的安全基线比普通接口高一个档次因为它调用的是“计算机自主决定要调的工具”。BizBuddy 的密钥管理坚持几个原则密钥不落代码、不落磁盘明文、进程内解密后短存、日志全脱敏。配置中心只存引用运行时通过独立的密钥管理接口校验权限后解码用完立刻从内存清掉。工具的越权防护放在 EventBus 的工具调用前钩子里每次调用都要重新校验当前会话主体的权限而不是在工具内部自己判断。这样做的好处是权限逻辑集中新工具接入不会忘了配权限就裸奔上线。还有一个容易被忽略的是 SSRF。很多 Agent 工具要访问外部 URL一个不小心模型就可能诱导工具去请求内网地址把企业内部端口暴露出来。BizBuddy 对工具的 HTTP 能力做了统一收口协议只允许白名单目标地址强制校验禁止内网网段重定向要二次校验。这个细节在安全评审时是必查项没有它安全组直接打回。4.4 限流、熔断与优雅降级依赖模型服务商的 API就要接受对方随时抖动的现实。BizBuddy 在模型网关层做了一整套流量治理。按租户限流的令牌桶单一模型服务商错误率达到阈值时自动熔断切换到备用模型或降级为“给出提示并引导人工”。重试做指数退避退避间隔带随机抖动避免所有会话同时撞击服务商。这一块最容易被忽略的是“成本熔断”某一个会话因为模型反复出错Token 消耗可能飙升到正常值的几十倍。BizBuddy 给每个会话设置 Token 预算超过预算立即终止循环把半成品状态持久化通知人工介入。没有这层保护一个失控的 Agent 一晚上能把成本烧出一个新台阶。5. 关键实现我不舍得删的几个现场5.1 Agent 主循环短而纯粹这一节给想看代码的读者。BizBuddy 的 AgentExecutor 主循环刻意保持短小确保逻辑可以被任何人一眼看懂public AgentResult execute(AgentSession session, UserMessage initial) { String traceId session.traceId(); MessageWindow window session.window(); window.append(initial); for (int turn 0; turn config.maxTurns(); turn) { if (session.tokensUsed() config.tokenBudget()) { return AgentResult.killed(token budget exceeded, turn); } LLMResponse response modelClient.chat(window.messages(), session.toolSet()); window.appendAssistant(response); if (response.isFinished()) { return AgentResult.finished(response.content(), turn); } for (ToolCall call : response.toolCalls()) { ToolResult result toolRegistry.invoke(call, session.securityContext()); window.appendToolResult(call.id(), result); } } return AgentResult.maxTurnsExceeded(turn); }很多人会在这个循环里忍不住加业务缓存、加特殊分支我劝你忍住。主循环越纯越容易测试越容易在出问题时用思维日志复现。业务逻辑放到 Tool 和 Workflow 节点里主循环保持“模型反馈驱动”的通用骨架。5.2 用注解生成 Tool Schema 的反射实现注解驱动的方法暴露核心是启动期的扫描和解析。实现骨架如下// 扫描阶段找到所有带 Tool 的 Bean 方法 for (Method method : candidateMethods) { Tool ann method.getAnnotation(Tool.class); FunctionSchema schema new FunctionSchema(ann.name(), ann.description(), buildParameterSchema(method, ann.params())); registry.register(ann.name(), new InvokableMethod(method, bean, schema)); } // 调用阶段把模型返回的 JSON 参数反序列化为 Java 类型 Object[] args bindArguments(invokable.schema(), call.arguments(), method); Object result invokable.method().invoke(invokable.bean(), args);这段逻辑短短几十行但要注意两个坑一是方法参数如果是复合类型比如上面的 OrderQuery需要递归解析字段生成嵌套 Schema二是模型偶尔会传错类型边界上要做宽松转换——数字字符串转 Long、缺省字段填默认值转换不了的字段直接作为校验错误返回给模型让模型自己修正重试。这样做实测比直接抛异常有效得多。5.3 带抖动的指数退避重试模型 API 的限流错误、超时错误直接重试往往有效但全员同时重试就是灾难。public T T retry(String opName, SupplierT action) { long delay config.initialBackoffMs(); // 例如 200ms for (int attempt 0; ; attempt) { try { return action.get(); } catch (RetryableException e) { if (attempt config.maxAttempts()) throw e; long jitter ThreadLocalRandom.current().nextLong(delay / 2); logger.warn(retry op{} attempt{} delay{}ms cause{}, opName, attempt, delay jitter, e.getMessage()); sleep(delay jitter); // 基础退避 正抖动 delay Math.min(delay * 2, config.maxBackoffMs()); } } }注意抖动用的是正抖动而不是全抖动避免出现太多短延迟同时打过去。退避上限要封顶我习惯设 30 秒单次会话最多重试 3 次再失败就进熔断不要让一次失败拖住整个会话。5.4 模型供应商适配层前面反复说适配各家协议这里给一个最小的模型网关接口。BizBuddy 定义统一的模型网关入口各家实现负责协议转换public interface ModelClient { ChatResponse chat(ListChatMessage messages, ListFunctionSchema tools); } public class VendorAdapter implements ModelClient { Override public ChatResponse chat(ListChatMessage messages, ListFunctionSchema tools) { Object request buildVendorRequest(messages, tools); // 厂商协议 Object raw httpClient.sendJson(request); // 通用 HTTP 客户端 return parseVendorResponse(raw); // 转统一结构 } }模型网关接口不能绑死任何厂商的字段内部统一用中立的消息结构。各家有各家的工具调用格式、流式与非流式差异、甚至拒绝内容的表达方式这些都靠适配器消化。将来新模型带来新协议接一个适配器就好不会污染业务代码。这个抽象做得越干净后续换模型就越无痛。6. 踩坑实录这些问题都是真实生产教训6.1 模型自作主张传参数上线第一周就遇到模型调用“查询订单”工具时把订单号传成了“用户的账号”调用“发送通知”时把渠道参数传成了错误的枚举值。这类问题根源不是模型笨是工具描述和参数说明不清晰。我们的解法从两层堵第一层工具说明里写清参数来源和格式约束必要时给正反例第二层参数绑定阶段做严格校验校验失败的参数不回源、不执行把一个解释性错误返回给模型。代码层面的处理原则是绝不信任模型给的参数全部校验成功后才有副作用。这个原则写进 BizBuddy 的安全基线谁都改不得。6.2 上下文无限膨胀成本失控Agent 做工具调用时每轮都要把历史消息包括上一轮的工具返回结果重新发给模型。轮数一多上下文增长速度很快Token 成本会突然爆发。我们实际发现某个会话跑了 20 轮单会话消耗了正常值的 30 倍。后来 BizBuddy 支持了消息窗口裁剪超过阈值的历史工具结果自动摘要工具返回结果超过长度限制的直接截断并提示“结果过长已截断”对话超过 N 轮强制触发一次上下文压缩。这些策略不是完美的但配合 Token 预算熔断成本失控的问题基本绝迹。6.3 反射调用的参数绑定翻车Java 反射调方法的参数绑定是个容易翻车的细节。模型返回参数是 JSON反序列化到方法签名时泛型容器、嵌套类型都会各种报错。我们用主流的 JSON 序列化库绑定到方法参数如果参数是普通类型就直接转换是 Record 类型就按构造器参数构建绕开了泛型擦除这个大坑。更隐蔽的问题是工具方法内部抓了异常却把异常信息原样返回给了模型。模型会拿内部异常日志继续分析反而暴露系统细节。BizBuddy 对工具异常做了统一包装对外返回“工具执行失败”和一句话原因内部异常细节只进审计日志。6.4 排查实录速查表最后放一张速查表几乎囊括了我们所有生产事故的现场症状首要怀疑排查动作会话卡死不结束工具调用后模型没有收到结果消息检查 ToolResult 是否追加进消息窗口工具调用成功但结果不对参数绑定错位用 traceId 看入参摘要成本飙升消息窗口膨胀重复发送工具结果检查上下文压缩策略是否生效模型反复重试同一工具工具 Schema 描述有歧义给参数补正反例校验失败返回给模型安全评审不通过工具 HTTP 未走统一网关收口到网关做内网网段拦截服务商 API 抖动拖垮全局没有熔断降级模型网关加熔断和备用模型7. 部署形态与落地节奏7.1 两种部署方式嵌入与独立服务BizBuddy 从一开始就支持两种部署形态。第一种是嵌入模式把 Harness 当作一个库打进现有的业务服务Agent 直接复用原有进程里的依赖注入容器、配置、监控。适合已经有了完整 Java 服务、不想引入新部署单元的团队。第二种是独立网关模式BizBuddy 独立成服务业务系统通过 HTTP 或消息队列来发起 Agent 会话统一收敛模型密钥和审计日志。适合从零建设、有多个业务方共用的平台场景。我们实际是先用嵌入模式跑试点等试点业务稳定后再把公共能力抽出来部署成独立网关。别一上来就追求大而全的平台那会让所有人陷进平台建设而忘了业务价值。先解决一个业务团队的痛再谈平台化。7.2 三段式落地节奏基于 BizBuddy 的经验我强烈建议分三段走。第一段做“查询类”工具给 Agent 接只读接口比如查订单、查库存、查政策风险低适合建立信心。第二段做“修改类但有人工审批”的流程比如退款、改价走 Human-in-the-loop让业务方逐步适应机器干活、人来把关。第三段才能在评估充分后放开“全自动高频”的场景比如自动化报表、批量通知那时候 Agent 的吞吐价值才真正显现。每一段都要配一个评估集把历史真实请求和预期结果沉淀成回归用例每次改动都跑一遍。没有评估集的 Agent 平台永远是摸着黑做优化。最后想说的是做 Agent Harness 这件事最难的不是技术而是克制。克制地把主循环保持简单克制地对外部依赖做隔离克制地不信任每一个模型返回的参数。我踩过几次坑之后现在的习惯是先写安全基线和观测埋点再写业务能力。BizBuddy 这套骨架后续可以继续扩展多 Agent 协作、评估回放、Prompt 版本管理但地基始终是那一圈“企业级”的底线。老实讲纯 Java 不是最时髦的选择但在我们这种靠 Java 吃饭的团队里它是最踏实的选择。
