1. 为什么最终选了 Java 来落地智能体说说我的取舍逻辑先交代一下背景。我所在的团队做过一段时间对话机器人最早确实用的是现成的低代码智能体平台拖拽流程、配提示词、接几个插件demo 半天就能跑通。但真正接到企业级需求时就发现平台方案在数据安全、私有化部署、和现有 Java 业务系统打通这几个维度上总有一堵墙绕不过去。后来我们决定自研技术栈几乎没有任何争议地选了 Java。这里先给还在观望的朋友一个判断标准如果你的智能体只是偶尔跑一跑、数据不敏感、不需要深度嵌入业务系统那低代码平台完全够用。但如果你要的是对话只是入口真正的价值在任务执行也就是智能体要操作内部系统、读写数据库、调用 RPC 服务、触发审批流那 Java 几乎是必选项。不是说 Python 不行而是 Java 生态里现成的 Spring Boot、MQ、规则引擎、分布式任务调度跟企业后端能无缝衔接。智能体的核心难点从来不是模型对话而是对话之后怎么可靠地干活这一点 Java 的成熟度远高于那些偏前端的方案。我的整体架构思路是三层对话接口层负责聊天输入输出任务理解层负责把大白话转成结构化任务指令任务执行层负责真正调动业务能力。这三层边界清晰每一层都可以独立演进。下面我把每一层做了什么、踩了哪些坑全部拆开讲。2. 对话接口层别急着接大模型先把消息协议设计明白2.1 会话与消息模型的设计很多第一次做智能体的人上来就写一个POST /chat接口把用户消息丢给大模型拿到结果就返回。这么搞 Demo 没问题但一旦进入真实业务立刻会遇到三个问题第一多轮对话的上下文放哪里第二任务执行类消息是异步的HTTP 长连接撑不住第三消息里除了文本可能还有文件、图片、结构化参数。我最后设计的是这样一套消息模型public class ChatRequest { private String sessionId; // 会话标识前端每次请求都带上 private String userId; // 用户标识用于权限与个性化 private MessageType type; // TEXT / IMAGE / FILE / EVENT private String content; // 文本内容文件场景下为URL或文件ID private MapString, Object extraParams; // 预留扩展参数 } public class ChatResponse { private String responseId; private MessageType type; private String content; private ListToolCallInfo toolCalls; // 本次对话触发的工具调用摘要 private ChatStatus status; // PROCESSING / SUCCEEDED / FAILED }sessionId 是整个接口层最核心的字段。它不只是用来存储上下文更关键的是当任务执行时间较长时客户端可以轮询或通过 WebSocket 接收后续结果而 sessionId 是连接前后端状态的唯一线索。2.2 同步与异步并存的双通道策略对话接口层有一个反直觉的设计点不是所有消息都走同一套响应逻辑。纯闲聊、简单问答这类请求用户期待快速回复走同步 HTTP 接口2 到 5 秒内返回完整结果。但任务执行类请求比如帮我批量导出上个月的销售数据通常要十几秒甚至几十秒如果让 HTTP 请求一直挂着网关超时就给你断掉了。我的做法是双通道同步通道POST /v1/chat/sync只处理轻量对话响应体内直接返回最终内容。异步通道POST /v1/chat/async接口立刻返回一个taskId任务实际执行过程在服务端异步推进客户端通过GET /v1/tasks/{taskId}轮询进度。用户感知上是我发了一句话它先告诉我收到然后过一会儿给我结果。这个体验比长时间转圈好得多。2.3 上下文管理的取舍上下文存储我试过两种方案一种是把完整历史消息塞进每次请求的 Prompt 里简单粗暴但 token 消耗大上下文一长模型注意力就漂另一种是自己维护一个结构化的会话状态只把关键信息传给模型。最终采用的是双轨制系统维护一个SessionState对象里面包含用户偏好、当前正在执行的任务、最近一次任务结果等结构化信息与此同时把最近 10 轮内的原始对话文本压缩成摘要放入 Prompt。这样模型既有全局感知又不会因为历史太长而丢失重点。Service public class SessionManager { private final RedisTemplateString, Object redisTemplate; public SessionState getOrCreateSession(String sessionId) { String key agent:session: sessionId; SessionState state (SessionState) redisTemplate.opsForValue().get(key); if (state null) { state new SessionState(sessionId, new ArrayList()); redisTemplate.opsForValue().set(key, state, Duration.ofHours(6)); } return state; } public void appendHistory(String sessionId, ChatMessage message) { SessionState state getOrCreateSession(sessionId); state.getHistory().add(message); // 只保留最近30条防止状态对象无限膨胀 if (state.getHistory().size() 30) { state.getHistory().subList(0, state.getHistory().size() - 30).clear(); } redisTemplate.opsForValue().set(agent:session: sessionId, state, Duration.ofHours(6)); } }这里有个值得注意的经验不要把所有东西都塞进 Redis 序列化。一开始我图省事把整个 SessionState 对象直接序列化存取结果对象里嵌套的MapString, Object在 Jackson 反序列化时会变成LinkedHashMap后面想取目标类型还得强转类改了还经常出现反序列化失败。现在我只把纯文本历史用 JSON 字符串存结构化状态字段单独存储。3. 任务理解层从自然语言到结构化任务指令这个转化比想象中难3.1 任务清单与工具声明的定义方式对话接口收上来的是一句话但任务执行层不认识帮我查一下张三今年请了多少天假这种话。中间必须有一个把自然语言翻译成结构化任务指令的过程。我在项目里定义了一套工具声明体系每个工具都是一份带描述和参数说明的 JSON Schema。这是任务理解层的关键——大模型不是凭空猜你想要干嘛而是基于工具清单做函数调用式的匹配。public class ToolDefinition { private String name; // 工具唯一名称如 leave.queryAnnualLeave private String description; // 人类可读描述如 查询员工年度剩余假期 private ListParamField params; // 参数定义 private boolean requireConfirm; // 执行前是否需要用户确认 }工具声明的质量直接决定意图识别的准确率。描述要具体而且要说明触发场景。比如查询请假这个工具描述写成查询员工请假记录很容易和大模型瞎猜混淆我改成了当用户询问某个员工某个时间段的请假天数、请假类型、请假状态时使用准确率提升非常明显。3.2 结构化输出的坑与对策让大模型输出结构化任务指令业界常用的办法是 Function Calling。但我在实践中发现不同模型对函数调用的支持程度差异很大而且有个特别隐蔽的坑模型可能会编造一个不存在的工具名称或者把参数值传成明显不对的类型。为了控制风险我加了两个机制第一工具调用校验器。模型返回的工具调用结果会经过一层校验工具名必须在注册表里存在参数类型必须匹配 Schema 定义。不合法就直接返回抱歉我无法完成这个操作而不是傻乎乎地把错误参数传下去。第二兜底意图识别规则。有些消息明显是闲聊比如你好谢谢没必要走大模型。我用了一组轻量规则先过滤命中就直接返回固定文案省一次模型调用。这个优化在高峰期能省 20% 左右的 token 成本。3.3 多意图拆解一句话之后藏了三个任务任务理解层最容易忽略的是一句话包含多个任务。比如帮我把周末的会议纪要发给项目组再提醒我周一早上跟进——这其实是两个任务发送纪要和设置提醒。我用模型做意图拆解时输出结构设计成了任务数组{ intent: batch_tasks, tasks: [ { tool: mail.send, params: {to: project_group, content: weekend_meeting_minutes} }, { tool: reminder.create, params: {time: 2025-06-02 09:00, content: follow_up_meeting_items} } ] }任务数组按顺序执行后一个任务可以引用前一个任务的输出。这个设计让帮我查下明天天气如果下雨就提醒我带伞这类条件式任务变得可以表达——第二步的参数来自第一步的输出。4. 任务执行层注册表、执行引擎与可靠回传4.1 工具注册表执行层的插件热插拔机制执行层我设计成了一个独立的模块核心是一个工具注册表。每个工具实现统一的接口注册到上下文里执行引擎拿到任务指令后从注册表找到对应实现并调用。public interface AgentTool { String getName(); ToolDefinition getDefinition(); ToolResult execute(ToolCallContext context, MapString, Object params); } Component public class LeaveQueryTool implements AgentTool { Override public String getName() { return leave.queryAnnualLeave; } Override public ToolResult execute(ToolCallContext context, MapString, Object params) { String employeeId (String) params.get(employeeId); // 调用内部服务查询请假数据 LeaveSummary summary leaveService.queryAnnualLeave(employeeId); return ToolResult.success(summary); } }这里有一个对实际开发影响很大的点——每个工具方法只接收MapString, Object参数。好处是工具实现跟模型输出完全解耦模型输出的 JSON 不管嵌套多复杂都能映射进来坏处则是类型安全几乎为零参数取值全凭约定。我的做法是在工具实现内部第一行就做参数解析与校验不符合就抛ParamValidationException。4.2 执行上下文传递ThreadLocal 的边界问题任务执行链路里用户身份、会话 ID、请求跟踪 ID 这些信息需要在多个工具之间传递。最开始我图省事用ThreadLocal跑单测没问题上生产就翻车了——一旦业务代码里用到了异步线程、线程池ThreadLocal 里的上下文就丢了工具拿不到 userId权限校验直接失败。后来我换成了显式传递的ToolCallContextpublic class ToolCallContext { private String userId; private String sessionId; private String traceId; private MapString, Object attributes; // 任务间共享的数据 }所有工具方法的第一个参数都是这个 Context工具之间如果需要传递数据就往attributes里放。这是牺牲了一点代码优雅换来了极高的可追溯性——出问题的时候每个工具拿到的上下文都是完整的排查效率高很多。4.3 任务间依赖与条件执行任务执行不是简单的 for 循环挨个调用经常有依赖关系。我实现了一个极简的任务执行引擎每个任务可以声明依赖哪些前置任务的输出public class TaskNode { private String taskId; private String toolName; private MapString, Object params; // 可以是模板如 ${task1.output.userId} private ListString dependsOn; // 前置任务ID列表 private String condition; // 可选的条件表达式如 ${task1.output.status rainy} }执行引擎先构建一个有向无环图然后按拓扑序依次执行。每次有任务完成就把输出写入一个TaskResultPool下一个任务在拼参数时遇到${taskId.output.field}这种模板字符串就去结果池里取值。这套机制让根据天气决定要不要提醒带伞变成了两个任务节点加一个条件表达式而不用在 Java 代码里写死逻辑。条件表达式我用的是一套极简的自定义语法没有引入重量级规则引擎因为实际需求还没到那个复杂度——等哪天要支持复杂的与或非嵌套再升级。5. 完整案例让智能体完成查询库存并生成补货单5.1 场景设定与工具准备为了让上面的架构更具体我拆一个我们实际跑通的场景用户发消息说查一下 SKU A10023 的库存如果低于安全库存就帮我生成一张补货单。这个场景涉及三个工具工具名作用关键参数inventory.query查询商品实时库存skuIdinventory.getSafetyStock获取商品安全库存阈值skuIdpurchase.order.create创建补货单skuId, quantity, reason三个工具的能力可以做成一个组合工具但刻意拆开是为了演示任务依赖与条件执行。真实项目中这种拆法也更容易复用——比如查库存可能在很多场景都要用到没必要跟生成补货单绑定。5.2 从一句话到任务指令的完整转化过程用户消息进入对话接口层被判定为异步任务返回taskId。任务理解层收到消息结合工具清单让大模型做函数调用输出如下结构化指令{ intent: conditional_tasks, tasks: [ { taskId: t1, tool: inventory.query, params: {skuId: A10023} }, { taskId: t2, tool: inventory.getSafetyStock, params: {skuId: A10023}, dependsOn: [t1] }, { taskId: t3, tool: purchase.order.create, params: { skuId: A10023, quantity: ${t1.output.suggestedOrderQuantity}, reason: auto_replenish_by_agent }, dependsOn: [t1, t2], condition: ${t1.output.stockLevel} ${t2.output.safetyStock} } ] }执行引擎按拓扑序执行t1 查库存t2 查安全库存t3 的条件表达式判断库存是否低于阈值只有成立才执行。整个过程的中间结果都会记录在日志里前端轮询接口时可以展示正在查询库存库存低于安全阈值正在生成补货单等进度信息。5.3 执行失败与补偿处理任务执行必然会遇到失败。我总结了四类典型失败及对应的处理策略第一类工具不存在或参数非法。这是最容易的直接返回失败告诉用户这个操作我暂时不支持。第二类下游服务超时。比如库存服务 3 秒没响应不能无限等要设置超时阈值并返回服务暂时不可用请稍后再试。第三类业务规则拒绝。比如补货单金额超过用户权限这种情况不能假装成功要把原因完整透传给用户。第四类部分成功。比如批量任务里后面两步失败前面已经执行了要支持回滚或人工介入。我给每个 TaskNode 都加了retryCount和timeoutMs两个字段。重试只对幂等操作开启像创建补货单这种非幂等操作宁可失败也不自动重试避免重复单子。这是拿真金白银换来的教训——上线第一周就因为自动重试导致重复生成了两张采购单。6. 性能优化与线上排障不太会有人告诉你的那些细节6.1 模型调用的并发控制与成本控制对话接口层和任务理解层都会调用大模型 API这里有个容易忽略的问题——模型 API 的限流。我们用的模型供应商并发上限不高但智能体一个任务可能要连续调用好几次模型意图理解、参数补全、结果摘要一压测就 429。我的方案是做一个模型调用的并发管理组件令牌桶限流 队列削峰Component public class ModelCallThrottler { private final RateLimiter rateLimiter RateLimiter.create(20); // 每秒最多20次调用 public T T callWithThrottle(SupplierT callable) { // 阻塞直到获取令牌 rateLimiter.acquire(); try { return callable.get(); } catch (RateLimitExceededException e) { // 二次尝试前等待更长时间 Thread.sleep(1000); return callable.get(); } } }真正的生产环境里限流的粒度要更细比如按用户限流或按模型版本限流。我们后来做到了按 userId 维度分配配额防止单个用户刷爆整个服务的模型预算。6.2 流式输出与首字延迟的权衡对话接口层如果走流式输出用户体验会好很多但任务执行类场景跟闲聊不一样——首字延迟反而不重要关键是结果准确性。所以我们做了一个差异化策略闲聊类消息走流式任务执行类消息走异步轮询。这么说吧闲聊是你说一句我说一句流式让用户感觉 AI 在思考但任务执行是我帮你干活用户已经做好了等待的心理预期这时候更重要的是让用户知道你的任务正在被执行而不是让模型在那儿一个字一个字地往外蹦废话。6.3 全链路日志必须记录每一步的输入输出智能体项目上线后我最大的感受就是——排障全靠日志。而且不是普通日志必须把每一轮对话的完整链路记录下来包括用户原始消息、任务理解层输出的结构化指令、每个任务的执行状态、每个工具的入参和出参、模型调用的 Prompt 和响应、最终返回用户的内容。我们用的方案是把自己实现的TraceContext跟日志框架联动在每个关键节点追加 traceId 和阶段标记然后采集到日志平台按 traceId 聚合查询。有了这个用户说你刚才答错了的时候我能 10 分钟之内定位到是模型理解错了、还是工具执行出错了、还是参数传递错了。我还给日志加了一个特殊标记位is_user_confirmed。工具执行前如果需要用户确认这个标记会记录确认状态。后续一旦出现纠纷比如为什么自动下单了日志能清楚地展示用户当时点了确认按钮这既是对用户负责也是对我们自己负责。6.4 知识库召回与提示词注入的顺序问题任务理解层如果接了知识库RAG那还有一个很容易犯的错知识召回要在意图识别之前还是之后我们最初把召回放在前面结果用户随便问一句你好也会触发知识库检索白白浪费一次 Embedding 调用而且检索结果混入 Prompt 反而干扰模型判断。后来调整了顺序先做轻量的意图预判只有判断用户可能在问具体业务问题的时候才触发知识库召回。同时引入了关键词兜底和白名单机制避免关键意图被模型误杀。这个顺序调整之后单轮对话的模型调用成本降了约 30%回答准确率反而有所提升。7. 从对话接口到任务执行还差一个可靠性的闭环很多人把智能体想得太神秘拆开看其实就是一个有嘴对话接口、有脑任务理解、有手任务执行的系统。Java 在这个生态里既不是最聪明的也不是最炫的但它能保证你干活的时候不掉链子——尤其是当你的智能体要操作生产环境的数据库、要调用真金白银的交易服务时Java 的稳定性和生态成熟度就是最大的优势。这套架构上线运营了几个月后我又补上了两个对可靠性影响很大的能力一个是人工审批流。高风险的执行动作下单、删除、转账必须卡一道人工审批智能体生成指令但不直接执行而是推送到审批系统由人工确认后才真正落库。另一个是执行结果的事后对账。每天跑一次定时任务把所有智能体执行的任务输出和业务系统的实际数据做比对发现不一致立刻告警。这两个能力很大程度上打消了业务方对AI 自动操作的顾虑。我个人最大的体会是做智能体不要一开始就追求全自动。最稳的路径是人审 机器执行的半自动模式先把链路跑通、把用户信任建立起来再逐步放开。从对话接口到任务执行这条路真正的难点不在代码而在于你有多了解业务边界在哪里。理清楚哪些动作可以放心交给机器、哪些必须留一道人工闸门这比写一万行工具代码都重要。