纯Java打造企业级Agent Harness平台：设计取舍与落地实录

上个月我在公司内部完成了一个挺拧巴的项目：用纯 Java 从零搭一个企业级 Agent Harness 平台，取名 BizBuddy。不是实验室做 Demo 那种智能体壳子，而是要把内部客服、运营、风控这些真实业务里的自动化流程，统一接进大模型驱动的 Agent 体系里，并且要能经受得住生产环境的权限、审计、并发和故障回溯。这篇文章我尽量把设计和取舍讲透，适合后端 Java 工程师、正在做企业级 AI 落地的团队，以及那些在“要不要自研 Agent 平台”之间纠结的朋友参考。

1. 为什么是 Agent Harness？为什么要纯 Java？

1.1 先理清几个概念：Agent 框架和 Agent Harness 的区别

很多朋友一听说“Agent Harness”就觉得跟 LangChain 是一回事，其实两者定位完全不同。LangChain、LangGraph、Spring AI 这类开发框架，核心是给开发者提供编排能力：提示词模板、链式调用、记忆管理、工具调用函数。它们的出发点是“怎么更方便地写一个 Agent 的逻辑”。而 Harness 的出发点是“怎么让写好的 Agent 像一个正经企业应用一样，稳定、安全、可控地一直跑下去”。

我用一个类比解释一下就很好懂了：Servlet 是业务代码，Tomcat 是 Web 容器；LangChain4j 就好比 Servlet API，BizBuddy 要做的则是 Tomcat 那一层。Servlet 写得再好，没有容器替它处理生命周期、线程分配、并发隔离、部署热插拔，它就只能在本地跑一跑，上不了线。Agent 也一样，你在 Notebook 里能跑通，不代表放到企业环境里能扛住权限校验、工具鉴权、会话恢复、限流熔断、全链路追踪这些“无聊但致命”的需求。

所以 BizBuddy 的定位很明确：不打算替代 LangChain 这类开发框架，而是在 Java 企业生态里补上“Agent 运行平台”这块空缺。Agent 的业务逻辑你随便写，平台只负责把它安全地托管起来，暴露成团队可以统一使用的服务。

1.2 为什么偏偏是纯 Java，而不是 Python 全家桶

我当时的备选方案大概有三条：第一条是用 LangChain + FastAPI 搭一个 Python 网关，Java 业务系统通过 HTTP 调用；第二条是等 Spring AI 这类 Java 框架足够成熟之后再上；第三条就是自己写。最终选了第三条，而且明确要求纯 Java，原因很现实。

我们团队和公司基础设施都是 Java 技术栈。订单、商户、库存、风控、财务这些核心系统的 API 全在 Java 服务里，权限体系、登录态、审计日志的规范也都沉淀在 Java 侧。如果用 Python 做一层网关，等于团队要长期养第二套运行时、第二套发布流程、第二套监控体系，就为了用一个 Agent 框架，这个成本在中小型团队里是扛不住的。

还有一个被很多人忽略的点：Java 的静态类型和反射机制，非常适合做“工具协议”的约束和校验。Agent 跟业务系统之间的交互要靠工具调用（Function Calling），每一次调用的参数都必须映射到真实服务的接口签名。Java 可以做到工具方法签名即协议，启动时通过反射生成 JSON Schema，编译器帮我们挡住大部分拼写错误。这在 Python 动态类型下，通常要等运行时才能暴露。

当然，选择纯 Java 也有明显的代价。Python 圈子里 Prompt 调试工具、模型评测体系、Agent 编排生态确实更丰富，我们的队友问过我“你们是不是在重新发明轮子”。我的回答是：如果业务目标只是“让模型聊聊天”，那确实别自研；但我们的目标是“把 Java 业务能力包装成 AI 可控调用的企业服务”，这个场景下 Java 自研反而更顺。

2. 总体设计：先想清楚边界再动手

2.1 平台的最小闭环是什么

在设计 BizBuddy 之前，我先列了一个“最小闭环清单”，缺一个环节，这个平台就只能算玩具：

• Agent 定义：系统提示词、模型参数、可调用工具列表、最大迭代轮数、超时时间。
• 工具注册与权限：业务系统暴露哪些能力给 Agent，谁能调用，调用前怎么鉴权。
• 会话管理：一个用户跟 Agent 的多次交互，需要保存上下文，而不是每次都从零开始。
• 运行引擎：大模型调用、解析工具调用意图、执行本地工具、把结果回灌给模型，直到任务完成。
• 审计与回溯：整个交互链路必须有完整事件日志，出问题能快速定位是哪一步“发疯”。

围绕这个闭环，我把 BizBuddy 拆成了四个模块：bizbuddy-core负责 Agent 运行循环和会话管理，bizbuddy-toolkit负责工具注册、扫描和调用执行，bizbuddy-api对业务方提供 HTTP 接入，bizbuddy-console则是给管理员配置 Agent、查看日志用的管理端。

2.2 核心抽象：AgentDef、AgentInstance、Session 和 ToolDef

这四个抽象是 BizBuddy 的地基，我单独讲讲每个抽象存在的意义。

AgentDef 是 Agent 的静态定义，相当于“部署单元”。它包含 Agent 名称、系统提示词、模型供应商、模型名称、温度、最大迭代轮数这些配置。AgentInstance 是 AgentDef 在一个租户或环境下的运行实例，同一个 Agent 可以在测试环境、生产环境各建一个实例，各自有独立的并发限制和运行状态。早期我做设计时直接把这两层合成了一层，后来发现完全行不通：因为同一个客服 Agent 可能被 A 部门和 B 部门同时接入，两边要限制不同的调用频率，甚至要用不同版本的提示词，如果不拆开，光配置隔离就是一团乱麻。

Session 很好理解，代表用户跟某个 AgentInstance 的一次连续会话。Session 里保存消息历史、当前状态、关联的 traceId。ToolDef 则是工具定义，通常跟后端某个 Service 方法一一对应。工具必须描述清楚自己是什么、能做什么、参数有哪些，因为这些描述会直接作为上下文提供给大模型，描述质量决定了模型能不能正确调用它。

数据库表设计我贴一下简化版，大家参考即可：

agent_def ( id BIGINT PRIMARY KEY, code VARCHAR(64) UNIQUE, name VARCHAR(128), system_prompt TEXT, model_provider VARCHAR(32), model_name VARCHAR(64), max_iterations INT DEFAULT 5, temperature DECIMAL(3,2) DEFAULT 0.3, timeout_seconds INT DEFAULT 30, enabled TINYINT DEFAULT 1, created_at DATETIME, updated_at DATETIME ) agent_instance ( id BIGINT PRIMARY KEY, agent_def_id BIGINT, env VARCHAR(16), tenant_id BIGINT, concurrency_limit INT DEFAULT 10, status VARCHAR(16), created_at DATETIME ) tool_def ( id BIGINT PRIMARY KEY, code VARCHAR(64) UNIQUE, name VARCHAR(128), description TEXT, param_schema_json TEXT, role_required VARCHAR(64), category VARCHAR(64), jar_location VARCHAR(255), class_name VARCHAR(255), method_name VARCHAR(128), read_only TINYINT DEFAULT 1, created_at DATETIME ) session ( id BIGINT PRIMARY KEY, agent_instance_id BIGINT, user_id VARCHAR(64), trace_id VARCHAR(64), status VARCHAR(16), context_json TEXT, created_at DATETIME, updated_at DATETIME ) event_log ( id BIGINT PRIMARY KEY, trace_id VARCHAR(64), event_type VARCHAR(32), payload_json TEXT, created_at DATETIME )

开发这些表的时候，我先用 MyBatis-Plus 的实体类生成能力把建表 SQL 快速拉出来，再手工补充索引，省了不少手写 SQL 的时间。对普通业务表这么做没问题，但注意 event_log 这种高频写入表，后面一定要按时间分表或接入日志系统，不能真堆在一张表里。

2.3 工具注册与发现：核心中的核心

Agent 本身是不直接碰业务系统的，所有外部能力都通过工具调用。所以工具的设计直接决定平台的上限。BizBuddy 里一个工具定义大概是这样的：

@BizTool( code = "order.query", name = "订单查询", description = "按商户号、订单号或时间范围查询订单列表，返回订单状态、物流单号等", category = "订单域" ) public class OrderQueryTool { private final OrderQueryService orderQueryService; public OrderQueryTool(OrderQueryService orderQueryService) { this.orderQueryService = orderQueryService; } @ToolAction(description = "查询订单，返回精简版订单对象，敏感字段自动脱敏") public List<OrderBrief> query( @ToolParam(name = "merchantId", description = "商户号，必填", required = true) String merchantId, @ToolParam(name = "startTime", description = "开始时间，格式yyyy-MM-dd HH:mm:ss，不填则默认近24小时") String startTime, @ToolParam(name = "endTime", description = "结束时间，不填默认当前时间") String endTime ) { return orderQueryService.query(merchantId, startTime, endTime); } }

工具注册机制上，我们用的是 Spring 容器扫描加注解路由。服务启动时扫描所有带@BizTool的 Bean，把方法上的@ToolParam信息反射出来，生成 LLM 需要的 JSON Schema，缓存在内存里。这里有个很关键的经验：参数描述必须写得“像一个不懂系统的用户在看注释”，模型完全靠你的描述来生成参数。比如你写“商户号”，模型不知道它长什么样，但如果你写“商户号，必填，例如 M10023，通常以M开头”，模型出错率立刻降一大截。

工具权限上我坚持一个原则：所有工具必须先注册、审批、绑定角色之后才能被 Agent 调用。启动时全量扫描出来的工具只是“候选”，只有管理员在 Console 里绑定到指定 Agent 并授权给角色，运行期才会放开调用。这样避免了“模型乱调用工具”变成生产事故。

2.4 事件总线与运行链路：能回溯是硬需求

Agent 的每一次运行都是一条完整的事件链：用户提问、模型返回内容、模型发起的工具调用、工具执行结果、再次调用模型、最终回复。如果这些环节没有完整的日志，一旦模型答错，你根本不知道它是哪一步跑偏的。

BizBuddy 的做法是内置事件总线，把每个环节都发送成一条结构化事件：

• session_start：会话开始，记录用户、Agent 实例、初始输入。
• llm_start：发起一次模型调用，记录请求上下文摘要。
• llm_result：模型返回，记录是否有 tool_calls，回复内容。
• tool_call：记录模型想要调用的工具名和参数。
• tool_result：记录工具真实执行结果、耗时、是否成功。
• retry：记录重试原因和次数。
• error：任何异常都会记录堆栈和环节。

所有事件都带同一个 traceId，从网关入口生成并贯穿整个链路。生产上我们同时做了两件事：事件落库到event_log表，同时以结构化 JSON 日志打印到应用日志里，方便对接现有的日志采集系统。这套设计在一次线上事故中救了我，具体案例后面第 5 章会讲。

3. 核心实现：关键技术细节与取舍

3.1 线程模型：虚拟线程是好东西，但别盲目梭哈

Agent 平台的调用链几乎全是 IO 密集型：等大模型响应、等业务系统接口返回、等数据库查询结果。这种场景下，Java 21 的虚拟线程理论上是最优解，单机可以开几万个虚拟线程等 IO，不会再被“线程池不够用”卡住。

我在 BizBuddy 里实际做了分层：模型调用这一段，用虚拟线程去执行，因为大模型响应的等待时间经常是几秒甚至几十秒，平台线程被占住太浪费；工具执行这一段，我没有直接用虚拟线程，而是走独立的固定线程池，每个工具的实例绑定到自己的执行器队列。原因很现实：工具的代码是业务团队写的，里面很可能有同步调 JDBC、调 Redis，甚至调外部 RPC 的操作。虚拟线程虽然能挂起等待，但某些传统连接池资源并不会跟着虚拟线程自动伸缩，如果所有工具都扔进虚拟线程，数据库连接池会被大量请求打穿，表现为“工具执行特别慢，日志里全是连接池超时”。

如果你所在团队还在 JDK 17 上跑，没有虚拟线程，我的建议是用CompletableFuture把模型调用异步化，不要在请求线程里死等模型返回；工具执行仍然用线程池隔离，这是兼容性最好也最容易排查的路线。总之，线程模型的核心不是“选最先进”，而是“别让一个慢工具拖垮整台机器”。

3.2 模型接入与结构化输出

BizBuddy 的模型层我做了一个很务实的取舍：底层统一走 OpenAI 兼容的 Chat Completions 协议，适配企业内部私有化部署的各种模型网关。放眼主流模型服务商，私有化网关基本上都兼容 OpenAI 的协议格式，差别只在地址和鉴权。我们封装了一个ChatClient接口，只保留几个核心方法：chat(messages)、chatWithTools(messages, toolDefs)、parseResponse()。

Function Calling 这个环节最大的坑不在协议，而在“模型返回的结构化输出不稳定”。我实测下来主要会遇到三种情况：模型返回的 JSON 里包着 Markdown 代码块标记，像json ...；模型把数字参数当成字符串传回来；模型干脆返回一个不在工具列表里的名字。所以 BizBuddy 里有一个专门的FunctionCallParser，先做文本清洗，再解析 JSON，再校验字段类型。简化版实现如下：

public record FunctionCall(String name, JsonNode arguments) {} public class FunctionCallParser { private static final ObjectMapper MAPPER = new ObjectMapper(); public FunctionCall parse(JsonNode toolCallsNode) { if (toolCallsNode == null || !toolCallsNode.isArray()) { throw new FunctionCallParseException("no tool calls"); } JsonNode call = toolCallsNode.get(0); String name = call.path("function").path("name").asText(); String arguments = call.path("function").path("arguments").asText(); JsonNode argsNode = MAPPER.readTree(cleanupJson(arguments)); return new FunctionCall(name, argsNode); } private String cleanupJson(String raw) { String cleaned = raw.trim(); if (cleaned.startsWith("```json")) { cleaned = cleaned.substring(7, cleaned.length() - 3); } else if (cleaned.startsWith("```")) { cleaned = cleaned.substring(3, cleaned.length() - 3); } return cleaned.trim(); } }

这个解析器每次解析失败都会返回可读的错误信息，并交给重试逻辑。重试时会在系统提示词里追加一句“严格按照工具参数的 JSON Schema 格式返回，不要添加任何额外标记”，实测能把结构化输出成功率从 92% 拉到 99% 以上，剩下的 1% 靠校验层兜底拦截。

3.3 工具动态加载与版本管理

工具的代码不能老跟平台主应用耦合在一起，否则每加一个工具就要整个平台发版。BizBuddy 用URLClassLoader做动态加载：每个业务工具打成独立 jar，上传到平台指定的目录，运行时为每个工具版本创建独立的 ClassLoader。

为什么一个工具要独立 ClassLoader？因为不同工具可能依赖不同版本的第三方库。比如订单工具依赖 commons-io 2.x，财务工具依赖 3.x，用同一个 App ClassLoader 必然冲突。独立 ClassLoader 是 JDK 层面隔离类的最佳手段，纯 Java 场景下这就是正确答案。发布新版本时，新版本对应一个新的 ClassLoader 实例，旧实例在下一次 GC 时卸载，这样就完成了无感升级。有几个坑必须写出来：

• 工具类不要持有 Spring 容器的静态引用，否则卸载 ClassLoader 时容器还会被引用，导致内存泄漏。
• 工具实例内部的 Spring Bean 由主容器管理，但工具 jar 里不要打包 Spring 本身的类，改成由主容器通过接口注入，避免双亲委派机制下出现类不一致。
• jar 包上传后要做完整性校验，最好记录 sha256，防止文件被篡改或者被错误覆盖。

这套机制一开始让团队觉得没必要，觉得“多加一个 jar 依赖不就行了”。后来我们在一次灰度升级中线上跑着两个版本的工具，老版本给一个部门用，新版本给另一个部门验证，这才体会到动态加载的价值：没有它，灰度工具版本根本无从谈起。

3.4 存量 Rest 接口如何快速包装成 Agent 工具

这是 BizBuddy 落地价值最大的一块，也正好回应了很多人问我的“Java Rest 接口怎么转成 MCP 协议”。其实思路不复杂：模型侧需要的是“工具描述 + 参数 Schema”，服务侧需要的是一个可执行入口，两者之间缺的是一个适配层。如果服务暴露的是 REST API，我们就可以直接从 OpenAPI 文档自动生成工具定义。

我们写了一个OpenApiToolGenerator，解析 OpenAPI 3.0 的 Operation 对象，把 Path、Method、Query 和 Path 参数映射成 ToolDef 的 JSON Schema，同时生成一个 HTTP 调用模板。示意结构如下：

{ "toolCode": "crm.customer.query", "method": "GET", "urlTemplate": "https://crm.internal/api/v1/customers/{customerId}", "headers": { "Authorization": "Bearer ${accessToken}" }, "params": [ { "name": "customerId", "in": "path", "required": true, "description": "客户ID" } ], "responsePath": "$.data" }

生成之后，管理员只需要在 Console 里审核一下描述是否清晰、参数是否够用，点击发布，这个 Rest 接口就变成 Agent 可以调用的工具了。这一块省掉了大量手写工具代码的时间，也是我强烈建议团队优先立项的方向。

4. 完整实战：订单查询与变更助理落地

4.1 业务场景与拆解

第一个真正上生产的 BizBuddy Agent 是“订单查询与变更助理”，使用方是客服团队。客服同学每天有大量工单都是“帮我查一下订单状态”“能不能把这个订单改一下状态”“商户在后台看不到某笔订单怎么办”。这些操作原来要登录两三个系统来回切，现在直接在一个对话框里完成。

业务拆解下来，Agent 需要的能力其实就四件事：查订单、查商户、改订单状态、给工单加备注。你要做的不是给模型一个“万能操作入口”，而是把业务边界定死，让它只能在这四件事里组合。

4.2 工具清单与权限设计

工具权限这里有一个容易被忽略的设计点：order.update_status 这类写操作，不是所有客服都有权限改状态，所以工具定义里加了“最低角色要求”。BizBuddy 在工具调用前会先做一次权限判断，如果当前用户角色不满足，直接返回“无权限”的工具执行结果，并且把这次尝试记录到审计日志。这个设计一开始也有人嫌啰嗦，直到后来有个低权限测试账号差点真的把订单改掉，团队才明白这层校验不是形式主义。

4.3 Prompt 设计的实用模板

Prompt 写得好不好，直接决定 Agent 的稳定程度。我分享一个经过多轮调优的模板，给大家一个可直接套用的底子：

你是电商运营助手 BizBuddy-Ops，负责协助客服处理订单、商户相关问题。 工作步骤： 1. 用户提问后，先确认是否具备必要信息（如商户号、订单号），缺失则明确询问。 2. 涉及订单查询时，先调用 order.query 确认订单是否存在。 3. 涉及状态变更时，必须将影响（原状态 -> 新状态）告知用户，并等待用户明确确认，确认后再调用 order.update_status。 4. 如果工具执行失败，如实返回错误码和提示，不得编造原因，建议用户联系技术侧。 5. 不得调用当前会话没有提到的工具，不得猜测参数值。

这个模板有几个关键点：第 3 条强制“先确认再执行”，是为了防止模型自作主张做状态变更；第 5 条专门限制模型“不要猜测参数值”，因为大模型非常容易在没有订单号的时候编一个订单号出来。这套 Prompt 配合运行层的工具白名单校验，上线后一次乱调用都没有发生过。

4.4 性能与稳定性验证

我们这个场景是内部客服使用，并发量不大，但要求单次交互稳定可预期。压测数据如下，给读者一个量级参考：

• 配置：2 核 8G，JDK 21，单实例。
• 场景：50 并发，每个会话最多 5 轮工具交互。
• 结果：平均响应 3.2 秒，P95 响应 5.6 秒，工具执行阶段耗时占比约 40%，模型响应耗时占比约 60%。

对于客服场景来说，这个延迟用户是可以接受的，毕竟比原来人工翻系统快得多。但如果你的场景是高频实时交互，那就要考虑预编译工具结果缓存、模型流式输出等手段了。BizBuddy 目前是同步返回，后续我计划把 SSE 推流加上，让用户看到模型边思考边输出，体感会好很多。

5. 踩坑记录与常见问题排查

5.1 模型总是幻觉一个不存在的工具

上线第一周就遇到了经典问题：模型在 function calling 阶段返回了一个我们根本没有注册的工具名，比如order.queryOrderDetail，而真实工具是order.query。模型不会老老实实只调用你给的工具，尤其当你系统 Prompt 里没有明确“只能使用提供的工具”时。

排查后发现模型是“理解”了业务语义，然后自行“发明”了一个更符合语义的工具名。解决分两层：第一层是 Prompt 层，在系统提示词中明确加约束“只能使用下方给定的工具，禁止自创工具名”；第二层是运行层，BizBuddy 在真正执行工具前，会对模型返回的 tool 名做白名单校验，不在当前工具列表里的直接拦截，并把异常结果返回给模型，让它重新选择。两层叠加后这类问题基本消失。

5.2 会话历史无限膨胀，几分钟就打爆请求体

Agent 跟用户对话时间越长，消息历史越多，大模型的上下文窗口迟早被塞满。我们遇到过连续使用一小时后，单单历史消息就超过 8 万 token 的情况，再往后模型要么报错要么开始“失忆”。解决方法是滑动窗口加摘要：保留最近 20 轮完整对话，之前的历史由一个小模型或规则逻辑压成一份摘要，注入到系统提示词里。

要注意的是，摘要会丢细节，所以这个策略只适合长会话场景。BizBuddy 把“上下文压缩策略”做成了 AgentDef 的可选配置项，默认不开启。如果客服场景不需要用户连续几小时聊同一个话题，那就没必要承担摘要造成的精度损失。

5.3 只读工具把主库拖垮了

某个分析类工具上线后，客服输入“查一下过去一年这个商户的订单变化”，Agent 调用查询工具，直接在主库上跑了全表扫描，一分钟内主库负载标高，连带影响了下单链路。排查日志的时候发现这个工具的定义里没有标注“只读”，运行层也没做数据库路由。

我重新梳理了一下工具定义，增加了一个readOnly字段。只读工具统一路由到只读从库，并且设置查询超时和返回行数上限；写操作工具必须走主库，同时内部强制开启短事务、快速提交。这个经验同样适用于所有 Agent 平台：不要相信模型会自觉“少查点数据”，平台必须在工具层把边界卡死。

5.4 大模型接口限流，Agent 直接超时失败

多个 Agent 实例同时开跑，模型网关那边 429 限流，BizBuddy 早期不做任何兜底，请求直接超时，用户看到的是“系统繁忙，请稍后再试”。后来我在模型适配层前面加了一个统一的流量控制：令牌桶限流、指数退避重试、熔断降级。

具体做法是每个 AgentInstance 配置一个并发上限，超过上限的请求进入阻塞队列；如果队列满了，直接快速失败，并给用户明确提示“当前咨询人数较多，请稍后重试”。重试策略要配合模型网关的 Retry-After 表头，不要死等固定 500ms。这个限流层还有一个意外的好处：它顺便防住了个别业务团队把 Agent 当并发压测工具猛打的问题。

5.5 “Agent 发疯”的十分钟回溯法

最后说一个最实用的排查技巧。无论你怎么调 Prompt，模型总有低概率“发疯”：可能是答非所问，可能是没调用工具却瞎给结论，也可能是调用了不该调用的工具。遇到这种问题，最忌讳凭感觉猜。

我的习惯是拿到 traceId，然后直接查 event_log 表，把整个事件链铺开。举例：

看到第 4 步直接调用了order.update_status，你就立刻能判断问题出在 Prompt 第 3 条没生效：模型没有先找用户确认就直接改状态，属于严重违规。修改 Prompt 后，再把这段事件序列回放给测试账号，验证修复效果。这个“事件回溯法”比看模型裸输出高效太多，也是我到现在为止最推荐的 Agent 排查手段。

回头总结一下做 BizBuddy 这段经历的体会：用纯 Java 做 Agent Harness 不是情怀，而是很多企业技术债下的务实选择。真正花时间的不是“让大模型回答问题”，而是把权限、审计、隔离、回溯这些平台能力打扎实。对我个人来说，最大的收获也不是学会了怎么调 Prompt，而是想明白了“企业级 Agent 平台的稳定 = 把能预判的错误全部拦截在模型之前”。这个思路后续会继续延伸到 Agent 之间的协作协议和更细粒度的工具权限模型上，也欢迎正在做类似平台的朋友一起来聊聊。