Agent 的核心工程原则很简单：模型负责推理，应用负责执行，平台负责治理。

分享日期：2026-06-16
主题：Java / Spring AI 2.0.0 / Spring Boot 4.1 / Spring Cloud / Tool Calling / MCP / Agent 治理
版本背景：Spring AI 2.0.0 GA 于 2026-06-12 发布；Spring Boot 4.1.0 于 2026-06-10 发布；Spring Cloud 2025.1.2 于 2026-06-12 发布

1. 为什么今天值得关注

截至 2026-06-16，Spring AI GitHub Releases 已经把 Spring AI 2.0.0 GA 标记为 Latest。这个版本不只是把 RC 推成正式版，它释放了一个更清晰的信号：Java 后端团队可以开始把 Agent 应用当作普通生产应用来设计，而不是只停留在 Demo、脚本和提示词实验。

这次 GA 的几个信息点很集中：

• Spring AI 2.0.0 GA 发布于 2026-06-12。
• 官方 2.0.0 参考文档已经成为稳定文档入口。
• Release notes 明确列出升级到 MCP SDK 2.0.0。
• Release notes 明确列出升级到 Spring Boot 4.1.0。
• 2.0 升级说明把 Tool Calling、Advisor、Chat Memory、配置属性、MCP 传输包迁移等破坏性变化集中整理出来。

一句话：Spring AI 2.0 GA 的热点不在于“又多接了几个模型”，而在于 Agent 工程边界开始稳定。模型调用、工具调用、MCP、记忆、RAG、观测、配置和升级路径，都开始进入 Java / Spring 团队熟悉的治理方式。

2. 版本坐标：别把 AI 栈孤立升级

今天看 Spring AI 2.0，不能只看一个依赖版本。它正好踩在三条线交汇处：

• Spring AI 2.0.0 GA：Agent、Tool Calling、MCP、RAG、Chat Memory 的应用层框架。
• Spring Boot 4.1.0：应用配置、自动装配、观测、HTTP client、安全默认值、AOT 等底座。
• Spring Cloud 2025.1.2：Gateway、Config、Vault、OpenFeign、Stream、Kubernetes 等分布式系统治理组件。

对团队来说，更合理的理解是：

Spring Cloud：治理入口、配置、网关、服务连接、密钥、消息
Spring Boot ：应用运行底座、自动装配、观测、HTTP 与安全策略
Spring AI   ：模型调用、工具编排、MCP、RAG、记忆与评估

如果你的 Agent 只是一个内部知识库问答，可以先在单个 Spring Boot 应用里升级验证。如果它要调用订单、库存、审批、CRM、工单、搜索、外部 SaaS，就应该把 Spring Cloud Gateway、Config、Vault、CircuitBreaker、Kubernetes 和日志链路一起纳入设计。

Agent 不是一个“更聪明的 Controller”。它会把应用主动访问外部系统、执行业务动作、读取上下文、保存对话历史的比例显著放大。升级 Spring AI 的同时，不治理出站调用、工具权限和配置边界，风险会跟着能力一起放大。

3. 2.0 GA 真正改变了什么

Spring AI 2.0 的核心变化可以压缩成四句话：

1. ChatClient 更应该成为应用侧调用模型的入口。
2. 工具执行从各个模型实现里收回到 ToolCallingAdvisor / ToolCallingManager 这条应用可控链路。
3. MCP 不再只是外部生态协议，而是通过 Spring Boot starters 和注解体系进入 Spring 应用。
4. 记忆、工具搜索、结构化输出、配置属性和 JSON 工具类都经历了更明确的 API 收敛。

这背后的工程方向很重要：模型可以提出“我要调用哪个工具、参数是什么”，但真正执行动作的是 Java 应用。鉴权、参数校验、幂等、审计、超时、重试、降级、脱敏、速率限制，都不应该交给模型。

官方 Tool Calling 文档也强调了这个边界：模型只请求工具调用并给出参数，应用负责执行工具并把结果返回给模型。这个安全边界是 Agent 生产化的底线。

4. 推荐架构：把 Agent 拆成三层

```mermaid
flowchart LR
    User[用户 / 业务系统] --> Gateway[Spring Cloud Gateway]
    Gateway --> App[Spring Boot Agent API]
    App --> ChatClient[Spring AI ChatClient]
    ChatClient --> Advisors[Advisors: Memory / RAG / Guardrails]
    Advisors --> Vector[(Vector Store)]
    Advisors --> Model[Chat Model]
    Model --> ToolAdvisor[ToolCallingAdvisor]
    ToolAdvisor --> LocalTools[本地业务工具]
    ToolAdvisor --> McpClient[MCP Client]
    McpClient --> McpServers[MCP Servers]
    McpServers --> Systems[数据库 / API / 文件 / SaaS]
    LocalTools --> Audit[(审计与指标)]
    McpClient --> Audit
```

这张图的重点不是组件多，而是职责边界清楚：

• Gateway 层负责入口鉴权、租户识别、限流、路径隔离和外部调用入口收敛。
• Agent API 层负责业务语义、用户上下文、会话 ID、权限上下文和响应契约。
• Spring AI 层负责编排模型、Advisor、工具、MCP 和记忆。
• Tool / MCP 层负责对真实系统的受控访问。
• Audit / Observability 负责记录“模型为什么调用工具、调用了什么、结果是什么、成本是多少”。

不要让模型绕过应用直接访问数据库、文件系统或内部 HTTP API。Agent 应用的稳定性来自“模型负责推理，应用负责执行”这个分工。

5. Tool Calling：从自动执行变成可治理执行

Spring AI 2.0 升级说明里，一个关键变化是移除 internalToolExecutionEnabled。之前一些代码会在模型级别打开或关闭内部工具执行；2.0 以后更推荐通过 ChatClient 和 ToolCallingAdvisor 管理工具调用链路。

最小示例：

import java.math.BigDecimal;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;

@Component
class OrderTools {

    @Tool(description = "Query an order summary by order id. Use only for authenticated users.")
    OrderSummary findOrder(
            @ToolParam(description = "Business order id, not database primary key") String orderId) {
        // 真实项目里这里必须做租户、用户、字段级权限和审计
        return new OrderSummary(orderId, "PAID", new BigDecimal("199.00"));
    }
}

record OrderSummary(String orderId, String status, BigDecimal amount) {
}

@Component
class AgentService {

    private final ChatClient chatClient;
    private final OrderTools orderTools;

    AgentService(ChatClient.Builder builder, OrderTools orderTools) {
        this.chatClient = builder
                .defaultSystem("""
                        You are an internal service assistant.
                        Never call tools unless the user request is related to the current authenticated business context.
                        """)
                .build();
        this.orderTools = orderTools;
    }

    String answer(String question) {
        return chatClient.prompt()
                .user(question)
                .tools(orderTools)
                .call()
                .content();
    }
}

这段代码不是为了展示“怎么让模型查订单”，而是为了提醒三件事：

• @Tool 不是权限注解，不能替代业务鉴权。
• 工具描述要说明适用场景和参数语义，减少模型误用。
• 工具内部必须按普通后端接口标准做鉴权、审计、幂等和异常处理。

生产环境建议给工具分级：

工具类型	示例	默认策略
只读公开信息	查公开文档、查产品说明	可自动调用
只读内部信息	查订单、查库存、查客户状态	需要用户上下文和字段脱敏
低风险动作	创建草稿、生成摘要、创建待确认工单	可执行但必须审计
高风险动作	退款、审批、发货、改价、删除数据	人工确认或业务工作流确认
外部网络访问	抓取 URL、调用 SaaS、Webhook	域名白名单、SSRF 防护、超时和限流

6. Tool Search：工具多了以后别全塞给模型

Spring AI 2.0 升级说明里新增了 spring-ai-starter-tool-search-advisor 和 spring.ai.chat.client.tool-search-advisor.enabled=true 配置。它的价值很直接：当工具数量变多时，不要每次把所有工具定义都发给模型，而是按关键词、Lucene 或向量检索挑出最相关的工具。

示例配置：

spring.ai.chat.client.tool-search-advisor.enabled=true
spring.ai.chat.client.tool-search-advisor.tool-index-type=regex

Maven 依赖：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-tool-search-advisor</artifactId>
</dependency>

这个能力对企业 Agent 很重要。一个真实业务系统里，工具很快会从 5 个变成 50 个甚至 500 个。全量暴露工具会带来四类问题：

• 提示词变长，调用成本上升。
• 模型选择工具的干扰项变多。
• 工具描述泄露内部业务能力。
• 不同租户、角色、业务线之间的工具边界变模糊。

更稳的做法是“三段式过滤”：

1. 先按租户、用户角色、业务场景过滤可用工具集合。
2. 再用 Tool Search 选择与本次请求最相关的工具。
3. 最后在工具执行时再次做业务鉴权和审计。

不要把 Tool Search 当权限系统。它解决的是“相关性”和“上下文长度”，不是访问控制。

7. MCP：让工具生态标准化，但仍要做网关治理

MCP 的价值是把外部工具、资源、提示模板和服务能力标准化。Spring AI 2.0 文档已经把 MCP 放在参考文档的一等入口，并提供客户端、服务端 Boot starters 以及 MCP 注解能力。

常见依赖方向：

<!-- Agent 应用作为 MCP Client，连接外部或内部 MCP Server -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>

<!-- Spring Boot 应用暴露 MCP Server，给其他 Agent 使用 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>

MCP Server 示例方向：

import org.springframework.ai.mcp.annotation.McpTool;
import org.springframework.stereotype.Component;

@Component
class InventoryMcpTools {

    @McpTool(description = "Find available stock for a SKU in the current tenant")
    StockView findStock(String sku) {
        // 这里仍然需要租户隔离、权限校验、缓存、审计
        return new StockView(sku, 42);
    }
}

record StockView(String sku, int available) {
}

工程上要注意：MCP 让工具接入更标准，但不会自动解决治理问题。尤其是跨进程、跨服务、跨团队的 MCP Server，更应该通过 Spring Cloud 能力统一管理：

• Gateway：统一入口、鉴权、限流、路径隔离。
• Config：区分 dev、test、prod 的 MCP server 列表和工具开关。
• Vault：管理模型 key、MCP server token、外部 SaaS 凭据。
• CircuitBreaker：限制异常 MCP server 对主链路的影响。
• Kubernetes：隔离高风险工具运行环境。
• Observability：记录工具发现、工具调用、失败率、耗时和 token 成本。

对 MCP 的推荐落地方式是先内后外：

1. 先把内部只读能力 MCP 化，例如文档检索、配置查询、库存查询。
2. 再暴露低风险动作，例如创建草稿、创建待处理任务。
3. 最后才考虑高风险动作，而且必须走业务确认流程。

8. Chat Memory：先修表结构，再谈长期记忆

Spring AI 2.0 升级说明提到 JdbcChatMemoryRepository schema 新增 sequence_id 字段，用于稳定同一会话里的消息顺序。这个变化看起来像数据库小改动，但对 Agent 很关键。

多轮 Agent 对话里，消息顺序一旦不稳定，可能出现非常隐蔽的问题：

• 模型把旧工具结果当成新结果。
• 用户撤销后的上下文仍被保留。
• 工具调用消息和最终回答顺序错乱。
• 审计时无法还原模型为什么执行某个动作。

升级前建议做三件事：

ALTER TABLE SPRING_AI_CHAT_MEMORY ADD COLUMN sequence_id BIGINT;

-- 按 conversation_id 和原 timestamp 回填顺序，具体 SQL 需要按数据库方言调整
-- PostgreSQL 可参考官方 upgrade notes 里的 ROW_NUMBER() 写法

CREATE INDEX SPRING_AI_CHAT_MEMORY_CONVERSATION_ID_SEQUENCE_ID_IDX
    ON SPRING_AI_CHAT_MEMORY(conversation_id, sequence_id);

更重要的是区分两类记忆：

• 短期会话记忆：用于本次对话连续性，可以过期、可重建。
• 长期业务记忆：影响用户画像、偏好、策略、审批和推荐，必须有明确授权、可解释和可删除机制。

不要把所有对话都无差别写入长期记忆。Agent 的“记住”能力一旦进入生产系统，就会变成数据治理问题。

9. Spring Boot 4.1：Agent 应用要吃到 Boot 的治理红利

Spring AI 2.0 GA 升级到 Spring Boot 4.1.0，这让 Agent 应用可以继续复用 Boot 的成熟能力。实践里建议优先打通这些点：

• 配置属性：模型、温度、超时、工具开关、MCP server 地址都走配置，不写死在代码里。
• Profile：本地、测试、生产使用不同模型、不同工具集合和不同 MCP server。
• Actuator：暴露健康检查、指标和配置审计入口。
• Micrometer：统计模型调用、工具调用、失败率、延迟、token 成本。
• HTTP client 安全策略：对 URL 抓取、Webhook、SaaS API 做 SSRF 防护和出站白名单。
• AOT / Native：如果工具大量依赖反射注解，提前验证 native image 的反射配置。

示例配置方向：

spring:
  ai:
    chat:
      client:
        tool-calling:
          enabled: true
        tool-search-advisor:
          enabled: true
          tool-index-type: regex
    mcp:
      client:
        enabled: true

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus

Agent 应用的配置要能做到“一键禁用高风险工具”。线上模型误判、外部 MCP server 异常、某个工具出现权限漏洞时，团队需要通过配置中心快速降级，而不是重新发版。

10. Spring Cloud：把 Agent 放回微服务体系

如果 Agent 会服务多个业务系统，不建议把它做成一个孤立应用。更稳的形态是：

用户入口 / 业务系统
        |
Spring Cloud Gateway
        |
Agent Orchestrator Service
        |
Tool Facade Services / MCP Servers
        |
订单、库存、知识库、CRM、审批、SaaS

Spring Cloud 在这里不是为了“凑技术栈”，而是解决四个实际问题：

• 入口一致：所有 Agent 请求先过 Gateway，统一身份、租户、限流和审计。
• 配置一致：模型、工具、MCP server、降级策略放在 Config / 配置中心里。
• 密钥一致：模型 API key、SaaS token、MCP server 凭据放在 Vault 或等价密钥系统里。
• 韧性一致：工具调用和外部系统访问纳入超时、重试、熔断和隔离。

尤其要避免一种常见错误：Agent 服务为了快速上线，直接拿一堆内部系统 token，然后绕过既有网关和权限模型去调服务。短期快，长期会变成权限和审计黑洞。

11. 升级检查清单

从 Spring AI 1.1.x 或 2.0 RC 升级到 2.0 GA，建议按这个顺序检查：

1. 锁版本：使用 spring-ai-bom，确认 Spring Boot、Spring AI、MCP SDK 不混用旧里程碑版本。
2. 改 Tool Calling：移除 internalToolExecutionEnabled，优先用 ChatClient + ToolCallingAdvisor。
3. 查工具注册：确认工具是按请求、角色或场景注入，不是全局无差别暴露。
4. 启用工具搜索：工具数量超过十几个时，评估 spring-ai-starter-tool-search-advisor。
5. 迁移 Chat Memory：如果使用 JDBC 记忆，补 sequence_id 和索引。
6. 检查配置属性：移除过时的 .options 配置层级，按 2.0 文档调整。
7. 检查 MCP 坐标：如果直接依赖 MCP Spring WebMVC/WebFlux 传输类，更新到 org.springframework.ai 坐标和包名。
8. 补观测字段：至少记录 conversationId、toolName、toolArgumentsHash、status、duration、model、tokenUsage。
9. 压测工具链路：模型正常但工具慢，用户体验仍然会失败。
10. 做降级演练：验证能通过配置关闭某类工具、某个 MCP server 或整条自动工具执行链路。

12. 今天可以直接落地的实践建议

如果团队还没开始做 Agent：

• 从只读场景开始，例如知识库问答、订单状态查询、配置解释。
• 先用 ChatClient，不要直接把模型 SDK 散落在 Controller 里。
• 工具数量少时手动注入，工具数量多时再引入 Tool Search。
• MCP 先用于内部工具标准化，不急着接一堆外部 server。

如果团队已经有 Spring AI 1.x 应用：

• 先升级一个非核心服务，验证 Tool Calling、Chat Memory 和配置属性变化。
• 把工具调用从模型适配层迁到应用可控的 Advisor 链路。
• 给每个工具补权限说明、参数校验、审计字段和超时。
• 把高风险工具改成“生成草稿 + 人工确认”，不要让模型直接执行。

如果团队正在做平台型 Agent：

• 把工具注册中心、MCP server 注册、租户权限、工具搜索、审计和成本统计做成平台能力。
• 用 Spring Cloud Gateway 收口入口和跨服务调用。
• 用 Config / Vault 控制模型、凭据、工具开关和环境差异。
• 给每个 Agent 定义最大工具调用次数、最大执行时间和最大成本预算。

13. 参考资料

• Spring AI GitHub Releases：https://github.com/spring-projects/spring-ai/releases
• Spring AI 2.0.0 Reference：https://docs.spring.io/spring-ai/reference/
• Spring AI 2.0 Upgrade Notes：https://docs.spring.io/spring-ai/reference/upgrade-notes.html
• Spring AI Tool Calling：https://docs.spring.io/spring-ai/reference/api/tools.html
• Spring AI MCP：https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html
• Spring Boot GitHub Releases：https://github.com/spring-projects/spring-boot/releases
• Spring Cloud Release Train Releases：https://github.com/spring-cloud/spring-cloud-release/release14. 总结