Spring AI React Agent对接阿里云服务实战指南

1. 项目概述：这不是一个“掌法”，而是一次Spring AI与阿里系基础设施的深度耦合实践

“降SpringAI阿里第9掌-或跃在渊-ReactAgent”——这个标题乍看像武侠小说里的秘籍名，但实际是当前Java生态中一个极具现实张力的技术实践代号。它不是玄学，而是指：在阿里云原生技术栈（含Maven私仓、RDS、OSS、短信API、SSL证书体系等）环境下，基于Spring AI框架构建具备React Agent能力的智能业务中枢，并完成从本地开发到云上部署、从提示词工程到真实业务闭环的全链路验证。核心关键词“SpringAI”“阿里”“ReactAgent”三者叠加，指向一个明确场景：企业级AI应用不再停留在Demo层面，必须能跑在阿里云这套被数百万开发者日日使用的生产级基础设施上，且要具备自主规划、工具调用、状态反思的Agent行为范式。

我带团队落地过3个Spring AI生产项目，其中两个就部署在阿里云ECS+RDS+OSS组合上。所谓“第9掌”，实则是我们踩坑总结出的第九类关键耦合点——当React Agent需要动态调用阿里云服务（比如用短信API发验证码、用OSS存用户上传的PDF、用RDS查风控规则）时，传统Spring Boot的自动配置机制会失效，必须手动注入阿里云SDK的Client实例，并将其包装成Spring AI可识别的Tool。而“或跃在渊”出自《周易》，这里特指Agent在调用外部服务前的临界决策状态：它得先判断“该不该调用”“调用哪个接口”“参数是否合规”，而不是盲目执行。这恰恰是React Agent区别于普通LLM调用的核心——它有“思考层”，而这一层必须与阿里云服务的鉴权模型（AccessKey+STS Token）、限流策略（QPS阈值）、错误码体系（如InvalidAccessKeyId.NotFound）深度对齐。如果你正在用Spring Boot接入阿里云服务，又想让LLM不只是“回答问题”而是“执行任务”，那这个标题背后的方法论，就是你绕不开的实战地图。

2. 整体设计思路：为什么必须放弃“纯Spring AI Demo思维”，转向阿里云原生架构

2.1 传统Spring AI示例的三大幻觉陷阱

几乎所有Spring AI官方文档和社区教程，都默认运行在本地H2数据库、Mock HTTP Client、内存缓存的“真空环境”里。这种设计在教学上很友好，但在阿里云生产环境里会立刻崩塌：

• 幻觉一：“依赖即插即用”
  Spring AI Starter（如spring-ai-openai-spring-boot-starter）会自动装配OpenAI Client，但阿里云所有服务（短信、OSS、RDS）的SDK都是独立Maven坐标，且版本强绑定阿里云Java SDK 5.x。若直接引入aliyun-java-sdk-core和spring-ai-*，Maven会因com.alibaba:fastjson与com.fasterxml.jackson.core:jackson-databind的版本冲突报错——这是我们在测试环境第一次启动就遇到的问题，耗时6小时才定位到是aliyun-java-sdk-core:4.5.33强制依赖fastjson:1.2.83，而Spring Boot 3.2默认用Jackson 2.15+。

• 幻觉二：“提示词万能”
  官方示例教你怎么写System Prompt让Agent调用工具，但没告诉你：阿里云短信API的SendSmsRequest要求PhoneNumbers字段必须是逗号分隔的字符串（如"13800138000,13900139000"），而LLM输出的JSON常是数组格式["13800138000","13900139000"]。若不加中间转换层，Agent会直接抛出com.aliyuncs.exceptions.ClientException: InvalidParameter.PhoneNumber——这个错误码在阿里云文档里藏在“常见错误”子章节第7页，根本不会出现在Spring AI的异常堆栈里。

• 幻觉三：“Agent=自动运维”
  React Agent的Plan阶段会生成工具调用序列，但阿里云RDS的DescribeDBInstances接口返回的是XML格式（默认），而Spring AI的JsonChatResponse解析器只认JSON。若不提前配置DefaultAcsClient的setAcceptFormat("JSON")，Agent拿到一堆XML标签后会陷入无限重试循环，CPU飙到100%却无任何日志输出——这是我们线上灰度时最惊险的一次事故，监控只看到线程池满，排查了4小时才发现是格式不匹配。

2.2 阿里云原生架构的四大刚性约束

要让React Agent在阿里云上“活下来”，必须接受这四条铁律：

1. 网络拓扑不可绕过
   阿里云ECS实例访问OSS Bucket需走内网Endpoint（如oss-cn-hangzhou-internal.aliyuncs.com），若Agent在application.yml里硬编码公网Endpoint，在VPC内会超时。而Spring AI的ChatClient不提供Endpoint动态切换钩子，必须通过@Bean覆盖OpenAiChatModel的RestTemplate，注入自定义HttpRequestInterceptor，在请求头里根据spring.profiles.active动态替换Host。

2. 鉴权模型必须显式声明
   阿里云所有服务都要求AccessKeyId+AccessKeySecret，但Spring AI的Tool接口只接收FunctionCallback，无法传递Credentials。解决方案是：将DefaultAcsClient声明为@Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE)，每次调用前用@Value("${aliyun.access-key-id}")注入，避免多线程下Credentials污染——这点在阿里云白皮书《AI Agent最佳实践》第3.2节有暗示，但没写具体代码。

3. 错误处理必须映射到业务语义
   阿里云短信API返回Code=OK表示成功，但Code=isp.RAM_PERMISSION_DENY表示权限不足。若Agent只捕获ClientException并打印堆栈，运营同学根本看不懂。我们必须在Tool实现里做二次封装：将Code转为ErrorCode.SMS_PERMISSION_DENIED，再映射到前端可读文案“短信发送权限未开通，请联系管理员”。

4. 资源生命周期必须与Spring容器对齐
   DefaultAcsClient内部维护HTTP连接池，若在@PostConstruct里初始化却不在@PreDestroy里关闭，应用重启时旧连接池会泄漏，最终触发阿里云RDS的Too many connections错误。而Spring AI的ToolRegistry不管理第三方Client生命周期，必须手写DisposableBean实现优雅关闭。

提示：别信“Spring Boot自动配置能搞定一切”。阿里云SDK的DefaultAcsClient是单例，但Spring AI的Tool是函数式接口，二者生命周期模型天然冲突。我们的解法是：用ObjectProvider<DefaultAcsClient>替代@Autowired，确保每次调用都获取新实例——这比全局单例更安全，实测QPS 200时内存泄漏下降92%。

3. 核心细节解析：React Agent与阿里云服务的七层耦合点

3.1 Maven依赖：如何在不引发版本地震的前提下引入阿里云全家桶

Spring Boot 3.2 + Spring AI 0.8.1 的依赖树里，spring-boot-starter-web已升级到Jackson 2.15.2，而阿里云SDK 4.5.33锁死fastjson:1.2.83。直接mvn clean compile必然失败。我们的解决方案不是降级Jackson（会破坏Spring AI的JSON Schema解析），而是用Maven的<exclusion>+<dependencyManagement>双保险：

<dependencyManagement> <dependencies> <!-- 强制统一fastjson版本，避免阿里云SDK拉低 --> <dependency> <groupId>com.alibaba</groupId> <artifactId>fastjson</artifactId> <version>2.0.44</version> </dependency> <!-- 阿里云SDK使用新版fastjson兼容包 --> <dependency> <groupId>com.aliyun</groupId> <artifactId>aliyun-java-sdk-core</artifactId> <version>4.5.33</version> <exclusions> <exclusion> <groupId>com.alibaba</groupId> <artifactId>fastjson</artifactId> </exclusion> </exclusions> </dependency> </dependencies> </dependencyManagement> <dependencies> <!-- Spring AI核心 --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> <version>0.8.1</version> </dependency> <!-- 阿里云短信SDK（注意：必须用5.x版，4.x不支持Spring Boot 3） --> <dependency> <groupId>com.aliyun</groupId> <artifactId>aliyun-java-sdk-dysmsapi</artifactId> <version>2.1.2</version> </dependency> <!-- 阿里云OSS SDK --> <dependency> <groupId>com.aliyun.oss</groupId> <artifactId>aliyun-sdk-oss</artifactId> <version>3.15.1</version> </dependency> <!-- 阿里云RDS SDK --> <dependency> <groupId>com.aliyun</groupId> <artifactId>aliyun-java-sdk-rds</artifactId> <version>3.1.4</version> </dependency> </dependencies>

关键点在于：aliyun-java-sdk-core的<exclusion>移除了fastjson，再通过<dependencyManagement>全局声明fastjson:2.0.44。为什么选2.0.44？因为它是fastjson2首个完全兼容Jackson注解的版本（@JsonProperty、@JsonIgnore都能识别），而Spring AI的JsonChatResponse大量使用这些注解。我们试过2.0.42，发现@JsonAlias不生效，导致Agent解析工具参数时字段名匹配失败。

注意：阿里云官网文档仍推荐4.x SDK，但其Maven坐标aliyun-java-sdk-*在5.x已改为alibabacloud-java-sdk-*。若你用的是阿里云新版控制台创建的AccessKey，必须用5.x SDK，否则SignatureDoesNotMatch错误无法解决——这是阿里云2023年10月起实施的签名算法升级，老SDK不支持SHA256withRSA。

3.2 工具注册：把阿里云API变成React Agent能理解的“语言”

Spring AI的Tool接口本质是FunctionCallback<T, R>，但阿里云SDK的SendSmsRequest是POJO，不能直接当函数用。必须做三层封装：

1. 参数标准化层：定义SmsToolInputPOJO，字段名与LLM提示词约定一致（如phoneNumbers而非PhoneNumber）
2. 协议适配层：将SmsToolInput转为SendSmsRequest，处理阿里云特有的字段（如SignName必须在控制台备案）
3. 错误归一化层：捕获ClientException，提取ErrorCode，转为Agent可处理的ToolExecutionResult

@Component public class SmsTool implements Tool { private final ObjectProvider<DefaultAcsClient> acsClientProvider; public SmsTool(ObjectProvider<DefaultAcsClient> acsClientProvider) { this.acsClientProvider = acsClientProvider; } @Override public String getName() { return "send_sms"; } @Override public String getDescription() { return "Send SMS to one or more phone numbers. Use this when user requests to send verification code or notification."; } @Override public String getParametersSchema() { return """ { "type": "object", "properties": { "phoneNumbers": { "type": "string", "description": "Comma-separated phone numbers, e.g., '13800138000,13900139000'" }, "templateCode": { "type": "string", "description": "SMS template code, e.g., 'SMS_123456789'" }, "templateParam": { "type": "object", "description": "JSON object for template variables, e.g., {\"code\":\"1234\"}" } }, "required": ["phoneNumbers", "templateCode"] } """; } @Override public FunctionCallback<SmsToolInput, String> getCallback() { return input -> { DefaultAcsClient client = acsClientProvider.getObject(); SendSmsRequest request = new SendSmsRequest(); request.setPhoneNumbers(input.getPhoneNumbers()); request.setTemplateCode(input.getTemplateCode()); request.setTemplateParam(JSON.toJSONString(input.getTemplateParam())); request.setSignName("您的签名"); // 签名必须在阿里云短信控制台备案 try { SendSmsResponse response = client.getAcsResponse(request); if ("OK".equals(response.getCode())) { return "SMS sent successfully. Message ID: " + response.getRequestId(); } else { throw new ToolExecutionException("SMS failed with code: " + response.getCode()); } } catch (ClientException e) { // 关键：将阿里云错误码映射为业务语义 switch (e.getErrCode()) { case "InvalidAccessKeyId.NotFound": return "SMS service is not configured. Please check AccessKey."; case "isv.BUSINESS_LIMIT_CONTROL": return "SMS quota exceeded. Please contact admin."; default: return "SMS failed: " + e.getErrMsg(); } } }; } }

这里有个易忽略的细节：request.setTemplateParam()必须传JSON字符串，而不是Map对象。因为阿里云API文档明确要求TemplateParam是String类型，若传Map，SDK会调用toString()生成{code=1234}，而API期望的是{"code":"1234"}——这个差异会导致TemplateParameterError错误，且错误码是isv.TEMPLATE_MISSING_PARAMETERS，根本看不出是JSON格式问题。

3.3 提示词工程：让Agent理解“阿里云语境”而非通用语境

React Agent的System Prompt不能只写“你是一个助手”，必须注入阿里云特有的业务规则。我们最终采用的Prompt结构包含四个区块：

# 角色设定 你是一个部署在阿里云上的智能业务代理，负责协调阿里云服务完成用户请求。你的所有操作都受限于阿里云服务的权限、配额和地域限制。 # 工具能力 - send_sms: 发送短信，需提供phoneNumbers（逗号分隔字符串）、templateCode（短信模板CODE）、templateParam（JSON字符串） - upload_to_oss: 上传文件到OSS，需提供bucketName（存储空间名）、objectKey（文件路径）、content（Base64编码内容） - query_rds: 查询RDS数据库，需提供dbInstanceId（实例ID）、sql（SQL语句，仅SELECT） # 阿里云约束 - 所有手机号必须是中国大陆号码，11位数字，以1开头 - OSS bucketName必须小写字母+数字+短横线，长度3-63字符 - RDS查询SQL必须以SELECT开头，禁止UPDATE/DELETE - 每次调用最多3个工具，避免并发超限 # 输出格式 严格按JSON格式输出Plan，例如： { "steps": [ { "tool": "send_sms", "toolInput": {"phoneNumbers":"13800138000","templateCode":"SMS_123456789","templateParam":"{\"code\":\"1234\"}"} } ] }

这个Prompt的关键创新点在于“阿里云约束”区块。我们测试发现，若不显式声明“手机号必须11位”，LLM会生成138-0013-8000这种带分隔符的格式，导致短信API拒绝；若不强调“OSS bucketName必须小写”，Agent可能生成MyBucket，而阿里云会返回InvalidBucketName错误。这些约束不是LLM常识，必须作为先验知识注入。

实操心得：不要把约束写在“角色设定”里。我们最初把“手机号规则”放在第一段，结果Agent在Plan阶段就生成了错误格式。后来移到“阿里云约束”独立区块，并用-符号列表化，LLM解析准确率从68%提升到94%——这说明结构化提示比段落式提示更有效。

3.4 环境配置：如何让application.yml同时满足Spring AI和阿里云需求

阿里云服务的Endpoint、Region、Credentials不能写死在代码里，必须通过配置中心管理。但Spring AI的ChatClient和阿里云SDK的DefaultAcsClient加载配置的路径不同，需统一到application.yml：

spring: ai: openai: api-key: ${OPENAI_API_KEY:sk-xxx} base-url: https://api.openai.com/v1/ chat: options: model: gpt-4-turbo temperature: 0.3 aliyun: access-key-id: ${ALIYUN_ACCESS_KEY_ID} access-key-secret: ${ALIYUN_ACCESS_KEY_SECRET} region-id: cn-hangzhou oss: endpoint: oss-cn-hangzhou-internal.aliyuncs.com # 内网Endpoint bucket-name: my-app-bucket sms: sign-name: "我的应用" template-code: SMS_123456789 rds: db-instance-id: rm-xxxxxx # 配置文件激活profile，决定用内网还是公网Endpoint spring: profiles: active: aliyun-prod

重点在于oss.endpoint的配置。阿里云文档说“内网Endpoint更快更安全”，但没告诉你：若ECS和OSS不在同一地域（Region），内网Endpoint会解析失败。我们的做法是：在application-aliyun-prod.yml里写死oss-cn-hangzhou-internal，在application-aliyun-test.yml里用oss-cn-beijing.aliyuncs.com（公网）。这样测试环境走公网，生产环境走内网，无需改代码。

注意：spring.profiles.active必须设为aliyun-prod，否则@Value("${aliyun.oss.endpoint}")会取不到值。我们曾因忘记激活profile，导致Agent上传文件时超时，日志里只显示java.net.UnknownHostException: oss-cn-hangzhou-internal.aliyuncs.com，排查了2小时才发现是profile没生效。

3.5 安全加固：避免AccessKey泄露的五道防线

把ALIYUN_ACCESS_KEY_ID明文写在application.yml里是高危操作。我们采用五层防护：

1. KMS加密：用阿里云KMS对AccessKey密文加密，部署时用kms decrypt解密后注入环境变量
2. RAM最小权限：为Agent创建独立RAM用户，只授予AliyunDysmsReadOnlyAccess、AliyunOSSFullAccess（限定Bucket）、AliyunRDSReadOnlyAccess（限定DB）
3. STS临时凭证：生产环境不用长期AccessKey，改用AssumeRole获取STS Token，有效期2小时
4. 配置中心脱敏：Nacos配置中心里，ALIYUN_ACCESS_KEY_SECRET字段设为encrypted，客户端解密后才注入Spring
5. 日志过滤：自定义LoggingFilter，拦截所有含accessKeyId、accessKeySecret的HTTP Header，替换为***

其中第3点最关键。我们用StsClient代替DefaultAcsClient：

@Bean @Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE) public DefaultAcsClient stsAcsClient() { // 从环境变量读取RAM Role ARN String roleArn = System.getenv("ALIYUN_ROLE_ARN"); String roleSessionName = "spring-ai-agent-" + UUID.randomUUID().toString(); AssumeRoleRequest request = new AssumeRoleRequest(); request.setRoleArn(roleArn); request.setRoleSessionName(roleSessionName); request.setDurationSeconds(7200); // 2小时 StsClient stsClient = new StsClient( new DefaultProfile("cn-hangzhou", System.getenv("ALIYUN_ACCESS_KEY_ID"), System.getenv("ALIYUN_ACCESS_KEY_SECRET")) ); AssumeRoleResponse response = stsClient.getAcsResponse(request); return new DefaultAcsClient( new DefaultProfile("cn-hangzhou", response.getCredentials().getAccessKeyId(), response.getCredentials().getAccessKeySecret(), response.getCredentials().getSecurityToken()) ); }

这样即使ECS被入侵，攻击者也只能拿到2小时有效的临时凭证，且权限受RAM策略限制。我们实测过，用此方案后，阿里云安全中心的“高危凭证泄露”告警下降100%。

3.6 监控埋点：让Agent行为在阿里云ARMS里可追踪

React Agent的调用链路必须接入阿里云ARMS（应用实时监控服务），否则故障时无法定位是LLM出错还是OSS超时。我们在Tool执行前后打点：

@Component public class TracedSmsTool extends SmsTool { private final Tracer tracer; // ARMS Tracer public TracedSmsTool(ObjectProvider<DefaultAcsClient> acsClientProvider, Tracer tracer) { super(acsClientProvider); this.tracer = tracer; } @Override public FunctionCallback<SmsToolInput, String> getCallback() { return input -> { Span span = tracer.buildSpan("sms-tool").start(); try (Scope scope = tracer.scopeManager().activate(span)) { // 设置Tag，便于ARMS筛选 span.setTag("sms.phoneCount", input.getPhoneNumbers().split(",").length); span.setTag("sms.templateCode", input.getTemplateCode()); String result = super.getCallback().apply(input); span.setTag("result", "success"); return result; } catch (Exception e) { span.setTag("result", "error"); span.setTag("error.type", e.getClass().getSimpleName()); throw e; } finally { span.finish(); } }; } }

关键点在于span.setTag()必须用ARMS预定义的Tag名（如result、error.type），否则在ARMS控制台里无法聚合分析。我们参考了ARMS官方文档《自定义Span最佳实践》第5.3节，确认这些Tag名是内置索引字段。

3.7 灰度发布：如何用阿里云EDAS实现Agent能力渐进式上线

React Agent上线不能一刀切，必须灰度。我们用阿里云EDAS（企业级分布式应用服务）的“金丝雀发布”功能：

1. 在EDAS控制台创建两个应用分组：agent-v1（旧版，无React Agent）、agent-v2（新版，含React Agent）
2. 配置路由规则：header("x-agent-version") == "v2"的流量打到agent-v2
3. 前端SDK在发起请求时，对特定用户（如UID尾号为0-2）注入x-agent-version: v2
4. EDAS实时监控两组的5xx error rate、avg response time，当agent-v2的错误率<0.1%且响应时间<800ms，自动将流量比例从10%提升到100%

这个方案的优势是：无需改代码，纯配置驱动。我们灰度期间发现agent-v2在高并发下OSS上传失败率升高，EDAS的“慢SQL分析”功能立刻定位到是upload_to_oss工具未设置putObjectRequest.setMetadata()，导致OSS默认用STANDARD存储类型，小文件上传延迟高。加上setStorageClass(StorageClassType.IA)后，P99延迟从1200ms降到320ms。

4. 实操全流程：从零搭建一个可运行的阿里云React Agent

4.1 环境准备：三台机器的最小可行配置

我们用三台阿里云ECS（CentOS Stream 9）搭建最小验证环境：

注意：ECS-A和ECS-B必须在同一VPC内，否则RDS连接会超时。我们一开始把ECS-B建在经典网络，花了3小时才意识到必须迁移到VPC——这是阿里云新手最常见的网络配置坑。

4.2 初始化Spring Boot项目：用Spring Initializr定制骨架

访问 start.spring.io ，选择：

• Project: Maven
• Spring Boot: 3.2.5
• Dependencies:
  • Spring Web
  • Spring Boot DevTools
  • Lombok
  • Spring Data JPA
  • MySQL Driver
  • Spring AI OpenAI Starter（手动添加org.springframework.ai:spring-ai-openai-spring-boot-starter:0.8.1）

生成ZIP后解压，用IDEA打开。关键修改：

1. pom.xml加入阿里云SDK依赖（见3.1节）
2. src/main/resources/application.properties改为application.yml（YAML格式更易读）
3. 创建config/AliyunConfig.java，用@ConfigurationProperties(prefix="aliyun")绑定配置

4.3 构建第一个Tool：短信发送能力

创建tool/SmsTool.java（代码见3.2节），然后在Application.java里注册：

@SpringBootApplication public class SpringAiAgentApplication { public static void main(String[] args) { SpringApplication.run(SpringAiAgentApplication.class, args); } @Bean public ToolRegistry toolRegistry(List<Tool> tools) { ToolRegistry registry = new ToolRegistry(); tools.forEach(registry::addTool); return registry; } }

启动应用，访问http://localhost:8080/actuator/health确认服务正常。此时Agent还不能工作，因为缺少ChatClient。

4.4 集成ChatClient：配置OpenAI并注入Tool

在application.yml里配置OpenAI（见3.4节），然后创建config/ChatConfig.java：

@Configuration public class ChatConfig { @Bean public ChatClient chatClient(ToolRegistry toolRegistry) { return ChatClient.builder() .chatModel(chatModel()) // OpenAI模型 .toolRegistry(toolRegistry) .build(); } @Bean public ChatModel chatModel() { return new OpenAiChatModel( new OpenAiApi( System.getenv("OPENAI_API_KEY"), "https://api.openai.com/v1/" ), OpenAiChatOptions.builder() .model("gpt-4-turbo") .temperature(0.3) .build() ); } }

此时启动应用，ChatClient会自动装配SmsTool。你可以用curl测试：

curl -X POST http://localhost:8080/chat \ -H "Content-Type: application/json" \ -d '{ "messages": [ {"role": "user", "content": "给13800138000发验证码1234"} ] }'

如果返回{"content":"SMS sent successfully..."}，说明Tool链路通了。

4.5 实现React Agent：编写Orchestrator协调逻辑

创建service/ReactAgentService.java：

@Service public class ReactAgentService { private final ChatClient chatClient; public ReactAgentService(ChatClient chatClient) { this.chatClient = chatClient; } public String execute(String userQuery) { // Step 1: 生成Plan（调用哪些Tool） String planJson = chatClient.call( ChatRequest.builder() .messages(List.of( new SystemMessage(getSystemPrompt()), new UserMessage(userQuery) )) .build() ).getResult().getOutput().getContent(); // Step 2: 解析Plan JSON，执行Tool JsonNode planNode = new ObjectMapper().readTree(planJson); ArrayNode steps = (ArrayNode) planNode.get("steps"); StringBuilder result = new StringBuilder(); for (JsonNode step : steps) { String toolName = step.get("tool").asText(); JsonNode toolInput = step.get("toolInput"); // 反射调用对应Tool Tool tool = getToolByName(toolName); String toolResult = tool.invoke(toolInput.toString()); result.append(toolResult).append("\n"); } return result.toString(); } private String getSystemPrompt() { return """ # 角色设定... # 工具能力... # 阿里云约束... # 输出格式... """; } private Tool getToolByName(String name) { // 从Spring容器获取Tool Bean return applicationContext.getBean(name + "Tool", Tool.class); } }

这个execute()方法就是React Agent的“大脑”。它先让LLM生成Plan，再解析执行，最后汇总结果。注意：tool.invoke()传入的是JSON字符串，不是POJO——因为LLM输出的toolInput是原始JSON，必须保持格式一致。

4.6 对接阿里云服务：RDS和OSS的Tool实现

RdsTool.java要点：

• query_rds工具必须校验SQL以防止注入：用正则^SELECT\\s+.*$匹配
• DescribeDBInstancesRequest需设置setRegionId("cn-hangzhou")
• 查询结果用JSONArray.fromObject()转JSON，避免JSONObject的toString()丢失类型信息

OssTool.java要点：

• upload_to_oss的content参数必须是Base64字符串，PutObjectRequest要求InputStream
• 用new ByteArrayInputStream(Base64.getDecoder().decode(content))转换
• 必须设置putObjectRequest.setMetadata(new ObjectMetadata())，否则OSS默认Content-Type为binary/octet-stream

4.7 全链路测试：用真实业务场景验证

我们设计了一个典型场景：“用户注册时，发送短信验证码、上传身份证照片、查询风控名单”。

测试步骤：

1. 前端调用/register接口，传参{"phone":"13800138000","idCardImage":"base64..."}
2. ReactAgentService.execute()生成Plan：

   { "steps": [ {"tool":"send_sms","toolInput":{"phoneNumbers":"13800138000",...}}, {"tool":"upload_to_oss","toolInput":{"bucketName":"spring-ai-demo",...}}, {"tool":"query_rds","toolInput":{"sql":"SELECT * FROM risk_list WHERE phone='13800138000'"}} ] }

3. Agent依次执行三个Tool，返回结果：

   SMS sent successfully. Message ID: xxx File uploaded to OSS: https://spring-ai-demo.oss-cn-hangzhou.aliyuncs.com/id/xxx.jpg Risk check passed. No blacklist record.

整个流程在2.3秒内完成，P95延迟<3秒，符合生产要求。

5. 常见问题与排查技巧：我们踩过的27个坑及解决方案

5.1 Maven依赖冲突：fastjson与Jackson的战争

现象：mvn clean compile报错java.lang.NoSuchMethodError: com.fasterxml.jackson.databind.ObjectMapper.readValue(Ljava/lang/String;Ljava/lang/Class;)Ljava/lang/Object;

根因：aliyun-java-sdk-core:4.5.33依赖fastjson:1.2.83，而spring-boot-starter-web:3.2.5用jackson-databind:2.15.2，二者ObjectMapper类冲突。

解决方案：

1. 在pom.xml的<dependencyManagement>里强制fastjson:2.0.44
2. 排除aliyun-java-sdk-core的fastjson依赖
3. 添加fastjson2-jackson桥接器：

   <dependency> <groupId>com.alibaba.fastjson2</groupId> <artifactId>fastjson2-jackson</artifactId> <version>2.0.44</version> </dependency>

验证命令：mvn dependency:tree | grep fastjson，应只显示fastjson2。

5.2 OSS上传失败：NoSuchBucket错误

现象：upload_to_oss工具抛出com.aliyun.oss.OSSException: The specified bucket does not exist.

根因：Bucket名称大小写敏感，且必须与OSS控制台创建的名称完全一致（包括中划线位置）。

排查步骤：

1. 登录OSS控制台，确认Bucket名称为spring-ai-demo（非Spring-Ai-Demo）
2. 检查application.yml里aliyun.oss.bucket-name是否为小写
3. 用curl -I https://spring-ai-demo.oss-cn-hangzhou.aliyuncs.com测试Endpoint连通性

修复方案：在OssTool里加校验：

if (!bucketName.matches("^[a-z0-9\\-]{3,63}$")) { throw new IllegalArgumentException("Bucket name must