1. 当 Java 后端遇上会幻觉的 Agent问题到底出在哪做 Java 后端的兄弟这两年应该都有同感业务代码写得再稳一旦把大模型 Agent 接进系统整个链路的确定性就开始崩塌。你给它一个订单查询需求它可能给你编一个根本不存在的接口你让它调用库存服务它信誓旦旦返回一个字段名都对不上的 JSON。这不是模型不行而是Agent 的本质是概率系统而 Java 后端赖以生存的根基是确定性。这两者硬碰硬结果就是线上事故、Token 账单爆炸、排查到凌晨三点。我所在的团队做的是跨境电商中台Spring Boot MyBatis 那一套日订单量在几十万级别。去年下半年开始尝试把 AI Agent 接入客服工单、库存预警、物流异常处理这几个场景。一开始走的是Java 直接调大模型 API 自己写 ReAct 循环的路子结果踩了一堆坑模型幻觉导致调用不存在的内部接口、多轮对话 Token 消耗失控、并发一上来整个线程池被阻塞。最夸张的一次一个简单的查询某 SKU 近 7 天销量的需求Agent 绕了 11 轮才给出答案单次消耗 4 万多 Token账单直接飙到让人心疼。后来我们把工作流编排层从 Java 里剥出来交给n8n来做Java 只负责暴露确定性的业务能力通过 MCP 协议封装成工具Agent 的推理和工具调用全部在 n8n 里编排。改造完之后同样的业务场景 Token 消耗直降 80%幻觉导致的错误调用几乎归零。这套方案的核心思路就一句话让概率的部分归概率让确定的部分归确定中间用 MCP 协议做契约。这篇文章我会把这套方案完整拆开讲包括为什么这么设计、n8n 工作流怎么搭、Java 侧 MCP 服务怎么写、Token 是怎么省下来的、并发怎么扛、以及我踩过的那些坑。适合正在做 Java 后端 AI Agent 集成、被幻觉和 Token 成本折磨的同行参考。不管你是刚接触 Agent 开发还是已经在生产环境跑了一段时间应该都能从里面找到能直接抄作业的东西。2. 整体架构设计为什么把编排层从 Java 里搬出去2.1 纯 Java 编排 Agent 的三个致命伤最开始我们的方案很Java 原生在 Spring Boot 里写一个 AgentService内部维护一个 ReAct 循环用 OkHttp 调大模型 API解析返回的 tool_calls反射调用本地 Service 方法把结果塞回对话历史再调一次模型。听起来很合理但实际跑起来问题一个接一个。第一个致命伤是幻觉无法收敛。Java 侧的工具描述是写在代码里的模型看到的只是方法名和参数说明。当工具数量超过 20 个模型开始频繁张冠李戴把queryOrderStatus的参数塞给queryInventory。更麻烦的是模型会编造一些根本不存在的工具名比如getUserInfoV2而我们的反射调用直接抛异常整个对话链路中断。第二个致命伤是Token 消耗失控。ReAct 循环每一轮都要把完整的历史对话 所有工具描述重新发给模型。工具描述本身就有几千 Token对话轮次一多输入 Token 呈平方级增长。我们统计过一个处理物流异常的工单平均 8 轮对话输入 Token 累计 3.8 万其中工具描述占了 40%。第三个致命伤是并发扛不住。Agent 的每一轮推理都是同步阻塞的一个请求占用一个 Tomcat 线程模型响应慢的时候线程池直接打满。我们试过用 WebFlux 改造但 ReAct 循环里的状态管理变得极其复杂调试成本高到离谱。2.2 n8n 作为编排层的四个优势把编排层搬到 n8n 之后上面三个问题基本都缓解了。n8n 是一个开源的工作流自动化工具节点式编排支持 HTTP 请求、条件分支、循环、代码节点最关键的是它原生支持 AI Agent 节点和 MCP 工具调用。第一个优势是可视化编排让幻觉可控。在 n8n 里Agent 能调用哪些工具是显式配置的每个工具的输入输出 schema 清清楚楚。当模型返回一个不存在的工具名n8n 的 Agent 节点会直接拦截并返回错误不会像 Java 反射那样抛异常炸掉整个链路。你还可以在工具节点后面加一个校验节点对返回结果做 schema 校验不合格的直接走 fallback 分支。第二个优势是Token 优化有抓手。n8n 的 Agent 节点支持配置最大迭代次数、工具调用结果截断、历史消息窗口大小。我们把最大迭代次数从无限改成 5历史窗口从全量改成最近 3 轮工具描述做了精简Token 消耗直接砍掉一大半。这些配置在 Java 里要写一堆代码在 n8n 里就是几个下拉框。第三个优势是并发模型天然友好。n8n 的工作流执行是异步的一个工作流实例阻塞不影响其他实例。Java 侧只需要暴露无状态的 MCP 工具接口请求进来处理完就返回不持有对话状态。状态全部在 n8n 的工作流上下文里Java 线程池再也不会被打满。第四个优势是调试和迭代快。改一个工具描述、调一个分支条件在 n8n 里点几下就生效不用重新编译部署 Java 服务。我们做 A/B 测试的时候同一套 Java 工具在 n8n 里配两条不同的工作流对比不同 prompt 和工具组合的效果效率比在 Java 里改代码高太多。2.3 MCP 协议Java 和 n8n 之间的契约MCPModel Context Protocol是这套架构的关键粘合剂。简单说它是一个标准化的协议让 AI 应用能以统一的方式发现和调用外部工具。Java 侧把业务能力封装成 MCP Servern8n 侧作为 MCP Client 来调用。为什么用 MCP 而不是直接写 HTTP 接口因为 MCP 自带工具描述、参数 schema、调用结果的结构化定义。模型看到的不再是模糊的调用某个 URL而是清晰的工具名、参数类型、返回值格式。这直接降低了幻觉概率。而且 MCP 支持工具的动态发现n8n 启动时自动拉取 Java 侧的工具列表新增工具不用改 n8n 配置。我们用的是 MCP 的 stdio 和 HTTP 两种传输方式。Java 侧用 Spring AI 的 MCP Server 实现暴露成 HTTP SSE 端点n8n 通过 MCP Client 节点连接。这样 Java 服务可以独立部署、独立扩缩容n8n 只负责编排逻辑。3. Java 侧 MCP 服务实现细节3.1 用 Spring AI 快速搭建 MCP ServerJava 侧我们用的是 Spring AI 1.0 的 MCP Server Starter。依赖很简单在 pom.xml 里加两个dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server-webflux/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server/artifactId /dependency然后写一个配置类注册工具。核心是用Tool注解标注方法Spring AI 会自动扫描并生成 MCP 工具描述Component public class InventoryMcpTools { Autowired private InventoryService inventoryService; Tool(description 根据SKU编码查询实时库存数量返回可用库存和锁定库存) public InventoryResult queryInventory( ToolParam(description 商品SKU编码格式为字母数字组合如SKU12345) String sku) { return inventoryService.queryBySku(sku); } Tool(description 查询指定仓库的库存预警列表返回低于安全库存的SKU) public ListStockAlert queryStockAlerts( ToolParam(description 仓库编码如WH-SH-01) String warehouseCode) { return inventoryService.getAlerts(warehouseCode); } }这里有个关键点工具描述要写得像给新人看的接口文档。模型判断该调哪个工具全靠这段描述。我们踩过的坑是描述写得太简略比如只写查询库存模型分不清是查实时库存还是查历史库存经常调错。后来改成根据SKU编码查询实时库存数量返回可用库存和锁定库存准确率明显提升。3.2 工具粒度设计粗一点还是细一点工具粒度是个需要反复权衡的问题。太细模型要调很多次才能完成一个任务Token 消耗高太粗一个工具内部逻辑复杂参数多模型容易传错参数。我们的经验是按业务动作划分而不是按数据库表划分。比如处理物流异常这个动作涉及查订单、查物流轨迹、判断异常类型、生成处理建议四个步骤。如果拆成四个工具模型要调四次如果合成一个工具参数只有一个订单号内部逻辑全在 Java 里完成。我们选择了后者因为物流异常处理的规则是确定的不需要模型参与判断。但有些场景必须拆细。比如客服工单分类模型需要先看工单内容再决定调用哪个知识库查询工具。这种需要模型做决策的场景工具就要拆细让模型有选择空间。我们最终的粒度原则是确定性的业务逻辑封装成粗粒度工具需要模型判断的决策点拆成细粒度工具。这样既减少了模型调用次数又保留了必要的灵活性。3.3 参数校验和错误处理MCP 工具的参数校验非常重要因为模型传参不可靠。我们在每个工具方法入口都加了校验Tool(description 根据订单号查询订单详情) public OrderDetail queryOrder( ToolParam(description 订单号18位数字) String orderNo) { if (orderNo null || !orderNo.matches(\\d{18})) { throw new McpToolException(订单号格式错误应为18位数字); } OrderDetail detail orderService.getByOrderNo(orderNo); if (detail null) { throw new McpToolException(订单不存在 orderNo); } return detail; }这里的关键是错误信息要结构化且对模型友好。不要抛一个 NullPointerException 让模型猜而是明确告诉它订单号格式错误应为18位数字。模型看到这个错误下一轮会尝试修正参数。我们统计过加了明确的错误提示后模型自我修正的成功率从 30% 提升到 75%。另外所有工具方法都要做超时控制。我们用 Resilience4j 的 TimeLimiter 包了一层单个工具调用超过 3 秒直接返回超时错误。避免某个慢查询拖垮整个工作流。4. n8n 工作流编排实战4.1 工作流整体结构我们的 n8n 工作流大致分四段入口接收 → Agent 推理 → 工具调用 → 结果返回。入口节点是一个 Webhook接收 Java 后端发来的请求请求体里包含用户输入和会话 ID。然后是 Agent 节点配置好模型、系统提示词、可用工具列表。Agent 节点内部会自动处理 ReAct 循环模型返回工具调用请求 → n8n 执行对应工具 → 结果回传给模型 → 模型继续推理直到给出最终答案或达到最大迭代次数。工具调用这一段n8n 通过 MCP Client 节点连接 Java 侧的 MCP Server。每个工具在 n8n 里是一个独立的节点Agent 节点根据模型返回的工具名自动路由到对应节点。最后是结果返回节点把 Agent 的最终输出通过 Webhook Response 返回给 Java 后端。4.2 Agent 节点的关键配置Agent 节点的配置直接决定 Token 消耗和幻觉概率。我们调了很久最终稳定下来的配置是配置项值说明最大迭代次数5超过 5 轮强制返回避免死循环历史消息窗口3只保留最近 3 轮对话减少输入 Token工具结果截断2000 字符超长结果截断避免撑爆上下文温度0.1低温度降低随机性减少幻觉系统提示词见下文明确约束模型行为系统提示词我们改了很多版最终这版效果最好你是一个电商中台助手。你可以调用工具来获取数据。 规则 1. 只使用提供的工具不要编造工具名。 2. 如果工具返回错误根据错误信息修正参数后重试最多重试2次。 3. 如果无法完成任务明确告知用户原因不要编造答案。 4. 回答要简洁只包含用户需要的信息。这段提示词的核心是明确禁止编造并给出重试策略。实测下来加了这段提示词后编造工具名的概率从 15% 降到 2% 以下。4.3 工具节点的错误分支处理n8n 的一个强大之处是每个节点都可以配置错误分支。我们在每个 MCP 工具节点后面都加了一个 IF 节点判断工具返回是否包含错误标识。如果有错误走错误处理分支把错误信息格式化后回传给 Agent如果没有错误走正常分支直接返回结果。这个设计的好处是错误不会中断整个工作流。在纯 Java 方案里工具抛异常会直接炸掉对话链路在 n8n 里错误被捕获并作为信息回传给模型模型有机会自我修正。我们还加了一个重试计数器节点记录每个工具被调用的次数。如果同一个工具被调用超过 3 次强制走 fallback 分支返回该操作暂时无法完成请稍后重试。避免模型陷入无限重试。4.4 Token 优化的具体手段Token 直降 80% 不是靠单一手段而是多个优化叠加的结果。我列一下我们做的几件事和各自的贡献优化手段Token 降幅实现方式历史窗口从全量改 3 轮约 35%Agent 节点配置工具描述精简约 15%Java 侧 Tool 描述优化工具结果截断约 20%n8n 代码节点处理最大迭代从无限改 5约 10%Agent 节点配置粗粒度工具合并约 15%Java 侧工具设计这些优化叠加起来综合降幅在 80% 左右。其中历史窗口和工具结果截断贡献最大。历史窗口从全量改成 3 轮直接砍掉了大量重复的上下文工具结果截断避免了长 JSON 撑爆上下文。这里有个细节要注意历史窗口不能设太小。我们试过设成 1 轮结果模型丢失了上下文经常重复问同样的问题。3 轮是个平衡点既能保留必要的上下文又不会太占 Token。5. 并发场景下的稳定性保障5.1 Java 侧的无状态设计Java 侧 MCP 工具全部设计成无状态的。每个工具方法只依赖入参不依赖任何会话状态。这样 Java 服务可以水平扩容n8n 可以配置多个 MCP Server 端点做负载均衡。会话状态全部放在 n8n 的工作流上下文里。n8n 支持把工作流执行状态持久化到数据库我们用的是 PostgreSQL即使 n8n 重启未完成的工作流也能恢复。5.2 n8n 的并发配置n8n 默认是单进程执行工作流并发能力有限。我们做了两件事提升并发第一开启 n8n 的 queue 模式用 Redis 做任务队列多个 worker 进程并行消费。配置在环境变量里EXECUTIONS_MODEqueue QUEUE_BULL_REDIS_HOSTredis-host QUEUE_BULL_REDIS_PORT6379第二给每个工作流设置执行超时。在 n8n 的工作流设置里把超时时间设为 30 秒。超过 30 秒的工作流强制终止避免慢请求堆积。5.3 限流和降级我们在 n8n 入口的 Webhook 节点后面加了一个限流节点用 Redis 做令牌桶。每个租户每分钟最多 60 次请求超过的直接返回 429。降级策略是当 MCP Server 不可用时n8n 工作流走 fallback 分支返回一个预设的兜底回复而不是报错。这样即使 Java 服务挂了用户也不会看到错误页面。6. 常见问题与排查技巧实录6.1 模型频繁调用错误工具怎么办这是最常见的问题。排查思路分三步第一步检查工具描述是否清晰。把工具描述打印出来让一个不了解业务的同事看问他能不能分清每个工具的用途。如果他都分不清模型更分不清。第二步检查工具数量。工具超过 20 个后模型的选择准确率会明显下降。解决方案是分组把工具按业务域分成多个 Agent每个 Agent 只加载相关工具。第三步检查系统提示词。提示词里要明确告诉模型只使用提供的工具并给出错误处理策略。6.2 Token 消耗突然飙升怎么排查Token 飙升通常是三个原因历史窗口配置被改大、工具返回了超长结果、模型陷入重试循环。排查方法是在 n8n 里开启执行日志记录每次模型调用的输入输出 Token 数。我们写了一个简单的代码节点把 Token 数打到日志里const usage $input.first().json.usage; console.log(Input: ${usage.prompt_tokens}, Output: ${usage.completion_tokens}); return $input.all();然后按会话 ID 聚合找出 Token 消耗异常的会话逐个分析。6.3 MCP 工具调用超时怎么处理超时通常是 Java 侧慢查询导致的。我们在 Java 侧加了慢查询日志超过 1 秒的查询全部记录。然后针对性优化加索引、加缓存。n8n 侧配置了工具调用超时 3 秒超时后返回错误给模型模型会尝试其他方式或告知用户。6.4 常见问题速查表问题现象可能原因排查方向解决方案模型编造工具名工具描述不清检查 Tool 描述补充描述明确用途Token 消耗高历史窗口过大检查 Agent 配置缩小窗口到 3 轮工具调用超时Java 慢查询检查慢查询日志加索引或缓存并发上不去n8n 单进程检查执行模式开启 queue 模式模型重复问同样问题历史窗口过小检查窗口配置增大到 3 轮工具参数传错参数描述不清检查 ToolParam补充格式说明6.5 几个踩过的坑第一个坑是n8n 的 MCP Client 节点版本兼容性。我们一开始用的 n8n 版本比较老MCP Client 节点不支持 SSE 传输只能走 stdio。后来升级到 1.30 以上版本才支持 HTTP SSE。升级前一定要确认版本。第二个坑是Java 侧 MCP Server 的线程模型。Spring AI 的 MCP Server 默认用 Reactor 的调度器如果工具方法里有阻塞操作会阻塞整个调度器。我们的解决方案是把阻塞操作包在Mono.fromCallable().subscribeOn(Schedulers.boundedElastic())里让阻塞操作在弹性线程池执行。第三个坑是n8n 工作流的错误处理。n8n 默认的错误处理是终止工作流但我们希望错误能被 Agent 感知并自我修正。解决方案是在工具节点上配置Continue On Fail让错误作为数据流继续往下走然后在 IF 节点里判断。第四个坑是Token 计数不准。不同模型厂商的 Token 计数方式不一样n8n 的 Token 统计节点用的是估算值。我们后来在 Java 侧也加了一层 Token 统计两边对账以 Java 侧的为准。7. 一些实操心得和后续扩展方向这套方案跑了大半年整体稳定性不错。我个人最大的体会是不要试图让 Java 去做它不擅长的事。Java 擅长的是确定性的业务逻辑、事务、并发控制Agent 的推理、工具选择、多轮对话这些交给专门的编排工具去做。两者通过 MCP 协议解耦各司其职系统反而更稳。另一个心得是工具描述的重要性被严重低估。很多人把工具描述当成注释随便写实际上它是模型理解工具的唯一入口。我们团队现在有个规矩每个 MCP 工具的描述必须经过 review确保清晰、准确、无歧义。这个投入的回报率极高。后续我们打算在这几个方向继续优化一是引入工具调用的缓存相同参数的调用直接返回缓存结果进一步降 Token二是做多 Agent 协作不同业务域用不同的 Agent通过 n8n 的工作流串联三是把 n8n 的工作流配置版本化用 Git 管理方便回滚和审计。最后分享一个小技巧n8n 的工作流可以导出成 JSON我们把这个 JSON 纳入 Git 仓库管理。每次改工作流都提交一次出问题直接回滚到上一个版本。这个习惯帮我们避免了好几次线上事故。