随着AI技术的快速发展Java开发者面临着如何将传统后端开发与智能体技术结合的挑战。Spring AI 2.0作为Java生态中的AI开发框架为大模型集成、工具链管理和智能体构建提供了完整的解决方案。本文将带你从零开始掌握Spring AI 2.0的核心技术栈。1. Spring AI 2.0技术栈全景解析1.1 核心架构设计理念Spring AI 2.0采用模块化设计将AI能力无缝集成到Spring生态中。其核心架构包含以下关键组件Chat Model抽象层统一不同大模型的API调用接口Prompt工程模块提供模板化提示词管理Tool Calling框架标准化工具调用协议MCP集成Model Context Protocol的完整支持Agent运行时智能体执行引擎1.2 环境准备与版本规划在开始实战前需要配置以下开发环境!-- pom.xml 依赖配置 -- properties java.version17/java.version spring-ai.version2.0.0/spring-ai.version spring-boot.version3.2.0/spring-boot.version /properties dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-client-spring-boot-starter/artifactId /dependency /dependencies2. MCP协议深度实践2.1 MCP核心概念与价值Model Context ProtocolMCP是Anthropic提出的标准化协议旨在解决AI应用与外部工具集成的碎片化问题。MCP的核心价值体现在标准化接口统一工具发现、调用和结果返回格式协议无关性支持stdio、SSE等多种通信方式生态互操作性实现不同AI框架间的工具共享2.2 基于stdio的MCP Server实现下面通过天气查询服务演示MCP Server的完整实现// MCP Server主应用类 SpringBootApplication public class WeatherMcpServerApplication { public static void main(String[] args) { SpringApplication.run(WeatherMcpServerApplication.class, args); } Bean public ToolCallbackProvider weatherTools(WeatherService weatherService) { return MethodToolCallbackProvider.builder() .toolObjects(weatherService) .build(); } } // 天气服务工具实现 Service public class WeatherService { private final WebClient webClient; public WeatherService(WebClient.Builder webClientBuilder) { this.webClient webClientBuilder .baseUrl(https://api.open-meteo.com/v1) .build(); } Tool(description 根据经纬度获取天气预报信息) public WeatherResponse getWeatherForecast( ToolParameter(description 纬度例如39.9042) double latitude, ToolParameter(description 经度例如116.4074) double longitude) { return webClient.get() .uri(uriBuilder - uriBuilder .path(/forecast) .queryParam(latitude, latitude) .queryParam(longitude, longitude) .queryParam(current, temperature_2m,wind_speed_10m) .queryParam(timezone, auto) .build()) .retrieve() .bodyToMono(WeatherResponse.class) .block(); } Tool(description 获取空气质量信息) public AirQualityResponse getAirQuality( ToolParameter(description 纬度) double latitude, ToolParameter(description 经度) double longitude) { // 实现空气质量API调用 return new AirQualityResponse(latitude, longitude); } } // 响应DTO定义 public record WeatherResponse( double latitude, double longitude, CurrentWeather current, ListDailyForecast daily ) {} public record CurrentWeather( double temperature_2m, double wind_speed_10m, String time ) {}配置文件application.ymlspring: main: web-application-type: none ai: mcp: server: stdio: true name: weather-mcp-server version: 1.0.0 logging: level: org.springframework.ai: DEBUG2.3 基于SSE的MCP Server部署对于需要远程访问的场景SSE模式更适合生产环境!-- 添加WebFlux依赖 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-webflux-spring-boot-starter/artifactId /dependencySSE模式配置server: port: 8080 spring: ai: mcp: server: name: weather-mcp-server version: 1.0.03. MCP Client集成实战3.1 stdio模式客户端配置SpringBootApplication public class McpClientApplication { public static void main(String[] args) { SpringApplication.run(McpClientApplication.class, args); } Bean public CommandLineRunner demo(ChatClient.Builder chatClientBuilder, ToolCallbackProvider tools) { return args - { ChatClient chatClient chatClientBuilder .defaultTools(tools) .build(); String response chatClient.prompt(查询北京今天天气如何) .call() .content(); System.out.println(AI响应: response); }; } }客户端配置文件spring: ai: openai: api-key: ${OPENAI_API_KEY} mcp: client: stdio: servers-configuration: classpath:/mcp-servers-config.jsonMCP服务器配置JSON{ mcpServers: { weather: { command: java, args: [ -jar, /path/to/weather-mcp-server.jar ], env: { SPRING_AI_MCP_SERVER_STDIO: true } } } }3.2 SSE模式客户端配置spring: ai: mcp: client: sse: connections: weather-server: url: http://localhost:80804. Agent智能体开发实战4.1 智能体架构设计Spring AI中的Agent采用规划-执行-总结的三阶段架构Component public class TravelAgent { private final ChatClient planningClient; private final ChatClient executionClient; private final ChatClient finalizeClient; public TravelAgent(ChatModel chatModel, ToolCallbackProvider tools) { this.planningClient ChatClient.builder(chatModel) .defaultSystem( 你是一个旅行规划专家需要将复杂旅行需求分解为可执行步骤。 每个步骤应该明确具体要使用哪个工具。 ) .defaultTools(tools) .build(); this.executionClient ChatClient.builder(chatModel) .defaultSystem(执行具体的旅行规划步骤) .defaultTools(tools) .build(); } public String planTravel(String requirement) { // 规划阶段 String plan planningClient.prompt(requirement).call().content(); // 执行阶段 String result executionClient.prompt(plan).call().content(); return result; } }4.2 多工具协同的旅行规划AgentService public class TravelPlanningService { Tool(description 获取城市坐标信息) public Coordinates getCityCoordinates(ToolParameter(description 城市名称) String city) { // 调用地图API获取坐标 return mapService.getCoordinates(city); } Tool(description 计算两点间路线规划) public RoutePlan calculateRoute(ToolParameter(description 起点坐标) Coordinates start, ToolParameter(description 终点坐标) Coordinates end) { // 调用路线规划API return routingService.calculateRoute(start, end); } Tool(description 查询天气预报) public WeatherForecast getWeatherForecast(ToolParameter(description 坐标) Coordinates coord) { return weatherService.getForecast(coord); } }5. 源码深度剖析5.1 Tool Calling机制解析Spring AI的Tool Calling基于动态代理和反射机制实现// 核心调用逻辑简化版 public class ToolProxyFactory { public Object createToolProxy(Object target, ToolMethodRegistry registry) { return Proxy.newProxyInstance( target.getClass().getClassLoader(), target.getClass().getInterfaces(), (proxy, method, args) - { Tool toolAnnotation method.getAnnotation(Tool.class); if (toolAnnotation ! null) { // 构建工具调用请求 ToolCallRequest request buildToolCallRequest(method, args); return registry.invokeTool(request); } return method.invoke(target, args); } ); } }5.2 MCP协议通信流程MCP客户端与服务端的通信遵循JSON-RPC 2.0协议public class McpClientSession { public CompletableFutureMcpResponse sendRequest(McpRequest request) { // 序列化请求 String jsonRequest objectMapper.writeValueAsString(request); // 通过传输层发送stdio或SSE transport.send(jsonRequest); // 异步等待响应 return responseFuture; } }6. 生产环境最佳实践6.1 性能优化策略连接池配置spring: ai: mcp: client: sse: connection-pool: max-size: 20 max-idle-time: 30s acquire-timeout: 10s工具调用超时控制Configuration public class ToolTimeoutConfig { Bean public ToolCallbackProvider toolCallbackProvider() { return MethodToolCallbackProvider.builder() .toolExecutionTimeout(Duration.ofSeconds(30)) .build(); } }6.2 错误处理与重试机制Component public class ResilientMcpClient { Retryable(value {McpConnectionException.class}, maxAttempts 3, backoff Backoff(delay 1000)) public String callWithRetry(String prompt) { return chatClient.prompt(prompt) .call() .content(); } Recover public String recover(McpConnectionException e, String prompt) { log.warn(MCP服务调用失败使用降级策略, e); return 服务暂时不可用请稍后重试; } }6.3 安全与权限控制Aspect Component public class ToolSecurityAspect { Around(annotation(org.springframework.ai.tool.Tool)) public Object checkToolPermission(ProceedingJoinPoint joinPoint) throws Throwable { Method method ((MethodSignature) joinPoint.getSignature()).getMethod(); Tool tool method.getAnnotation(Tool.class); // 检查调用权限 if (!securityService.hasPermission(tool.value())) { throw new SecurityException(无权限调用工具: tool.value()); } return joinPoint.proceed(); } }7. 常见问题排查指南7.1 工具注册失败问题问题现象Tool registration failed: Multiple tools with the same name解决方案SpringBootApplication(exclude { SseHttpClientTransportAutoConfiguration.class }) public class Application { // 排除冲突的自动配置类 }7.2 MCP连接超时问题配置调整spring: ai: mcp: client: sse: timeout: connect: 10s read: 30s write: 10s7.3 内存泄漏排查使用JVM参数监控内存使用java -Xmx512m -XX:UseG1GC -XX:PrintGCDetails -jar your-app.jar8. 项目实战智能旅行助手8.1 需求分析与架构设计构建一个支持多数据源的旅行规划智能体集成天气、地图、交通等MCP服务。8.2 核心实现代码Service public class SmartTravelAgent { private final ChatClient chatClient; private final ListToolCallbackProvider toolProviders; public String planCompleteTravel(String userRequest) { // 多工具协同处理旅行规划 TravelPlan plan analyzeUserRequirements(userRequest); TravelResult result executeTravelPlan(plan); return generateTravelReport(result); } private TravelPlan analyzeUserRequirements(String request) { String analysis chatClient.prompt( 分析用户旅行需求并生成执行计划 ${request} 可用工具 - 天气查询 - 路线规划 - 景点推荐 - 酒店查询 .replace(${request}, request)) .call() .content(); return parseTravelPlan(analysis); } }8.3 集成测试与验证SpringBootTest class TravelAgentTest { Autowired private SmartTravelAgent travelAgent; Test void testCompleteTravelPlanning() { String request 我想下周从北京到上海旅行3天预算5000元; String result travelAgent.planCompleteTravel(request); assertThat(result).contains(行程规划); assertThat(result).contains(天气信息); assertThat(result).contains(路线建议); } }通过本教程的完整学习你将掌握Spring AI 2.0的核心技术栈具备构建企业级AI应用的能力。从基础的MCP协议理解到复杂的Agent系统开发每个环节都提供了可运行的代码示例和最佳实践建议。在实际项目开发中建议先从简单的工具集成开始逐步扩展到复杂的多Agent协作系统。关注性能监控和错误处理确保系统的稳定性和可维护性。随着Spring AI生态的不断发展这些技术将成为Java开发者必备的核心竞争力。
Spring AI 2.0实战：MCP协议与智能体开发完整指南
随着AI技术的快速发展Java开发者面临着如何将传统后端开发与智能体技术结合的挑战。Spring AI 2.0作为Java生态中的AI开发框架为大模型集成、工具链管理和智能体构建提供了完整的解决方案。本文将带你从零开始掌握Spring AI 2.0的核心技术栈。1. Spring AI 2.0技术栈全景解析1.1 核心架构设计理念Spring AI 2.0采用模块化设计将AI能力无缝集成到Spring生态中。其核心架构包含以下关键组件Chat Model抽象层统一不同大模型的API调用接口Prompt工程模块提供模板化提示词管理Tool Calling框架标准化工具调用协议MCP集成Model Context Protocol的完整支持Agent运行时智能体执行引擎1.2 环境准备与版本规划在开始实战前需要配置以下开发环境!-- pom.xml 依赖配置 -- properties java.version17/java.version spring-ai.version2.0.0/spring-ai.version spring-boot.version3.2.0/spring-boot.version /properties dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-client-spring-boot-starter/artifactId /dependency /dependencies2. MCP协议深度实践2.1 MCP核心概念与价值Model Context ProtocolMCP是Anthropic提出的标准化协议旨在解决AI应用与外部工具集成的碎片化问题。MCP的核心价值体现在标准化接口统一工具发现、调用和结果返回格式协议无关性支持stdio、SSE等多种通信方式生态互操作性实现不同AI框架间的工具共享2.2 基于stdio的MCP Server实现下面通过天气查询服务演示MCP Server的完整实现// MCP Server主应用类 SpringBootApplication public class WeatherMcpServerApplication { public static void main(String[] args) { SpringApplication.run(WeatherMcpServerApplication.class, args); } Bean public ToolCallbackProvider weatherTools(WeatherService weatherService) { return MethodToolCallbackProvider.builder() .toolObjects(weatherService) .build(); } } // 天气服务工具实现 Service public class WeatherService { private final WebClient webClient; public WeatherService(WebClient.Builder webClientBuilder) { this.webClient webClientBuilder .baseUrl(https://api.open-meteo.com/v1) .build(); } Tool(description 根据经纬度获取天气预报信息) public WeatherResponse getWeatherForecast( ToolParameter(description 纬度例如39.9042) double latitude, ToolParameter(description 经度例如116.4074) double longitude) { return webClient.get() .uri(uriBuilder - uriBuilder .path(/forecast) .queryParam(latitude, latitude) .queryParam(longitude, longitude) .queryParam(current, temperature_2m,wind_speed_10m) .queryParam(timezone, auto) .build()) .retrieve() .bodyToMono(WeatherResponse.class) .block(); } Tool(description 获取空气质量信息) public AirQualityResponse getAirQuality( ToolParameter(description 纬度) double latitude, ToolParameter(description 经度) double longitude) { // 实现空气质量API调用 return new AirQualityResponse(latitude, longitude); } } // 响应DTO定义 public record WeatherResponse( double latitude, double longitude, CurrentWeather current, ListDailyForecast daily ) {} public record CurrentWeather( double temperature_2m, double wind_speed_10m, String time ) {}配置文件application.ymlspring: main: web-application-type: none ai: mcp: server: stdio: true name: weather-mcp-server version: 1.0.0 logging: level: org.springframework.ai: DEBUG2.3 基于SSE的MCP Server部署对于需要远程访问的场景SSE模式更适合生产环境!-- 添加WebFlux依赖 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-webflux-spring-boot-starter/artifactId /dependencySSE模式配置server: port: 8080 spring: ai: mcp: server: name: weather-mcp-server version: 1.0.03. MCP Client集成实战3.1 stdio模式客户端配置SpringBootApplication public class McpClientApplication { public static void main(String[] args) { SpringApplication.run(McpClientApplication.class, args); } Bean public CommandLineRunner demo(ChatClient.Builder chatClientBuilder, ToolCallbackProvider tools) { return args - { ChatClient chatClient chatClientBuilder .defaultTools(tools) .build(); String response chatClient.prompt(查询北京今天天气如何) .call() .content(); System.out.println(AI响应: response); }; } }客户端配置文件spring: ai: openai: api-key: ${OPENAI_API_KEY} mcp: client: stdio: servers-configuration: classpath:/mcp-servers-config.jsonMCP服务器配置JSON{ mcpServers: { weather: { command: java, args: [ -jar, /path/to/weather-mcp-server.jar ], env: { SPRING_AI_MCP_SERVER_STDIO: true } } } }3.2 SSE模式客户端配置spring: ai: mcp: client: sse: connections: weather-server: url: http://localhost:80804. Agent智能体开发实战4.1 智能体架构设计Spring AI中的Agent采用规划-执行-总结的三阶段架构Component public class TravelAgent { private final ChatClient planningClient; private final ChatClient executionClient; private final ChatClient finalizeClient; public TravelAgent(ChatModel chatModel, ToolCallbackProvider tools) { this.planningClient ChatClient.builder(chatModel) .defaultSystem( 你是一个旅行规划专家需要将复杂旅行需求分解为可执行步骤。 每个步骤应该明确具体要使用哪个工具。 ) .defaultTools(tools) .build(); this.executionClient ChatClient.builder(chatModel) .defaultSystem(执行具体的旅行规划步骤) .defaultTools(tools) .build(); } public String planTravel(String requirement) { // 规划阶段 String plan planningClient.prompt(requirement).call().content(); // 执行阶段 String result executionClient.prompt(plan).call().content(); return result; } }4.2 多工具协同的旅行规划AgentService public class TravelPlanningService { Tool(description 获取城市坐标信息) public Coordinates getCityCoordinates(ToolParameter(description 城市名称) String city) { // 调用地图API获取坐标 return mapService.getCoordinates(city); } Tool(description 计算两点间路线规划) public RoutePlan calculateRoute(ToolParameter(description 起点坐标) Coordinates start, ToolParameter(description 终点坐标) Coordinates end) { // 调用路线规划API return routingService.calculateRoute(start, end); } Tool(description 查询天气预报) public WeatherForecast getWeatherForecast(ToolParameter(description 坐标) Coordinates coord) { return weatherService.getForecast(coord); } }5. 源码深度剖析5.1 Tool Calling机制解析Spring AI的Tool Calling基于动态代理和反射机制实现// 核心调用逻辑简化版 public class ToolProxyFactory { public Object createToolProxy(Object target, ToolMethodRegistry registry) { return Proxy.newProxyInstance( target.getClass().getClassLoader(), target.getClass().getInterfaces(), (proxy, method, args) - { Tool toolAnnotation method.getAnnotation(Tool.class); if (toolAnnotation ! null) { // 构建工具调用请求 ToolCallRequest request buildToolCallRequest(method, args); return registry.invokeTool(request); } return method.invoke(target, args); } ); } }5.2 MCP协议通信流程MCP客户端与服务端的通信遵循JSON-RPC 2.0协议public class McpClientSession { public CompletableFutureMcpResponse sendRequest(McpRequest request) { // 序列化请求 String jsonRequest objectMapper.writeValueAsString(request); // 通过传输层发送stdio或SSE transport.send(jsonRequest); // 异步等待响应 return responseFuture; } }6. 生产环境最佳实践6.1 性能优化策略连接池配置spring: ai: mcp: client: sse: connection-pool: max-size: 20 max-idle-time: 30s acquire-timeout: 10s工具调用超时控制Configuration public class ToolTimeoutConfig { Bean public ToolCallbackProvider toolCallbackProvider() { return MethodToolCallbackProvider.builder() .toolExecutionTimeout(Duration.ofSeconds(30)) .build(); } }6.2 错误处理与重试机制Component public class ResilientMcpClient { Retryable(value {McpConnectionException.class}, maxAttempts 3, backoff Backoff(delay 1000)) public String callWithRetry(String prompt) { return chatClient.prompt(prompt) .call() .content(); } Recover public String recover(McpConnectionException e, String prompt) { log.warn(MCP服务调用失败使用降级策略, e); return 服务暂时不可用请稍后重试; } }6.3 安全与权限控制Aspect Component public class ToolSecurityAspect { Around(annotation(org.springframework.ai.tool.Tool)) public Object checkToolPermission(ProceedingJoinPoint joinPoint) throws Throwable { Method method ((MethodSignature) joinPoint.getSignature()).getMethod(); Tool tool method.getAnnotation(Tool.class); // 检查调用权限 if (!securityService.hasPermission(tool.value())) { throw new SecurityException(无权限调用工具: tool.value()); } return joinPoint.proceed(); } }7. 常见问题排查指南7.1 工具注册失败问题问题现象Tool registration failed: Multiple tools with the same name解决方案SpringBootApplication(exclude { SseHttpClientTransportAutoConfiguration.class }) public class Application { // 排除冲突的自动配置类 }7.2 MCP连接超时问题配置调整spring: ai: mcp: client: sse: timeout: connect: 10s read: 30s write: 10s7.3 内存泄漏排查使用JVM参数监控内存使用java -Xmx512m -XX:UseG1GC -XX:PrintGCDetails -jar your-app.jar8. 项目实战智能旅行助手8.1 需求分析与架构设计构建一个支持多数据源的旅行规划智能体集成天气、地图、交通等MCP服务。8.2 核心实现代码Service public class SmartTravelAgent { private final ChatClient chatClient; private final ListToolCallbackProvider toolProviders; public String planCompleteTravel(String userRequest) { // 多工具协同处理旅行规划 TravelPlan plan analyzeUserRequirements(userRequest); TravelResult result executeTravelPlan(plan); return generateTravelReport(result); } private TravelPlan analyzeUserRequirements(String request) { String analysis chatClient.prompt( 分析用户旅行需求并生成执行计划 ${request} 可用工具 - 天气查询 - 路线规划 - 景点推荐 - 酒店查询 .replace(${request}, request)) .call() .content(); return parseTravelPlan(analysis); } }8.3 集成测试与验证SpringBootTest class TravelAgentTest { Autowired private SmartTravelAgent travelAgent; Test void testCompleteTravelPlanning() { String request 我想下周从北京到上海旅行3天预算5000元; String result travelAgent.planCompleteTravel(request); assertThat(result).contains(行程规划); assertThat(result).contains(天气信息); assertThat(result).contains(路线建议); } }通过本教程的完整学习你将掌握Spring AI 2.0的核心技术栈具备构建企业级AI应用的能力。从基础的MCP协议理解到复杂的Agent系统开发每个环节都提供了可运行的代码示例和最佳实践建议。在实际项目开发中建议先从简单的工具集成开始逐步扩展到复杂的多Agent协作系统。关注性能监控和错误处理确保系统的稳定性和可维护性。随着Spring AI生态的不断发展这些技术将成为Java开发者必备的核心竞争力。
生成 SQL 的方法：)
双梁正问题 【 torch 实战】（Python代码实现）)
