聊聊 Agent 工程化：Demo 很好写，生产却处处是坑-北京尧图网络

前言很多同学初学 Spring AI Alibaba 智能体时都会觉得 Agent 开发非常简单定义工具、注入模型、写一段提示词、调用agent.call()即可运行。但这种只能跑通的 Demo Agent绝对无法上线生产。日常开发中90% 的 Agent 线上问题无限循环调用工具、模型幻觉、参数乱传、任务失控、无法排查全部源于缺少生产级防护。本文不讲传统编程、Workflow、Skill 基础概念只讲Spring AI Alibaba 生产级 Agent 的核心落地标准带完整可运行代码案例区分「玩具 Agent」和「线上可用 Agent」的本质区别。阅读提示本文基于 Spring AI Alibaba 1.1.x 版本部分 API 与早期版本存在差异建议对照实际依赖版本确认方法签名。一、为什么 Demo Agent 不能上生产1.1 Demo 版简易 Agent反面案例不要直接上生产特点代码少跑 Demo 很爽上线会出各种问题ServiceRequiredArgsConstructorpublic class SimpleDemoAgentService {private final ChatModel chatModel;private final DemoTool demoTool;public ReactAgent buildDemoAgent() {ToolCallbackProvider toolProvider ToolCallbackProvider.of(demoTool);return ReactAgent.builder().name(demo-agent).model(chatModel).tools(toolProvider.getToolCallbacks()).instruction(你是订单故障排查专家使用工具完成故障排查。)// 没有最大迭代、没有超时、没有持久化、没有监听.saver(new MemorySaver()).build();}public String execute(String goal) {ReactAgent agent buildDemoAgent();return agent.call(goal).getContent();}}Serviceclass DemoTool {Tool(description 根据订单号查询错误日志)public String queryErrorLog(ToolParam(description 订单号) String orderNo) {throw new RuntimeException(数据库查询异常);}}1.2 Demo Agent 线上必现的坑没有最大迭代限制模型可能无限循环调用同一个工具工具抛出异常直接打断整个 ReAct 推理循环任务直接失败使用MemorySaver服务重启任务状态全部丢失没有事件监听工具调用、思考过程无记录出问题无法排查无超时控制遇到大模型慢响应会持续占用业务线程提示词只有角色缺少失败策略、禁止行为约束二、生产级 Agent 完整代码案例2.1 生产工具层Skill 改造重点工具只负责原子能力异常由框架统一处理无需在每个工具方法中重复 try-catch。Spring AI Alibaba 内置了ToolExecutionExceptionProcessor机制。该接口是一个函数式接口用于将工具抛出的ToolExecutionException转换为可发送回 AI 模型的字符串或者抛出异常供调用者处理。这意味着我们可以在 Agent Builder 层面统一配置异常处理策略工具类本身保持干净。import lombok.RequiredArgsConstructor;import lombok.extern.slf4j.Slf4j;import org.springframework.ai.tool.annotation.Tool;import org.springframework.ai.tool.annotation.ToolParam;import org.springframework.stereotype.Service;Slf4jServiceRequiredArgsConstructorpublic class TroubleShootTool {Tool(description 根据订单号查询订单错误日志获取故障信息)public String queryErrorLog(ToolParam(description 订单编号) String orderNo) {// 入参校验直接抛异常由 ToolExecutionExceptionProcessor 统一处理if (orderNo null || orderNo.isBlank()) {throw new IllegalArgumentException(orderNo不能为空);}// 模拟业务查询逻辑// return db.selectLog(orderNo);throw new RuntimeException(数据库连接异常);}Tool(description 查询订单基础信息)public String queryOrderInfo(ToolParam(description 订单编号) String orderNo) {if (orderNo null || orderNo.isBlank()) {throw new IllegalArgumentException(orderNo不能为空);}return {\orderNo\:\ orderNo \,\userId\:10001,\amount\:129.00};}}2.2 全链路可观测基于 Hook 机制采集运行轨迹重点框架提供Hook机制可在模型调用前后、工具执行前后插入自定义逻辑。Hook 逻辑要轻不能阻塞主链路。Spring AI Alibaba 内置了多种 Hook包括ModelCallLimitHook限制 LLM 调用次数、ToolCallLimitHook限制工具执行次数、HumanInTheLoopHook人工审批、PIIDetectionHook敏感信息检测等。以下自定义 Hook 用于采集 Agent 全链路运行轨迹import com.alibaba.cloud.ai.graph.agent.hook.Hook;import lombok.extern.slf4j.Slf4j;import org.springframework.stereotype.Component;import java.util.Map;Slf4jComponentpublic class TraceHook implements Hook {private long taskStartTime;Overridepublic int getOrder() {return 0;}Overridepublic MapString, Object beforeModelCall(MapString, Object context) {if (taskStartTime 0) {taskStartTime System.currentTimeMillis();log.info([AgentTrace]任务开始);}log.info([AgentTrace]模型调用前上下文键:{}, context.keySet());return context;}Overridepublic MapString, Object afterModelCall(MapString, Object context) {log.info([AgentTrace]模型调用完成);return context;}public long getCostMs() {return System.currentTimeMillis() - taskStartTime;}}Hook 接口提供了getTools()默认方法允许 Hook 向 Agent 动态注册工具。耗时统计需业务代码自行完成并落库框架不会自动持久化。2.3 构建生产级 ReactAgent 服务核心点工具级超时、模型调用限制、生产提示词、注入 Hook、持久化 Saver、异常兜底。import com.alibaba.cloud.ai.graph.agent.ReactAgent;import com.alibaba.cloud.ai.graph.checkpoint.BaseCheckpointSaver;import com.alibaba.cloud.ai.graph.agent.hook.modelcalllimit.ModelCallLimitHook;import lombok.RequiredArgsConstructor;import lombok.extern.slf4j.Slf4j;import org.springframework.ai.chat.model.ChatModel;import org.springframework.stereotype.Service;import java.time.Duration;Slf4jServiceRequiredArgsConstructorpublic class ProductionAgentService {private final ChatModel chatModel;private final TroubleShootTool troubleShootTool;private final TraceHook traceHook;// 生产替换 MemorySaver使用 RedisSaver / JDBCSaver 等持久化实现private final BaseCheckpointSaver checkpointSaver;/*** 构建生产可用 Agent 实例*/public ReactAgent buildProductionAgent() {// 生产提示词不只是角色增加强制约束、失败策略String productionInstruct 你是订单故障排查专家。1. 可以调用工具查询订单信息、查询错误日志。2. 如果工具返回以【工具调用异常/工具业务错误】开头内容不要无限重试同一个工具。3. 证据收集充分后直接输出排查结论主动结束任务禁止无意义调用工具。4. 禁止编造工具禁止编造业务数据全部信息来源于工具返回。;return ReactAgent.builder().name(production-trouble-agent).model(chatModel).methodTools(troubleShootTool) // 直接传入工具对象.instruction(productionInstruct).checkpointSaver(checkpointSaver) // 持久化状态存储.toolExecutionTimeout(Duration.ofSeconds(30)) // 工具级超时默认5分钟.toolExecutionExceptionProcessor((ex, toolName, toolInput) - {// 统一异常处理将异常转为可发送给模型的错误文本log.error(工具[{}]执行异常入参:{}, toolName, toolInput, ex);return 【工具调用异常】 toolName 执行失败 ex.getMessage();}).hooks(ModelCallLimitHook.builder().runLimit(5).build(), // 限制模型调用次数traceHook // 全链路轨迹采集).build();}/*** 对外执行 Agent 任务统一异常兜底*/public String runAgentTask(String userGoal) {ReactAgent agent buildProductionAgent();try {String result agent.call(userGoal).getContent();log.info([Agent]任务完成总耗时{}ms, traceHook.getCostMs());return result;} catch (Exception e) {log.error([Agent]执行发生系统异常耗时{}ms, traceHook.getCostMs(), e);if (e.getClass().getSimpleName().contains(MaxIterations)|| e.getMessage() ! null e.getMessage().contains(limit)) {return 任务终止已达到最大工具调用轮次无法继续执行请精简问题重试。;}return AI任务执行系统异常请稍后重试。;}}}2.4 持久化 Saver 的选择MemorySaver仅适合开发测试生产环境需选用持久化实现。Spring AI Alibaba 提供了多种开箱即用的 SaverSaver 实现存储后端适用场景MemorySaverJVM 堆内存开发/测试/单机进程重启丢失RedisSaverRedis生产级分布式部署支持过期策略JDBCSaverMySQL/PostgreSQL/H2关系型数据库持久化MongoDBSaverMongoDB文档型数据库持久化FileSaver文件系统本地文件持久化Configurationpublic class GraphSaverConfig {BeanConditionalOnMissingBeanpublic BaseCheckpointSaver redisSaver(RedisConnectionFactory connectionFactory) {return new RedisSaver(connectionFactory);}}2.5 简单测试 ControllerRestControllerRequiredArgsConstructorpublic class AgentTestController {private final ProductionAgentService productionAgentService;GetMapping(/agent/prod/execute)public String execute(RequestParam String goal) {return productionAgentService.runAgentTask(goal);}}访问示例http://localhost:8080/agent/prod/execute?goal帮我排查订单O20260919001为什么提交失败三、Demo Agent vs 生产 Agent 核心对比维度Demo 玩具 Agent生产级 Agent执行约束完全依赖模型自觉ModelCallLimitHooktoolExecutionTimeout双重硬护栏工具异常处理直接抛异常中断任务ToolExecutionExceptionProcessor统一处理模型自主决策提示词仅角色描述包含完整业务约束、禁止行为、容错策略可观测性无轨迹、无日志、无法排查Hook 机制监听模型调用、工具执行、耗时全记录状态存储MemorySaver内存重启丢失RedisSaver/JDBCSaver持久化可回溯可恢复上层编排直接对外暴露调用嵌入 Workflow作为子任务执行四、代码关键点解读1. 工具异常统一处理 ——ToolExecutionExceptionProcessorToolExecutionExceptionProcessor是一个函数式接口用于处理ToolExecutionException将异常转换为可发送回 AI 模型的字符串。这意味着工具类只需抛出异常无需在每个方法中重复 try-catch。模型收到错误文本后会自主决策是重试还是放弃而不是被异常中断推理循环。2. 硬护栏 ——ModelCallLimitHooktoolExecutionTimeoutModelCallLimitHook是 Spring AI Alibaba 内置的 Hook用于限制每个线程或每次运行的 LLM 调用次数。toolExecutionTimeout控制单个工具的执行超时默认值为 5 分钟。两者配合形成双重保护前者防止模型无限循环后者防止单个工具挂起。3. Hook 机制 —— 可观测性的核心Spring AI Alibaba 的 Hook 机制允许在 Agent 执行流程的特定位置BEFORE_MODEL、AFTER_MODEL 等插入自定义逻辑。工具调用名称、参数、模型思考均可通过 Hook 捕获。耗时、迭代计数需要业务代码自行统计落库框架不会自动持久化。Hook 逻辑要轻不能阻塞主链路。4. 状态存储 ——BaseCheckpointSaverMemorySaver只适合单元测试、Demo生产要实现BaseCheckpointSaver接口把消息历史、中间状态存入数据库。Spring AI Alibaba Graph 具有内置的持久化层通过检查点实现检查点会在每个超级步骤保存图状态的检查点。5. 异常统一捕获 —— 对外接口友好降级对外接口不能把框架原始异常直接抛给前端要做业务友好降级返回。同时Agent 级的总超时建议通过 Spring 的AsyncCompletableFuture.get(timeout)在外层做兜底。五、官方能力补充5.1 结构化输出生产级 Agent 往往需要结构化的输出而非自由文本。Spring AI Alibaba 的ReactAgent.Builder通过outputSchema和outputType方法处理结构化输出。推荐使用outputType(Class)—— 传入 Java 类框架自动通过BeanOutputConverter转换为 JSON Schema兼顾类型安全与代码可维护性。public record DiagnosisResult(String orderNo,String rootCause,String suggestion) {}ReactAgent agent ReactAgent.builder().name(diagnosis-agent).model(chatModel).methodTools(troubleShootTool).outputType(DiagnosisResult.class) // 结构化输出.build();这样上层业务代码可以直接获得 Java POJO无需解析自然语言。5.2 Workflow 编排Spring AI Alibaba Agent Framework 预置了多种多智能体工作流模式SequentialAgent顺序代理、ParallelAgent并行代理、RoutingAgent路由代理和LoopAgent循环代理。生产架构建议Workflow 控边界Agent 做动态子任务决策。var workflow SequentialAgent.builder().name(order-troubleshoot-workflow).agents(routingAgent, // 路由判断问题类型分发到不同 AgentreactAgent // 动态子任务ReAct Agent 完成具体排查).build();六、核心总结能调用工具、能跑通流程的只是 Demo不是生产 Agent。生产 Agent 80% 代码都是护栏、容错、观测、兜底而非核心推理逻辑。Hook 机制是生产排查核心可以捕获每一轮模型调用、工具执行、运行状态实现全链路可追溯。ModelCallLimitHook和ToolCallLimitHook是官方提供的开箱即用的调用限制手段。生产 Agent 必须代码硬约束模型软约束结合提示词约束模型行为ModelCallLimitHooktoolExecutionTimeout强制兜底双向防失控。工具定位是原子能力只干活不决策。异常通过ToolExecutionExceptionProcessor在 Agent 层面统一消化不打断推理循环。线上理想架构Workflow 控边界Agent 做动态子任务决策。通过SequentialAgent、RoutingAgent等编排模式组合多个 Agent规避 AI 不确定性带来的业务风险。结构化输出通过outputType(Class)实现让 Agent 返回可直接被业务代码消费的 Java POJO是生产级 Agent 的重要能力。

聊聊 Agent 工程化：Demo 很好写，生产却处处是坑

相关推荐

Agentic Awesome Skills 工作流实战：用 Antigravity 执行手册编排多技能完成端到端目标

转：文化变革

AWS Serverless 生产级实战指南：基于 AAS Core 技能库的 Lambda、API Gateway 与事件驱动模式详解

更多资讯

SparkSQL空值关联引发的数据倾斜与三段式分流优化

OpenCV4.5.5 C++开发实战：源码编译与DNN部署指南

AI辅助学术专著写作：工具组合、实操流程与避坑指南

MASM汇编集成环境：从环境配置到中断调用的完整实践指南

C#异步TCP通信：把工业RFID读卡器接入MES的数据采集实践

单周期CPU时序收敛实战：Vivado中关键路径优化与物理约束

今日更新

微信云开发旅游小程序实战：LBS打卡+UGC社交全栈方案

金融AI代理平台核心拆解：从多代理协作到财报分析实战

基于大数据的智慧旅游推荐与可视化平台架构实践

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？