戰(zhàn)：Java開(kāi)發(fā)者快速構(gòu)建多模型Agent應(yīng)用)
從 2024 年開(kāi)始AI 應(yīng)用開(kāi)發(fā)幾乎成了 Python 開(kāi)發(fā)者專屬賽道LangChain、LlamaIndex 各種框架層出不窮。Java 開(kāi)發(fā)者想在自己的 Spring Boot 項(xiàng)目里接一個(gè)大模型要么寫裸 HTTP 請(qǐng)求調(diào)用 OpenAI 兼容接口要么硬套 Python 生態(tài)的思路代碼風(fēng)格割裂維護(hù)成本極高。到了 2026 年這個(gè)局面的答案已經(jīng)非常明確Spring AI 2.0。這篇文章要把 Spring AI 2.0 里最重要的五件事——多模型、Tools、MCP、Skills、Agent——完整串起來(lái)講一遍。不是單純介紹概念而是從一個(gè)小型實(shí)戰(zhàn)項(xiàng)目出發(fā)把每一步的配置、代碼、踩坑點(diǎn)全部鋪開(kāi)。如果你是一個(gè) Java 工程師正在糾結(jié)怎么在公司項(xiàng)目里落地 AI 能力這篇文章可以直接當(dāng)參考手冊(cè)用。先說(shuō)結(jié)論Spring AI 2.0 真正解決的問(wèn)題是把“和大模型打交道”這件事變成了符合 Spring 編程模型的普通后端開(kāi)發(fā)。它不追求把 LangChain 那套 Python 生態(tài)搬過(guò)來(lái)而是用 Spring 自己的依賴注入、自動(dòng)配置、約定優(yōu)于配置把多模型切換、工具調(diào)用、協(xié)議接入、Agent 編排統(tǒng)一成一個(gè)標(biāo)準(zhǔn)范式。讀完這篇文章你能獨(dú)立搭出一個(gè)支持多模型切換、能調(diào)用自定義工具、能通過(guò) MCP 接入外部服務(wù)、帶記憶和會(huì)話的客服 Agent 原型。1. 這篇文章真正要解決的問(wèn)題很多 Java 開(kāi)發(fā)者學(xué) AI 編程的第一反應(yīng)是先去學(xué) Python。這個(gè)認(rèn)知正在變成一種路徑依賴。如果項(xiàng)目底層是 Java團(tuán)隊(duì)是 Java 團(tuán)隊(duì)業(yè)務(wù)邏輯都在 Spring Boot 服務(wù)里那用 Python 重寫一套 AI 應(yīng)用等于把整個(gè)工程體系復(fù)制了一份。Spring AI 2.0 的價(jià)值就在這里。它處理的不只是“調(diào)一次大模型接口”這種小事而是一整套企業(yè)級(jí) AI 應(yīng)用開(kāi)發(fā)中必須面對(duì)的問(wèn)題同一個(gè)業(yè)務(wù)要支持多家模型供應(yīng)商比如線上用 GPT-4o本地開(kāi)發(fā)用 Ollama 里的開(kāi)源模型怎么做到切換模型而不改業(yè)務(wù)代碼模型返回的是 JSON 文本怎么穩(wěn)定地映射成 Java 對(duì)象而不是靠正則硬解析大模型不知道你的訂單數(shù)據(jù)、用戶數(shù)據(jù)怎么安全地讓它調(diào)用你已有的 Service 方法外部工具生態(tài)已經(jīng)約定了統(tǒng)一接入?yún)f(xié)議比如數(shù)據(jù)庫(kù) MCP Server、文件系統(tǒng) MCP ServerSpring 項(xiàng)目怎么接入最省事一個(gè)智能客服 Agent 需要有角色設(shè)定、工具列表、會(huì)話記憶、多輪上下文這些怎么工程化管理這些問(wèn)題的答案就是 Spring AI 2.0 的核心抽象體系。它跟 Python 的 LangChain 解決的問(wèn)題高度重合但實(shí)現(xiàn)思路完全是 Java 式的自動(dòng)配置、Bean 管理、類型安全、Starter 依賴。從實(shí)用角度看這篇文章適合四類讀者還沒(méi)接觸過(guò) Spring AI但項(xiàng)目里已經(jīng)有 Spring Boot 3.x 基礎(chǔ)想快速上手已經(jīng)在用 Spring AI 1.x想知道 2.0 在 Tools、MCP、Skills、Agent 這幾個(gè)方向有什么變化被“多模型”“MCP”“Agent”這些概念繞暈需要一個(gè)能跑通的最小案例準(zhǔn)備把 AI 能力集成進(jìn)企業(yè)系統(tǒng)的架構(gòu)師或技術(shù)負(fù)責(zé)人需要判斷技術(shù)選型和工程邊界。有 Spring Boot 基礎(chǔ)的人今天就能把鏈路跑通。2. Spring AI 2.0 核心概念從 ChatModel 到 Agent2.1 最核心的抽象ChatModelSpring AI 對(duì) LLM 的抽象核心就是ChatModel接口。不管底層是 OpenAI、Anthropic、通義千問(wèn)、DeepSeek 還是 Ollama 里的本地模型對(duì)上層業(yè)務(wù)代碼來(lái)說(shuō)暴露出來(lái)的都是同一個(gè)接口。public interface ChatModel { ChatResponse call(Prompt prompt); }這個(gè)設(shè)計(jì)的價(jià)值在業(yè)務(wù)方不在實(shí)現(xiàn)方。你寫的 Service 層不需要關(guān)心當(dāng)前接的是哪個(gè)大模型。以后要從 GPT 切到本地模型只改配置不碰 Java 代碼。這就是多模型支持的第一層含義。圍繞ChatModelSpring AI 還提供了幾個(gè)配套抽象ChatClient更面向業(yè)務(wù)的流式調(diào)用入口支持 system prompt、user prompt、工具注冊(cè)、結(jié)構(gòu)化輸出。這是最常用的對(duì)象。EmbeddingModel負(fù)責(zé)把文本轉(zhuǎn)成向量用于 RAG、語(yǔ)義搜索等場(chǎng)景。StructuredOutputConverter將模型輸出解析為指定 Java 類型。2.2 Tools讓大模型調(diào)用你的函數(shù)大模型本身不持有你的業(yè)務(wù)數(shù)據(jù)它只能“說(shuō)出”一個(gè)新的 JSON 結(jié)構(gòu)表達(dá)“我想調(diào)用某個(gè)函數(shù)”。Tools 就是把這層機(jī)制封裝成了 Spring 風(fēng)格的工具方法。在 Spring AI 中只需要在方法上標(biāo)記Tool注解框架自動(dòng)完成“模型生成函數(shù)調(diào)用參數(shù) → 框架反射調(diào)用方法 → 把結(jié)果回傳給模型 → 模型基于結(jié)果繼續(xù)生成”的循環(huán)。這里真正容易踩坑的地方在于模型是否真的會(huì)調(diào)用你的 Tool取決于你寫的description是否足夠清晰。描述寫得含糊模型就會(huì)跳過(guò)函數(shù)調(diào)用直接憑幻覺(jué)回答。2.3 MCP模型上下文協(xié)議MCPModel Context Protocol是 Anthropic 在 2024 年底提出的開(kāi)放協(xié)議目標(biāo)是標(biāo)準(zhǔn)化“模型如何發(fā)現(xiàn)并調(diào)用外部工具/數(shù)據(jù)源”。它把工具、資源、提示詞統(tǒng)一成一套標(biāo)準(zhǔn)接口。一個(gè)團(tuán)隊(duì)只要實(shí)現(xiàn)了 MCP Server任何支持 MCP 的客戶端都能復(fù)用。Spring AI 2.0 對(duì) MCP 的支持是完整的可以作為 MCP Client連接現(xiàn)成的 MCP Server比如文件系統(tǒng)、數(shù)據(jù)庫(kù)、藍(lán)湖設(shè)計(jì)稿、GitHub 等也可以作為 MCP Server把 Spring 服務(wù)里的能力暴露給其他 AI 應(yīng)用。MCP 和 Tools 的關(guān)系不是二選一。Tools 是 Spring AI 內(nèi)部的函數(shù)調(diào)用機(jī)制MCP 是跨應(yīng)用、跨語(yǔ)言的工具發(fā)現(xiàn)與傳輸標(biāo)準(zhǔn)。MCP Server 在遠(yuǎn)端提供的工具最終會(huì)被 Spring AI 包裝成本地 Tool 參與模型對(duì)話。2.4 Skills更貼近業(yè)務(wù)的 Agent 能力封裝如果說(shuō) Tools 解決的是“單個(gè)函數(shù)”的調(diào)用那么 Skills 解決的是“一組能力”的復(fù)用。一個(gè) Skill 通常包含多部分內(nèi)容清晰的技能描述、可能用到的多個(gè)工具方法、提示詞模板、輸入校驗(yàn)規(guī)則甚至內(nèi)部的異常處理邏輯。從 Spring AI 2.0 的演進(jìn)方向看Skill 就是為 Agent 誕生的“能力包”。舉個(gè)例子一個(gè)“訂單查詢技能”可以包含“按訂單號(hào)查狀態(tài)”“按手機(jī)號(hào)查訂單列表”“查詢物流軌跡”三個(gè)工具并統(tǒng)一處理參數(shù)校驗(yàn)和返回格式。Agent 只需要知道“有一個(gè)訂單查詢技能”就能在合適的時(shí)候調(diào)用它。2.5 Skill 和 MCP 的區(qū)別這是很多初學(xué)者最暈的地方。用一句話概括它們的差異MCP 是標(biāo)準(zhǔn)與協(xié)議Skills 是業(yè)務(wù)封裝。MCP 解決的是“怎么連接、傳什么格式”的問(wèn)題比如你用 npx 啟動(dòng)一個(gè) filesystem MCP Server客戶端連上它就能列出可用的工具列表。Skill 解決的是“以什么方式參與 Agent 編排”的問(wèn)題它更像是一個(gè)高層的業(yè)務(wù)抽象背后既可以封裝本地 Tools也可以封裝對(duì) MCP 工具的調(diào)用。打個(gè)比方MCP 像是 USB-C 接口標(biāo)準(zhǔn)任何設(shè)備只要按這個(gè)標(biāo)準(zhǔn)生產(chǎn)就能互聯(lián)Skill 則像一個(gè)“即插即用的功能包”比如一個(gè)“高清投屏技能”它可能包含了軟件、驅(qū)動(dòng)和推薦配置。兩者不在同一個(gè)抽象層。2.6 Agent用對(duì)話能力編排一切Agent 不是一個(gè)新框架而是ChatModel Tools Skills 記憶 多輪編排的組合產(chǎn)物。在 Spring AI 2.0 中一個(gè) Agent 的編程模型非常簡(jiǎn)單準(zhǔn)備好一個(gè)ChatClient給它配置系統(tǒng)角色、工具列表和會(huì)話記憶剩下的循環(huán)推理全部交給框架。Agent 內(nèi)部會(huì)反復(fù)執(zhí)行“模型生成 → 決定是否調(diào)用工具 → 拿到結(jié)果 → 繼續(xù)生成”的流程直到它能給出最終回答。不過(guò)簡(jiǎn)單不代表沒(méi)有難點(diǎn)。真正考驗(yàn)工程能力的是 Agent 的安全邊界、工具權(quán)限、會(huì)話存儲(chǔ)、失敗降級(jí)這些外圍問(wèn)題。后面會(huì)專門用一整節(jié)說(shuō)清楚。3. 環(huán)境準(zhǔn)備與前置條件3.1 JDK 與構(gòu)建工具Spring AI 2.x 基于 Spring Framework 6.x 和 Spring Boot 3.x要求 JDK 17 及以上。推薦直接使用 JDK 21理由很實(shí)際虛擬線程、更完善的 ZGC 行為以及 Spring Boot 對(duì) JDK 21 的完整官方支持。構(gòu)建工具用 Maven 或 Gradle 都可以。本文示例以 Maven 為主因?yàn)閲?guó)內(nèi) Java 項(xiàng)目里 Maven 還是絕對(duì)主流。版本方面Spring AI 的版本更新速度比較快不建議把具體版本號(hào)寫死在文章里。正確做法在pom.xml里通過(guò)spring-ai-bom做依賴管理版本統(tǒng)一放到屬性里使用 Maven Central 上的最新穩(wěn)定版。!-- 文件路徑pom.xml 片段 -- properties java.version21/java.version spring-boot.version3.4.x/spring-boot.version spring-ai.version2.0.x/spring-ai.version /properties實(shí)際使用中把x替換成發(fā)布時(shí)的具體小版本號(hào)即可。3.2 Spring Boot 項(xiàng)目初始化先在 Spring Initializr 上生成一個(gè)基礎(chǔ)工程或者直接在 IDEA 里用 Spring Initializr 創(chuàng)建。需要選擇的依賴如下Spring WebSpring AI OpenAISpring AI OllamaLombok可選Spring AI MCP Client WebMVC如果你需要把 Spring 服務(wù)本身暴露成 MCP Server還需要加Spring AI MCP Server WebMVC。本文的示例會(huì)先做 MCP Client 接入。3.3 模型 API Key 準(zhǔn)備至少準(zhǔn)備一個(gè)可用的大模型 API Key。如果公司有統(tǒng)一的模型網(wǎng)關(guān)也可以把 base-url 指向網(wǎng)關(guān)地址。本地開(kāi)發(fā)優(yōu)先推薦 Ollama 方式下載 Ollama再拉一個(gè)支持 function calling 的模型比如qwen2.5系列。這樣即使沒(méi)有公網(wǎng) API Key也可以完成 Tools 和 Agent 的全流程測(cè)試。這里補(bǔ)充一個(gè)重要約定任何 API Key 都不要硬編碼到application.yml里更不要提交到 Git 倉(cāng)庫(kù)。用環(huán)境變量注入例如${OPENAI_API_KEY:}。如果你有配置中心例如 Apollo、Nacos Config應(yīng)該走配置中心統(tǒng)一管理。4. 核心流程拆解從配置到 Agent 的六步鏈路4.1 第一步配置多模型目標(biāo)是一個(gè) Spring Boot 項(xiàng)目里同時(shí)存在多個(gè)ChatModelBean。Spring AI 的自動(dòng)配置會(huì)為每個(gè)已引入的模型 Starter 創(chuàng)建對(duì)應(yīng)的ChatModelBean比如引入spring-ai-openai會(huì)自動(dòng)創(chuàng)建OpenAiChatModel引入spring-ai-ollama會(huì)自動(dòng)創(chuàng)建OllamaChatModel。但問(wèn)題來(lái)了如果項(xiàng)目里同時(shí)有多個(gè)ChatModelBean注入ChatClient.Builder時(shí) Spring 會(huì)由于類型不唯一而報(bào)錯(cuò)。解決辦法就是顯式聲明一個(gè)多模型路由服務(wù)用 Map 按名稱保存所有模型。這個(gè)設(shè)計(jì)本質(zhì)上是“多模型策略模式”后續(xù)切換模型時(shí)業(yè)務(wù)層只面向ChatModel接口編程選誰(shuí)用誰(shuí)由配置或路由邏輯決定。這是 Spring AI 多模型落地最實(shí)用的架構(gòu)。4.2 第二步搞定結(jié)構(gòu)化輸出大模型返回的是自然語(yǔ)言但業(yè)務(wù)系統(tǒng)需要的是FlightReservation、UserInfo這樣的 Java 對(duì)象。Spring AI 的ChatClient.entity()方法幫你做了類型轉(zhuǎn)換。實(shí)際操作時(shí)不要在實(shí)體里放太多復(fù)雜嵌套類型。大模型不是 JSON Schema 解析器越復(fù)雜的類型越容易解析失敗。先用扁平化的 record跑通后再逐步增加字段。4.3 第三步讓模型能調(diào)用工具定義一個(gè)繼承自Component的類在業(yè)務(wù)方法上標(biāo)注Tool描述要寫到“模型一聽(tīng)就懂”的程度。然后用ChatClient.Builder.defaultTools()把工具傳進(jìn)去。驗(yàn)證這一步是否成功最直接的辦法是問(wèn)一個(gè)必須靠工具才能回答的問(wèn)題比如“北京今天天氣怎么樣”。如果模型準(zhǔn)確返回了天氣說(shuō)明函數(shù)調(diào)用鏈路已經(jīng)通了。4.4 第四步接入 MCP引入 MCP Client 依賴在配置里聲明要連的 stdio MCP ServerSpring AI 會(huì)自動(dòng)把這個(gè)服務(wù)器提供的工具合并到模型對(duì)話中。如果公司內(nèi)部有 HTTP 方式的 MCP Server也可以走 SSE 或 WebMVC 配置。接入方式和 stdio 略有不同但核心思想一致遠(yuǎn)程工具被包裝成本地 Tool不需要業(yè)務(wù)代碼感知。4.5 第五步封裝 Skills把“散裝工具提示詞規(guī)則”收斂成一個(gè)高內(nèi)聚的類。Skill 通常是普通 Spring Service內(nèi)部依賴多個(gè) Tool 方法再通過(guò)構(gòu)造器注入到ChatClient。這里的一個(gè)工程建議每個(gè) Skill 類都寫清楚Description讓 Agent 知道這個(gè)技能在什么場(chǎng)景下使用。Agent 判斷“該不該用這個(gè)技能”依賴的就是這個(gè)描述。4.6 第六步用 Agent 編排落地把系統(tǒng)角色、工具列表、Skills、會(huì)話記憶整合到一個(gè)ChatClientBean 里對(duì)外暴露一個(gè)chat(userMessage, conversationId)方法。這個(gè) Bean 就是你的客服 Agent。會(huì)話記憶的實(shí)現(xiàn)方式依賴于ChatClient的id(conversationId)參數(shù)框架會(huì)把同一 id 的多輪對(duì)話保存到ChatMemory。生產(chǎn)環(huán)境應(yīng)該替換成 Redis 或數(shù)據(jù)庫(kù)存儲(chǔ)避免單機(jī)內(nèi)存丟失?，F(xiàn)在整條鏈路就通了。下面用可運(yùn)行代碼過(guò)一遍。5. 完整示例代碼實(shí)現(xiàn)本節(jié)的工程結(jié)構(gòu)如下src/main/java/com/example/ai/ ├── AiApplication.java ├── config/ │ └── ChatClientConfig.java ├── controller/ │ ├── ChatController.java │ ├── StructuredOutputController.java │ └── MultiModelController.java ├── service/ │ ├── MultiModelService.java │ └── OrderQuerySkill.java ├── tool/ │ └── WeatherTools.java ├── agent/ │ └── CustomerServiceAgent.java └── entity/ └── FlightReservation.java5.1 新增 Maven 依賴先更新pom.xml加入 Spring AI BOM 以及所需的 Starter!-- 文件路徑pom.xml -- dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-client-webmvc/artifactId /dependency /dependenciesspring-ai-bom的作用是統(tǒng)一管理所有 Spring AI 模塊的版本號(hào)避免手動(dòng)逐個(gè)對(duì)齊版本。5.2 配置文件在application.yml中配置多模型和 MCP Client# 文件路徑src/main/resources/application.yml server: port: 8080 spring: application: name: spring-ai-demo ai: openai: base-url: ${OPENAI_BASE_URL:https://api.openai.com} api-key: ${OPENAI_API_KEY:} chat: options: model: gpt-4o-mini temperature: 0.7 ollama: base-url: http://localhost:11434 chat: options: model: qwen2.5:7b temperature: 0.7 mcp: client: stdio: servers: filesystem: command: npx args: -y,modelcontextprotocol/server-filesystem,/tmp/data這里最需要注意的地方是args的寫法。Spring AI 的 MCP 配置要求 args 是一個(gè)數(shù)組不同版本對(duì)分隔符的處理略有差異。如果啟動(dòng)時(shí) MCP Server 沒(méi)有連上第一優(yōu)先排查的就是這個(gè)參數(shù)里的逗號(hào)分隔是否正確以及本機(jī)是否安裝并可以使用 npx。5.3 多模型調(diào)用用具體的ChatModel實(shí)現(xiàn)類型做構(gòu)造器注入這樣不會(huì)被多 Bean 問(wèn)題干擾// 文件路徑src/main/java/com/example/ai/service/MultiModelService.java Service public class MultiModelService { private final OpenAiChatModel openAiChatModel; private final OllamaChatModel ollamaChatModel; public MultiModelService(OpenAiChatModel openAiChatModel, OllamaChatModel ollamaChatModel) { this.openAiChatModel openAiChatModel; this.ollamaChatModel ollamaChatModel; } public String chatWith(String provider, String message) { ChatModel chatModel switch (provider) { case openai - openAiChatModel; case ollama - ollamaChatModel; default - throw new IllegalArgumentException(未知模型: provider); }; return chatModel.call(new Prompt(message)) .getResult() .getOutput() .getText(); } }這段代碼的關(guān)鍵點(diǎn)是“面向接口編程”。業(yè)務(wù)方拿到的是ChatModel具體實(shí)現(xiàn)可以隨時(shí)替換。以后新增模型供應(yīng)商只需要增加一個(gè) Starter 依賴再在 switch 里加一行分支。5.4 結(jié)構(gòu)化輸出定義一個(gè)實(shí)體類用 record 保持簡(jiǎn)潔// 文件路徑src/main/java/com/example/ai/entity/FlightReservation.java public record FlightReservation( String flightNumber, String from, String to, String departureTime, String price ) { }不推薦在這個(gè) record 里放LocalDateTime、BigDecimal這類需要強(qiáng)類型轉(zhuǎn)換的字段。大模型返回的 JSON 字符串在解析成本地類型時(shí)一旦格式不匹配會(huì)直接拋出類型轉(zhuǎn)換異常。先用字符串類型跑通是結(jié)構(gòu)化輸出最容易成功的路徑。再寫一個(gè) Controller 展示如何使用// 文件路徑src/main/java/com/example/ai/controller/StructuredOutputController.java RestController RequestMapping(/api/structured) public class StructuredOutputController { private final ChatClient chatClient; public StructuredOutputController(ChatClient.Builder builder) { this.chatClient builder.build(); } GetMapping(/parse-reservation) public FlightReservation parseReservation(RequestParam String text) { return chatClient.prompt() .system(你是航班信息解析助手。請(qǐng)從用戶文本中抽取航班編號(hào)、出發(fā)地、目的地、出發(fā)時(shí)間和價(jià)格。) .user(text) .call() .entity(FlightReservation.class); } }5.5 自定義 Tools定義一個(gè)天氣工具類。這是本文最典型的Tool用法// 文件路徑src/main/java/com/example/ai/tool/WeatherTools.java Component public class WeatherTools { Tool(description 根據(jù)城市名稱查詢當(dāng)前天氣) public String getWeatherByCity(String city) { // 實(shí)際項(xiàng)目里替換為天氣服務(wù) API 調(diào)用 if (北京.equals(city)) { return 北京晴25℃東南風(fēng)2級(jí); } return city 多云22℃東北風(fēng)1級(jí); } Tool(description 根據(jù)城市名稱查詢未來(lái)三天天氣預(yù)報(bào)需要傳入城市和天數(shù)) public String getForecast(String city, int days) { return city 未來(lái) days 天晴轉(zhuǎn)多云最低18℃最高27℃; } }注意Tool的描述寫清楚“需要傳入什么參數(shù)”這直接影響模型生成參數(shù)的成功率。5.6 MCP 客戶端接入前面已經(jīng)在application.yml里配置了 filesystem 這個(gè) stdio 服務(wù)。當(dāng) Spring AI 檢測(cè)到 MCP Client 依賴時(shí)會(huì)自動(dòng)連接該服務(wù)并把它暴露出的工具合并到工具注冊(cè)表。如果不想使用 stdio 方式也可以把spring-ai-mcp-client-webmvc換成或互補(bǔ)使用 HTTP 方式spring: ai: mcp: client: url: http://localhost:8081url方式適合連接已經(jīng)部署為獨(dú)立服務(wù)的 MCP Server。這里強(qiáng)調(diào)一個(gè)重要過(guò)程MCP 工具是“動(dòng)態(tài)發(fā)現(xiàn)”的。你在代碼里看不到 filesystem 工具的 Java 類但它會(huì)在運(yùn)行期被注冊(cè)成一個(gè)ToolCallback。排查 MCP 工具是否生效看啟動(dòng)日志里是否打印了 MCP 工具調(diào)用的注冊(cè)信息即可。5.7 Skill 定義用一個(gè)高內(nèi)聚的 Skill 類封裝“訂單查詢”能力。它不僅包含工具方法還包含面向 Agent 的描述和參數(shù)校驗(yàn)邏輯// 文件路徑src/main/java/com/example/ai/service/OrderQuerySkill.java Service public class OrderQuerySkill { Tool(description 根據(jù)訂單號(hào)查詢訂單狀態(tài)和物流信息訂單號(hào)為數(shù)字字符串) public String queryOrderStatus(String orderId) { if (orderId null || !orderId.matches(\\d{6,})) { return 訂單號(hào)格式不正確; } // 實(shí)際項(xiàng)目里注入 OrderRepository 查詢數(shù)據(jù)庫(kù) return 訂單 orderId 狀態(tài)已發(fā)貨預(yù)計(jì) 3 天內(nèi)送達(dá); } Tool(description 根據(jù)用戶手機(jī)號(hào)查詢最近三個(gè)月訂單列表) public String listRecentOrders(String mobile) { if (mobile null || !mobile.matches(1\\d{10})) { return 手機(jī)號(hào)格式不正確; } return 最近訂單2026030101已簽收、2026021502已發(fā)貨; } }所謂 Skill 和普通 Tool 類的差別更多體現(xiàn)在設(shè)計(jì)意圖上。一個(gè) Skill 可以包含多個(gè) Tool并負(fù)責(zé)它們之間的業(yè)務(wù)規(guī)則。Agent 只需要注入這一個(gè)類就能獲得整套能力。5.8 Agent 編排最后把所有能力整合到一個(gè)客服 Agent 中// 文件路徑src/main/java/com/example/ai/agent/CustomerServiceAgent.java Component public class CustomerServiceAgent { private final ChatClient chatClient; public CustomerServiceAgent(ChatClient.Builder builder, WeatherTools weatherTools, OrderQuerySkill orderQuerySkill) { this.chatClient builder .defaultSystem(你是企業(yè)智能客服回答要簡(jiǎn)潔、準(zhǔn)確、友好。當(dāng)用戶詢問(wèn)天氣時(shí)必須使用天氣工具 當(dāng)用戶查詢訂單時(shí)必須使用訂單查詢技能不要編造訂單數(shù)據(jù)。) .defaultTools(weatherTools, orderQuerySkill) .build(); } public String chat(String userMessage, String conversationId) { return chatClient.prompt() .id(conversationId) .user(userMessage) .call() .content(); } public String chatWithSystem(String systemPrompt, String userMessage, String conversationId) { return chatClient.prompt() .system(systemPrompt) .id(conversationId) .user(userMessage) .call() .content(); } }sytem提示詞里明確寫了“必須使用天氣工具”“不要編造訂單數(shù)據(jù)”這種約束是 Agent 工程質(zhì)量的重要來(lái)源。模型有概率忽略模糊指令但你把指令寫進(jìn)系統(tǒng)提示詞輔助工具描述清晰成功率會(huì)大幅提高。再提供一個(gè)入口 Controller// 文件路徑src/main/java/com/example/ai/controller/ChatController.java RestController RequestMapping(/api/agent) public class ChatController { private final CustomerServiceAgent customerServiceAgent; private final MultiModelService multiModelService; public ChatController(CustomerServiceAgent customerServiceAgent, MultiModelService multiModelService) { this.customerServiceAgent customerServiceAgent; this.multiModelService multiModelService; } GetMapping(/chat) public String chat(RequestParam String message, RequestParam(defaultValue default) String conversationId) { return customerServiceAgent.chat(message, conversationId); } GetMapping(/multi) public String multi(RequestParam String provider, RequestParam String message) { return multiModelService.chatWith(provider, message); } }到這里一個(gè)支持多模型、自定義 Tools、MCP 外部工具、Skill 能力封裝、多輪會(huì)話記憶的 Agent 原型已經(jīng)完整落地。下面看看怎么驗(yàn)證它。6. 運(yùn)行結(jié)果與效果驗(yàn)證啟動(dòng)項(xiàng)目mvn spring-boot:run如果本地Ollama已經(jīng)拉取了qwen2.5:7b啟動(dòng)日志里會(huì)同時(shí)出現(xiàn) OpenAI 和 Ollama 的模型初始化信息。MCP Client 啟動(dòng)時(shí)會(huì)嘗試執(zhí)行npx -y modelcontextprotocol/server-filesystem /tmp/data日志里會(huì)出現(xiàn) MCP Server connected 之類的記錄。依次驗(yàn)證幾個(gè)核心能力基礎(chǔ)對(duì)話curl http://localhost:8080/api/agent/chat?message你好conversationIdtest-001預(yù)期輸出一句問(wèn)候語(yǔ)說(shuō)明ChatClient鏈路正常。結(jié)構(gòu)化輸出curl http://localhost:8080/api/structured/parse-reservation?text幫我訂明天從北京到上海的MU5111航班價(jià)格850元提醒我上午十點(diǎn)出發(fā)預(yù)期返回 JSON{flightNumber:MU5111,from:北京,to:上海,departureTime:10:00,price:850元}工具調(diào)用聯(lián)動(dòng)curl http://localhost:8080/api/agent/chat?message北京今天天氣怎么樣conversationIdtest-001如果模型沒(méi)有調(diào)工具可能只會(huì)回答“我無(wú)法獲取實(shí)時(shí)天氣”。如果正確調(diào)用了WeatherTools.getWeatherByCity會(huì)返回“北京晴25℃”等相關(guān)信息。多輪會(huì)話驗(yàn)證curl http://localhost:8080/api/agent/chat?message我的手機(jī)號(hào)是13800138000幫我查一下最近訂單conversationIdtest-001 curl http://localhost:8080/api/agent/chat?message再看看第一單的物流conversationIdtest-001第二次提問(wèn)依賴第一次的上下文。如果返回結(jié)果包含第一單的訂單號(hào)或狀態(tài)說(shuō)明會(huì)話記憶已生效。判斷 Agent 是否正常不能只看是否返回結(jié)果還要看它是不是在正確的步驟調(diào)用了正確的工具。建議在本地開(kāi)發(fā)時(shí)打開(kāi) Spring AI 的調(diào)試日志logging: level: org.springframework.ai: DEBUG這樣可以在控制臺(tái)看到完整的工具調(diào)用鏈模型請(qǐng)求 → 工具調(diào)用 → 工具返回 → 模型最終回答。如果失敗優(yōu)先看這幾個(gè)位置啟動(dòng)階段MCP Server 是否連接成功Ollama 服務(wù)是否可用調(diào)用階段模型返回是否超時(shí)工具階段Tool方法是否有日志返回內(nèi)容是否被模型正確消費(fèi)。7. 常見(jiàn)問(wèn)題與排查思路問(wèn)題現(xiàn)象可能原因排查方式解決方案啟動(dòng)報(bào)錯(cuò)說(shuō)存在多個(gè) ChatModel Bean同時(shí)引入了多個(gè)模型 Starter自動(dòng)配置創(chuàng)建了多個(gè)同類型 Bean查看啟動(dòng)日志中 Bean 創(chuàng)建記錄用Qualifier或顯式配置指定使用的模型或封裝多模型路由服務(wù)請(qǐng)求時(shí)模型長(zhǎng)時(shí)間無(wú)響應(yīng)模型 API Key 無(wú)效、網(wǎng)絡(luò)不通、本地 Ollama 沒(méi)有啟動(dòng)先 curl 模型供應(yīng)商接口查看 Ollama 是否在 11434 端口監(jiān)聽(tīng)修正 API Key / base-url啟動(dòng) Ollama 并確認(rèn)模型已拉取工具沒(méi)有被調(diào)用模型直接瞎回答Tool的描述不夠清晰或 system prompt 沒(méi)有強(qiáng)制要求檢查工具描述打開(kāi) DEBUG 日志確認(rèn)模型請(qǐng)求里是否包含 tool_calls重寫描述加入“必須使用工具回答”等約束結(jié)構(gòu)化輸出解析失敗拋類型轉(zhuǎn)換異常模型返回文本格式不匹配 Java 類型查看實(shí)際返回的 JSON簡(jiǎn)化實(shí)體字段統(tǒng)一使用 String逐步增加字段MCP Server 連接失敗npx 未安裝、args 參數(shù)格式錯(cuò)誤、服務(wù)端地址不通在終端手動(dòng)執(zhí)行npx -y modelcontextprotocol/server-filesystem /tmp/data檢查啟動(dòng)日志 MCP 部分修正 args 寫法安裝 npx改用可訪問(wèn)的 HTTP MCP Server多輪對(duì)話上下文丟失conversationId傳遞不一致或沒(méi)有配置持久化 ChatMemory檢查每次請(qǐng)求是否傳同一個(gè) id查看內(nèi)存存儲(chǔ)的日志用 Redis/數(shù)據(jù)庫(kù)實(shí)現(xiàn) ChatMemory統(tǒng)一會(huì)話 id 生成規(guī)則本地模型不支持 function callingOllama 拉取的模型版本較老或本身不支持工具調(diào)用查詢模型文檔確認(rèn)是否支持 tools更換支持 function calling 的模型例如qwen2.5系列這些問(wèn)題是獨(dú)立開(kāi)發(fā)者在完整跑通鏈路時(shí)最容易遇到的。嚴(yán)格按照排查路徑走大多數(shù)問(wèn)題會(huì)在十分鐘內(nèi)定位。8. 最佳實(shí)踐與工程建議8.1 模型接入層統(tǒng)一路由隔離供應(yīng)商不要把模型供應(yīng)商的 SDK 直接散落在業(yè)務(wù)代碼里。所有模型訪問(wèn)統(tǒng)一走ChatModel接口模型路由邏輯收斂到一個(gè)服務(wù)中。這樣才能做到“線上用商業(yè)模型、測(cè)試用本地模型”而不修改業(yè)務(wù)代碼。8.2 提示詞管理模板化、版本化System prompt 不要散落在 Controller 里。建議用提示詞模板文件配合 Spring 的Resource加載放到系統(tǒng)資源目錄下。提示詞實(shí)際上是需要評(píng)審和版本管理的“代碼”它直接影響模型行為質(zhì)量。8.3 工具安全最小權(quán)限原則Tool方法本質(zhì)上是把內(nèi)部能力暴露給外部模型調(diào)用。必須遵守最小權(quán)限原則工具方法只做自己該做的事不要聲明一個(gè)大而全的方法例如“執(zhí)行任意 SQL”。所有涉及數(shù)據(jù)庫(kù)、文件、外部 API 的工具都要做參數(shù)校驗(yàn)就像對(duì)待用戶輸入一樣。8.4 會(huì)話記憶生產(chǎn)環(huán)境不要用默認(rèn)內(nèi)存實(shí)現(xiàn)ChatClient的默認(rèn)記憶是內(nèi)存級(jí)的應(yīng)用重啟即丟失。生產(chǎn)環(huán)境應(yīng)該把ChatMemory替換為 Redis 或數(shù)據(jù)庫(kù)實(shí)現(xiàn)。會(huì)話 ID 必須由后端統(tǒng)一生成不要信任前端傳入的任意 key否則容易出現(xiàn)會(huì)話串臺(tái)問(wèn)題。8.5 MCP 生命周期管理MCP stdio 服務(wù)本質(zhì)上是啟動(dòng)一個(gè)子進(jìn)程它的生命周期需要被關(guān)注。不要在生產(chǎn)環(huán)境用 npx 臨時(shí)拉取 MCP Server盡量構(gòu)建成獨(dú)立服務(wù)用 HTTP 方式接入這樣便于監(jiān)控和擴(kuò)縮容。8.6 Agent 可觀測(cè)性Agent 是一個(gè)多步?jīng)Q策系統(tǒng)每一步都可能出錯(cuò)。生產(chǎn)環(huán)境必須記錄用戶問(wèn)題原文模型是否發(fā)起了工具調(diào)用調(diào)用了哪個(gè)工具、參數(shù)是什么工具返回結(jié)果最終回答內(nèi)容。這些日志鏈路是排查問(wèn)題的唯一依據(jù)。建議在Tool方法和 Agent 調(diào)用層都加上結(jié)構(gòu)化日志而不是只靠框架默認(rèn)日志。8.7 成本與限流多模型配置帶來(lái)成本控制能力的同時(shí)也帶來(lái)新的風(fēng)險(xiǎn)工具循環(huán)次數(shù)過(guò)多會(huì)導(dǎo)致 Token 消耗膨脹。建議給 Agent 調(diào)用設(shè)置超時(shí)時(shí)間、最大工具調(diào)用輪數(shù)并針對(duì)不同模型配置不同的限流策略。8.8 版本升級(jí)策略Spring AI 版本迭代快API 偶有調(diào)整。升級(jí)前先看官方遷移指南并且保留一個(gè)小范圍的兼容層。比如你寫一個(gè)AgentChatService包裝ChatClient未來(lái)內(nèi)部 API 變化時(shí)只改這個(gè)類業(yè)務(wù)層不受影響。9. 總結(jié)與后續(xù)學(xué)習(xí)方向Spring AI 2.0 給 Java 生態(tài)帶來(lái)的價(jià)值不只是一套可以調(diào)大模型的 Starter而是一整套符合 Spring 編程模型的 AI 應(yīng)用開(kāi)發(fā)范式。本文把這條鏈路完整拆解了一遍多模型解決了供應(yīng)商鎖定問(wèn)題Tool讓模型具備調(diào)用業(yè)務(wù)方法的能力MCP 把外部工具生態(tài)標(biāo)準(zhǔn)化Skills 讓能力封裝更貼近業(yè)務(wù)Agent 則把這一切組合成了可交付的智能服務(wù)。建議你按順序完成三個(gè)練習(xí)先跑通多模型切換和結(jié)構(gòu)化輸出再實(shí)現(xiàn)一個(gè)包含兩個(gè)Tool的客服助手最后接入一個(gè)外部 MCP Server例如文件系統(tǒng)或數(shù)據(jù)庫(kù)服務(wù)。這三步做完Spring AI 2.0 的主要能力就算真正掌握。接下來(lái)值得深入的方向包括RAG 與向量數(shù)據(jù)庫(kù)的集成、Agent 與業(yè)務(wù)流程引擎的結(jié)合、基于 MCP Server 暴露公司內(nèi)部服務(wù)給 AI 應(yīng)用、以及多 Agent 協(xié)作模式。每一條都比單純調(diào)大模型接口更有工程價(jià)值也是 Java 工程師在 AI 時(shí)代不可替代的底牌。 Spring AI 2.0實(shí)戰(zhàn)：Java開(kāi)發(fā)者快速構(gòu)建多模型Agent應(yīng)用
從 2024 年開(kāi)始AI 應(yīng)用開(kāi)發(fā)幾乎成了 Python 開(kāi)發(fā)者專屬賽道LangChain、LlamaIndex 各種框架層出不窮。Java 開(kāi)發(fā)者想在自己的 Spring Boot 項(xiàng)目里接一個(gè)大模型要么寫裸 HTTP 請(qǐng)求調(diào)用 OpenAI 兼容接口要么硬套 Python 生態(tài)的思路代碼風(fēng)格割裂維護(hù)成本極高。到了 2026 年這個(gè)局面的答案已經(jīng)非常明確Spring AI 2.0。這篇文章要把 Spring AI 2.0 里最重要的五件事——多模型、Tools、MCP、Skills、Agent——完整串起來(lái)講一遍。不是單純介紹概念而是從一個(gè)小型實(shí)戰(zhàn)項(xiàng)目出發(fā)把每一步的配置、代碼、踩坑點(diǎn)全部鋪開(kāi)。如果你是一個(gè) Java 工程師正在糾結(jié)怎么在公司項(xiàng)目里落地 AI 能力這篇文章可以直接當(dāng)參考手冊(cè)用。先說(shuō)結(jié)論Spring AI 2.0 真正解決的問(wèn)題是把“和大模型打交道”這件事變成了符合 Spring 編程模型的普通后端開(kāi)發(fā)。它不追求把 LangChain 那套 Python 生態(tài)搬過(guò)來(lái)而是用 Spring 自己的依賴注入、自動(dòng)配置、約定優(yōu)于配置把多模型切換、工具調(diào)用、協(xié)議接入、Agent 編排統(tǒng)一成一個(gè)標(biāo)準(zhǔn)范式。讀完這篇文章你能獨(dú)立搭出一個(gè)支持多模型切換、能調(diào)用自定義工具、能通過(guò) MCP 接入外部服務(wù)、帶記憶和會(huì)話的客服 Agent 原型。1. 這篇文章真正要解決的問(wèn)題很多 Java 開(kāi)發(fā)者學(xué) AI 編程的第一反應(yīng)是先去學(xué) Python。這個(gè)認(rèn)知正在變成一種路徑依賴。如果項(xiàng)目底層是 Java團(tuán)隊(duì)是 Java 團(tuán)隊(duì)業(yè)務(wù)邏輯都在 Spring Boot 服務(wù)里那用 Python 重寫一套 AI 應(yīng)用等于把整個(gè)工程體系復(fù)制了一份。Spring AI 2.0 的價(jià)值就在這里。它處理的不只是“調(diào)一次大模型接口”這種小事而是一整套企業(yè)級(jí) AI 應(yīng)用開(kāi)發(fā)中必須面對(duì)的問(wèn)題同一個(gè)業(yè)務(wù)要支持多家模型供應(yīng)商比如線上用 GPT-4o本地開(kāi)發(fā)用 Ollama 里的開(kāi)源模型怎么做到切換模型而不改業(yè)務(wù)代碼模型返回的是 JSON 文本怎么穩(wěn)定地映射成 Java 對(duì)象而不是靠正則硬解析大模型不知道你的訂單數(shù)據(jù)、用戶數(shù)據(jù)怎么安全地讓它調(diào)用你已有的 Service 方法外部工具生態(tài)已經(jīng)約定了統(tǒng)一接入?yún)f(xié)議比如數(shù)據(jù)庫(kù) MCP Server、文件系統(tǒng) MCP ServerSpring 項(xiàng)目怎么接入最省事一個(gè)智能客服 Agent 需要有角色設(shè)定、工具列表、會(huì)話記憶、多輪上下文這些怎么工程化管理這些問(wèn)題的答案就是 Spring AI 2.0 的核心抽象體系。它跟 Python 的 LangChain 解決的問(wèn)題高度重合但實(shí)現(xiàn)思路完全是 Java 式的自動(dòng)配置、Bean 管理、類型安全、Starter 依賴。從實(shí)用角度看這篇文章適合四類讀者還沒(méi)接觸過(guò) Spring AI但項(xiàng)目里已經(jīng)有 Spring Boot 3.x 基礎(chǔ)想快速上手已經(jīng)在用 Spring AI 1.x想知道 2.0 在 Tools、MCP、Skills、Agent 這幾個(gè)方向有什么變化被“多模型”“MCP”“Agent”這些概念繞暈需要一個(gè)能跑通的最小案例準(zhǔn)備把 AI 能力集成進(jìn)企業(yè)系統(tǒng)的架構(gòu)師或技術(shù)負(fù)責(zé)人需要判斷技術(shù)選型和工程邊界。有 Spring Boot 基礎(chǔ)的人今天就能把鏈路跑通。2. Spring AI 2.0 核心概念從 ChatModel 到 Agent2.1 最核心的抽象ChatModelSpring AI 對(duì) LLM 的抽象核心就是ChatModel接口。不管底層是 OpenAI、Anthropic、通義千問(wèn)、DeepSeek 還是 Ollama 里的本地模型對(duì)上層業(yè)務(wù)代碼來(lái)說(shuō)暴露出來(lái)的都是同一個(gè)接口。public interface ChatModel { ChatResponse call(Prompt prompt); }這個(gè)設(shè)計(jì)的價(jià)值在業(yè)務(wù)方不在實(shí)現(xiàn)方。你寫的 Service 層不需要關(guān)心當(dāng)前接的是哪個(gè)大模型。以后要從 GPT 切到本地模型只改配置不碰 Java 代碼。這就是多模型支持的第一層含義。圍繞ChatModelSpring AI 還提供了幾個(gè)配套抽象ChatClient更面向業(yè)務(wù)的流式調(diào)用入口支持 system prompt、user prompt、工具注冊(cè)、結(jié)構(gòu)化輸出。這是最常用的對(duì)象。EmbeddingModel負(fù)責(zé)把文本轉(zhuǎn)成向量用于 RAG、語(yǔ)義搜索等場(chǎng)景。StructuredOutputConverter將模型輸出解析為指定 Java 類型。2.2 Tools讓大模型調(diào)用你的函數(shù)大模型本身不持有你的業(yè)務(wù)數(shù)據(jù)它只能“說(shuō)出”一個(gè)新的 JSON 結(jié)構(gòu)表達(dá)“我想調(diào)用某個(gè)函數(shù)”。Tools 就是把這層機(jī)制封裝成了 Spring 風(fēng)格的工具方法。在 Spring AI 中只需要在方法上標(biāo)記Tool注解框架自動(dòng)完成“模型生成函數(shù)調(diào)用參數(shù) → 框架反射調(diào)用方法 → 把結(jié)果回傳給模型 → 模型基于結(jié)果繼續(xù)生成”的循環(huán)。這里真正容易踩坑的地方在于模型是否真的會(huì)調(diào)用你的 Tool取決于你寫的description是否足夠清晰。描述寫得含糊模型就會(huì)跳過(guò)函數(shù)調(diào)用直接憑幻覺(jué)回答。2.3 MCP模型上下文協(xié)議MCPModel Context Protocol是 Anthropic 在 2024 年底提出的開(kāi)放協(xié)議目標(biāo)是標(biāo)準(zhǔn)化“模型如何發(fā)現(xiàn)并調(diào)用外部工具/數(shù)據(jù)源”。它把工具、資源、提示詞統(tǒng)一成一套標(biāo)準(zhǔn)接口。一個(gè)團(tuán)隊(duì)只要實(shí)現(xiàn)了 MCP Server任何支持 MCP 的客戶端都能復(fù)用。Spring AI 2.0 對(duì) MCP 的支持是完整的可以作為 MCP Client連接現(xiàn)成的 MCP Server比如文件系統(tǒng)、數(shù)據(jù)庫(kù)、藍(lán)湖設(shè)計(jì)稿、GitHub 等也可以作為 MCP Server把 Spring 服務(wù)里的能力暴露給其他 AI 應(yīng)用。MCP 和 Tools 的關(guān)系不是二選一。Tools 是 Spring AI 內(nèi)部的函數(shù)調(diào)用機(jī)制MCP 是跨應(yīng)用、跨語(yǔ)言的工具發(fā)現(xiàn)與傳輸標(biāo)準(zhǔn)。MCP Server 在遠(yuǎn)端提供的工具最終會(huì)被 Spring AI 包裝成本地 Tool 參與模型對(duì)話。2.4 Skills更貼近業(yè)務(wù)的 Agent 能力封裝如果說(shuō) Tools 解決的是“單個(gè)函數(shù)”的調(diào)用那么 Skills 解決的是“一組能力”的復(fù)用。一個(gè) Skill 通常包含多部分內(nèi)容清晰的技能描述、可能用到的多個(gè)工具方法、提示詞模板、輸入校驗(yàn)規(guī)則甚至內(nèi)部的異常處理邏輯。從 Spring AI 2.0 的演進(jìn)方向看Skill 就是為 Agent 誕生的“能力包”。舉個(gè)例子一個(gè)“訂單查詢技能”可以包含“按訂單號(hào)查狀態(tài)”“按手機(jī)號(hào)查訂單列表”“查詢物流軌跡”三個(gè)工具并統(tǒng)一處理參數(shù)校驗(yàn)和返回格式。Agent 只需要知道“有一個(gè)訂單查詢技能”就能在合適的時(shí)候調(diào)用它。2.5 Skill 和 MCP 的區(qū)別這是很多初學(xué)者最暈的地方。用一句話概括它們的差異MCP 是標(biāo)準(zhǔn)與協(xié)議Skills 是業(yè)務(wù)封裝。MCP 解決的是“怎么連接、傳什么格式”的問(wèn)題比如你用 npx 啟動(dòng)一個(gè) filesystem MCP Server客戶端連上它就能列出可用的工具列表。Skill 解決的是“以什么方式參與 Agent 編排”的問(wèn)題它更像是一個(gè)高層的業(yè)務(wù)抽象背后既可以封裝本地 Tools也可以封裝對(duì) MCP 工具的調(diào)用。打個(gè)比方MCP 像是 USB-C 接口標(biāo)準(zhǔn)任何設(shè)備只要按這個(gè)標(biāo)準(zhǔn)生產(chǎn)就能互聯(lián)Skill 則像一個(gè)“即插即用的功能包”比如一個(gè)“高清投屏技能”它可能包含了軟件、驅(qū)動(dòng)和推薦配置。兩者不在同一個(gè)抽象層。2.6 Agent用對(duì)話能力編排一切Agent 不是一個(gè)新框架而是ChatModel Tools Skills 記憶 多輪編排的組合產(chǎn)物。在 Spring AI 2.0 中一個(gè) Agent 的編程模型非常簡(jiǎn)單準(zhǔn)備好一個(gè)ChatClient給它配置系統(tǒng)角色、工具列表和會(huì)話記憶剩下的循環(huán)推理全部交給框架。Agent 內(nèi)部會(huì)反復(fù)執(zhí)行“模型生成 → 決定是否調(diào)用工具 → 拿到結(jié)果 → 繼續(xù)生成”的流程直到它能給出最終回答。不過(guò)簡(jiǎn)單不代表沒(méi)有難點(diǎn)。真正考驗(yàn)工程能力的是 Agent 的安全邊界、工具權(quán)限、會(huì)話存儲(chǔ)、失敗降級(jí)這些外圍問(wèn)題。后面會(huì)專門用一整節(jié)說(shuō)清楚。3. 環(huán)境準(zhǔn)備與前置條件3.1 JDK 與構(gòu)建工具Spring AI 2.x 基于 Spring Framework 6.x 和 Spring Boot 3.x要求 JDK 17 及以上。推薦直接使用 JDK 21理由很實(shí)際虛擬線程、更完善的 ZGC 行為以及 Spring Boot 對(duì) JDK 21 的完整官方支持。構(gòu)建工具用 Maven 或 Gradle 都可以。本文示例以 Maven 為主因?yàn)閲?guó)內(nèi) Java 項(xiàng)目里 Maven 還是絕對(duì)主流。版本方面Spring AI 的版本更新速度比較快不建議把具體版本號(hào)寫死在文章里。正確做法在pom.xml里通過(guò)spring-ai-bom做依賴管理版本統(tǒng)一放到屬性里使用 Maven Central 上的最新穩(wěn)定版。!-- 文件路徑pom.xml 片段 -- properties java.version21/java.version spring-boot.version3.4.x/spring-boot.version spring-ai.version2.0.x/spring-ai.version /properties實(shí)際使用中把x替換成發(fā)布時(shí)的具體小版本號(hào)即可。3.2 Spring Boot 項(xiàng)目初始化先在 Spring Initializr 上生成一個(gè)基礎(chǔ)工程或者直接在 IDEA 里用 Spring Initializr 創(chuàng)建。需要選擇的依賴如下Spring WebSpring AI OpenAISpring AI OllamaLombok可選Spring AI MCP Client WebMVC如果你需要把 Spring 服務(wù)本身暴露成 MCP Server還需要加Spring AI MCP Server WebMVC。本文的示例會(huì)先做 MCP Client 接入。3.3 模型 API Key 準(zhǔn)備至少準(zhǔn)備一個(gè)可用的大模型 API Key。如果公司有統(tǒng)一的模型網(wǎng)關(guān)也可以把 base-url 指向網(wǎng)關(guān)地址。本地開(kāi)發(fā)優(yōu)先推薦 Ollama 方式下載 Ollama再拉一個(gè)支持 function calling 的模型比如qwen2.5系列。這樣即使沒(méi)有公網(wǎng) API Key也可以完成 Tools 和 Agent 的全流程測(cè)試。這里補(bǔ)充一個(gè)重要約定任何 API Key 都不要硬編碼到application.yml里更不要提交到 Git 倉(cāng)庫(kù)。用環(huán)境變量注入例如${OPENAI_API_KEY:}。如果你有配置中心例如 Apollo、Nacos Config應(yīng)該走配置中心統(tǒng)一管理。4. 核心流程拆解從配置到 Agent 的六步鏈路4.1 第一步配置多模型目標(biāo)是一個(gè) Spring Boot 項(xiàng)目里同時(shí)存在多個(gè)ChatModelBean。Spring AI 的自動(dòng)配置會(huì)為每個(gè)已引入的模型 Starter 創(chuàng)建對(duì)應(yīng)的ChatModelBean比如引入spring-ai-openai會(huì)自動(dòng)創(chuàng)建OpenAiChatModel引入spring-ai-ollama會(huì)自動(dòng)創(chuàng)建OllamaChatModel。但問(wèn)題來(lái)了如果項(xiàng)目里同時(shí)有多個(gè)ChatModelBean注入ChatClient.Builder時(shí) Spring 會(huì)由于類型不唯一而報(bào)錯(cuò)。解決辦法就是顯式聲明一個(gè)多模型路由服務(wù)用 Map 按名稱保存所有模型。這個(gè)設(shè)計(jì)本質(zhì)上是“多模型策略模式”后續(xù)切換模型時(shí)業(yè)務(wù)層只面向ChatModel接口編程選誰(shuí)用誰(shuí)由配置或路由邏輯決定。這是 Spring AI 多模型落地最實(shí)用的架構(gòu)。4.2 第二步搞定結(jié)構(gòu)化輸出大模型返回的是自然語(yǔ)言但業(yè)務(wù)系統(tǒng)需要的是FlightReservation、UserInfo這樣的 Java 對(duì)象。Spring AI 的ChatClient.entity()方法幫你做了類型轉(zhuǎn)換。實(shí)際操作時(shí)不要在實(shí)體里放太多復(fù)雜嵌套類型。大模型不是 JSON Schema 解析器越復(fù)雜的類型越容易解析失敗。先用扁平化的 record跑通后再逐步增加字段。4.3 第三步讓模型能調(diào)用工具定義一個(gè)繼承自Component的類在業(yè)務(wù)方法上標(biāo)注Tool描述要寫到“模型一聽(tīng)就懂”的程度。然后用ChatClient.Builder.defaultTools()把工具傳進(jìn)去。驗(yàn)證這一步是否成功最直接的辦法是問(wèn)一個(gè)必須靠工具才能回答的問(wèn)題比如“北京今天天氣怎么樣”。如果模型準(zhǔn)確返回了天氣說(shuō)明函數(shù)調(diào)用鏈路已經(jīng)通了。4.4 第四步接入 MCP引入 MCP Client 依賴在配置里聲明要連的 stdio MCP ServerSpring AI 會(huì)自動(dòng)把這個(gè)服務(wù)器提供的工具合并到模型對(duì)話中。如果公司內(nèi)部有 HTTP 方式的 MCP Server也可以走 SSE 或 WebMVC 配置。接入方式和 stdio 略有不同但核心思想一致遠(yuǎn)程工具被包裝成本地 Tool不需要業(yè)務(wù)代碼感知。4.5 第五步封裝 Skills把“散裝工具提示詞規(guī)則”收斂成一個(gè)高內(nèi)聚的類。Skill 通常是普通 Spring Service內(nèi)部依賴多個(gè) Tool 方法再通過(guò)構(gòu)造器注入到ChatClient。這里的一個(gè)工程建議每個(gè) Skill 類都寫清楚Description讓 Agent 知道這個(gè)技能在什么場(chǎng)景下使用。Agent 判斷“該不該用這個(gè)技能”依賴的就是這個(gè)描述。4.6 第六步用 Agent 編排落地把系統(tǒng)角色、工具列表、Skills、會(huì)話記憶整合到一個(gè)ChatClientBean 里對(duì)外暴露一個(gè)chat(userMessage, conversationId)方法。這個(gè) Bean 就是你的客服 Agent。會(huì)話記憶的實(shí)現(xiàn)方式依賴于ChatClient的id(conversationId)參數(shù)框架會(huì)把同一 id 的多輪對(duì)話保存到ChatMemory。生產(chǎn)環(huán)境應(yīng)該替換成 Redis 或數(shù)據(jù)庫(kù)存儲(chǔ)避免單機(jī)內(nèi)存丟失?，F(xiàn)在整條鏈路就通了。下面用可運(yùn)行代碼過(guò)一遍。5. 完整示例代碼實(shí)現(xiàn)本節(jié)的工程結(jié)構(gòu)如下src/main/java/com/example/ai/ ├── AiApplication.java ├── config/ │ └── ChatClientConfig.java ├── controller/ │ ├── ChatController.java │ ├── StructuredOutputController.java │ └── MultiModelController.java ├── service/ │ ├── MultiModelService.java │ └── OrderQuerySkill.java ├── tool/ │ └── WeatherTools.java ├── agent/ │ └── CustomerServiceAgent.java └── entity/ └── FlightReservation.java5.1 新增 Maven 依賴先更新pom.xml加入 Spring AI BOM 以及所需的 Starter!-- 文件路徑pom.xml -- dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-client-webmvc/artifactId /dependency /dependenciesspring-ai-bom的作用是統(tǒng)一管理所有 Spring AI 模塊的版本號(hào)避免手動(dòng)逐個(gè)對(duì)齊版本。5.2 配置文件在application.yml中配置多模型和 MCP Client# 文件路徑src/main/resources/application.yml server: port: 8080 spring: application: name: spring-ai-demo ai: openai: base-url: ${OPENAI_BASE_URL:https://api.openai.com} api-key: ${OPENAI_API_KEY:} chat: options: model: gpt-4o-mini temperature: 0.7 ollama: base-url: http://localhost:11434 chat: options: model: qwen2.5:7b temperature: 0.7 mcp: client: stdio: servers: filesystem: command: npx args: -y,modelcontextprotocol/server-filesystem,/tmp/data這里最需要注意的地方是args的寫法。Spring AI 的 MCP 配置要求 args 是一個(gè)數(shù)組不同版本對(duì)分隔符的處理略有差異。如果啟動(dòng)時(shí) MCP Server 沒(méi)有連上第一優(yōu)先排查的就是這個(gè)參數(shù)里的逗號(hào)分隔是否正確以及本機(jī)是否安裝并可以使用 npx。5.3 多模型調(diào)用用具體的ChatModel實(shí)現(xiàn)類型做構(gòu)造器注入這樣不會(huì)被多 Bean 問(wèn)題干擾// 文件路徑src/main/java/com/example/ai/service/MultiModelService.java Service public class MultiModelService { private final OpenAiChatModel openAiChatModel; private final OllamaChatModel ollamaChatModel; public MultiModelService(OpenAiChatModel openAiChatModel, OllamaChatModel ollamaChatModel) { this.openAiChatModel openAiChatModel; this.ollamaChatModel ollamaChatModel; } public String chatWith(String provider, String message) { ChatModel chatModel switch (provider) { case openai - openAiChatModel; case ollama - ollamaChatModel; default - throw new IllegalArgumentException(未知模型: provider); }; return chatModel.call(new Prompt(message)) .getResult() .getOutput() .getText(); } }這段代碼的關(guān)鍵點(diǎn)是“面向接口編程”。業(yè)務(wù)方拿到的是ChatModel具體實(shí)現(xiàn)可以隨時(shí)替換。以后新增模型供應(yīng)商只需要增加一個(gè) Starter 依賴再在 switch 里加一行分支。5.4 結(jié)構(gòu)化輸出定義一個(gè)實(shí)體類用 record 保持簡(jiǎn)潔// 文件路徑src/main/java/com/example/ai/entity/FlightReservation.java public record FlightReservation( String flightNumber, String from, String to, String departureTime, String price ) { }不推薦在這個(gè) record 里放LocalDateTime、BigDecimal這類需要強(qiáng)類型轉(zhuǎn)換的字段。大模型返回的 JSON 字符串在解析成本地類型時(shí)一旦格式不匹配會(huì)直接拋出類型轉(zhuǎn)換異常。先用字符串類型跑通是結(jié)構(gòu)化輸出最容易成功的路徑。再寫一個(gè) Controller 展示如何使用// 文件路徑src/main/java/com/example/ai/controller/StructuredOutputController.java RestController RequestMapping(/api/structured) public class StructuredOutputController { private final ChatClient chatClient; public StructuredOutputController(ChatClient.Builder builder) { this.chatClient builder.build(); } GetMapping(/parse-reservation) public FlightReservation parseReservation(RequestParam String text) { return chatClient.prompt() .system(你是航班信息解析助手。請(qǐng)從用戶文本中抽取航班編號(hào)、出發(fā)地、目的地、出發(fā)時(shí)間和價(jià)格。) .user(text) .call() .entity(FlightReservation.class); } }5.5 自定義 Tools定義一個(gè)天氣工具類。這是本文最典型的Tool用法// 文件路徑src/main/java/com/example/ai/tool/WeatherTools.java Component public class WeatherTools { Tool(description 根據(jù)城市名稱查詢當(dāng)前天氣) public String getWeatherByCity(String city) { // 實(shí)際項(xiàng)目里替換為天氣服務(wù) API 調(diào)用 if (北京.equals(city)) { return 北京晴25℃東南風(fēng)2級(jí); } return city 多云22℃東北風(fēng)1級(jí); } Tool(description 根據(jù)城市名稱查詢未來(lái)三天天氣預(yù)報(bào)需要傳入城市和天數(shù)) public String getForecast(String city, int days) { return city 未來(lái) days 天晴轉(zhuǎn)多云最低18℃最高27℃; } }注意Tool的描述寫清楚“需要傳入什么參數(shù)”這直接影響模型生成參數(shù)的成功率。5.6 MCP 客戶端接入前面已經(jīng)在application.yml里配置了 filesystem 這個(gè) stdio 服務(wù)。當(dāng) Spring AI 檢測(cè)到 MCP Client 依賴時(shí)會(huì)自動(dòng)連接該服務(wù)并把它暴露出的工具合并到工具注冊(cè)表。如果不想使用 stdio 方式也可以把spring-ai-mcp-client-webmvc換成或互補(bǔ)使用 HTTP 方式spring: ai: mcp: client: url: http://localhost:8081url方式適合連接已經(jīng)部署為獨(dú)立服務(wù)的 MCP Server。這里強(qiáng)調(diào)一個(gè)重要過(guò)程MCP 工具是“動(dòng)態(tài)發(fā)現(xiàn)”的。你在代碼里看不到 filesystem 工具的 Java 類但它會(huì)在運(yùn)行期被注冊(cè)成一個(gè)ToolCallback。排查 MCP 工具是否生效看啟動(dòng)日志里是否打印了 MCP 工具調(diào)用的注冊(cè)信息即可。5.7 Skill 定義用一個(gè)高內(nèi)聚的 Skill 類封裝“訂單查詢”能力。它不僅包含工具方法還包含面向 Agent 的描述和參數(shù)校驗(yàn)邏輯// 文件路徑src/main/java/com/example/ai/service/OrderQuerySkill.java Service public class OrderQuerySkill { Tool(description 根據(jù)訂單號(hào)查詢訂單狀態(tài)和物流信息訂單號(hào)為數(shù)字字符串) public String queryOrderStatus(String orderId) { if (orderId null || !orderId.matches(\\d{6,})) { return 訂單號(hào)格式不正確; } // 實(shí)際項(xiàng)目里注入 OrderRepository 查詢數(shù)據(jù)庫(kù) return 訂單 orderId 狀態(tài)已發(fā)貨預(yù)計(jì) 3 天內(nèi)送達(dá); } Tool(description 根據(jù)用戶手機(jī)號(hào)查詢最近三個(gè)月訂單列表) public String listRecentOrders(String mobile) { if (mobile null || !mobile.matches(1\\d{10})) { return 手機(jī)號(hào)格式不正確; } return 最近訂單2026030101已簽收、2026021502已發(fā)貨; } }所謂 Skill 和普通 Tool 類的差別更多體現(xiàn)在設(shè)計(jì)意圖上。一個(gè) Skill 可以包含多個(gè) Tool并負(fù)責(zé)它們之間的業(yè)務(wù)規(guī)則。Agent 只需要注入這一個(gè)類就能獲得整套能力。5.8 Agent 編排最后把所有能力整合到一個(gè)客服 Agent 中// 文件路徑src/main/java/com/example/ai/agent/CustomerServiceAgent.java Component public class CustomerServiceAgent { private final ChatClient chatClient; public CustomerServiceAgent(ChatClient.Builder builder, WeatherTools weatherTools, OrderQuerySkill orderQuerySkill) { this.chatClient builder .defaultSystem(你是企業(yè)智能客服回答要簡(jiǎn)潔、準(zhǔn)確、友好。當(dāng)用戶詢問(wèn)天氣時(shí)必須使用天氣工具 當(dāng)用戶查詢訂單時(shí)必須使用訂單查詢技能不要編造訂單數(shù)據(jù)。) .defaultTools(weatherTools, orderQuerySkill) .build(); } public String chat(String userMessage, String conversationId) { return chatClient.prompt() .id(conversationId) .user(userMessage) .call() .content(); } public String chatWithSystem(String systemPrompt, String userMessage, String conversationId) { return chatClient.prompt() .system(systemPrompt) .id(conversationId) .user(userMessage) .call() .content(); } }sytem提示詞里明確寫了“必須使用天氣工具”“不要編造訂單數(shù)據(jù)”這種約束是 Agent 工程質(zhì)量的重要來(lái)源。模型有概率忽略模糊指令但你把指令寫進(jìn)系統(tǒng)提示詞輔助工具描述清晰成功率會(huì)大幅提高。再提供一個(gè)入口 Controller// 文件路徑src/main/java/com/example/ai/controller/ChatController.java RestController RequestMapping(/api/agent) public class ChatController { private final CustomerServiceAgent customerServiceAgent; private final MultiModelService multiModelService; public ChatController(CustomerServiceAgent customerServiceAgent, MultiModelService multiModelService) { this.customerServiceAgent customerServiceAgent; this.multiModelService multiModelService; } GetMapping(/chat) public String chat(RequestParam String message, RequestParam(defaultValue default) String conversationId) { return customerServiceAgent.chat(message, conversationId); } GetMapping(/multi) public String multi(RequestParam String provider, RequestParam String message) { return multiModelService.chatWith(provider, message); } }到這里一個(gè)支持多模型、自定義 Tools、MCP 外部工具、Skill 能力封裝、多輪會(huì)話記憶的 Agent 原型已經(jīng)完整落地。下面看看怎么驗(yàn)證它。6. 運(yùn)行結(jié)果與效果驗(yàn)證啟動(dòng)項(xiàng)目mvn spring-boot:run如果本地Ollama已經(jīng)拉取了qwen2.5:7b啟動(dòng)日志里會(huì)同時(shí)出現(xiàn) OpenAI 和 Ollama 的模型初始化信息。MCP Client 啟動(dòng)時(shí)會(huì)嘗試執(zhí)行npx -y modelcontextprotocol/server-filesystem /tmp/data日志里會(huì)出現(xiàn) MCP Server connected 之類的記錄。依次驗(yàn)證幾個(gè)核心能力基礎(chǔ)對(duì)話curl http://localhost:8080/api/agent/chat?message你好conversationIdtest-001預(yù)期輸出一句問(wèn)候語(yǔ)說(shuō)明ChatClient鏈路正常。結(jié)構(gòu)化輸出curl http://localhost:8080/api/structured/parse-reservation?text幫我訂明天從北京到上海的MU5111航班價(jià)格850元提醒我上午十點(diǎn)出發(fā)預(yù)期返回 JSON{flightNumber:MU5111,from:北京,to:上海,departureTime:10:00,price:850元}工具調(diào)用聯(lián)動(dòng)curl http://localhost:8080/api/agent/chat?message北京今天天氣怎么樣conversationIdtest-001如果模型沒(méi)有調(diào)工具可能只會(huì)回答“我無(wú)法獲取實(shí)時(shí)天氣”。如果正確調(diào)用了WeatherTools.getWeatherByCity會(huì)返回“北京晴25℃”等相關(guān)信息。多輪會(huì)話驗(yàn)證curl http://localhost:8080/api/agent/chat?message我的手機(jī)號(hào)是13800138000幫我查一下最近訂單conversationIdtest-001 curl http://localhost:8080/api/agent/chat?message再看看第一單的物流conversationIdtest-001第二次提問(wèn)依賴第一次的上下文。如果返回結(jié)果包含第一單的訂單號(hào)或狀態(tài)說(shuō)明會(huì)話記憶已生效。判斷 Agent 是否正常不能只看是否返回結(jié)果還要看它是不是在正確的步驟調(diào)用了正確的工具。建議在本地開(kāi)發(fā)時(shí)打開(kāi) Spring AI 的調(diào)試日志logging: level: org.springframework.ai: DEBUG這樣可以在控制臺(tái)看到完整的工具調(diào)用鏈模型請(qǐng)求 → 工具調(diào)用 → 工具返回 → 模型最終回答。如果失敗優(yōu)先看這幾個(gè)位置啟動(dòng)階段MCP Server 是否連接成功Ollama 服務(wù)是否可用調(diào)用階段模型返回是否超時(shí)工具階段Tool方法是否有日志返回內(nèi)容是否被模型正確消費(fèi)。7. 常見(jiàn)問(wèn)題與排查思路問(wèn)題現(xiàn)象可能原因排查方式解決方案啟動(dòng)報(bào)錯(cuò)說(shuō)存在多個(gè) ChatModel Bean同時(shí)引入了多個(gè)模型 Starter自動(dòng)配置創(chuàng)建了多個(gè)同類型 Bean查看啟動(dòng)日志中 Bean 創(chuàng)建記錄用Qualifier或顯式配置指定使用的模型或封裝多模型路由服務(wù)請(qǐng)求時(shí)模型長(zhǎng)時(shí)間無(wú)響應(yīng)模型 API Key 無(wú)效、網(wǎng)絡(luò)不通、本地 Ollama 沒(méi)有啟動(dòng)先 curl 模型供應(yīng)商接口查看 Ollama 是否在 11434 端口監(jiān)聽(tīng)修正 API Key / base-url啟動(dòng) Ollama 并確認(rèn)模型已拉取工具沒(méi)有被調(diào)用模型直接瞎回答Tool的描述不夠清晰或 system prompt 沒(méi)有強(qiáng)制要求檢查工具描述打開(kāi) DEBUG 日志確認(rèn)模型請(qǐng)求里是否包含 tool_calls重寫描述加入“必須使用工具回答”等約束結(jié)構(gòu)化輸出解析失敗拋類型轉(zhuǎn)換異常模型返回文本格式不匹配 Java 類型查看實(shí)際返回的 JSON簡(jiǎn)化實(shí)體字段統(tǒng)一使用 String逐步增加字段MCP Server 連接失敗npx 未安裝、args 參數(shù)格式錯(cuò)誤、服務(wù)端地址不通在終端手動(dòng)執(zhí)行npx -y modelcontextprotocol/server-filesystem /tmp/data檢查啟動(dòng)日志 MCP 部分修正 args 寫法安裝 npx改用可訪問(wèn)的 HTTP MCP Server多輪對(duì)話上下文丟失conversationId傳遞不一致或沒(méi)有配置持久化 ChatMemory檢查每次請(qǐng)求是否傳同一個(gè) id查看內(nèi)存存儲(chǔ)的日志用 Redis/數(shù)據(jù)庫(kù)實(shí)現(xiàn) ChatMemory統(tǒng)一會(huì)話 id 生成規(guī)則本地模型不支持 function callingOllama 拉取的模型版本較老或本身不支持工具調(diào)用查詢模型文檔確認(rèn)是否支持 tools更換支持 function calling 的模型例如qwen2.5系列這些問(wèn)題是獨(dú)立開(kāi)發(fā)者在完整跑通鏈路時(shí)最容易遇到的。嚴(yán)格按照排查路徑走大多數(shù)問(wèn)題會(huì)在十分鐘內(nèi)定位。8. 最佳實(shí)踐與工程建議8.1 模型接入層統(tǒng)一路由隔離供應(yīng)商不要把模型供應(yīng)商的 SDK 直接散落在業(yè)務(wù)代碼里。所有模型訪問(wèn)統(tǒng)一走ChatModel接口模型路由邏輯收斂到一個(gè)服務(wù)中。這樣才能做到“線上用商業(yè)模型、測(cè)試用本地模型”而不修改業(yè)務(wù)代碼。8.2 提示詞管理模板化、版本化System prompt 不要散落在 Controller 里。建議用提示詞模板文件配合 Spring 的Resource加載放到系統(tǒng)資源目錄下。提示詞實(shí)際上是需要評(píng)審和版本管理的“代碼”它直接影響模型行為質(zhì)量。8.3 工具安全最小權(quán)限原則Tool方法本質(zhì)上是把內(nèi)部能力暴露給外部模型調(diào)用。必須遵守最小權(quán)限原則工具方法只做自己該做的事不要聲明一個(gè)大而全的方法例如“執(zhí)行任意 SQL”。所有涉及數(shù)據(jù)庫(kù)、文件、外部 API 的工具都要做參數(shù)校驗(yàn)就像對(duì)待用戶輸入一樣。8.4 會(huì)話記憶生產(chǎn)環(huán)境不要用默認(rèn)內(nèi)存實(shí)現(xiàn)ChatClient的默認(rèn)記憶是內(nèi)存級(jí)的應(yīng)用重啟即丟失。生產(chǎn)環(huán)境應(yīng)該把ChatMemory替換為 Redis 或數(shù)據(jù)庫(kù)實(shí)現(xiàn)。會(huì)話 ID 必須由后端統(tǒng)一生成不要信任前端傳入的任意 key否則容易出現(xiàn)會(huì)話串臺(tái)問(wèn)題。8.5 MCP 生命周期管理MCP stdio 服務(wù)本質(zhì)上是啟動(dòng)一個(gè)子進(jìn)程它的生命周期需要被關(guān)注。不要在生產(chǎn)環(huán)境用 npx 臨時(shí)拉取 MCP Server盡量構(gòu)建成獨(dú)立服務(wù)用 HTTP 方式接入這樣便于監(jiān)控和擴(kuò)縮容。8.6 Agent 可觀測(cè)性Agent 是一個(gè)多步?jīng)Q策系統(tǒng)每一步都可能出錯(cuò)。生產(chǎn)環(huán)境必須記錄用戶問(wèn)題原文模型是否發(fā)起了工具調(diào)用調(diào)用了哪個(gè)工具、參數(shù)是什么工具返回結(jié)果最終回答內(nèi)容。這些日志鏈路是排查問(wèn)題的唯一依據(jù)。建議在Tool方法和 Agent 調(diào)用層都加上結(jié)構(gòu)化日志而不是只靠框架默認(rèn)日志。8.7 成本與限流多模型配置帶來(lái)成本控制能力的同時(shí)也帶來(lái)新的風(fēng)險(xiǎn)工具循環(huán)次數(shù)過(guò)多會(huì)導(dǎo)致 Token 消耗膨脹。建議給 Agent 調(diào)用設(shè)置超時(shí)時(shí)間、最大工具調(diào)用輪數(shù)并針對(duì)不同模型配置不同的限流策略。8.8 版本升級(jí)策略Spring AI 版本迭代快API 偶有調(diào)整。升級(jí)前先看官方遷移指南并且保留一個(gè)小范圍的兼容層。比如你寫一個(gè)AgentChatService包裝ChatClient未來(lái)內(nèi)部 API 變化時(shí)只改這個(gè)類業(yè)務(wù)層不受影響。9. 總結(jié)與后續(xù)學(xué)習(xí)方向Spring AI 2.0 給 Java 生態(tài)帶來(lái)的價(jià)值不只是一套可以調(diào)大模型的 Starter而是一整套符合 Spring 編程模型的 AI 應(yīng)用開(kāi)發(fā)范式。本文把這條鏈路完整拆解了一遍多模型解決了供應(yīng)商鎖定問(wèn)題Tool讓模型具備調(diào)用業(yè)務(wù)方法的能力MCP 把外部工具生態(tài)標(biāo)準(zhǔn)化Skills 讓能力封裝更貼近業(yè)務(wù)Agent 則把這一切組合成了可交付的智能服務(wù)。建議你按順序完成三個(gè)練習(xí)先跑通多模型切換和結(jié)構(gòu)化輸出再實(shí)現(xiàn)一個(gè)包含兩個(gè)Tool的客服助手最后接入一個(gè)外部 MCP Server例如文件系統(tǒng)或數(shù)據(jù)庫(kù)服務(wù)。這三步做完Spring AI 2.0 的主要能力就算真正掌握。接下來(lái)值得深入的方向包括RAG 與向量數(shù)據(jù)庫(kù)的集成、Agent 與業(yè)務(wù)流程引擎的結(jié)合、基于 MCP Server 暴露公司內(nèi)部服務(wù)給 AI 應(yīng)用、以及多 Agent 協(xié)作模式。每一條都比單純調(diào)大模型接口更有工程價(jià)值也是 Java 工程師在 AI 時(shí)代不可替代的底牌。