從 2024 年開始AI 應(yīng)用開發(fā)幾乎成了 Python 開發(fā)者專屬賽道LangChain、LlamaIndex 各種框架層出不窮。Java 開發(fā)者想在自己的 Spring Boot 項(xiàng)目里接一個(gè)大模型要么寫裸 HTTP 請求調(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——完整串起來講一遍。不是單純介紹概念而是從一個(gè)小型實(shí)戰(zhàn)項(xiàng)目出發(fā)把每一步的配置、代碼、踩坑點(diǎn)全部鋪開。如果你是一個(gè) Java 工程師正在糾結(jié)怎么在公司項(xiàng)目里落地 AI 能力這篇文章可以直接當(dāng)參考手冊用。先說結(jié)論Spring AI 2.0 真正解決的問題是把“和大模型打交道”這件事變成了符合 Spring 編程模型的普通后端開發(fā)。它不追求把 LangChain 那套 Python 生態(tài)搬過來而是用 Spring 自己的依賴注入、自動配置、約定優(yōu)于配置把多模型切換、工具調(diào)用、協(xié)議接入、Agent 編排統(tǒng)一成一個(gè)標(biāo)準(zhǔn)范式。讀完這篇文章你能獨(dú)立搭出一個(gè)支持多模型切換、能調(diào)用自定義工具、能通過 MCP 接入外部服務(wù)、帶記憶和會話的客服 Agent 原型。1. 這篇文章真正要解決的問題很多 Java 開發(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è)級 AI 應(yīng)用開發(fā)中必須面對的問題同一個(gè)業(yè)務(wù)要支持多家模型供應(yīng)商比如線上用 GPT-4o本地開發(fā)用 Ollama 里的開源模型怎么做到切換模型而不改業(yè)務(wù)代碼模型返回的是 JSON 文本怎么穩(wěn)定地映射成 Java 對象而不是靠正則硬解析大模型不知道你的訂單數(shù)據(jù)、用戶數(shù)據(jù)怎么安全地讓它調(diào)用你已有的 Service 方法外部工具生態(tài)已經(jīng)約定了統(tǒng)一接入?yún)f(xié)議比如數(shù)據(jù)庫 MCP Server、文件系統(tǒng) MCP ServerSpring 項(xiàng)目怎么接入最省事一個(gè)智能客服 Agent 需要有角色設(shè)定、工具列表、會話記憶、多輪上下文這些怎么工程化管理這些問題的答案就是 Spring AI 2.0 的核心抽象體系。它跟 Python 的 LangChain 解決的問題高度重合但實(shí)現(xiàn)思路完全是 Java 式的自動配置、Bean 管理、類型安全、Starter 依賴。從實(shí)用角度看這篇文章適合四類讀者還沒接觸過 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 對 LLM 的抽象核心就是ChatModel接口。不管底層是 OpenAI、Anthropic、通義千問、DeepSeek 還是 Ollama 里的本地模型對上層業(yè)務(wù)代碼來說暴露出來的都是同一個(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、工具注冊、結(jié)構(gòu)化輸出。這是最常用的對象。EmbeddingModel負(fù)責(zé)把文本轉(zhuǎn)成向量用于 RAG、語義搜索等場景。StructuredOutputConverter將模型輸出解析為指定 Java 類型。2.2 Tools讓大模型調(diào)用你的函數(shù)大模型本身不持有你的業(yè)務(wù)數(shù)據(jù)它只能“說出”一個(gè)新的 JSON 結(jié)構(gòu)表達(dá)“我想調(diào)用某個(gè)函數(shù)”。Tools 就是把這層機(jī)制封裝成了 Spring 風(fēng)格的工具方法。在 Spring AI 中只需要在方法上標(biāo)記Tool注解框架自動完成“模型生成函數(shù)調(diào)用參數(shù) → 框架反射調(diào)用方法 → 把結(jié)果回傳給模型 → 模型基于結(jié)果繼續(xù)生成”的循環(huán)。這里真正容易踩坑的地方在于模型是否真的會調(diào)用你的 Tool取決于你寫的description是否足夠清晰。描述寫得含糊模型就會跳過函數(shù)調(diào)用直接憑幻覺回答。2.3 MCP模型上下文協(xié)議MCPModel Context Protocol是 Anthropic 在 2024 年底提出的開放協(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 對 MCP 的支持是完整的可以作為 MCP Client連接現(xiàn)成的 MCP Server比如文件系統(tǒng)、數(shù)據(jù)庫、藍(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)用、跨語言的工具發(fā)現(xiàn)與傳輸標(biāo)準(zhǔn)。MCP Server 在遠(yuǎn)端提供的工具最終會被 Spring AI 包裝成本地 Tool 參與模型對話。2.4 Skills更貼近業(yè)務(wù)的 Agent 能力封裝如果說 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è)“訂單查詢技能”可以包含“按訂單號查狀態(tài)”“按手機(jī)號查訂單列表”“查詢物流軌跡”三個(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 解決的是“怎么連接、傳什么格式”的問題比如你用 npx 啟動一個(gè) filesystem MCP Server客戶端連上它就能列出可用的工具列表。Skill 解決的是“以什么方式參與 Agent 編排”的問題它更像是一個(gè)高層的業(yè)務(wù)抽象背后既可以封裝本地 Tools也可以封裝對 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ū)動和推薦配置。兩者不在同一個(gè)抽象層。2.6 Agent用對話能力編排一切Agent 不是一個(gè)新框架而是ChatModel Tools Skills 記憶 多輪編排的組合產(chǎn)物。在 Spring AI 2.0 中一個(gè) Agent 的編程模型非常簡單準(zhǔn)備好一個(gè)ChatClient給它配置系統(tǒng)角色、工具列表和會話記憶剩下的循環(huán)推理全部交給框架。Agent 內(nèi)部會反復(fù)執(zhí)行“模型生成 → 決定是否調(diào)用工具 → 拿到結(jié)果 → 繼續(xù)生成”的流程直到它能給出最終回答。不過簡單不代表沒有難點(diǎn)。真正考驗(yàn)工程能力的是 Agent 的安全邊界、工具權(quán)限、會話存儲、失敗降級這些外圍問題。后面會專門用一整節(jié)說清楚。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 對 JDK 21 的完整官方支持。構(gòu)建工具用 Maven 或 Gradle 都可以。本文示例以 Maven 為主因?yàn)閲鴥?nèi) Java 項(xiàng)目里 Maven 還是絕對主流。版本方面Spring AI 的版本更新速度比較快不建議把具體版本號寫死在文章里。正確做法在pom.xml里通過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í)的具體小版本號即可。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。本文的示例會先做 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)地址。本地開發(fā)優(yōu)先推薦 Ollama 方式下載 Ollama再拉一個(gè)支持 function calling 的模型比如qwen2.5系列。這樣即使沒有公網(wǎng) API Key也可以完成 Tools 和 Agent 的全流程測試。這里補(bǔ)充一個(gè)重要約定任何 API Key 都不要硬編碼到application.yml里更不要提交到 Git 倉庫。用環(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 的自動配置會為每個(gè)已引入的模型 Starter 創(chuàng)建對應(yīng)的ChatModelBean比如引入spring-ai-openai會自動創(chuàng)建OpenAiChatModel引入spring-ai-ollama會自動創(chuàng)建OllamaChatModel。但問題來了如果項(xiàng)目里同時(shí)有多個(gè)ChatModelBean注入ChatClient.Builder時(shí) Spring 會由于類型不唯一而報(bào)錯(cuò)。解決辦法就是顯式聲明一個(gè)多模型路由服務(wù)用 Map 按名稱保存所有模型。這個(gè)設(shè)計(jì)本質(zhì)上是“多模型策略模式”后續(xù)切換模型時(shí)業(yè)務(wù)層只面向ChatModel接口編程選誰用誰由配置或路由邏輯決定。這是 Spring AI 多模型落地最實(shí)用的架構(gòu)。4.2 第二步搞定結(jié)構(gòu)化輸出大模型返回的是自然語言但業(yè)務(wù)系統(tǒng)需要的是FlightReservation、UserInfo這樣的 Java 對象。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描述要寫到“模型一聽就懂”的程度。然后用ChatClient.Builder.defaultTools()把工具傳進(jìn)去。驗(yàn)證這一步是否成功最直接的辦法是問一個(gè)必須靠工具才能回答的問題比如“北京今天天氣怎么樣”。如果模型準(zhǔn)確返回了天氣說明函數(shù)調(diào)用鏈路已經(jīng)通了。4.4 第四步接入 MCP引入 MCP Client 依賴在配置里聲明要連的 stdio MCP ServerSpring AI 會自動把這個(gè)服務(wù)器提供的工具合并到模型對話中。如果公司內(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 方法再通過構(gòu)造器注入到ChatClient。這里的一個(gè)工程建議每個(gè) Skill 類都寫清楚Description讓 Agent 知道這個(gè)技能在什么場景下使用。Agent 判斷“該不該用這個(gè)技能”依賴的就是這個(gè)描述。4.6 第六步用 Agent 編排落地把系統(tǒng)角色、工具列表、Skills、會話記憶整合到一個(gè)ChatClientBean 里對外暴露一個(gè)chat(userMessage, conversationId)方法。這個(gè) Bean 就是你的客服 Agent。會話記憶的實(shí)現(xiàn)方式依賴于ChatClient的id(conversationId)參數(shù)框架會把同一 id 的多輪對話保存到ChatMemory。生產(chǎn)環(huán)境應(yīng)該替換成 Redis 或數(shù)據(jù)庫存儲避免單機(jī)內(nèi)存丟失。現(xiàn)在整條鏈路就通了。下面用可運(yùn)行代碼過一遍。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 模塊的版本號避免手動逐個(gè)對齊版本。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ù)組不同版本對分隔符的處理略有差異。如果啟動時(shí) MCP Server 沒有連上第一優(yōu)先排查的就是這個(gè)參數(shù)里的逗號分隔是否正確以及本機(jī)是否安裝并可以使用 npx。5.3 多模型調(diào)用用具體的ChatModel實(shí)現(xiàn)類型做構(gòu)造器注入這樣不會被多 Bean 問題干擾// 文件路徑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 保持簡潔// 文件路徑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í)一旦格式不匹配會直接拋出類型轉(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(你是航班信息解析助手。請從用戶文本中抽取航班編號、出發(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級; } return city 多云22℃東北風(fēng)1級; } Tool(description 根據(jù)城市名稱查詢未來三天天氣預(yù)報(bào)需要傳入城市和天數(shù)) public String getForecast(String city, int days) { return city 未來 days 天晴轉(zhuǎn)多云最低18℃最高27℃; } }注意Tool的描述寫清楚“需要傳入什么參數(shù)”這直接影響模型生成參數(shù)的成功率。5.6 MCP 客戶端接入前面已經(jīng)在application.yml里配置了 filesystem 這個(gè) stdio 服務(wù)。當(dāng) Spring AI 檢測到 MCP Client 依賴時(shí)會自動連接該服務(wù)并把它暴露出的工具合并到工具注冊表。如果不想使用 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è)重要過程MCP 工具是“動態(tài)發(fā)現(xiàn)”的。你在代碼里看不到 filesystem 工具的 Java 類但它會在運(yùn)行期被注冊成一個(gè)ToolCallback。排查 MCP 工具是否生效看啟動日志里是否打印了 MCP 工具調(diào)用的注冊信息即可。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ù)訂單號查詢訂單狀態(tài)和物流信息訂單號為數(shù)字字符串) public String queryOrderStatus(String orderId) { if (orderId null || !orderId.matches(\\d{6,})) { return 訂單號格式不正確; } // 實(shí)際項(xiàng)目里注入 OrderRepository 查詢數(shù)據(jù)庫 return 訂單 orderId 狀態(tài)已發(fā)貨預(yù)計(jì) 3 天內(nèi)送達(dá); } Tool(description 根據(jù)用戶手機(jī)號查詢最近三個(gè)月訂單列表) public String listRecentOrders(String mobile) { if (mobile null || !mobile.matches(1\\d{10})) { return 手機(jī)號格式不正確; } 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è)智能客服回答要簡潔、準(zhǔn)確、友好。當(dāng)用戶詢問天氣時(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ì)量的重要來源。模型有概率忽略模糊指令但你把指令寫進(jìn)系統(tǒng)提示詞輔助工具描述清晰成功率會大幅提高。再提供一個(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 能力封裝、多輪會話記憶的 Agent 原型已經(jīng)完整落地。下面看看怎么驗(yàn)證它。6. 運(yùn)行結(jié)果與效果驗(yàn)證啟動項(xiàng)目mvn spring-boot:run如果本地Ollama已經(jīng)拉取了qwen2.5:7b啟動日志里會同時(shí)出現(xiàn) OpenAI 和 Ollama 的模型初始化信息。MCP Client 啟動時(shí)會嘗試執(zhí)行npx -y modelcontextprotocol/server-filesystem /tmp/data日志里會出現(xiàn) MCP Server connected 之類的記錄。依次驗(yàn)證幾個(gè)核心能力基礎(chǔ)對話curl http://localhost:8080/api/agent/chat?message你好conversationIdtest-001預(yù)期輸出一句問候語說明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)動curl http://localhost:8080/api/agent/chat?message北京今天天氣怎么樣conversationIdtest-001如果模型沒有調(diào)工具可能只會回答“我無法獲取實(shí)時(shí)天氣”。如果正確調(diào)用了WeatherTools.getWeatherByCity會返回“北京晴25℃”等相關(guān)信息。多輪會話驗(yàn)證curl http://localhost:8080/api/agent/chat?message我的手機(jī)號是13800138000幫我查一下最近訂單conversationIdtest-001 curl http://localhost:8080/api/agent/chat?message再看看第一單的物流conversationIdtest-001第二次提問依賴第一次的上下文。如果返回結(jié)果包含第一單的訂單號或狀態(tài)說明會話記憶已生效。判斷 Agent 是否正常不能只看是否返回結(jié)果還要看它是不是在正確的步驟調(diào)用了正確的工具。建議在本地開發(fā)時(shí)打開 Spring AI 的調(diào)試日志logging: level: org.springframework.ai: DEBUG這樣可以在控制臺看到完整的工具調(diào)用鏈模型請求 → 工具調(diào)用 → 工具返回 → 模型最終回答。如果失敗優(yōu)先看這幾個(gè)位置啟動階段MCP Server 是否連接成功Ollama 服務(wù)是否可用調(diào)用階段模型返回是否超時(shí)工具階段Tool方法是否有日志返回內(nèi)容是否被模型正確消費(fèi)。7. 常見問題與排查思路問題現(xiàn)象可能原因排查方式解決方案啟動報(bào)錯(cuò)說存在多個(gè) ChatModel Bean同時(shí)引入了多個(gè)模型 Starter自動配置創(chuàng)建了多個(gè)同類型 Bean查看啟動日志中 Bean 創(chuàng)建記錄用Qualifier或顯式配置指定使用的模型或封裝多模型路由服務(wù)請求時(shí)模型長時(shí)間無響應(yīng)模型 API Key 無效、網(wǎng)絡(luò)不通、本地 Ollama 沒有啟動先 curl 模型供應(yīng)商接口查看 Ollama 是否在 11434 端口監(jiān)聽修正 API Key / base-url啟動 Ollama 并確認(rèn)模型已拉取工具沒有被調(diào)用模型直接瞎回答Tool的描述不夠清晰或 system prompt 沒有強(qiáng)制要求檢查工具描述打開 DEBUG 日志確認(rèn)模型請求里是否包含 tool_calls重寫描述加入“必須使用工具回答”等約束結(jié)構(gòu)化輸出解析失敗拋類型轉(zhuǎn)換異常模型返回文本格式不匹配 Java 類型查看實(shí)際返回的 JSON簡化實(shí)體字段統(tǒng)一使用 String逐步增加字段MCP Server 連接失敗npx 未安裝、args 參數(shù)格式錯(cuò)誤、服務(wù)端地址不通在終端手動執(zhí)行npx -y modelcontextprotocol/server-filesystem /tmp/data檢查啟動日志 MCP 部分修正 args 寫法安裝 npx改用可訪問的 HTTP MCP Server多輪對話上下文丟失conversationId傳遞不一致或沒有配置持久化 ChatMemory檢查每次請求是否傳同一個(gè) id查看內(nèi)存存儲的日志用 Redis/數(shù)據(jù)庫實(shí)現(xiàn) ChatMemory統(tǒng)一會話 id 生成規(guī)則本地模型不支持 function callingOllama 拉取的模型版本較老或本身不支持工具調(diào)用查詢模型文檔確認(rèn)是否支持 tools更換支持 function calling 的模型例如qwen2.5系列這些問題是獨(dú)立開發(fā)者在完整跑通鏈路時(shí)最容易遇到的。嚴(yán)格按照排查路徑走大多數(shù)問題會在十分鐘內(nèi)定位。8. 最佳實(shí)踐與工程建議8.1 模型接入層統(tǒng)一路由隔離供應(yīng)商不要把模型供應(yīng)商的 SDK 直接散落在業(yè)務(wù)代碼里。所有模型訪問統(tǒng)一走ChatModel接口模型路由邏輯收斂到一個(gè)服務(wù)中。這樣才能做到“線上用商業(yè)模型、測試用本地模型”而不修改業(yè)務(wù)代碼。8.2 提示詞管理模板化、版本化System prompt 不要散落在 Controller 里。建議用提示詞模板文件配合 Spring 的Resource加載放到系統(tǒng)資源目錄下。提示詞實(shí)際上是需要評審和版本管理的“代碼”它直接影響模型行為質(zhì)量。8.3 工具安全最小權(quán)限原則Tool方法本質(zhì)上是把內(nèi)部能力暴露給外部模型調(diào)用。必須遵守最小權(quán)限原則工具方法只做自己該做的事不要聲明一個(gè)大而全的方法例如“執(zhí)行任意 SQL”。所有涉及數(shù)據(jù)庫、文件、外部 API 的工具都要做參數(shù)校驗(yàn)就像對待用戶輸入一樣。8.4 會話記憶生產(chǎn)環(huán)境不要用默認(rèn)內(nèi)存實(shí)現(xiàn)ChatClient的默認(rèn)記憶是內(nèi)存級的應(yīng)用重啟即丟失。生產(chǎn)環(huán)境應(yīng)該把ChatMemory替換為 Redis 或數(shù)據(jù)庫實(shí)現(xiàn)。會話 ID 必須由后端統(tǒng)一生成不要信任前端傳入的任意 key否則容易出現(xiàn)會話串臺問題。8.5 MCP 生命周期管理MCP stdio 服務(wù)本質(zhì)上是啟動一個(gè)子進(jìn)程它的生命周期需要被關(guān)注。不要在生產(chǎn)環(huán)境用 npx 臨時(shí)拉取 MCP Server盡量構(gòu)建成獨(dú)立服務(wù)用 HTTP 方式接入這樣便于監(jiān)控和擴(kuò)縮容。8.6 Agent 可觀測性Agent 是一個(gè)多步?jīng)Q策系統(tǒng)每一步都可能出錯(cuò)。生產(chǎn)環(huán)境必須記錄用戶問題原文模型是否發(fā)起了工具調(diào)用調(diào)用了哪個(gè)工具、參數(shù)是什么工具返回結(jié)果最終回答內(nèi)容。這些日志鏈路是排查問題的唯一依據(jù)。建議在Tool方法和 Agent 調(diào)用層都加上結(jié)構(gòu)化日志而不是只靠框架默認(rèn)日志。8.7 成本與限流多模型配置帶來成本控制能力的同時(shí)也帶來新的風(fēng)險(xiǎn)工具循環(huán)次數(shù)過多會導(dǎo)致 Token 消耗膨脹。建議給 Agent 調(diào)用設(shè)置超時(shí)時(shí)間、最大工具調(diào)用輪數(shù)并針對不同模型配置不同的限流策略。8.8 版本升級策略Spring AI 版本迭代快API 偶有調(diào)整。升級前先看官方遷移指南并且保留一個(gè)小范圍的兼容層。比如你寫一個(gè)AgentChatService包裝ChatClient未來內(nèi)部 API 變化時(shí)只改這個(gè)類業(yè)務(wù)層不受影響。9. 總結(jié)與后續(xù)學(xué)習(xí)方向Spring AI 2.0 給 Java 生態(tài)帶來的價(jià)值不只是一套可以調(diào)大模型的 Starter而是一整套符合 Spring 編程模型的 AI 應(yīng)用開發(fā)范式。本文把這條鏈路完整拆解了一遍多模型解決了供應(yīng)商鎖定問題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ù)庫服務(wù)。這三步做完Spring AI 2.0 的主要能力就算真正掌握。接下來值得深入的方向包括RAG 與向量數(shù)據(jù)庫的集成、Agent 與業(yè)務(wù)流程引擎的結(jié)合、基于 MCP Server 暴露公司內(nèi)部服務(wù)給 AI 應(yīng)用、以及多 Agent 協(xié)作模式。每一條都比單純調(diào)大模型接口更有工程價(jià)值也是 Java 工程師在 AI 時(shí)代不可替代的底牌。