1. 为什么企业需要一个 Agent Harness而不是一堆 Agent 框架1.1 从一次线上故障说起前不久我们内部做了一个工单自动分诊的 Agent上线后不到一个月就出现了一个很典型的事故两个业务小组分别实现了两个 Agent一个是销售助手负责回答“最近跟单情况”会调用 CRM 查询接口另一个是客户画像补全负责分析历史订单也会调 CRM。两个 Agent 各写各的代码各用各的 API Key权限模型完全不一样。某个下午 CRM 上游锁表销售助手先超时了然后它的重试逻辑不区分场景硬重试了三次客户画像那边没有降级直接把上游数据库连接池打满。最后整个销售系统的接口都变慢排查的人翻了两套日志才发现是两个互不相干的 Agent 在互相放大故障。这个案例特别典型它说明的其实不是“Agent 不够聪明”而是缺少企业级的基础设施把 Agent 的调用边界、超时策略、权限、观测都统一管理起来。这也是我做 BizBuddy 的直接动机与其让每个业务线在 Agent 框架上各自发挥不如做一个统一的运行时平台也就是标题里说的 Agent Harness。1.2 Harness 与 Agent 框架的本质区别很多人第一次听到 Agent Harness会以为它是又一个 LangChain 或者 AutoGen。这两个概念确实容易混淆但它们解决的问题层次完全不同。Agent 框架解决的是“模型怎么思考、怎么用工具”核心是 Chain、Memory、Tool Calling 这些编排逻辑。而 Agent Harness 解决的是“这些 Agent 怎么被安全稳定地运行”核心是生命周期、治理、可观测、故障恢复。如果拿汽车来类比框架是发动机Harness 是底盘、座舱、刹车和仪表盘。你可能先造出了发动机但没有刹车和仪表盘你不敢让它上路。我在实际设计 BizBuddy 时刻意把这两个层次分开框架层面的东西可以选型、可以替换但 Harness 层面的东西必须自己做因为它和企业的运维体系、权限体系、审计要求深度绑定。维度Agent 框架LangChain4j / Spring AIAgent HarnessBizBuddy核心问题让模型能推理、能调用工具让 Agent 能被运维、被治理关注层次单个 Agent 的智能能力多 Agent、多业务线的统一运行生命周期较弱通常只存在于内存中强每个 Task 可恢复、可追踪权限与审计基本不负责要自己去管原生设计每次调用都有记录典型使用人应用开发者平台 / 基础设施团队1.3 企业级四个关键词我在企业里落 Agent 服务最忌讳一个词玩具化。所谓企业级在我这里是由四个关键词撑起来的稳定、可控、可观测、可审计。稳定是指超时、重试、熔断、降级这些高可用手段一个都不能少Agent 不是实验脚本它是生产链路的一部分。可控是指工具白名单、权限模型、模型路由都要有运维入口不能让研发在代码里写死。可观测是指日志、指标、链路追踪能跟现有业务监控打通出了事能在同一个 Grafana 里看。可审计是指每次模型调用、每次工具调用都要留痕能追溯到人、时间和完整上下文。BizBuddy 的所有设计都是围着这四个关键词转的。后面讲的架构和实现细节也都是从这四个词倒推出来的。2. 纯 Java 选型的动机与代价不跟风 Python 生态的底气2.1 AI 功能只是订单系统里的一个环节很多团队在讨论要不要用 Python 写 AI 服务时忽略了一个事实在企业系统里Agent 并不是独立软件它是订单、CRM、工单这些业务系统里的一个环节。我们的核心服务都是 Java / Spring Boot 写的Agent 需要直接调用这些系统的内部 API、读写数据库、发消息。如果用 Python 写 Agent就意味着公司要在 Java 之外再维护一条 Python 服务链路Python 的依赖管理、部署、日志体系、监控都要重新搞。对大多数非 AI 公司来说这个成本远比想象高。纯 Java 方案最大的动机不是技术有多先进而是“少维护一条技术线”。这条理由在技术选型评审会上往往比任何性能指标都管用。2.2 为什么不用 LangChain4j 或 Spring AI一开始我也考虑过直接用 Spring AI 或者 LangChain4j。Spring AI 起步快和 Spring 生态集成方便在构建单一 AI 应用的场景下很顺手。LangChain4j 是 Java 社区里比较有代表性的 LangChain 移植版抽象比较全。但真正评估下来它们作为 Agent 框架是合格的作为企业级 Agent Harness还差一截。LangChain4j 的抽象偏“大而全”Chain、Memory、RAG、OutputParser 一应俱全团队不仅要学框架本身的思路还要花力气砍掉不需要的部分。Spring AI 则偏应用开发面向多 Agent 的应用编排、审计体系、工具权限控制这些 Harness 层面的能力基本上要自己另外搭。我们最终选择自研 BizBuddy不是因为别人不行而是想按自己的场景定义边界核心只做 Harness 的事情把模型调用、工具管理、生命周期这些抽象做到够用且可控而不是把一个大而全的框架引进来再做减法。维度Spring AILangChain4j自研 BizBuddy起步速度很快较快慢需要先做基础架构治理能力弱弱原生设计工具管理基础注解支持较灵活可定制权限、审计、幂等多 Agent 编排较弱有但偏框架层围绕 Task / Step 显式建模学习成本低中中等但内部可控2.3 纯 Java 的技术代价与补偿方案客观说一句微软 OpenAI SDK 的官方生态、LangChain 的精巧设计大部分都是 Python 优先这是事实。但 Java 生态也有自己的方法论来补偿LLM 本质上就是 HTTP SSE JSONJava 的 WebClient、虚拟线程、Jackson 这套组合在并发和稳定性层面反而有优势。工具调用本质上就是把模型的 JSON 输出映射到 Java 方法调用这种强类型映射是 Java 的强项。我们要注意的不是 Java 能不能做而是别把 Python 的 Agent 抽象直接搬过来。Python 那套 dict 加动态调用的风格在 Java 里应该用 record、SPI、注解、反射去重新建模才符合 Java 工程的习惯。3. BizBuddy 的核心架构把 Agent 当成组件来管理3.1 模块划分harness-core / runtime / adapter / consoleBizBuddy 目前分成四个 Maven 模块边界划分是经过几次重构后定下来的harness-core核心模型、抽象接口、工具注册、生命周期定义。不依赖任何 Web 框架方便单元测试和复用。harness-runtime运行引擎负责 Task 执行、编排、状态机、故障恢复。内置可插拔的调度器。harness-adapter接入不同模型、向量库、存储的适配层比如 OpenAI 兼容协议、通义、DeepSeek、本地 Ollama。harness-console基于 Spring Boot 的管理端提供 Agent 注册、工具管理、任务监控、审计查询等 REST API。之所以把 core 和 Web 框架解耦是为了让核心逻辑可以脱离 Spring 独立测试也能嵌入到非 Spring 的系统里。这个设计让我在后面接不同的业务线时省了很多事。3.2 核心抽象Agent、Task、Step、Context在 BizBuddy 里核心模型只有四个Agent、Task、Step、Context。Agent 是静态定义描述一个 AI 助手具备什么能力、用什么模型、能调用哪些工具。Task 是运行单元一次具体执行的完整记录。Step 是任务里的一个原子步骤可能是调用一次模型、调用一次工具、做一个条件分支也可能是等待人工审批。Context 是跨 Step 传递的状态包含会话消息、中间变量、Token 用量。我把 Step 设计成 sealed interface这样编译器就能帮我们穷举所有步骤类型。public sealed interface Step permits LlmCallStep, ToolCallStep, BranchStep, HumanApproveStep { StepId stepId(); }业务上一个 Task 可以由多个 Step 组成。需要人工审批的时候状态机进入 waiting 状态审批通过后继续执行。这样 AI 任务就纳入了和普通流程一样的审批体系。3.3 工具注册与 SPI 插件化机制工具注册是整个 Harness 的核心。每个工具就是一组 Java 方法通过 SPI 或注解自动加载。工具定义包括 name、description、parametersSchema、permissionScope 等元数据。public interface ToolProvider { ToolDefinition definition(); Object invoke(ToolInvocation invocation); }系统启动时扫描 ToolProvider为每个工具动态生成 JSON Schema注册到模型接口。这里有一个很值得注意的点模型给出的 tool_calls 是 JSON 结构我们并不直接反射调用而是在 ToolInvocation 参数里做一层校验和映射防止恶意参数绕过权限检查。这个设计借鉴了云平台 IAM 的思想模型没有权限概念它只负责生成输出真正的权限校验一定在工具调用层强制做不要相信模型“不会调用”某个工具。3.4 会话与上下文状态管理内存为主、数据库兜底每个 Task 的 Context 里存放会话消息、变量、Token 用量。我们采用“内存为主、数据库兜底”的策略Context 在 JVM 内存里有一份方便快速访问每执行完一个 Step就把脏字段写入数据库形成持久化快照。如果 JVM 重启可以从最近的快照恢复任务。这里有个细节值得留意快照里带 version 乐观锁避免并发恢复导致状态覆盖。持久化层我们用 MyBatis-Plus 处理表结构按 agent_id、task_id、step_seq 建索引查询和恢复都很快。4. 落地 Java 时最难啃的五个技术点4.1 LLM 调用的统一抽象与流式响应第一步是定义 ChatClient 接口。两种调用方式必须都支持同步一次性返回和流式增量返回。Java 里流式用 Reactor 的 Flux 比较顺手。public interface ChatClient { ChatResponse chat(ChatRequest request); FluxChatChunk stream(ChatRequest request); }不同模型适配器实现同一个接口。内部都是 HTTP 调用非流式用同步 HTTP流式用 WebClient 的 SSE 接收再转发给前端。前端对话、动态输出这些场景都需要流式所以这个接口值得尽早设计。4.2 工具调用Function Calling的协议转换模型返回一个 AssistantMessage它的 toolCalls 字段是结构化的 JSON比如[{ name: queryOrder, arguments: {\orderId\:\123\} }]。我们需要做三件事第一把 arguments JSON 解析成 Java 对象。第二做参数校验包括类型、长度、白名单。第三调用注册的 Tool 方法把结果包装成 ToolResult 回传给模型。这里最容易出错的点是模型偶尔会生成不合法 JSON比如字符串缺少引号。我们的做法是解析失败时把错误信息直接作为 tool 结果返回给模型让模型自己修正而不是抛出异常中断流程。4.3 超时、重试与熔断策略模型服务的超时和熔断策略必须按 endpoint 单独配置。我建议一组比较稳的初始值连接超时 3 秒读取超时 60 秒。生成式模型响应时间波动大读取超时不能设太短否则容易误杀但连接超时要短避免被网络问题拖死。重试要区分动作类型幂等的读操作重试 2 次非幂等写操作不做自动重试只能人工审批后重试。熔断用 Resilience4j滑动窗口统计最近 30 秒的错误率高于 40% 就熔断 15 秒期间直接返回降级结果。策略项推荐配置连接超时3 秒读取超时60 秒幂等读重试2 次非幂等写重试不自动重试熔断窗口30 秒错误率 40%熔断恢复15 秒后半开4.4 上下文窗口的压缩与截断Agent 长时间对话Token 很容易超出窗口。Java 生态没有 Python 里 tiktoken 那么方便但我们有两个办法一是接入模型的 tokenizer 或官方估算表二是定义统一的 MessageWindow 策略当消息数超过阈值时把旧消息做一个摘要替换进上下文。还有一个容易忽略的点工具返回的内容可能很大我们会对内容长度做阈值控制超限只保留摘要同时在审计表里保存完整结果。这样既不撑爆上下文又不丢证据。4.5 线程模型与连接池Java 21 的虚拟线程对 Agent 场景是很大的优势。一个 Task 对应一个虚拟线程让阻塞的模型调用不再占据昂贵的平台线程。如果你的系统还在 Java 17要么用响应式 WebClient要么把线程池调大但要注意阻塞线程比例不能过高。连接池也要分类隔离LLM 出口连接池、数据库连接池、Redis 连接池要分开配因为一个拖垮了会影响另一个。实测下来LLM 出口最好单独配一个连接池不然模型响应慢的时候会反过来拖垮数据库连接。5. 企业级硬性要求权限、审计、可观测与安全过滤5.1 谁可以调用哪个工具权限模型与强制校验工具注册时就带上 permissionScope比如crm:read、order:write。Agent 定义时声明自己需要的 scope。Task 执行时由 PermissionEvaluator 判断当前用户是否有权限发起这个调用。这个模型借鉴了 IAM 的思想。权限校验一定要在工具调用层强制做不能依赖模型不调用某个工具。因为模型只是生成文本它不理解也不用理解权限边界。public class PermissionEvaluator { public boolean canInvoke(User user, ToolInvocation invocation) { SetString required toolRegistry.requiredScopes(invocation.toolName()); return user.scopes().containsAll(required); } }5.2 每条 prompt 都留痕审计日志怎么设计才可用审计日志是 Harness 平台最容易被低估的部分。我设计的 audit_log 表包含这些字段request_id、user_id、agent_id、task_id、step_id、model、prompt_hash、tool_name、invocation_args_hash、result_summary、latency_ms、token_usage、created_at。为了避免把敏感信息全部落库prompt 和参数只存哈希和脱敏后的摘要。审计日志通过异步队列写入但要注意保持顺序否则同一个 Task 的执行记录会乱掉排查时很难受。这里我强烈建议用 request_id 作为所有日志和追踪的关联键从用户发起请求那刻起就生成贯穿所有环节。这是排查线上问题的基础设施。5.3 敏感信息脱敏输入输出双向过滤在模型输入出口和输出入口分别做过滤。用户资料里的手机号、邮箱在进入 prompt 前就被替换成占位符模型返回的内容也要过一遍检测避免模型生成与隐私相关的输出。Java 实现这一层不复杂核心是定义统一的 SensitiveFilter SPI允许各业务线自己注册脱敏规则。比如营销线要脱敏客户手机号客服线要保留手机号后四位做核对规则不同但框架是同一套。5.4 可观测性指标、日志与链路追踪Micrometer Prometheus Grafana 这条链路在企业里已经很成熟。我们会暴露几个核心指标agent_run_total按 agent 与结果标签、tool_invoke_total按工具与结果标签、llm_latency_seconds直方图、token_usage_total。链路追踪依赖 MDC 里的 requestId 贯穿所有日志这样查问题的时候只要拿到一个 requestId就能看到这个 Task 在所有服务里的完整轨迹。这个对于多 Agent 协作和跨服务调用尤为重要。6. 生产环境实测踩坑记录6.1 流式输出的断线重连与消息游标第一个坑是前端页面刷新后SSE 断掉后端还在继续跑。后来我们改成消息表存完整输出前端重连时通过游标把没有消费的消息重新拉取像读 Kafka 一样。这里的关键是每条消息都带一个自增 seq避免重复展示。断线重连后客户端只需要记住自己消费到哪个 seq从那个位置继续拉就行。这个设计在对话场景里非常实用。6.2 长任务的内存压力与快照恢复有一个每天跑很多次的长任务 AgentContext 里存了大量中间变量在 JVM 里越积越多Young GC 频繁服务响应变差。后来我们把 Context 做快照超过阈值就序列化到存储内存里只留远程引用。这个方案多一次反序列化开销但整体稳定性提升很大。如果任务规模继续涨可以考虑事件溯源把所有状态变更都变成事件流彻底消除内存状态。6.3 重试导致重复副作用的幂等设计模型调用成功但响应丢失时如果直接重试上游可能重复下单。我们给所有写操作工具增加幂等键参数里带一个 requestId stepId写数据库时做唯一约束。这个设计一定要在 Harness 层面做不要依赖各业务线自觉。工具调用记录表加唯一索引重复的 invocation 直接返回上次的结果。幂等键的生成规则是agentId taskId stepId toolName。6.4 几个零碎的工程经验最后分享几个零碎但在生产环境里很关键的细节。模型输出的 JSON 容错必须做。解析失败时不要把异常抛出中断而是把错误信息作为 tool 结果返回给模型让它自己修正。这个策略在处理真实流量时效果很好模型自己修正的成功率很高。Token 计费以模型返回的 usage 字段为准不要用本地估算值对账否则月底账单对不上。前端对话在超时时间内要有 loading 和取消按钮否则用户会重复点击产生重复任务。这个看起来是前端问题但后端 Harness 也得有对应的重复任务检测机制两段都要处理。目前 BizBuddy 已经在内部支撑了三个业务线的 Agent 场景包括工单分诊、销售助手、知识库问答。我个人最大的体会是Harness 平台的价值不在于把 Agent 变得多智能而在于让 Agent 像普通接口服务一样被管理、被恢复、被审计。很多团队自研的时候容易把精力花在 prompt 和 tool 设计上反而忽略了生命周期和治理这些不那么出彩但至关重要的部分。如果你也打算在 Java 技术栈里搭类似的平台我的建议是先做最小闭环一个 Agent、两个工具、一套审计跑通后再加编排和熔断不要一上来就追求大而全。