【AI超级智能体】快速搞懂工具调用Tool Calling 和 MCP协议

本文为个人学习AI项目笔记，部分资源来源于网上，仅供学习记录分享，无其他用途。

工具调用

什么是工具调用？

工具调用（Tool Calling）可以理解为让 AI 大模型 借用外部工具 来完成它自己做不到的事情。 跟人类一样⁠，如果只凭手脚完成‌不了工作，那么就可以利用工具箱来完成‎。工具可以是⁠任何东西，比如网页‌搜索、对外部 API 的调用、访问外‎部数据、或执行特定‌的代码等。

比如用户提⁠问 "帮我查询上海最‌新的天气"，AI 本身并没有这些知识，它‎就可以调用 "查询天‌气工具"，来完成任务。

工具调用的工作原理

工具调用的工作原理其实非常简单，并不是 AI 服务器自己调用这些工具、也不是把工具的代码发送给 AI 服务器让它执行，它只能提出要求，表示 "我需要执行 XX 工具完成任务"。而真正执行工具的是我们自己的应用程序，执行后再把结果告诉 AI，让它继续工作。

为啥要这样设计？这样不是会让程序多次请求AI嘛？为啥不直接让AI服务器调用工具呢？

最关键的一点就是安全性，AI 模型永远无法直接接触你的 API 或系统资源，所有操作都必须通过你的程序来执行，这样你可以完全控制 AI 能做什么、不能做什么。

工具调用 / Spring AI工具开发

**工具定义与注册：**Spring AI 可以通过简洁的注解自动生成工具定义和 JSON Schema，让 Java 方法轻松转变为 AI 可调用的工具。
**工具调用请求：**Spring AI 自动处理与 AI 模型的通信并解析工具调用请求，并且支持多个工具链式调用。
**工具执行：**Spring AI 提供统一的工具管理接口，自动根据 AI 返回的工具调用请求找到对应的工具并解析参数进行调用，让开发者专注于业务逻辑实现。
**处理工具结果：**Spring AI 内置结果转换和异常处理机制，支持各种复杂 Java 对象作为返回值并优雅处理错误情况。
**返回结果给模型：**Spring AI 封装响应结果并管理上下文，确保工具执行结果正确传递给模型或直接返回给用户。
**生成最终响应：**Spring AI 自动整合工具调用结果到对话上下文，支持多轮复杂交互，确保 AI 回复的连贯性和准确性。

定义工具

在Spring AI中提供了两种模式来定义工具，分别是基于Methods方法或者Functions函数式编程。这里推荐用前者来定义工具，更容易进行编写。只需添加@Tool注解即可绑定工具

复制代码

class WeatherTools {
    @Tool(description = "Get current weather for a location")
    public String getWeather(@ToolParam(description = "The city name") String city) {
        return "Current weather in " + city + ": Sunny, 25°C";
    }
}
ChatClient.create(chatModel)
    .prompt("What's the weather in Beijing?")
    .tools(new WeatherTools())
    .call();

使用工具

Spring AI提供了多种灵活的方式将工具提供给ChatClient，可以按需使用，也可以全局使用等方式。

还可以直接使用更底层的方式（直接绑定给ChatModel），还可以动态解析。后两种不过多介绍。

现在有很多开源的工具，可以去GitHub上寻找更多的工具源码进行拉取使用。

复制代码

// 按需使用：直接在构建ChatClient请求时通过tools()方法附加工具
String response = ChatClient.create(chatModel)
    .prompt("北京今天天气怎么样？")
    .tools(new WeatherTools())  // 附加工具
    .call()
    .content();

// 全局使用：可以在构建ChatClient时注册默认工具
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultTools(new WeatherTools(), new TimeTools())  // 注册默认工具
    .build();

工具进阶知识

工具底层数据结构

Spring AI工具调用的核心在于ToolCallback接口，它是所有工具实现的基础

复制代码

public interface ToolCallback {

    /*
    提供了工具的基本定义，包括名称、描述和调用参数，这些信息会传递给 AI 模型，
    帮助模型了解什么时候应该调用这个工具、以及如何构造参数
    */
    ToolDefinition getToolDefinition();

    /*
    提供了处理工具的附加信息，比如是否直接返回结果等控制选项
    */
    ToolMetadata getToolMetadata();

    /*
    两个 call() 方法是工具的执行入口，分别支持有上下文和无上下文的调用场景
    */
    String call(String toolInput);
    String call(String toolInput, ToolContext tooContext);
}
/*
此外 在Spring Ai使用注解定义工具时，会做大量幕后工作
1. JsonSchemaGenerator 会解析方法签名和注解，自动生成符合 JSON Schema 规范的参数定义，作为 ToolDefinition 的一部分提供给 AI 大模型
2. ToolCallResultConverter 负责将各种类型的方法返回值统一转换为字符串，便于传递给 AI 大模型处理
3. MethodToolCallback 实现了对注解方法的封装，使其符合 ToolCallback 接口规范
*/

工具上下文

在实际应用中，工具执行可能需要额外的上下文信息 ，比如登录用户信息、会话 ID 或者其他环境参数。Spring AI 通过ToolContext提供了这一能力（有点类似于TheadLocal）。

ToolContext本质上是一个Map，它可以携带任何与当前请求相关的信息，但**这些信息不会传递给 AI 模型，只在应用程序内部使用（是由程序直接调工具）。**这样做既增强了工具的安全性，也很灵活。适用于下面的场景：

用户认证信息：可以在上下文中传递用户 token，而不暴露给模型
请求追踪：在上下文中添加请求 ID，便于日志追踪和调试
自定义配置：根据不同场景传递特定配置参数

立即返回

有时候，工具执行的结果不需要再经过 AI 模型处理，而是希望直接返回给用户（比如生成 PDF 文档）。Spring AI 通过 returnDirect 属性支持这一功能，只要在定义工具时，设置returnDirect设置为true。这样可以节省资源，处理一些不必要再传给AI进行处理的结果。

工具底层执行原理

Spring AI 提供了两种工具执行模式：框架控制的工具执行和用户控制的工具执行。这两种模式都离不开一个核心组件 ToolCallingManager**，** 它是 管理 AI 工具调用全过程 的核心组件，负责根据 AI 模型的响应执行对应的工具并返回执行结果给大模型。此外，它还支持异常处理，可以统一处理工具执行过程中的错误情况。

其中的 2 个核心方法：

resolveToolDefinitions：从模型的工具调用选项中解析工具定义
executeToolCalls：执行模型请求对应的工具调用

MCP协议

什么是MCP？

**MCP（Model Co⁠ntext Protocol，模型上下文协议）是‌一种开放标准，目的是增强 AI 与外部系统的交互能力。**MCP 为 AI 提供了与外部工具、资源和‎服务交互的标准化方式，让 AI 能够访问最新数据‌、执行复杂操作，并与现有系统集成。

MCP 是一种开放协议，它标准化了应用程序如何向大模型提供上下文的方式。 可以将 MCP 想象成 AI 应用的 USB 接口。就像 USB 为设备连接各种外设和配件提供了标准化方式一样，MCP 为 AI 模型连接不同的数据源和工具提供了标准化的方法。

MCP架构

宏观上看：

MCP 的核心是 "⁠客户端 - 服务器" 架构，其中 MCP‌ 客户端主机可以连接到多个服务器。客户端主机是指希望访问 MCP 服务的程序，比‎如 Claude Desktop、IDE‌、AI 工具或部署在服务器上的项目。

从SDK3层架构上，分别来看每一层的作用：

客户端 / 服务器层：McpClient 处理客户端操作，而 McpServer 管理服务器端协议操作。两者都使用 McpSession 进行通信管理。
会话层（McpSession）：通过 DefaultMcpSession 实现管理通信模式和状态。
传输层（McpTransport）：处理 JSON-RPC 消息序列化和反序列化，支持多种传输实现，比如 Stdio 标准 IO 流传输和 HTTP SSE 远程传输。

MCP客户端

MCP Client 是⁠ MCP 架构中的关键组件**，主要负责和 MCP‌ 服务器建立连接并进行通信。它能自动匹配服务器的协议版本、确认可用功能、负责数据传输和 JS‎ON-RPC 交互。此外，它还能发现和使用各种‌工具、管理资源、和提示词系统进行交互。**

除了这些核心功⁠能，MCP 客户端还支持一‌些额外特性，比如根管理、采样控制，以及同步或异步操作‎。为了适应不同场景，它提供‌了多种数据传输方式，包括：

Stdio 标准输入 / 输出：适用于本地调用
基于 Java HttpClient 和 WebFlux 的 SSE 传输：适用于远程调用

客户端可以⁠通过不同传输方式调‌用不同的 MCP 服务，可以是本地的‎、也可以是远程的。‌

MCP服务端

MCP S⁠erver 也是整‌个 MCP 架构的关键组件，主要用来‎为客户端提供各种工‌具、资源和功能支持。

它负责处理客户端⁠的请求，包括解析协议、提供工具‌、管理资源以及处理各种交互信息 。同时，它还能记录日志、发送通‎知，并且支持多个客户端同时连接‌，保证高效的通信和协作。和客户端一样，它也⁠可以通过多种方式进行数据传输，比如‌ Stdio 标准输入 / 输出、基于 Servlet / WebF‎lux / WebMVC 的 SS‌E 传输，满足不同应用场景。这种设计使⁠得客户端和服务端完‌全解耦，任何语言开发的客户端都可以调‎用 MCP 服务。‌

MCP核心概念（六大核心概念）

**Resources 资源：**让服务端向客户端提供各种数据，比如文本、文件、数据库记录、API 响应等，客户端可以决定什么时候使用这些资源。使 AI 能够访问最新信息和外部知识，为模型提供更丰富的上下文。
**Prompts 提示词：**服务端可以定义可复用的提示词模板和工作流，供客户端和用户直接使用。它的作用是标准化常见的 AI 交互模式，比如能作为 UI 元素（如斜杠命令、快捷操作）呈现给用户，从而简化用户与 LLM 的交互过程。
**Tools 工具：**MCP 中最实用的特性，服务端可以提供给客户端可调用的函数，使 AI 模型能够执行计算、查询信息或者和外部系统交互，极大扩展了 AI 的能力范围。
**Sampling 采样：**允许服务端通过客户端向大模型发送生成内容的请求（反向请求）。使 MCP 服务能够实现复杂的智能代理行为，同时保持用户对整个过程的控制和数据隐私保护。
**Roots 根目录：**MCP 协议的安全机制，定义了服务器可以访问的文件系统位置，限制访问范围，为 MCP 服务提供安全边界，防止恶意文件访问。
**Transports 传输：**定义客户端和服务器间的通信方式，包括 Stdio（本地进程间通信）和 SSE（网络实时通信），确保不同环境下的可靠信息交换。