AI Agent 开发实战六用 Spring AI 搭建你的第一个 Agent这是「AI Agent 开发实战」系列的第 6 篇。前 5 篇我们聊了概念、LLM、记忆、工具和框架横评今天终于要动手了——用 Spring AI 从零搭建一个能调用工具的 Agent跑通 ReAct 循环。读完本文你会得到一个可运行的 Spring AI Agent 项目它能让 LLM 自主决定何时调用工具、何时直接回答。一、Spring AI 是什么不是什么先对齐预期维度Spring AILangChain4j定位Spring 官方 AI 抽象层Java 版 LangChain风格Spring Boot 自动配置 Bean 注入Builder 模式 链式调用上手成本Spring 开发者几乎零成本需要学一套新 API灵活性通过 Adapter 扩展内置组件丰富生态Spring 全家桶天然集成多框架适配Spring AI 的核心理念把 LLM 当作 Spring 生态的一等公民——像用JdbcTemplate访问数据库一样用ChatClient访问大模型。Spring AI 架构全景 │ ├── Model 层 │ ├── ChatModel对话模型抽象 │ ├── EmbeddingModel向量模型抽象 │ ├── ImageModel图像模型抽象 │ └── AudioModel语音模型抽象 │ ├── API 层各厂商适配器 │ ├── OpenAI / Azure OpenAI │ ├── Anthropic Claude │ ├── 阿里通义 / 百度文心 / 智谱 │ └── Ollama本地模型 │ ├── 功能层 │ ├── ChatClient统一调用入口 │ ├── Function Calling工具调用 │ ├── RAG检索增强 │ ├── Advisors拦截器链 │ └── Memory对话记忆 │ └── 集成层 ├── Vector Store向量存储 ├── Spring Boot AutoConfiguration └── ObservabilityMicrometer Zipkin二、项目搭建5 分钟跑起来2.1 创建项目使用 Spring Initializrhttps://start.spring.io选Java 17Spring Boot 3.3依赖Spring Web Spring AIpom.xml关键依赖dependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion1.0.0/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagementdependencies!-- Spring AI 核心 --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-openai-spring-boot-starter/artifactId/dependencydependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency/dependencies2.2 配置模型application.ymlspring:ai:openai:api-key:${OPENAI_API_KEY}base-url:https://api.openai.com# 或你的代理地址chat:options:model:gpt-4o-minitemperature:0.7如果用国内模型换对应的 starter。比如用智谱spring-ai-zhipuai-spring-boot-starter配置spring.ai.zhipuai.api-key。2.3 验证连通RestControllerRequestMapping(/api/agent)publicclassAgentController{privatefinalChatClientchatClient;publicAgentController(ChatClient.Builderbuilder){this.chatClientbuilder.build();}GetMapping(/chat)publicStringchat(RequestParamStringmessage){returnchatClient.prompt().user(message).call().content();}}启动后访问http://localhost:8080/api/agent/chat?message你好能返回回复就说明通了。三、给 Agent 加上手脚Function Calling没有工具的 Agent 只是个 Chatbot。Spring AI 通过Tool注解或函数式注册让 LLM 能调用你的 Java 方法。3.1 定义工具ComponentpublicclassWeatherTools{Tool(description查询指定城市的当前天气信息返回温度、天气状况和风力)publicStringgetWeather(ToolParam(description城市名称如北京、上海)Stringcity){// 实际项目中调用天气 API// 这里模拟返回MapString,StringmockDataMap.of(北京,晴天温度 28°C北风 3 级,上海,多云温度 31°C东南风 2 级,深圳,雷阵雨温度 33°C南风 4 级);returnmockData.getOrDefault(city,city暂无天气数据);}Tool(description计算两个城市之间的距离单位公里)publicStringgetDistance(ToolParam(description出发城市)StringfromCity,ToolParam(description目的城市)StringtoCity){// 模拟距离计算returnfromCity 到 toCity 约 1200 公里;}}3.2 注册工具并调用Spring AI 1.0 的方式——在 ChatClient 调用时指定工具RestControllerRequestMapping(/api/agent)publicclassAgentController{privatefinalChatClientchatClient;privatefinalWeatherToolsweatherTools;publicAgentController(ChatClient.Builderbuilder,WeatherToolsweatherTools){this.chatClientbuilder.build();this.weatherToolsweatherTools;}GetMapping(/chat)publicStringchat(RequestParamStringmessage){returnchatClient.prompt().user(message).tools(weatherTools)// 注册工具.call().content();}}3.3 测试用户北京今天天气怎么样适合出门吗 LLM 思考 → 需要查询天气 → 调用 getWeather(北京) → 拿到结果晴天温度 28°C北风 3 级 → 综合回答北京今天晴天28°C北风3级非常适合出门关键点你不需要写任何 if-else 来判断用户问的是不是天气。LLM 自己根据工具描述决定调不调、传什么参数。这就是 Agent 的自主。四、加记忆让 Agent 记住上下文上面的 Agent 每次对话都是失忆的。加上对话记忆4.1 对话记忆Chat MemoryConfigurationpublicclassAgentConfig{BeanpublicChatClientchatClient(ChatClient.Builderbuilder){returnbuilder.defaultAdvisors(MessageChatMemoryAdvisor.builder(newInMemoryChatMemory()).build()).build();}}4.2 区分会话多用户场景下需要按会话 ID 隔离记忆GetMapping(/chat)publicStringchat(RequestParamStringmessage,RequestParam(defaultValuedefault)StringsessionId){returnchatClient.prompt().user(message).advisors(a-a.param(CHAT_MEMORY_CONVERSATION_ID_KEY,sessionId)).tools(weatherTools).call().content();}记忆内部结构InMemoryChatMemory │ ├── session user-001 │ ├── [UserMessage] 北京天气怎么样 │ ├── [AssistantMessage] 北京今天晴天28°C... │ └── [UserMessage] 那上海呢 │ ├── session user-002 │ └── [UserMessage] 深圳到北京多远 │ └── ...五、完整 Agent 示例出行助手把工具、记忆、提示词模板组合起来搭一个出行助手 Agent5.1 Agent 服务层ServicepublicclassTravelAssistant{privatefinalChatClientchatClient;privatefinalWeatherToolsweatherTools;publicTravelAssistant(ChatClient.Builderbuilder,WeatherToolsweatherTools){this.weatherToolsweatherTools;this.chatClientbuilder.defaultSystem( 你是一个出行助手。用户会问你天气、距离等出行相关问题。 你需要根据问题自主决定调用哪些工具综合信息后给出建议。 回答时 1. 先给出事实数据天气、距离等 2. 再给出出行建议穿什么、带伞、交通方式等 3. 语气友好像一个懂行的朋友 ).defaultAdvisors(MessageChatMemoryAdvisor.builder(newInMemoryChatMemory()).build()).build();}publicStringchat(StringsessionId,StringuserMessage){returnchatClient.prompt().user(userMessage).advisors(a-a.param(MessageChatMemoryAdvisor.CHAT_MEMORY_CONVERSATION_ID_KEY,sessionId)).tools(weatherTools).call().content();}}5.2 多轮对话效果第 1 轮 用户我明天要从北京去上海出差帮我看看两边的天气 Agent → 调用 getWeather(北京) getWeather(北京) Agent北京明天晴天28°C上海多云31°C。建议北京穿薄外套上海比较闷热穿短袖即可不用带伞。 第 2 轮 用户北京到上海多远 Agent → 调用 getDistance(北京, 上海) Agent北京到上海约1200公里。高铁大约4.5小时飞机约2小时。出差的话高铁更稳当不受天气影响。 第 3 轮 用户那我还是坐高铁吧 Agent好选择高铁准点率高而且市中心到市中心比飞机省了机场往返时间。记得提前买票热门时段容易售罄。注意第 3 轮——Agent 没有调用任何工具纯靠记忆上下文就给出了合理建议。这就是 LLM 的自主决策它知道什么时候需要工具、什么时候不需要。六、Advisor 机制Agent 的中间件Spring AI 的 Advisor 机制类似 Servlet Filter可以在 LLM 调用的前后插入逻辑用户请求 │ ▼ Advisor 链 │ ├── 1. MessageChatMemoryAdvisor注入对话记忆 ├── 2. 你的自定义 Advisor日志/限流/兜底 ├── ... │ ▼ ChatModel.call() → LLM API │ ▼ Advisor 链逆向 │ ├── 2. 你的自定义 Advisor处理响应 ├── 1. MessageChatMemoryAdvisor保存本轮对话到记忆 │ ▼ 返回给用户自定义 Advisor 示例调用日志publicclassLoggingAdvisorimplementsCallAroundAdvisor{OverridepublicStringgetName(){returnLoggingAdvisor;}OverridepublicAdvisedResponsearoundCall(AdvisedRequestrequest,CallAroundAdvisorChainchain){longstartSystem.currentTimeMillis();// 打印用户输入log.info(用户输入: {},request.userText());// 继续调用链AdvisedResponseresponsechain.nextAroundCall(request);// 打印 LLM 输出和耗时longcostSystem.currentTimeMillis()-start;log.info(LLM 输出: {}, 耗时: {}ms,response.response().getResult().getOutput().getText(),cost);returnresponse;}}注册BeanpublicChatClientchatClient(ChatClient.Builderbuilder){returnbuilder.defaultAdvisors(newLoggingAdvisor(),MessageChatMemoryAdvisor.builder(newInMemoryChatMemory()).build()).build();}七、生产环境的注意事项7.1 超时与重试BeanpublicChatClientchatClient(ChatClient.Builderbuilder,WeatherToolsweatherTools){returnbuilder.defaultOptions(ChatOptionsBuilder.builder().withMaxTokens(2048).build()).build();}// 外层用 Spring Retry 包裹Retryable(maxAttempts3,backoffBackoff(delay1000))publicStringchat(StringsessionId,Stringmessage){// ...}7.2 工具调用的安全边界ComponentpublicclassSafeWeatherTools{privatestaticfinalSetStringALLOWED_CITIESSet.of(北京,上海,深圳,广州);Tool(description查询指定城市的当前天气)publicStringgetWeather(ToolParam(description城市名称)Stringcity){// 防止 LLM 幻觉出非法城市名if(!ALLOWED_CITIES.contains(city)){return不支持查询该城市的天气;}returndoQueryWeather(city);}privateStringdoQueryWeather(Stringcity){// 调用真实 APIreturn...;}}7.3 记忆持久化InMemoryChatMemory重启就丢。生产环境用持久化实现// 基于 Redis 的记忆存储publicclassRedisChatMemoryimplementsChatMemory{privatefinalRedisTemplateString,StringredisTemplate;Overridepublicvoidadd(StringconversationId,ListMessagemessages){Stringkeychat:memory:conversationId;// 序列化并存储设置过期时间messages.forEach(msg-redisTemplate.opsForList().rightPush(key,serialize(msg)));redisTemplate.expire(key,Duration.ofHours(24));}OverridepublicListMessageget(StringconversationId,intlastN){Stringkeychat:memory:conversationId;// 取最近 N 条ListStringrawredisTemplate.opsForList().range(key,-lastN,-1);returnraw.stream().map(this::deserialize).toList();}// ... 序列化/反序列化省略}八、Spring AI vs 手写 Agent什么时候用框架场景推荐理由快速验证 Agent 概念手写 MiniAgent理解原理没有黑盒Spring 技术栈团队Spring AI零学习成本Bean 注入需要丰富的内置组件LangChain4jRAG 管道、文档加载等开箱即用生产级 Agent 服务Spring AI 自定义 Advisor既有框架支撑又能灵活扩展需要精细控制 Agent 行为手写 框架混合核心循环自己写工具调用用框架我的建议先用 Spring AI 跑通一个 Agent就是本文的做法理解ChatClient Tool Advisor Memory这四件套怎么协作。遇到框架限制再手写核心部分不要一上来就造轮子。九、小结Spring AI Agent 四件套 │ ├── ChatClient → 统一调用入口替代手写 HTTP │ ├── Tool → 声明式工具注册LLM 自主选择调用 │ ├── Advisor → 拦截器链记忆/日志/限流/兜底 │ └── ChatMemory → 对话记忆支持按会话隔离要点说明工具注册ToolToolParam声明式零配置LLM 自主决策不需要写 if-elseLLM 根据 Tool 描述自动选择记忆隔离通过 sessionId 区分不同用户的对话上下文Advisor 机制类似 Filter 的中间件可组合扩展安全边界工具方法内部做参数校验防止 LLM 幻觉注入下一篇我们聊Harness Engineering 与约束管理怎么用 Plan 模板、工具注册约束、输出 Schema 让 Agent 的行为更可控——毕竟自由和可控之间需要找到一个平衡。这是「AI Agent 开发实战」系列第 6 篇系列目录别再把 LLM 当聊天机器人了这才是 Agent 的正确打开方式三大基石之 LLM 调用与 Prompt 工程三大基石之记忆系统三大基石之工具调用Java 生态 Agent 框架横评本文用 Spring AI 搭建你的第一个 Agent
