半年前我们团队接了一个内部运营助手的活，要在私有化环境里跑一批 AI Agent 处理工单分类、合同信息抽取和业务数据问答。最开始我用 Python 生态把 Agent 骨架搭了出来，三个晚上就能对话了，同事都说效果不错。可真正准备上生产的时候，问题一个接一个冒出来：模型调用怎么和现有权限体系打通？多个 Agent 的会话怎么隔离？工具调用怎么审计？日志里怎么追踪一次完整的多步推理？Python 那边的小样完全答不上来。
于是我们转回去用纯 Java 重新实现，做了个内部代号叫 BizBuddy 的 Agent Harness 平台。这篇文章想把这个过程中的设计取舍讲清楚：哪些地方我坚持了 Java 的路子，哪些地方故意没有照搬社区框架，哪些决定是拿生产事故换来的。
1. 起因：小样用 Python 三天跑通，上生产的时候全卡住了
1.1 我们最初想要的东西
其实需求本身并不玄乎。一个内部助手，用户在对话框里提问题，Agent 自己判断要不要调用我们已有的业务接口，再把结果组织成自然语言回复回来。这里有对外的客服工单分类、有合同文本的字段抽取、也有针对业务数据的多轮问答。难点从来不是"模型会不会回答"，而是这些问题在企业环境里要过安全评审、要接统一登录、要扣费审计、要能灰度发布。
1.2 小样的快，恰好就是它上不了生产的理由
Python 小样确实快，因为生态里现成的东西多。但当你认真问生产环境的问题，就会发现全是坑：
第一是环境碎片化。模型推理主要走远端 API，本地不需要太重的东西，但 Python 的依赖管理和虚拟环境在公司安全策略下还是被反复盘问。私有化部署到客户现场的时候更是头疼，客户环境里能不能装包、能不能联网、用哪个 Python 版本都得协商。
第二是并发和稳定性。一个 Python 进程的并发能力有限，对于"几十个用户同时提问"这种再普通不过的场景，需要额外上异步框架，而团队里没人愿意长期维护第二套技术栈。
第三是治理和集成。业务系统是 Java 技术栈，用户权限、组织架构、数据库访问、消息队列、统一配置中心全都长在 Java 这边。Python Agent 想调用这些能力，要么开 HTTP 接口硬桥接，要么在 Python 里再连一遍那些中间件。两条路都意味着双倍的运维面和双倍的审计面。
那段小样最终没有被浪费，它证明了"用 Agent 处理这些业务可行"。但架构上的账算得很清楚：用 Java 实现同样的东西，可能要多花两三周，但之后它会和现有系统长在一起，而不是在旁边另起炉灶。
1.3 用纯 Java 做，不是情怀，是账算得过来
我需要澄清一下"纯 Java"的边界。BizBuddy 不是一个机器学习训练平台，不需要跑模型，也不碰向量检索算法的内部实现。它是一个偏"运行引擎"和"治理底座"的东西，主要负责 Agent 的生命周期、上下文、工具调用、流程编排、模型接入抽象、限流监控。这些活儿 JVM 生态天生就擅长，而且我们有一整支熟悉 Spring、理解并发编程、会调 JVM 参数的技术团队。
同样重要的是，Java 生态里对"企业级集成"的沉淀非常深。安全框架、缓存抽象、连接池、事务管理、配置中心都已经有成熟方案，BizBuddy 要做的不是重造这些轮子，而是把它们和 Agent 的运行时协议衔接起来。
1.4 什么是 Agent Harness
现在"Agent 框架"满天飞，但 Harness 和框架是两种位置的东西。框架解决的是"Agent 怎么写"，比如怎么解析模型输出、怎么构造 Prompt、怎么调用工具，它更像造船厂。Harness 解决的是"Agent 怎么跑"，比如一个 Agent 从部署到下线谁在管、多个会话之间怎么隔离、失败了谁来重试、调用一次模型的成本记到哪个项目头上，它更像船运公司。
BizBuddy 的定位更偏 Harness。在它之上有业务团队写的具体 Agent，在它之下是各种基础设施。它必须足够薄，才能不绑架业务方的开发方式；又必须足够强，才能让 Agent 在真实生产环境里不出乱子。
2. 核心抽象：Agent 是一个业务单元，不是一个"模型调用壳"
2.1 为什么我把 Agent 接口做得这么简单
最开始设计 BizBuddy 的 Agent 抽象时，团队里有人建议照搬社区框架的路子，把 Agent 做成一个大而全的类，里面直接塞模型、记忆、工具、规划器。我坚持没有这么做，因为这个层一旦变重，所有 Agent 实现都要被框架牵着走。
BizBuddy 的 Agent 接口收缩到只有四个方法：
public interface Agent { String name(); void initialize(AgentRuntime runtime); AgentReply invoke(AgentRequest request, AgentSession session); void destroy(); }我们不定义"该不该反思""该用哪种 Prompt 策略""该选哪个模型"，这些属于具体 Agent 的个性。框架只要约定：你有一个名字；启动时我给你运行时能力；请求来了我拿会话和请求调你；服务下线我通知你做清理。这样业务团队写 Agent 时可以自由组合工具调用、模型调用和本地逻辑，而 Harness 统一拿到生命周期与执行入口。
AgentRuntime 是 BizBuddy 给 Agent 的能力清单，里面包括工具注册表、模型 Provider、审批接口、指标收集器等。每个 Agent 在 initialize 阶段拿到的 runtime 是同一个，但可以声明自己需要哪些子集，这样测试时也能注入 mock。
2.2 Session 持有状态，Agent 本身保持无状态
这是整个设计里我最看重的一个取舍：Agent 实例禁止持有用户级状态。
曾经有同事图省事，把用户对话历史直接放在 Agent 的成员变量里。开发时什么问题都没有，一上联调就出乱子：A 用户的问题被 B 用户的上下文干扰，工单查询结果串号。排查了好几个小时，最后发现是 Agent 被注册成了单例，所有并发请求共享了同一个成员变量。
BizBuddy 里所有状态都放在 AgentSession 中：
public final class AgentSession implements AutoCloseable { private final String sessionId; private final String tenantId; private final String agentName; private final Map<String, Object> variables = new ConcurrentHashMap<>(); private final ChatWindow chatWindow; public void setVariable(String key, Object value) { ... } public Object getVariable(String key) { ... } public void appendMessage(ChatMessage message) { ... } public List<ChatMessage> visibleMessages() { ... } @Override public void close() { ... } }sessionId 是全局唯一标识，tenantId 保证一个租户的会话不会串到另一个租户。ChatWindow 是带预算的对话窗口，负责控制发往模型的 token 量，这个放到后面讲。
所有 Agent 实现都被要求写成无状态：本次请求需要什么，就通过参数从 session 里拿。这个约束让 BizBuddy 可以一个 Agent 实例服务几千个并发会话，也让压测和生产环境的偶发问题变得好查。
2.3 和 Spring 容器怎么协作
BizBuddy 没有另搞一套依赖注入。Agent 本身就是普通的 Spring 组件，通过注解注册：
@Agent(name = "order_query_agent") public class OrderQueryAgent implements Agent { ... }应用启动时，BizBuddy 的 Starter 组件扫描所有带 @Agent 的类，检查接口方法实现，然后以单例方式注册到 AgentRegistry。Agent 内部想调什么业务服务，直接使用平常的构造器注入或字段注入，不需要自定义扩展机制。
这样做的好处是，业务方写 Agent 和写普通 Spring 服务几乎没有区别。他们不需要理解"框架如何接管对象生命周期"之类的东西，只需要按常规方式写代码，BizBuddy 在边界上把 Agent 的运行协议接住。
3. 工具调用链路的设计取舍：注解式 Tool 才是 Java 的答案
3.1 为什么不直接暴露 JSON Schema
做 Function Calling 相关的 Agent，第一步通常是定义模型可以调用的工具。很多框架推荐直接给 JSON Schema，让 Agent 决定调用哪个函数。我在 BizBuddy 里没有采用"手写 schema"的方案，原因很实际：字段一变，schema 和人写的代码就会漂移；类型一复杂，手工维护成本直线上升；更重要的是，Java 是个强类型语言，手写字符串让编译期完全帮不上忙。
BizBuddy 的做法是用注解定义工具，编译期和 IDE 都能参与到检查中：
@Tool(name = "query_order", description = "按条件查询订单列表，返回订单ID、金额和状态") public OrderQueryResult queryOrder( @ToolParam(name = "customerId", description = "客户ID") String customerId, @ToolParam(name = "startDate", description = "开始日期，格式 yyyy-MM-dd") LocalDate startDate, @ToolParam(name = "status", description = "订单状态") OrderStatus status) { return orderQueryService.query(customerId, startDate, status); }这里有几个隐性好处。参数类型是真的对象类型，LocalDate、枚举、业务对象都能被正确序列化与校验；方法是现成的 Spring Bean 方法，可以直接用注解扫描与反射机制接管，不需要额外包一层适配器。
3.2 一个 Tool 从注册到执行的完整路径
BizBuddy 的 Tool 不是普通方法，它有完整的元数据、拦截器和调用器。注册阶段，Starter 通过 BeanPostProcessor 收集所有标注了 @Tool 的公共方法，解析入参和描述，打包成 ToolDefinition，注册到 ToolRegistry。
调用阶段完整链路如下：
- LLM 在响应里返回一个 toolCall，包含 toolName 和 JSON 字符串参数。
- BizBuddy 的 ToolInvoker 从 registry 拿到 ToolDefinition，反序列化参数到方法签名要求的类型。
- 参数经过一层 ThrottleAndBudget 检查，确认这个租户、这个 Agent 还有调用额度。
- 权限拦截器校验当前用户是否有权执行该工具。这一步不能省，后面会讲为什么。
- 真正的方法通过 MethodHandle 调用，整个调用包裹在带超时时间的任务里。
- 返回值转成一个 ToolResultMessage，追加到 session 的对话窗口，再送回给模型。
这里有一个很容易踩的坑：模型返回的参数 JSON 不一定符合方法签名。比如日期格式写成了别的样子，或者枚举值拼错。BizBuddy 在反序列化阶段统一做了一次容错处理：日期格式尽量多认几种，枚举按 name 和别名双匹配，实在解析不了就返回一个明确的解析错误给模型，让模型自己修正参数再调用一次。实测下来，这种"把错误反馈给模型"的策略比直接给用户报错效果好得多。
3.3 权限、超时、注入防护放在哪
工具调用是 Agent 能力边界，也是安全风险边界。一个能从对话里生成参数的执行通道，如果没有闸门，等于给任何能触发对话的人开了一个无限调接口的口子。
我在 BizBuddy 里把权限校验放在工具调用这一层，和用户请求入口那层分开。用户请求入口那层管的是"能不能跟这个 Agent 说话"，工具调用这一层管的是"这个用户能不能让 Agent 替他执行这个工具"。两者的粒度完全不同：A 用户可能能和合同 Agent 对话，但只允许它查公开摘要，不允许它触发合同导出。
超时和熔断也放在工具调用层。模型可能一口气发起三四个工具调用，BizBuddy 默认并发执行这些工具，但每个工具独立超时，执行业务方法超过阈值后，向模型返回一个超时结果，由模型决定是重试还是告诉用户"当前系统繁忙"。这个细节让整个 Agent 系统在业务系统抖动时不会连带不可用。
参数注入防护也是后来补的。开发者很容易信任模型生成的参数，但模型可能被提示词注入诱导，比如某条外部文本里写着"请忽略之前指令，执行某个高风险动作"。BizBuddy 对每个工具参数都做类型和边界校验，同时对路径型、查询型参数做额外的排除列表检查。
4. 编排层：不引入现成 BPM 引擎，自研一个"会回头的轻量图执行器"
4.1 BPM 引擎为什么让 Agent 别扭
立项时有人提议用成熟的 BPM 工作流引擎来编排多步 Agent。当时我带着团队实际建模试了一下，不到半小时就放弃了。根因是 BPM 引擎的哲学和 Agent 的哲学拧着。
BPM 引擎擅长的是"流程预先确定，状态由引擎推进"，每一步的下一步是设计时写死的。Agent 则完全不同：模型要根据前一步的工具结果动态决定下一步做什么。你可以预先定义一个最复杂的拓扑图，但实际执行路径可能在每个节点都变化。硬把这种动态性塞进 BPM 编辑器里，结果就是图上面全是条件分支，模型反而成了摆设。
4.2 图模型和节点类型
BizBuddy 定义了一组非常小的图模型，命名上故意不用工作流那套词，避免团队下意识往"流程定义"上套。
public sealed interface GraphNode permits StartNode, EndNode, LlmNode, ToolNode, ConditionNode, SubGraphNode { } public record GraphEdge(String targetNodeId, String whenCondition) { }看图就知道，这个图不是流程图，更像一棵"执行树加循环控制"：Start 进入，End 退出；Llm 节点调用模型；Tool 节点调用工具；Condition 节点根据 session 里的变量走不同分支；SubGraph 节点复用一张子图。每条边上可以带 SpEL 表达式，比如：
graph.exit() .hasNode("tool_result_check", SpelCondition.on("result.status == 'NEED_MORE_INFO'").then("query_more")) .hasNode("tool_result_check", SpelCondition.on("result.status == 'SUCCESS'").then("final_answer"));没有复杂的网关、会签、子流程约定，只有节点和边。团队学习成本很低，而表达力对大部分 Agent 场景已经够了。
4.3 执行器的递归式实现与防呆
执行器用显式栈模拟递归，避免深调用把栈打爆：
public GraphExecutionResult execute(AgentGraph graph, AgentSession session, String entryNodeId) { Deque<NodeFrame> stack = new ArrayDeque<>(); stack.push(new NodeFrame(entryNodeId, Map.of())); while (!stack.isEmpty()) { NodeFrame frame = stack.pop(); GraphNode node = graph.node(frame.nodeId()); NodeResult nodeResult = node.run(session, frame.input()); for (GraphEdge edge : graph.outEdges(frame.nodeId())) { if (edge.whenCondition() == null || evalCondition(edge.whenCondition(), session, nodeResult)) { stack.push(new NodeFrame(edge.targetNodeId(), nodeResult.output())); } } if (stack.size() > maxDepth) { throw new GraphExecutionException("graph exceeds max depth " + maxDepth); } } return new GraphExecutionResult(session); }这个执行器实现了最关键的一个能力：回头。Llm 节点输出工具调用请求后，执行器可以先把控制权交给 Tool 节点，Tool 的返回结果再作为下一次 Llm 节点的输入。这在图里不需要画圈，只需要让 Llm 节点在"存在 toolCall 请求"时，把后继边同时指向工具节点和自己即可。
防呆方面我加了三个硬性上限：最大执行深度、最大循环次数、整体超时时间。任意一个触发都以失败状态结束，并且返回足够明确的错误信息。因为 Agent 模式的失败率本来就高于普通接口，开发环境里跑 5 次可能没事，到生产模型换版本后，就可能出现死循环。
4.4 多 Agent 协作：我只先做了 Supervisor 和 Pipeline 两种
多 Agent 协作听起来很酷，但我没打算做一整套完整的 Agent 市场、辩论、群体共识机制。BizBuddy 第一版只支持两种模式：
Supervisor 模式：一个协调 Agent 根据用户描述选择可用的子 Agent，把子 Agent 的执行结果再组织成最终答复。
Pipeline 模式：请求按固定顺序经过多个 Agent，上一个 Agent 的输出作为下一个 Agent 的输入。适合"先分类再处理"这类稳定链路。
这两种模式覆盖了我们目前遇到的绝大多数业务场景，而且实现都很简单，就是图执行器上的特定排列。刻意不加更多模式，是因为多 Agent 的调试成本是单 Agent 的好几倍，绝大多数项目根本用不到那些花哨能力，先把基础路径做稳比什么都强。
5. LLM Provider 抽象：能做 80% 的统一，剩下的 20% 留给能力协商
5.1 内部消息协议与适配器
BizBuddy 面向业务开发者的 API 里，不应该出现任何具体厂商的类型。所以第一步是定义一套内部消息协议：
public record ChatMessage(ChatRole role, String content, List<ToolCall> toolCalls, String toolCallId) { } public record ChatRequest(List<ChatMessage> messages, ChatOptions options, String agentName) { } public record ChatResult(ChatMessage message, Usage usage, ChatProvider provider) { }然后每个厂商一个适配器，负责把内部协议翻译成厂商 SDK 的请求、再把厂商响应翻译回内部协议。这样业务 Agent 永远不需要 import 某个具体模型服务商的包，后续切换模型时，改的只是配置和适配器，而不是具体 Agent 代码。
5.2 流式输出落地：从 Stream 到 SSE
对话体验需要流式输出，模型一个 Token 一个 Token 地蹦出来，用户不会盯着转圈等二十秒。BizBuddy 在 Provider 接口里定义：
public interface ChatProvider { ChatResult complete(ChatRequest request, AgentSession session); Stream<ChatDelta> stream(ChatRequest request, AgentSession session); }流式实现的第一个版本我直接用响应式流一路铺到前端，结果发现团队里大量成员对背压、异步上下文传递不熟悉，容易写出难维护的代码。后来换了一种更工程化的做法：内部用阻塞队列收集供应商的回调事件，对外以 Java 21 的虚拟线程逐个消费，再桥接成 SSE 推给浏览器。这样流式处理的代码写起来像同步循环，心智负担低，线上也稳定很多。
5.3 不硬抹平厂商差异
早期我们想把所有厂商的能力对齐成一个超集，结果代码里到处是"如果支持这个特性则……"的条件分支，反而难维护。后来我把抽象目标下调到 80%，只统一那些 Agent 逻辑真正依赖的基础能力：对话补全、流式、工具调用、token 用量统计。剩下的差异，比如工具调用格式的细节偏好、JSON 输出模式的支持程度、某些模型特有的参数，通过能力协商来处理：
public record ProviderCapabilities( boolean supportsToolCall, boolean supportsJsonMode, boolean supportsVision, int maxOutputTokens ) { }请求构造器先看 capability，能支持再做对应处理，不支持就退回到更通用的路径，并且日志里明确记录"当前模型不支持某特性，已降级"。这个设计避免了大一统抽象带来的复杂度陷阱，也让新接入一个厂商变得非常快。
6. 生产环境里几次救命的调优：线程模型、链路追踪和幂等
6.1 虚拟线程不是银弹
BizBuddy 部署在 Java 21 上，LLM 调用是典型的阻塞式网络 IO，正好适合虚拟线程。我用虚拟线程来处理一次 Agent 执行的整条链路，并发量提升非常明显，线程占用从几千个降到几十个。
但有一个坑必须讲：虚拟线程在遇到 synchronized 同步块时会发生 pinning，如果同时配上数据库连接池驱逐，高并发场景会出现连接拿不到的诡异现象。我们排查过一周，最后发现是某处工具方法里加了 synchronized，而方法内部阻塞在 JDBC 调用上。解决方法是把这段同步逻辑换成显式锁或原子类，并限制连接池与虚拟线程的并发比例，别让虚拟线程无限挤爆数据库连接数。
6.2 让每一条日志都带 sessionId、agentName、nodeId
Agent 执行链路比普通接口长得多，一个用户问题可能触发五六次模型调用、十几次工具调用，没有统一的追踪上下文，排障就是灾难。
BizBuddy 在入口处把会话维度信息写入日志上下文，打印的关键 log 都带上 sessionId、agentName、nodeId、toolCallId。最开始实现时用了简单的线程变量，结果流式线程一切换，上下文就丢了，日志串联断裂。后来我改成在每段异步任务提交时显式传递上下文快照，由执行线程恢复，才算稳定。
这个投入看起来小，回报非常大。现在出问题第一件事就是按 sessionId 拉日志，能把一次完整推理路径完整回放出来。
6.3 LLM 重试带来的重复工具调用
有一次工单系统出现了重复创建，查了半天发现根因是模型侧的网络重试。模型服务返回超时，实际请求已经到达 BizBuddy，BizBuddy 里工具也执行成功了，但客户端重试导致同一个 toolCall 被再次执行。
这是 Agent 系统独有的幂等问题。普通接口可以要求客户端传幂等键，但 BizBuddy 的调用方是模型服务，它不会主动传幂等键。我们的解决方式是，在 ToolInvoker 里对每一次 toolCall 生成唯一执行记录，以 sessionId + nodeId + toolCallId 作为幂等键，第二次命中直接返回第一次的结果，不再真正调用业务方法。类似地，同一个 Llm 节点如果因为网络超时重试，也优先复用已有输出。
6.4 按租户和 Agent 维度做限流配额
大模型 API 不是免费午饭，一次复杂的多步推理可能消耗上万 token，还可能有并发配额上限。BizBuddy 提供两层级联的令牌桶：租户级配额管整体预算，Agent 级配额管单个场景上限。超过配额时不直接抛粗鲁的异常，而是返回一个结构化错误，Agent 能把这个信息转成对用户友好的提示，比如"当前该类服务的调用额度已用完，请稍后再试"。
这套配额也作用于工具调用。有些工具比模型调用更贵，比如导出报表、发送短信，BizBuddy 在工具调用链路里加了同样的闸门，防止模型被诱导触发高成本操作。
7. 收尾：BizBuddy 只解决了 80% 的问题
写这篇文章时 BizBuddy 已经在内部支撑了三个业务 Agent 的上线，这个量级不算大，但足够暴露很多设计问题。实际做下来我最大的体会是：Agent 平台最难的不是模型调用那一层，而是把"动态执行"这件事装进企业现有的运维和治理体系里。BizBuddy 在生命周期、工具调用、编排、可观测和配额上切出了一个比较合理的边界，团队写业务 Agent 时不用关心底层，底层出问题时又能顺着日志和追踪一路查到底。
下一阶段我想补两件事。一是把会话和图中断点做持久化，让很长的任务可以挂起恢复；二是把图执行过程可视化出来，让业务同学也能看懂 Agent 是怎么得出答案的。至于那些还没做到的部分，我宁可继续慢慢补，也不愿意现在就堆一堆华而不实的功能进去。毕竟 Harness 这东西，稳定和可控比热闹重要得多。
