Spring AI 的 Harness Engineering：从 Prompt 模板到 Agent 运行时

Spring AI 在国内 Java 圈最近是真的火不少团队已经从“用 RestTemplate 调 OpenAI”进化到了“Spring AI 大模型”的阶段。但我在帮几个朋友项目做技术评审时发现一个共同现象大家的代码里全是PromptTemplateChatClient的直调接口一多、场景一变代码就开始失控。说白了很多人还停留在“把 Prompt 当字符串拼接”的阶段根本没进入“Agent 运行时”的思维。这篇文章想聊一个我最近在反复琢磨的概念Harness Engineering。它不是说让你去搞一套重型框架而是提醒我们——围绕 LLM 的能力要做工程约束、编排、治理和可观测。标题有点扎心Java Spring AI 作为国内 Java 生态接入 LLM 最顺手的路径逃得过 Prompt 模板的诱惑但逃不过 Harness Engineering 的必然性。下面是基于我用 Spring AI 搭 Agent 运行时的一些实测记录、踩坑日记和设计思路写给正准备从“demo 阶段”往“生产阶段”走的 Java 开发者。1. 为什么说“Prompt 模板”撑不起真正的 Agent1.1 从“问个问题”到“要干活”需求的本质变化先还原一个常见的演进路径。最早接到需求往往是“帮我总结一篇文章”“帮我翻译一段话”。这种任务用一个PromptTemplate就够PromptTemplate template new PromptTemplate(请将以下内容翻译成英文:\\n{content}); Prompt prompt template.create(Map.of(content, content));这阶段没啥问题模型一次性输出你拿字符串去用就完事了。但随着需求变复杂情况就变了多步任务用户说“帮我查一下最近的订单如果金额超过一万就生成一封催款邮件”。这不是一次模型调用能解决的你需要先调用订单查询工具拿到结果后让模型决定下一步。条件分支模型需要根据中间结果决定调用哪个工具、是否继续、是否需要向用户确认。长期记忆多轮对话中用户可能改了需求模型必须记住上下文。权限与安全工具调用得有边界不能让模型随便调删除接口。成本与耗时控制一次任务可能产生十几次模型调用怎么控制总 token 消耗和响应时间。一旦需求变成“要干活”Prompt 模板就只是一个碎片化的零件而不是系统。你缺的是对整个执行过程的管理谁来循环、谁来终止、谁负责兜底、错误怎么恢复。这些东西合在一起其实就是 Agent 的运行时。1.2 Harness Engineering不是玄学是把 LLM“套上缰绳”第一次听到 Harness Engineering 这个概念我脑子里蹦出来的是“马具”——给马套上缰绳、鞍具让它按人的方向跑而不是放任它四处乱窜。放在 AI 工程里其实就是这个意思LLM 是一个很强但很不稳定的“动力源”你要做的不是膜拜它的能力而是给它设计一套可控制、可观测、可恢复的工程结构。我理解 Harness Engineering 在 AI Agent 场景下至少包含四层能力层次要解决的问题工程手段约束层Prompt 注入、敏感词、输出格式失控输入校验、输出校验、分隔符策略、权限白名单编排层多步任务谁来调度、怎么循环、何时终止任务循环、状态机、工具注册表、路由策略可观测层模型调了哪些工具、花了多少 token、哪一步出错审计日志、链路追踪、token 计量、耗时统计恢复层模型返回格式错误、工具调用失败、上下文超长重试、降级、截断、人工兜底这四层恰好是 Spring AI 生态里官方没有直接给你做成一体却把积木全给齐了的东西。你拿ChatClient、Advisor、Tool、ChatMemory自己拼拼出来就是“Agent 运行时”。提示不要把“框架叫不叫 Agent 框架”看得太重。Spring AI 官方文档里没有给你一个AgentExecutor但基于它的扩展点你完全可以搭出轻量级的运行时。关键是你有没有“工程化”的意识而不是代码里有没有Agent这两个字母。1.3 关键认知Agent 不是“模型会调用工具”而是“运行时能承接失败”这里必须纠正一个很常见的误区。不少人以为只要给模型注册了一个Tool它就会乖乖调用工具、处理结果、返回正确答案。实测告诉我模型对工具的调用本质上是一种概率行为不是可靠行为。它会该调工具时不调凭空编造数据调了工具但不按JSON Schema 来传参导致解析失败工具返回结果后它看不懂或曲解结果陷入循环反复调用同一个工具越调越迷茫。所以如果你把“模型调用工具”当成理所当然那你的 Agent 就是个“概率性正确”的玩具。真正的 Agent 运行时核心职责就是承接失败捕捉解析异常、检测循环、超时兜底、必要时让模型重来或者直接转人工。Harness Engineering 的“缰绳”主要就是套在这些不稳定的环节上。2. Spring AI 给 Java 开发者留下了哪些可编排的基础2.1 ChatClient 和 PromptTemplate入门利器但不是终点Spring AI 1.0 之后ChatClient成了主推的入口。它的流式调用、call()/stream()重载、entity()自动映射到 POJO 等功能确实比原生 SDK 顺手得多。比如你可以这么干ChatClient client ChatClient.builder(chatModel).build(); String answer client.prompt() .system(你是一个订单助手回答用户关于订单的问题。) .user(帮我查一下订单 #20240801 的状态) .call() .content();但如果仅止步于此它和“用模板拼字符串”没有本质区别。你要想真正编排就必须用它的扩展点尤其是Advisor链。2.2 Advisor 链拦截器思想在 AI 世界中彻底重演如果你写过 Spring MVC 的拦截器、Spring AOP 的切面或者写过 Dubbo 的 Filter你会秒懂Advisor的定位在模型调用前后插入逻辑。Spring AI 的Advisor接口很简单核心方法Advisor advisor (Advisor) (request, chain) - { // 调用前可以改 prompt、加上下文、校验内容 // 调用chain.call(request) // 调用后可以改 output、记录日志、做数据脱敏 };它的价值在于——你终于可以在不改业务代码的情况下给所有 AI 调用统一套上治理逻辑。我当时把下面这些逻辑全部做成了 Advisor输入安全过滤器检测 prompt 里有没有指令注入比如“忽略之前所有指令”这类模式。输出校验器要求模型输出 JSON 时先做语法校验再返回。审计日志 Advisor记录每次请求的 user prompt、system prompt、响应的前 500 字、token 用量。脱敏 Advisor在 prompt 发给模型之前把身份证号、手机号等敏感信息替换成占位符拿到响应后再还原。这其实就是 Harness Engineering 里的“约束层”。没有 Advisor 之前做这些要全靠手动在业务代码里调痛苦且极易漏。2.3 Tool / Function Calling让 Agent 真正能“干活”Spring AI 的Tool注解让 Java 开发者注册工具变得非常爽Component public class OrderTools { Tool(根据订单号查询订单状态和金额) public OrderInfo getOrderStatus(String orderId) { // 调用订单服务 } }只要把这个 Bean 作为tool传进去Spring AI 会自动生成 OpenAI 格式的 function schema并在模型决定调用时把它代理到这个方法上。这背后的原理是关键模型不直接执行工具而是输出一段结构化的“调用请求”由 Spring AI 解析后反射调用你的方法。听起来很完美实战里的坑却不少我放在下一部分详细说。但先记住一点工具层是 Agent 的“手脚”但你得给“手脚”画好边界。比如删除操作、写操作一定要加权限校验工具方法的入参要设计得尽量简单避免复杂嵌套对象。2.4 ChatMemory别小看了多轮对话的“记忆工程”很多人觉得记忆就是把历史消息丢给模型。错。工程上要头疼的是上下文长度限制模型窗口有限历史消息全塞进去很快就爆。摘要压缩长对话要把早期内容压缩成摘要。多会话隔离用户 A 的记忆不能漏给用户 B。窗口策略选择只保留最近 N 条还是按 token 数切割Spring AI 提供ChatMemory接口常用实现是InMemoryChatMemory可以按conversationId存取消息ChatMemory chatMemory new InMemoryChatMemory(); ChatClient client ChatClient.builder(chatModel) .defaultAdvisors(new MessageChatMemoryAdvisor(chatMemory)) .build(); // 使用时传入 conversationId自动从历史中加载上下文 String answer client.prompt() .user(继续我们刚才的话题) .advisors(a - a.param(ChatMemoryAdvisor.CHAT_MEMORY_CONVERSATION_ID_KEY, user-001)) .call() .content();但实测下来InMemoryChatMemory只适合单机 demo。生产环境要么改成 Redis 存储要么自己实现ChatMemory接口。这块细节后面会讲。3. 从零到一个能跑起来的 Agent 运行时实操记录3.1 分层设计入口、编排器、执行器、工具层我不会直接上 StateMachine 或者工作流引擎那对大多数场景是过度设计。最实用的分层是四层入口层Controller / MQ Consumer接收用户请求负责鉴权、会话绑定。编排层AgentOrchestrator决定“要不要继续调用模型”“调哪个工具”“何时结束”。执行层Executor真正调用 ChatClient处理工具结果管理重试。工具层ToolRegistry注册的工具集合附带校验、权限、熔断逻辑。编排层是核心我用一个很朴素的循环来实现public AgentResult run(AgentRequest request) { int maxIterations 5; ListMessage messages new ArrayList(buildInitialMessages(request)); for (int i 0; i maxIterations; i) { ChatResponse response chatClient.prompt() .messages(messages) .tools(toolRegistry.getAllToolCallbacks()) .call() .chatResponse(); AssistantMessage assistantMessage response.getResult().getOutput(); messages.add(assistantMessage); if (assistantMessage.hasToolCalls()) { // 执行工具调用把结果作为 ToolResponseMessage 加回 messages ListToolResponseMessage toolResults executeToolCalls(assistantMessage.getToolCalls()); messages.addAll(toolResults); continue; // 继续下一轮 } // 没有工具调用说明模型准备输出最终结果 return AgentResult.success(assistantMessage.getText()); } return AgentResult.failure(超过最大迭代次数任务中止); }注意几个细节maxIterations必须硬限制否则模型可能疯狂循环把你 token 烧光。messages手动管理而不直接用 ChatMemory Advisor是为了在编排循环里完全掌控上下文。每次循环工具的注入顺序要保持一致虽然模型大概率不受影响但实测不一致会偶发“幻觉工具调用”。3.2 用 Advisor 搭护栏输入校验、输出校验、审计日志运行时跑起来后第一件事是加护栏。我的经验是用三个 Advisor 搞定Bean public Advisor safetyAdvisor() { return (request, chain) - { String userText request.getInstructions().stream() .map(Instruction::getText) .filter(Objects::nonNull) .collect(Collectors.joining( )); // 简单的注入检测出现这类模式就拒绝请求 if (userText.matches(.*(忽略|无视|ignore|disregard).*(指令|提示|规则).*)) { throw new SecurityException(检测到疑似指令注入已拦截); } return chain.call(request); }; } Bean public Advisor auditAdvisor(ObjectMapper mapper) { return (request, chain) - { long start System.currentTimeMillis(); try { ChatResponse response chain.call(request); // 记录审计日志请求内容、响应摘要、耗时、模型、token auditService.log(request, response, System.currentTimeMillis() - start); return response; } catch (Exception e) { auditService.logError(request, e); throw e; } }; } Bean public Advisor outputGuardAdvisor() { return (request, chain) - { ChatResponse response chain.call(request); String output response.getResult().getOutput().getText(); // 如果业务要求返回 JSON这里做预校验 if (request.getInstructions().stream() .anyMatch(ins - json.equals(ins.getMetadata().get(requireJson)))) { if (!isValidJson(output)) { throw new RuntimeException(模型输出不是合法 JSON终止处理); } } return response; }; }这里有个容易被忽略的细节Advisor 的执行顺序很重要。我建议“输入校验 → 审计 → 模型调用 → 输出校验 → 审计响应”所以要用Order或者显式指定顺序。如果顺序反了审计日志就记不到被拦截的请求了等于白做。3.3 工具注册与参数 Schema 的坑Spring AI 的Tool用起来简单但到了复杂场景就碰到硬茬坑一嵌套对象参数。如果你的工具方法是updateOrder(OrderRequest req)而OrderRequest里有枚举、日期、嵌套对象模型生成的参数大概率对不齐。实测下来模型对复杂 JSON Schema 的参数生成相当不稳定。我的对策是把工具参数直接拍平只用基本类型和简单 String。Tool(更新订单状态。orderId:订单号;status:新状态(枚举值:CREATED,PAID,SHIPPED,DONE);remark:备注) public boolean updateOrder(String orderId, String status, String remark) { // ... }这样模型每次生成参数都不容易错。如果确实需要复杂对象我会在工具方法内部再做一次解析。坑二工具描述不够明确。模型选择工具的行为很大程度依赖Tool的描述。我见过有人写Tool(处理订单)结果模型完全不知道什么时候该用它。正确姿势是描述清楚“这个工具的触发条件 入参含义 返回值”。比如上面那个例子我会写Tool(当用户要求修改订单状态时调用。注意只有订单创建者或管理员可以调用。orderId为订单号status为目标状态。)坑三工具数量不要贪多。注册十几个工具模型选择时不仅耗时变长错误率也会升高。除非业务必要我建议控制在 8 个以内。超过 8 个考虑分组路由先用一个路由工具决定走哪个业务域再到具体工具域里选。3.4 会话级状态管理与超时、重试策略Agent 运行时里还有个很容易被忽视的东西会话状态。比如用户在进行一个“售后工单处理流程”中途可能走了 3 步描述问题 → 上传凭证 → 确认退款。每一步的中间结果放哪里我的方案是引入一个AgentSession对象存在 Redis 里public class AgentSession { private String sessionId; private String userId; private MapString, Object state new ConcurrentHashMap(); private int step; private Instant lastActiveTime; }每一步的工具调用都可能读取/更新这个 state。好处是Agent 不再是“一次性问答”而是有状态的“会话式业务流程”。这也更贴近真实的业务系统。超时与重试我也给出实测推荐值场景推荐策略ChatClient call 超时30 秒视模型而定OpenAI 系建议 60 秒单次工具执行5 秒超时记录错误并让模型“换个方式”编排循环最大轮次5 轮重试策略指数退避 最大 2 次重试并发控制对同一 session 加分布式锁避免并发改写 state注意不要对模型调用做“重试无脑拉满”的配置。模型侧偶发超时还好如果它产生了重复循环重试只会加速烧钱。4. 效果不理想八成是运行时而非模型的问题4.1 工具调用“空转”与死循环如何退避、限流我调试第一个真实 Agent 时模型在“查订单状态 → 发现已发货 → 查物流 → 再看一眼订单”之间来回跳连续循环了 8 次还没停最终靠 maxIterations 兜底中止。单纯扩大循环上限显然是死路更科学的做法是识别重复模式。简单有效的方案在编排层记录最近 N 次工具调用签名如果发现同一个工具 相同参数出现两次以上就主动干预。private SetString recentCallSignatures new HashSet(); boolean isRepeatedCall(String toolName, String argSignature) { String key toolName | argSignature; if (recentCallSignatures.contains(key)) { return true; } recentCallSignatures.add(key); return false; }检测到重复后我的处理方式不是直接报错而是给模型注入一条系统提示“你刚刚已经查过订单 #20240801 的状态了结果是已发货。请不要重复调用直接基于现有信息回答用户。”实测这种“温柔干预”比硬中止效果好用户感知也更平滑。4.2 模型“自说自话”不回工具要不要强插提示另一类高频问题是反过来的模型明明该调用工具它偏不调自己编答案。比如用户问“我上周的订单到哪了”模型直接回答“您的订单已发货预计明天到达”——它根本没查过物流。应对策略有两个方向Prompt 强制约束在 system prompt 里明确写死“如果你需要订单数据必须先调用 getOrderStatus 工具不要猜测”。输出校验拦截让输出内容里包含明确的“数据置信标记”如果模型回答里有数字、日期但又不来自工具结果直接判定为幻觉强制它重新回答。实测下来强插提示只解决一部分问题。最终可靠的做法是在运行时里规定“工具结果为事实来源”核心业务数据必须由工具返回模型只是负责组织语言。如果工具没有返回某字段模型回答就不能包含该字段。这个规则写成 system prompt 的一部分再配合输出校验效果好了非常多。4.3 可观测性从“玄学调优”到“数据调优”很多团队做 Agent调优全凭感觉。同一个 Prompt今天好明天坏不知道为什么。我的做法是把可观测性做进运行时每次模型调用记录模型名、Prompt token、Completion token、总耗时、工具调用列表、是否成功。每次 Agent 任务记录总轮次、总 token、总耗时、结果状态成功/失败/超时、终止原因。定期聚合分析哪个工具调用失败率最高、哪类 prompt 最容易触发幻觉、哪个环节 token 消耗最大。有了这些数据你再回头看那些“玄学”问题会发现大部分都能找到规律。比如我之前发现一个会话的 token 消耗异常高追查日志发现是InMemoryChatMemory在长会话中把历史消息全量带上导致 prompt 越来越长、响应越来越慢。这个问题不看数据光靠猜是猜不出来的。5. 常见问题与排查速查含避坑技巧5.1 高频问题实录现象可能原因排查方向我的处理模型反复调用同一个工具上下文缺乏约束模型没理解“结果已经拿到”查看最近几轮消息确认工具结果是否被模型理解注入“结果已获取不要重复”的提示或识别重复调用签名直接截断工具参数解析失败参数类型复杂、嵌套层级太深查看 Spring AI 生成的 JSON Schema拍平参数为基本类型或在描述里写明取值枚举模型返回 JSON 但解析失败模型输出被 markdown 包裹、或有额外说明文本打印原始响应输出校验 Advisor 里做提取校验必要时让模型只输出 JSON同一 session 上下文错乱多请求并发写同一个 conversationId检查是否存在并发对 session 加分布式锁token 消耗激增上下文无裁剪、历史消息全量携带统计每次调用 prompt token 变化实现窗口截断 摘要压缩按 token 上限裁剪模型不调用工具瞎编数据工具描述不清晰、prompt 约束不够检查 Tool 描述和 system prompt强约束“数据必须来自工具结果”输出校验拦截无来源数据5.2 几个必须避开的“大坑”坑一上下文无限膨胀。如果你的ChatMemory不做窗口限制长会话会越跑越慢、越跑越贵。我建议按 token 数裁剪超过 8000 token 就把最早的消息移除再超过 12000 token 就对前面内容做一轮摘要。摘要可以用单独的模型调用生成成本比全量携带低得多。坑二工具数量失控。我已经反复强调过工具是“越少越好”。每加一个工具模型选错的概率就多一分。架构上可以分层但单个 Agent 的工具集一定要精简。坑三忽略输出校验。模型的输出是自由文本你只凭“prompt 要求它输出 JSON”就相信它会输出合法 JSON这是在赌博。所有结构化输出都要过一层校验校验失败就重试或降级。坑四测试环境与生产环境用同一个模型 Key。测试时刷的 token 是真实成本。我建议测试环境用低配模型或者加限流避免月底账单爆炸。6. 一些摸爬滚打后的个人体会回到开头的话题。我用 Spring AI 把 Agent 从“Prompt 模板”阶段推进到“可编排运行时”阶段最大的感触是真正花时间的不是写工具、不是调 Prompt而是想清楚运行时怎么兜住各种失败。模型的能力边界你控制不了但工程上能控制的是上下文给它喂什么、工具允许它碰什么、输出怎么校验、循环怎么终止、失败怎么恢复。这正好是 Harness Engineering 的核心含义——用一个扎实的“马具”把 LLM 这匹烈马驾驭在业务轨道上。Spring AI 没有直接给你一整套编排运行时但它提供的Advisor、ChatMemory、Tool、ChatClient这些积木足够你搭建一版轻量级的运行时。别指望框架替你解决所有问题工程的责任始终在你这边。如果你也在用 Spring AI 做 Agent建议先别急着加新功能停下来审视一下自己的代码你的模型调用链路上有没有护栏有没有日志循环有没有兜底上下文有没有裁剪这几个问题回答不上来那就说明你还没走到 Agent 运行时还在 Prompt 模板的舒适区里打转。