Java AI Agent 从 Demo 到生产Spring AI / LangChain4j 的真实踩坑清单Demo 能跑不代表生产能活。这是大量 Java 团队在把 LLM Agent 接入既有 Spring Boot 系统后得到的共同结论聊天界面能出字、工具能调通、演示视频很流畅可一旦进入多轮会话、真实数据、成本核算和灰度运维问题就会从模型答得不好变成系统边界没守住。这些问题往往不是换一个更强的模型就能解决的它们属于工程化外壳的职责缺口。需要先说明两点证据边界。其一本文引用的 AgentScope 2.0 Harness 工程化层表述来自知乎上两篇产品线解读文章[1][2]属于二手材料本文只借用其分析视角不引入该运行时也未核实其官方定义措辞与发布日期。其二文中的具体故障现象来自 Stack Overflow 的单点提问[3][4][5][6][7]本文按现象 → 排查 → 改造 → 验证展开不下某框架存在缺陷的结论凡涉及类名、方法名、配置属性的代码块均标注为示意骨架实际 API 请以所用版本的官方文档和源码为准。研究数据中各条来源均无可靠发布时间与热度值因此本文不做近期趋势断言。Demo 能跑为什么生产会翻车先建立 Harness 角度的自查框架Harness 工程化层把模型能力和系统可靠性分开看按 AgentScope 2.0 相关解读文章的提法企业级 Agent 需要在模型与推理循环之外再加一层工程化外壳用它承担记忆管理、工具边界治理、组件注册装配、可观测计量、评测回归等职责[1][2]。这个分层的价值不在于发明新概念而在于给出了一个归因工具当你遇到上下文丢了“SQL 执行出事了”账单对不上这类问题时先问它属于哪一层再决定是改框架配置、改装配方式还是必须在业务侧兜底。把这套视角映射到 Spring AI 与 LangChain4j可以得到一张故障面矩阵Harness 职责典型故障本文对应章节主要归因层记忆与上下文管理记忆里存入原始 JSON 响应重载后上下文异常第二节框架行为 业务序列化约定工具边界与副作用治理LLM 生成的 SQL 被直接执行产生副作用第三节必须由业务侧兜底可观测与计量拿不到 token 用量成本与限流无从谈起第四节SDK 与封装层的响应模型差异装配与注册子 Agent 报 “No agent found with name”第五节Spring 装配与框架注册机制不互认模型与数据接入Embedding 凭据、维度、检索链路不通第六节基础设施与一致性约束这张表同时是一份自查清单如果五格中有三格以上说不清我们的处理方式是什么那么问题已经不是框架选型而是缺少一个稳定的工程化外壳。关于版本还有一处必须提醒Spring AI、LangChain4j 在演进过程中对用量对象、记忆抽象、Agent 注册相关 API 做过调整社区文章标题中的Spring AI 2.0称谓来自第三方内容[10][11]本文未核实其正式发布状态。因此本文的代码一律按思路骨架给出落地前请锁定你实际使用的版本并对照其文档。记忆坑MessageChatMemoryAdvisor 存下 raw JSON导致上下文丢失现象一个在 Stack Overflow 上被提出的典型问题是在 Spring AI 中使用 JSON_OBJECT 响应格式时MessageChatMemoryAdvisor 把模型返回的原始 JSON 文本整体存进了对话记忆当会话被重新加载、继续多轮对话时上下文表现异常用户的感受就是模型忘了之前聊过什么[3]。注意上下文丢失这个说法在这里其实是两件事的混合一是记忆里存的内容不正确二是不正确的内容被回灌进后续 prompt污染了上下文。前者是序列化问题后者是通道隔离问题排查时要分开。排查路径按三条线拆开定位可以很快排除模型能力因素**写入记忆的到底是什么对象。**是模型原始响应文本、解析后的结构化对象还是规范化后的 assistant 消息如果是前者那么记忆里存的 JSON 壳子本身就不是合格的对话内容。可以在记忆实现上加日志直接打印落库的消息类型与内容前若干字符。**读取记忆时如何还原。**重载会话后记忆读出的消息被怎样转换成 prompt 的一部分如果把 raw JSON 当作 assistant 的发言回灌模型会把它当成上一轮模型就是这么说话的从而在风格和结构上被带偏。**格式化指令是否被当作对话历史。**JSON_OBJECT 这类响应格式要求通常通过系统提示或请求参数施加如果把请输出合法 JSON这类指令也当作用户/助手消息写进记忆它会在后续轮次反复出现并干扰语义。区分这三条线之后结论会落在哪一层也就清楚了如果写入的是原始响应属于框架默认行为与业务序列化约定不匹配如果记忆容器在请求结束时随作用域销毁属于状态管理问题两者都不是模型质量问题。改造要点**第一记忆写入前先做规范化。**在响应进入记忆之前插入一层解析与归一化只把结构化的 assistant 消息内容入库格式化外壳和中间解析产物一律丢弃。下面是示意骨架展示管道形状具体 Advisor 与消息类型的构造方式请对照你所用版本的 Spring AI 文档// 示意骨架响应 - 解析 - 规范化消息 - 入记忆具体 API 以官方文档为准publicAssistantMessagenormalize(ChatResponseraw,ResponseFormatformat){Stringtextraw.getResult().getOutput().getText();if(formatResponseFormat.JSON_OBJECT){JsonNodenodejsonParser.parse(text);// 解析失败应走明确的重试/降级分支returnnewAssistantMessage(canonicalize(node));// 只存规范化后的语义内容}returnnewAssistantMessage(text);}**第二记忆存储与请求生命周期解耦。**生产环境里内存型 ChatMemory 无法跨实例、跨重启存活需要换成持久化实现如基于 JDBC 或 Redis 的消息存储并明确会话 ID 的生成与过期策略。社区案例中出现的 pgvector SSE 多模型组合项目也把状态落库当作基本盘[8]。**第三通道隔离。**系统指令、格式化约束、工具调用结果、用户输入与助手回答应当分通道存储与回放不要都压平成一串字符串。工具调用尤其容易出问题原始 tool payload 回灌会迅速撑爆上下文窗口。验证方式写一个两轮对话的集成测试第一轮用 JSON_OBJECT 格式提问并解析结果第二轮提出依赖第一轮答案的追问同时打印记忆读回内容并断言其中不包含 JSON 结构壳子。这个测试比人工看输出可靠得多也应当成为回归集的一部分。工具边界坑LLM 生成 SQLAST 校验必须做在执行之前现象与原则Stack Overflow 上有开发者提出LLM 生成 PostgreSQL 查询时如何在 Java 侧安全校验 AST以防止副作用[4]。这是典型的工具边界问题也是全文最不能妥协的一节。必须先确立原则**模型侧约束只作提示不作安全边界。**系统提示里写只生成 SELECT对真正的攻击面没有任何保证因为提示词可被用户输入、检索到的文档、甚至工具返回内容间接注入。安全边界必须落在代码路径上位于 SQL 文本与数据库连接之间。分层防护一个可执行的最小方案至少包含五层**1. 语句切分与预拒绝。**先把多语句、注释、异常字符挡掉。注意三类常见绕过;藏在--注释后、藏在/* */块注释中、藏在 PostgreSQL 的 dollar-quoted string$$ ... $$里。用字符串切割判断语句数量是不可靠的必须依赖真正的词法/语法解析结果。**2. AST 解析。**候选解析库包括 JSqlParser 与 Apache Calcite但两者对 PostgreSQL 方言扩展语法的覆盖度不同使用前必须用你实际会生成的语句做覆盖测试解析失败应当直接拒绝而不是降级为放行并执行。这一点在实践中常被写反。**3. 节点白名单。**只允许 SELECT 与 WITH 开头的只读查询遍历 AST 时对出现的节点类型做白名单判定// 示意骨架AST 节点白名单判定具体 API 以所选解析库文档为准booleanisSafe(Noderoot){returnvisitor.visitAll(root,node-switch(node.type()){caseSELECT,FROM,WHERE,JOIN,GROUP_BY,ORDER_BY,LIMIT,COLUMN,LITERAL,FUNCTION_WHITELISTED-true;caseINSERT,UPDATE,DELETE,DROP,ALTER,CREATE,GRANT,CALL,TRANSACTION_CTL,SET-false;default-false;// 未识别节点一律拒绝});}白名单要特别覆盖 PostgreSQL 的几个隐蔽面数据修改型 CTEWITH x AS (INSERT ...) SELECT ...、SELECT ... FOR UPDATE这类加锁子句、可能有副作用或高开销的函数如pg_sleep、dblink、大对象函数、以及set_config这类会改会话状态的调用。函数名也要走白名单而不是黑名单。**4. 执行层兜底。**即便 AST 判断通过数据库侧仍要设防使用只读账号或只读事务、设置语句超时与锁等待超时、限制返回行数、限制可访问的 schema固定search_path、关闭不必要的扩展。这一层独立于解析库是纵深防御的底座。**5. 模型侧约束。**在提示中要求只读查询并要求模型先输出意图再输出 SQL便于审计与回放。它能降低误操作概率但不能替代前四层。执行流水线的形状是用户意图 → LLM 生成 SQL 文本 → AST 校验 → 只读执行沙箱 → 结果脱敏返回。其中模型不可信边界恰好落在 SQL 文本生成之后任何跨越这条边界的直连执行都是缺陷。一个容易被忽略的取舍严格白名单会带来拒答率上升。正确的处理不是放宽校验而是把被拒绝的 SQL作为可观测事件记录下来回到提示工程或语义层预定义查询模板、语义视图去解决。在高可靠场景里宁可让 Agent 回答这个查询我不能执行也不要让它执行一个没人审计过的语句。可观测坑token 用量拿不到成本与限流就无从谈起现象有开发者在使用 google-genai Java SDK v1.23.0 调用 Gemini 2.5 Flash 时询问如何从 GenerateContentResponse 中取得 usageMetadata 的 token 用量信息[5]。这类问题在多框架混合的技术栈里非常普遍用量信息存在但藏在不同的响应结构里经过封装层之后又可能被丢掉。排查路径**确认原生响应上的实际访问路径。**用量元数据在不同 SDK 版本中的字段名和暴露方式可能不同必须以该版本的 javadoc 为准不要凭印象写 getter。**区分两条链路。**直连 SDK 的响应对象与经过 Spring AI / LangChain4j 封装后的响应对象不是一回事。封装层如果只取了文本结果用量元数据就会在这一层蒸发。这解释了为什么在 SDK 文档里看得到、在业务代码里拿不到。**注意 OpenAI 兼容接口的差异。**很多团队通过兼容网关接入模型此时 usage 的位置和字段命名跟随兼容协议与厂商原生 SDK 不同混用时极易取到 null。改造要点把用量采集做成统一出口的拦截器而不是散落在每个调用点。拦截器按模型、租户、场景、Agent 名称打点输出至少包括输入 tokens、输出 tokens、总 tokens、调用延迟、失败类别。这些指标同时支撑三件事成本分摊、限流配额、容量规划。拿不到精确用量时要有降级方案用 tokenizer 估算 token 数并在指标中显式打上估算标记避免估算值污染成本核算口径。这一点常被省略结果是报表里出现一批来源不明的数字。在指标侧建议把精确计量覆盖率本身作为一个指标上报即多少比例的调用拿到了真实 usage。这个覆盖率若长期偏低说明采集点埋设有遗漏。装配坑Spring Bean 子 Agent 报 “No agent found with name”现象LangChain4j 与 Spring 集成时有开发者遇到使用 Spring Bean 声明的子 Agent 在运行时抛出 “No agent found with name” 的错误[6]。这个报错的表象是找不到根因可能是命名、注册、生命周期或条件装配中的任意一种不能一上来就归因于框架。排查清单按以下顺序逐条验证通常前两条就能定位**注册名与引用名是否一致。**包括大小写、前后缀、限定符。多 Agent 编排时名称常由常量或字符串字面量维护重命名重构很容易漏改引用。**子 Agent 是否真的进入了框架的注册表。**Spring 的 Bean 只保证它是一个 Spring Bean不等于框架的 Agent 注册机制会自动发现它。如果框架依赖自己的注解或扫描机制注册而你只写了 Bean就会出现Bean 在容器里、不在注册表里的错位。**初始化顺序。**主 Agent 装配时若子 Agent 尚未完成注册引用解析会失败。注意 Bean 的依赖声明是否显式避免依赖脆弱的初始化顺序巧合。条件装配。Conditional、Profile、配置开关都可能让某个 Bean 在特定环境根本不存在此时报错是症状条件表达式才是病因。在排查时先确认所用 LangChain4j 版本中子 Agent 的实际注册接口或注解名称以及是否有已采纳答案给出结论不同版本的集成方式并不一致凭记忆命名 API 是高风险动作。改造要点**集中注册。**用一个显式的注册配置类把所有 Agent 的定义收拢名称统一定义为常量主 Agent 与子 Agent 的引用都指向这些常量。**启动期自检。**在应用启动完成后遍历引用关系缺引用立即 fail-fast而不是等到第一个用户请求才报错// 示意骨架启动期注册完整性自检具体注册表 API 视框架版本而定voidvalidateRegistry(AgentRegistryregistry,RequiredRefsrefs){SetStringmissingrefs.names().stream().filter(name-!registry.contains(name)).collect(toSet());if(!missing.isEmpty()){thrownewIllegalStateException(Agent 注册缺失: missing);}}**集成测试覆盖注册完整性。**用最浅层的上下文启动测试跑一遍装配成本很低但能在 CI 阶段拦住绝大多数装配类问题。这类问题在单测中永远不出现在生产中却以某个功能整体不可用的形式爆发是最典型的 Harness 缺口。接入坑Embedding以 Vertex AI 为例在 Spring Boot 里的最小接入路径常见卡点有开发者询问在 Spring Boot 应用中使用 Vertex AI Embedding 的做法[7]。这类问题通常不是调不出向量而是一串连环卡点**凭据与环境。**服务账号、Application Default Credentials 的加载顺序、区域端点与项目 ID 的配置在本地、CI、生产三套环境往往不一致。最常见的表现是本地跑通、容器里抛权限或端点异常。**模型接入层。**Spring AI 与 LangChain4j 都提供了 Embedding 抽象但与 Vertex AI 对应的实现模块的官方支持状态、实现类名与配置属性会随版本变化接入前应查证所用版本的文档与模块清单而不是照搬教程代码。**存储与检索。**向量库可选 pgvector 或 Elasticsearch社区案例中两者都有实践参考[8][12]。选择时考虑现有基础设施如果团队已经运行 PostgreSQLpgvector 的运维成本更低如果已有 Elasticsearch 集群并需要混合检索则后者更顺手。**一致性。**这是最容易出隐性故障的地方入库向量与查询向量必须来自同一模型版本、同一维度、同一归一化约定。一旦中途升级了 embedding 模型旧向量与新查询之间的相似度不再可比检索质量会静默下降而监控往往看不到错误只能看到效果变差。最小接入流程// 示意骨架Embedding 调用流程接口签名以官方文档为准float[]docVectorembeddingModel.embed(documentText);float[]queryVectorembeddingModel.embed(userQuery);ListMatchmatchesvectorStore.topK(queryVector,8);向量表的 DDL 形状大致如下以 pgvector 为例维度按你的模型实际输出填写-- 示意骨架向量表结构维度需与所用 embedding 模型输出一致CREATETABLEdocument_chunks(id bigserialPRIMARYKEY,doc_idvarchar(64)NOTNULL,chunk_texttextNOTNULL,embedding vector(768)NOTNULL,model_vervarchar(32)NOTNULL,created_at timestamptzNOTNULLDEFAULTnow());CREATEINDEXONdocument_chunksUSINGhnsw(embedding vector_cosine_ops);model_ver字段值得保留它让模型升级时可以并行写入新版本向量、灰度切换检索版本而不是一次性全量重算后被迫回滚。RAG 数据流为文档 → 切分 → embedding → 向量库 → 检索 → 组装上下文其中切分粒度、top-k 数量与上下文预算需要联动调优否则会出现检索到的片段塞不下上下文窗口的问题。面向存量 Spring 项目的最小改造路径对于已经有多年业务逻辑的 Spring 项目核心原则是不动主干、旁路接入、状态外置、治理收口。分三阶段推进每阶段都有明确的回滚点。**阶段 0旁路接入1–2 天。**在一个独立模块或 starter 中引入模型客户端先做无状态单轮能力例如文案生成、摘要、分类打标。不碰业务事务不引入记忆不开放工具调用。此时的风险面只有网络调用与超时回滚方式是关闭功能开关走原逻辑。**阶段 1状态与工具外置约 1–2 周。**把第二节的记忆持久化、第三节的工具白名单与 SQL 校验、第四节的用量采集一次性补齐。这三项必须在开放工具调用之前完成顺序不能颠倒先有边界与计量再有能力。回滚点是保留旧的无状态路径Agent 能力通过开关降级。**阶段 2治理收口按需。**加入第五节的 Agent 注册自检、第六节的 RAG 与 Embedding、评测回归集、灰度与熔断。此时 Agent 已经承载业务流量治理能力必须同步到位。回滚点是按场景灰度回退到上一阶段能力。每阶段的改动清单、新增依赖与验证方式归纳如下阶段改动点新增依赖验证方式回滚方式0 旁路接入独立 AI 模块、模型客户端、超时配置模型 SDK 或框架 starter单轮调用集成测试功能开关关闭1 状态与工具外置记忆持久化、SQL 校验、用量采集持久化记忆实现、SQL 解析库、指标组件两轮记忆测试、SQL 校验单测、用量指标核对降级到无状态路径2 治理收口注册自检、RAG、评测集、灰度熔断向量库驱动、检索组件注册完整性测试、检索回归集按场景灰度回退需要强调的是社区已有的案例组合Spring AI RAG MCP pgvector SSE[8]以及给老 Spring 项目装 AI Agent的实践讨论[9]可以作为技术栈选型的参考坐标但其内部实现细节不在本文复述范围本文也不假定其可复现性。真实落地时应优先选取可运行的开源仓库作为参照并自行完成依赖版本与安全审计。落地检查清单与证据边界上线前逐项核对检查项通过标准记忆持久化重启后会话可恢复测试中可断言记忆内容不含原始响应壳子SQL 校验多语句、注释绕过、数据修改型 CTE、危险函数均有单测覆盖执行沙箱只读账号、语句超时、行数上限、schema 限制全部生效用量计量指标可见、按模型/租户维度可分组估算值有独立标记Agent 注册启动期自检 fail-fast集成测试覆盖注册完整性Embedding 一致性模型版本锁定入库与查询向量维度、归一化一致降级与熔断超时、限流、模型不可用时可回退到非 AI 路径数据出网审计敏感字段脱敏策略明确调用日志可追溯最后交代本文的证据边界以免读者把局部经验当成普遍结论第一五个故障现象均来自 Stack Overflow 的单点提问[3][4][5][6][7]本文未能在写作过程中逐条复现也未核实全部已采纳答案的结论请将其当作排查起点而非定论。第二Harness 工程化层的表述来自与产品线相关的解读文章[1][2]存在内容营销放大效应的可能本文只借其分类框架未引用其产品结论。第三本文所有代码块均为思路骨架。Java AI 框架的 API 演进较快类名、方法名、配置属性在不同版本间存在差异落地前必须以所用版本的官方文档与源码为准无法确认的抽象宁可写框架提供 X 能力具体接口见官方文档也不要凭印象命名。第四本批研究数据缺少发布时间与热度信息也没有 GitHub、官方博客等一手来源因此本文不做时间敏感的趋势判断。若要把本文中的某个坑位写成生产事故复盘还需要补充可复现的工程数据。归根结底从 Demo 到生产隔着的不是一个更大的模型而是记忆、工具边界、可观测性、装配注册、模型接入这五块工程化外壳。它们都不性感但决定了 Agent 在真实系统里能活多久。参考资料[1] 研发企业级 AI Agent为什么需要 Harness 工程化层解析 AgentScope 2.0 的设计哲学知乎https://zhuanlan.zhihu.com/p/2061417519588680299[2] AI Agent 从 Demo 到大规模生产中间隔着多少工程化鸿沟AgentScope 2.0 深度解析知乎https://zhuanlan.zhihu.com/p/2046267814298784797[3] MessageChatMemoryAdvisor stores raw JSON response when using JSON_OBJECT response format, causing context loss on conversation reloadStack Overflowhttps://stackoverflow.com/questions/79894013/[4] Safely validating AST of LLM-generated PostgreSQL queries in Java to prevent side effectsStack Overflowhttps://stackoverflow.com/questions/79906727/[5] How to access usageMetadata (token usage) from GenerateContentResponse using google-genai Java SDK (v1.23.0) with Gemini 2.5 Flash?Stack Overflowhttps://stackoverflow.com/questions/79794964/[6] LangChain4j throws “No agent found with name” when using Spring Bean sub-agentsStack Overflowhttps://stackoverflow.com/questions/79890669/[7] using Vertex AI Embedding in Spring Boot AppStack Overflowhttps://stackoverflow.com/questions/79880065/[8] JChatMindJava AI Agent 项目实战Spring AI RAG MCP pgvector SSE 多模型知乎https://zhuanlan.zhihu.com/p/1992998854321254698[9] 给老 Spring 项目装个 AI Agent知乎https://zhuanlan.zhihu.com/p/2081328811451466147[10] Spring AI 2.0 进阶入门RAG、Structured Output 与 Agent 信息闭环知乎https://zhuanlan.zhihu.com/p/2082759430844827524[11] Spring AI 2.0 Agent 进阶Tool Calling、Action 与可靠执行知乎https://zhuanlan.zhihu.com/p/2084562921976230508[12] JD Conf 2026使用 Spring AI 与 Elasticsearch 轻松构建 Java RAGB站https://www.bilibili.com/video/BV1FF9mBTEUY[13] 2026 年了Java AI 五大框架根本不用五选一知乎https://zhuanlan.zhihu.com/p/2076310870624413559[14] 华为首次发布智能体编程平台码道不是拼生成量而是在百万行 Java、长周期维护与高可靠中运行知乎https://zhuanlan.zhihu.com/p/2010426113038521363[15] Spring AI Alibaba Nacos 动态 MCP Server 代理方案知乎https://zhuanlan.zhihu.com/p/1913275830370538706
