从 MCP 协议到 ToolCallingAdvisor：构建可编排、可观测的多 Agent 协作系统
2026年6月12日，Spring AI 2.0.0 GA 正式发布。与 1.x 相比，这不仅仅是一次依赖升级，而是一次架构层面的重构：工具调用循环从各 Chat Model 内部提升到 Advisor 链中成为一等公民，MCP 注解从社区孵化项目并入核心模块，ToolSearchToolCallingAdvisor 让上千个工具的动态发现成为可能。
对 Java 技术栈的开发者来说，这意味着：构建生产级多 Agent 系统不再依赖 Python 生态的 LangChain 或 CrewAI——用 Spring Boot 4 + Spring AI 2.0，你可以在一个熟悉的 DI/IoC 模型里，写出类型安全、可测试、可观测的 Agentic 应用。
本文将从"IDE"的视角切入——不是 Visual Studio Code 或 IntelliJ 里的那个 IDE，而是Agent Development Environment（多 Agent 编排开发环境）——逐一拆解 Spring AI 2.0 如何把每个核心特性变成可组合的积木，并用可运行的代码块串联起一个完整的多 Agent 协作工作流。
本文目标读者：有 Spring Boot 使用经验的 Java 开发者，想了解如何在 Spring 生态里构建 AI Agent 系统。阅读完本文后你将可以：用 @Tool 定义工具、用 ToolCallingAdvisor 观测调用链路、用 MCP 协议跨服务调用工具、用 Agentic Patterns 编排多 Agent 工作流。
一、架构全景：Spring AI 2.0 的 Agent 编程模型
先看一张心智模型图。Spring AI 2.0 把一次 LLM 调用抽象为一个通过 Advisor 链的请求：
这与 Spring Web 的 Filter Chain 或 Spring Security 的过滤器链是同构的设计思想。但关键差异在于：Advisor Chain 支持递归循环。这意味着 ToolCallingAdvisor 可以在一次请求中反复执行"发提示 → 模型请求工具 → 执行工具 → 将结果返回模型 → 模型再请求工具"的循环，直到模型认为它有了足够的信息来给出最终答案。
⚡ 与 1.x 的关键区别：在 1.x 中，每个 Chat Model 内部有自己的私有工具调用循环，无法拦截、无法观测、无法替换执行策略。2.0 将工具调用循环从模型中"提升"到 Advisor 链中，使其成为可组合的一等组件。这一点是理解整个 2.0 Agent 模型的基础。
二、上手：一个 50 行的 Tool-Calling Agent
从零开始。创建一个 Spring Boot 4.0 项目，依赖只需要两个：
<!-- pom.xml -->org.springframework.aispring-ai-bom2.0.0pomimportorg.springframework.aispring-ai-starter-model-openaiorg.springframework.bootspring-boot-starter-web
2.1 定义工具：@Tool 注解
定义一个查询订单的工具类：
几个细节值得注意：
description 是给模型看的——模型通过它决定何时调用哪个工具。把它写成清晰的功能说明，而非变量名注释。
Java Record 可以直接作为返回类型——框架通过 Jackson 3 序列化为 JSON。
@ToolParam(required = false)会从 JSON Schema 中移除 required 约束，模型可以不传该参数。
2.2 组装 ChatClient
✅ 不到 50 行业务代码，你得到了什么？
① 模型自动判断何时需要调用工具（无需 if/else 路由）
② 工具执行的完整循环：模型选工具 → 执行 → 结果回传 → 模型继续思考 → 最终回答
③ 类型安全的工具定义，编译期检查参数类型
④ Spring DI 管理工具生命周期，测试时可直接 Mock
三、ToolCallingAdvisor：观测与控制工具调用链
基本工具调用只是起点。真正体现 Spring AI 2.0 架构优势的是Advisor 的可组合性。你可以通过自定义 Advisor 来观测、拦截、甚至修改工具调用行为。
3.1 观测工具调用：构建 Claude-Style 调用指示器
用过 Claude 或 ChatGPT 的人都知道那个 "Calling tool…" 的动态指示器。在 Spring AI 2.0 中，要实现同样的效果，需要写一个 Advisor 坐到 ToolCallingAdvisor 前面来观察调用事件：
Advisor 排序是关键：getOrder() 返回的值决定了 Advisor 在链中的位置。
ToolCallingAdvisor.DEFAULT_ORDER + 100 意味着你的 Advisor 在每次工具调用循环中都会被触发——而不仅仅是在请求的入口和出口。这就是"把工具调用循环从黑盒变为白盒"的核心机制。
3.2 扩展到百级工具：ToolSearchToolCallingAdvisor
当工具数量达到几十甚至上百个时，把所有工具的 Schema 都塞进每次请求的 system prompt 会导致：token 消耗巨大、模型选择工具的准确率下降。Spring AI 2.0 给出的方案是渐进式工具披露：
它的工作方式是：首次请求时，将所有工具的 description 向量化存入内存索引；模型收到用户消息后，先用一次轻量的语义搜索找到相关的 3-5 个工具，只把这几个工具的 Schema 发给模型。实测中，这个方案可以将单次请求的 token 消耗降低 60-80%。
四、MCP 协议：跨服务工具调用的标准答案
当你需要让运行在 A 服务中的 Agent 调用部署在 B 服务中的工具时，Model Context Protocol（MCP）就是为此设计的。Spring AI 2.0 将 MCP Java SDK 与注解驱动编程模型深度集成，使跨进程工具调用像本地调用一样简单。
4.1 注解驱动 MCP Server
将你的工具暴露为 MCP Server——只需在已有 @Tool 方法上添加 @McpTool 注解，再加上一个 starter 依赖：
4.2 MCP Client：一行配置接入远端工具
在你的 Agent 服务中，只需在配置文件里声明远端 MCP Server 的地址：
传输方式Starter适用场景注意事项
stdiospring-ai-starter-mcp-server本地开发工具、Claude Code 集成无法多用户/网络化部署
Streamable HTTP (WebMVC)spring-ai-starter-mcp-server-webmvc生产环境标准选择需要 Web 容器
Streamable HTTP (WebFlux)spring-ai-starter-mcp-server-webflux高并发、响应式栈调试难度更高
SSE同上（配置 protocol=SSE）兼容旧客户端⚠ MCP 规范已废弃，新项目不要用
⚠ 错误处理陷阱：工具方法中抛出的普通 RuntimeException 在早期版本中会直接终止 Agent 循环。正确的做法是抛出
ToolExecutionException，框架会将其消息序列化后返回给模型，让模型可以推理错误并决定下一步（重试、让用户澄清等）。异常消息要包含可操作的提示，而非堆栈信息。
五、编排多 Agent：五种 Agentic Pattern 的 Spring AI 实现
Anthropic 在《Building Effective Agents》研究报告中提出了五种工作流模式。Spring AI 官方文档对这五种模式给出了完整的实现参考。下面逐一拆解。
5.1 Chain Workflow（链式工作流）
适用场景：任务有明确的顺序步骤，每步输出是下一步的输入。
5.2 Parallelization Workflow（并行工作流）
适用场景：大量独立子任务需要并行处理。
5.3 Routing Workflow（路由工作流）
适用场景：不同输入类别需要不同专家处理。
5.4 Orchestrator-Workers（编排器-执行者）
适用场景：子任务无法提前预知，需要动态分解。
5.5 Evaluator-Optimizer（评估-优化循环）
适用场景：有明确评估标准，需要迭代优化的任务（代码生成、文案润色等）。
选择指南：从最简单开始。Chain
适合 80% 的明确流程场景；Routing
适合多类型输入；Parallel
适合大量独立任务；Orchestrator-Workers
适合开放式复杂任务；Evaluator-Optimizer
适合质量要求极高的生成场景。绝大多数生产系统只需要前三种。
六、全流程实战：构建一个多 Agent 客服系统
现在把以上所有特性组合成一个现实的场景——智能客服系统，包含三个专用 Agent 通过 MCP 协议协作：
6.1 主 Agent：Routing + Orchestrator 混合
6.2 完整对话流转示意
✅ 这个系统的核心价值：
①
主 Agent 与子 Agent 解耦——每个子 Agent 独立部署、独立扩展
②
工具动态发现——新增子 Agent 无需修改主 Agent 代码
③
对话记忆——ChatMemory 管理上下文，支持多轮追问
④
错误弹性——ToolExecutionException 让模型能优雅处理业务异常
⑤
结构化输出自修正——当模型生成的 JSON 不符合 Schema 时自动重试
七、生产部署 Checklist
以下是从开发到生产需要注意的要点：
可观测性
Spring AI 2.0 集成 Micrometer 和 OpenTelemetry。工具调用耗时、Token 消耗、MCP 通信等全部自动埋点。搭配 Grafana 可构建完整的 Agent 监控面板。
写在最后
Spring AI 2.0 做对了一件事：把 Agent 开发的复杂性封装进 DI 容器和 Advisor 链中，而不像某些框架那样让你手动管理执行图的状态机。对于已经在用 Spring 生态的 Java 团队来说，这意味着构建 Agent 系统的学习曲线从"学一套全新范式"降到了"理解三个新注解和一个新概念"。
ToolCallingAdvisor 的可组合性、MCP 的跨服务工具调用、五种 Agentic Pattern 的开箱实现——这三个支柱共同构成了一个完整的多 Agent 编程 IDE。它不是要替代 LangChain 或 CrewAI，而是在 JVM 生态里提供了一个类型安全、可观测、生产就绪的替代方案。
2026 年下半年的趋势已经明确：Agent 不再是 Demo 里的玩具，而是要跑在生产环境里、处理真实业务流量、接受 SLA 考核的服务。Spring AI 2.0 的 GA 发布，正是在这个节点上给了 Java 开发者一把趁手的工具。
从 50 行的 Tool-Calling Agent 开始，从那里再到 MCP 多服务编排——每一步都是可落地的。不着急，一步步来。
#Spring AI 2.0 #MCP 协议 #Agentic AI #Tool Calling #ChatClient #Advisor Chain #Java Agent #Spring Boot 4 #多Agent协作 #ToolSearch
