Agentic RAG 技术解析

RAG 基本原理回顾

**检索增强生成（RAG）**是一种结合检索系统与大语言模型（LLM）的技术范式，其核心思想是在生成答案时引入外部知识，从而提升回答的准确性和可靠性。传统RAG的流程通常包括以下步骤：首先，将用户的问题输入检索模块，从预构建的知识库中检索出相关的文档或信息片段；然后，将这些检索结果与原始问题一起送入LLM，由模型生成最终答案。这种"检索+生成"的两阶段模式，使得模型可以利用最新的或特定领域的数据，避免仅依赖模型内部知识而产生幻觉或过时信息。例如，在企业问答系统中，RAG可以将用户提问与内部文档数据库关联，确保回答有据可查。

然而，传统 RAG存在一定局限：检索策略和内容通常是静态预设的，缺乏根据具体问题动态调整的能力。当遇到复杂问题时，单一的检索和生成可能无法满足需求，例如需要多轮检索、跨数据源查询或调用外部工具（如数据库查询、计算等）。此外，传统RAG对检索结果的利用较为被动，模型往往只能一次性使用检索到的内容，缺乏对检索过程的反馈和优化。

Agentic RAG 引入智能体

Agentic RAG（智能体增强的检索生成）是 RAG的演进版本，其特点是在系统中引入了自主智能体（Agent）来监督和优化检索与生成过程。这里的智能体是一个能够自主决策的模块，它充当检索系统和生成模型之间的"智能中介"，可以根据当前上下文和目标动态调整检索策略、选择工具并控制生成过程。与传统RAG 按照固定流程执行不同，Agentic RAG中的智能体能够主动规划：例如，当遇到复杂问题时，它可能决定先进行一轮检索获取背景信息，再根据结果决定是否需要进一步检索或调用工具，最后将综合的信息提供给LLM 生成答案。

智能体的引入使系统具备了自主决策和动态适应能力。具体来说，智能体可以：

• 分析查询意图：理解用户问题的含义和所需信息类型，判断是否需要拆分为子问题或调整查询表述。
• 选择检索策略：根据问题内容决定使用何种检索方式（如稀疏向量检索、稠密向量检索或混合检索）以及从哪些数据源获取信息。必要时，还能动态调整检索参数（如检索结果数量、相似度阈值等）以优化召回效果。
• 调用外部工具：当仅靠文本检索不足以解决问题时，智能体可以调用专门的工具或API获取数据。例如，查询实时天气可能需要调用天气API，计算数学问题可能需要调用计算器工具，访问数据库可能需要执行SQL查询等。
• 控制生成过程：智能体可以在一定程度上控制 LLM
  的生成行为，例如通过调整提示词、约束输出格式或要求模型分步推理等，来确保生成的答案符合预期。
• 反馈与学习：通过监控检索和生成结果，智能体可以收集反馈信息，并据此改进自身策略。例如，如果发现某类问题总是检索不到相关内容，智能体可以学习调整检索关键词或扩大检索范围；又如用户对答案不满意，智能体可以记录并优化下次应对策略。

通过以上能力，Agentic RAG 将传统 RAG的"检索+生成"固定流水线升级为可自主规划的循环：智能体不断感知当前状态（用户问题、已检索信息、已执行操作等），决定下一步行动，执行检索或工具操作，将结果融入上下文，再交由LLM生成答案，并评估答案质量以决定是否需要迭代。这种自主循环使系统更具灵活性和智能性，能够处理更复杂的任务。

Agentic RAG 的架构与流程

Agentic RAG 的典型架构包含三大核心组件：

• 检索系统（Retrieval System）：负责从知识库中获取相关信息。通常包括对数据的预处理和索引构建（如构建倒排索引或向量索引），以及根据查询进行文档匹配和排序的算法（如 BM25、向量相似度搜索等）。检索系统可以对接多种数据源，如文本数据库、知识库、搜索引擎等。
• 生成模型（Generation Model）：通常是一个大型语言模型（LLM），负责在给定上下文和问题时生成自然语言答案。生成模型会将检索系统提供的相关内容纳入其提示（Prompt）中，从而生成基于事实的回答。
• 智能体层（Agent Layer）：这是 Agentic RAG 区别于传统 RAG 的关键模块。智能体层由一个或多个智能体组成，每个智能体具备决策、规划和行动能力。智能体层根据需要可以采用单智能体或多智能体架构：
  • 单智能体架构：使用一个全局智能体来处理所有决策。该智能体充当中央调度者，根据用户查询选择最合适的检索源或工具进行处理。单智能体架构简单高效，适合处理较为直接的单一任务。
  • 多智能体架构：由一个主智能体协调多个子智能体共同完成任务。主智能体负责将复杂任务分解为子任务，并为每个子任务指派擅长相应领域或工具的子智能体并行执行。子智能体各自与特定的数据源或工具交互，最后将结果汇总给主智能体进行综合。多智能体架构能够并行处理复杂查询的不同部分，提高效率和扩展性。

下图是单智能体的Agentic RAG 系统架构：

下图是多智能体的Agentic RAG 系统架构：

下图直观地展示了单智能体架构的 Agentic RAG 系统工作流程：

在具体工作流程中，Agentic RAG 通常包括以下环节：

1. 用户输入查询：用户提出问题或任务请求，作为系统输入。
2. 查询分析与预处理：智能体首先对用户查询进行分析，理解其意图和需求。必要时，智能体会对查询进行改写或扩展，例如拆分为子问题、添加关键词等，以提高检索效果。
3. 信息充分性检查：智能体判断当前掌握的信息是否足以直接回答问题。如果信息不足，进入检索或工具调用流程；如果已有足够信息，可跳过检索直接生成答案。
4. 数据源/工具选择：根据查询内容和所需信息类型，智能体选择合适的数据源或工具来获取信息。例如，选择使用向量数据库检索相关文档，还是调用某个API获取实时数据。
5. 执行检索或工具操作：智能体向选定的数据源发出检索请求，或调用指定的工具执行操作，获取返回的结果数据。这一步可能返回文本片段、数据库查询结果、计算结果等各种形式的信息。
6. 上下文整合：将检索或工具返回的结果与原始查询一起整合成模型可用的上下文。智能体可能对结果进行过滤、排序或摘要，以突出相关部分并控制上下文长度。
7. LLM 生成答案：将整合后的上下文提供给 LLM，由模型生成回答。生成过程中，智能体可以根据需要在提示中加入指令，引导模型如何利用上下文作答。
8. 答案验证与优化：智能体对生成的答案进行评估，检查其是否准确、相关，是否解决了用户的问题。如果答案不充分或存在错误，智能体可能决定进入下一个循环，例如调整检索策略重新获取信息，或要求模型进行修正。
9. 输出最终结果：当智能体认为答案符合要求时，将其返回给用户。同时，本次交互的信息（如用户问题、检索内容、答案等）可以记录下来，用于后续的学习和优化。

上述流程体现了 Agentic RAG的自主闭环特性：智能体在"感知-决策-行动-反馈"的循环中不断迭代，直到产生令用户满意的结果。这种架构使系统能够应对复杂多变的查询，在需要时进行多轮交互和工具使用，从而显著提升回答的深度和准确性。

Agentic RAG 的优势与应用场景

与传统 RAG 相比，Agentic RAG 具有多方面的优势：

• 更智能的决策：引入智能体后，系统不再只是被动地执行预设流程，而是能够根据实时信息主动决定检索什么、如何处理以及何时调用工具。这使回答更贴合问题需求，减少无关信息干扰。
• 动态适应能力：智能体可以根据反馈不断调整策略，例如在检索结果不佳时尝试不同的关键词或数据源，在用户追加提问时结合上下文调整回答。系统表现出更强的适应新问题和变化的能力。
• 支持复杂任务：借助多步规划和工具使用，Agentic RAG 能够处理复杂问答和多轮对话。例如，在客服场景中，智能体可以根据用户的复杂问题逐步检索相关知识库条目、计算费用、查询订单状态等，最终给出综合答复。这种能力是传统一次性检索生成难以实现的。
• 可扩展性：模块化的智能体设计便于扩展系统功能。可以通过添加新的智能体或工具来支持新的数据类型和任务，而无需大幅改动原有架构。例如，增加一个数据库查询智能体即可让系统具备SQL查询能力，而其他部分可以保持不变。
• 上下文感知和一致性：智能体可以维护对话的上下文状态，确保多轮交互中信息的一致性。它还可以根据需要在不同交互之间共享知识（通过长期记忆组件），从而提供更连贯的对话体验。

由于上述优势，Agentic RAG适用于多种应用场景，尤其是需要结合外部知识和执行操作的问答系统。例如：

• 企业智能客服：Agentic RAG 可以接入企业内部知识库、数据库和业务系统，为客户提供准确且个性化的解答。当客户提出复杂问题时，智能体能够查询产品手册、订单数据库，甚至调用后台服务完成操作（如重置密码），然后综合信息给出答复。
• 专业领域问答：在医疗、法律、金融等领域，引入智能体可以让问答系统更"聪明"地检索专业文献、数据库和计算工具。例如医疗诊断助手可以根据症状检索医学指南、调用计算器评估风险指标，然后给出诊断建议，确保答案有依据且准确。
• 个人智能助理：个人助手可以利用 Agentic RAG 连接日历、邮件、日程管理等工具。当用户提问"下周一上午我有哪些会议？“时，智能体可检索日历数据并直接回答；如果用户问"帮我预约下周三和张三的会议”，智能体则可以调用日历API创建会议。这种能够执行操作的问答极大地方便了日常事务处理。
• 教育与培训：在在线教育场景，Agentic RAG 可以作为智能辅导老师。它可以根据学生的问题从教材和题库中检索相关知识点，必要时调用计算或绘图工具演示过程，然后生成详细的讲解。智能体还能根据学生的回答调整教学策略，实现个性化辅导。

总之，Agentic RAG将检索增强生成提升到了一个新的高度，通过赋予系统自主决策和工具使用能力，使其在需要知识驱动和行动驱动的任务中表现得更为出色。接下来，我们将介绍实现这类智能体系统的关键支撑技术------模型上下文协议（MCP），以及如何利用MCP 来连接和管理各种外部工具与数据源。

MCP (Model Context Protocol) 技术解析

MCP 的产生背景与设计目标

随着大型语言模型开始广泛用于构建智能应用，如何让模型安全、方便地访问外部资源成为一个重要课题。在
MCP出现之前，不同应用往往各自实现一套与外部工具交互的方式，缺乏统一标准。例如，有的系统通过自定义插件接口调用数据库，有的通过特殊格式的Prompt触发外部API，这种碎片化的方案不利于工具的复用和生态的形成。

模型上下文协议（Model Context Protocol，简称MCP）正是在这样的背景下由 Anthropic 等机构于 2024
年提出的开放标准。MCP 的设计目标是在AI应用与外部系统之间建立标准化的通信接口，使得开发者能够以一致的方式将各种数据源、工具和功能连接到AI 模型上。简单来说，MCP 定义了 AI模型（或其所在的宿主应用）与外部服务（即 MCP Server）之间交换上下文信息和执行操作的规范。通过 MCP，不同的 AI应用可以无缝对接各类工具，而不需要为每个工具编写定制的集成代码。

MCP 常被比喻为"AI 应用的 USB-C 接口"。正如 USB-C统一了电子设备的连接标准，MCP 提供了统一的方式将 AI应用连接到外部系统。无论 AI 应用使用的是 Claude、ChatGPT还是其他模型，也无论外部资源是本地文件、数据库，还是云端API、专业软件，都可以通过 MCP这个"通用接口"进行连接。这大大降低了集成复杂度，促进了工具的即插即用和生态繁荣。

MCP 的架构与核心组件

MCP 采用典型的客户端-服务器架构，其核心组件包括：

• MCP 宿主（Host）：通常是指运行 AI 模型或智能体的应用程序。例如，Claude Desktop、集成了 AI 助手的 IDE（如 Cursor）、或者自定义的 Agentic RAG 系统等，都可以看作 MCP Host。Host
  负责管理多个 MCP 连接，并将获取的上下文提供给 AI 模型使用。
• MCP 客户端（Client）：Host 内部用于与每个 MCP Server 通信的连接器。一个 Host 可以有多个 Client，每个 Client 维护与一个 Server 的一对一连接。Client 的职责是按照 MCP 协议发送请求、接收响应，并将结果反馈给 Host 中的智能体或模型。
• MCP 服务器（Server）：由开发者实现的轻量级服务程序，对外提供特定的功能或数据访问能力。每个 MCP Server 封装了一类外部资源或工具的操作逻辑，并通过标准的 MCP 接口将其能力暴露出来。例如，一个文件系统 MCP Server 可以提供读取本地文件的功能，一个数据库 MCP Server 可以提供 SQL 查询功能，等等。Server 运行在独立的进程或服务中，通过网络或本地通信与 Host 上的 Client 交互。
• 本地数据源（Data Sources）：指 MCP Server 能够访问的数据或服务。这包括计算机上的文件、数据库、网络服务等。MCP Server 作为桥梁，使得 AI 模型可以通过它间接地访问这些本地或远程的数据源。

MCP 的客户端-服务器架构如下图所示：

在上述架构中，Host 是发起请求的一方，它通过 Client 向各个 Server发出MCP 请求；Server接收到请求后执行相应操作（如查询数据库、调用工具等），并将结果通过Client 回传给 Host。Host 再将这些结果整合到 AI模型的上下文中，供模型生成回答或进行下一步决策。整个过程对 AI模型来说是透明的，模型只需通过统一的 MCP接口获取所需的信息或执行操作，而无需关心具体是哪个 Server提供的以及如何实现的。

MCP协议本身是与传输无关的，它可以运行在多种底层传输协议之上，包括标准输入输出(stdio)、HTTP(S)、WebSocket、本地套接字等。这种灵活性使得 MCP既可以用于本地进程间通信（例如 AI助手调用本地工具），也可以用于远程服务调用（例如 AI应用通过网络调用云端的 MCP Server）。

MCP 的通信机制与协议细节

MCP 的通信内容采用结构化的消息格式，通常使用 JSON来封装请求和响应（实际上 MCP 基于 JSON-RPC 2.0 规范）。每条 MCP消息包含一个方法名（或操作类型）和相应的参数，以及用于关联请求和响应的ID。Host 向 Server 发送请求消息，Server处理后返回包含结果或错误的响应消息。

MCP 定义了几类核心的功能接口，即 Server 可以提供给 Host使用的能力类型：

• 资源（Resources）：资源是指 Server 能够提供的数据片段或内容。可以将资源视为只读的数据接口，用于获取静态或动态的数据。例如，一个文件系统 Server 可能提供资源 file:///path/to/file.txt，Host 可以通过 MCP 请求读取该文件的内容。资源通常对应于"获取"类操作，相当于 RESTful 中的 GET 操作。
• 工具（Tools）：工具是 Server 提供的可执行函数或操作。Host 可以请求执行某个工具，并传入必要的参数，工具执行后返回结果。工具对应于"执行"类操作，相当于 RESTful 中的 POST/Action 操作。例如，一个计算器 Server 可能提供 add(a, b) 工具用于两数相加；一个数据库 Server 可能提供 query(sql) 工具用于执行 SQL 查询。通过工具接口，AI 模型能够触发外部系统的动作或计算。
• 提示模板（Prompts）：提示模板是 Server 定义的可复用提示词模板或交互流程。AI 应用可以使用这些模板来引导模型的行为，而不必每次都手动编写复杂的 Prompt。例如，一个写作辅助 Server 可能提供"总结文章"的提示模板，Host 在需要时可以调用该模板，传入文章内容，由模型按照模板要求生成摘要。提示模板的引入使常见的交互模式得以封装和共享。
• 工作流（Workflows）：工作流是指 Server 提供的复合操作序列，可以将多个资源获取和工具调用组合成一个流程。通过工作流，开发者可以定义一些固定的处理流程，让 AI 应用一次性触发复杂的多步骤操作。例如，一个数据分析 Server 可能提供"数据清洗->可视化"的工作流，Host 调用该工作流时，Server 会依次执行数据清洗工具、生成可视化图表资源等步骤，最终返回结果。工作流提高了复杂任务的集成度。

除了上述功能接口，MCP 协议还定义了发现与配置机制：Host如何发现可用的 MCP Server 以及如何配置连接。通常，Host 会维护一个 MCPServer 列表配置，其中包含每个 Server 的标识、地址、认证信息等。当 Host
启动时，它会根据配置连接到各个 Server，并通过 MCP 的发现请求获取每个Server 所提供的资源、工具、提示模板和工作流清单。这样，Host中的智能体就可以了解有哪些外部能力可用，并在需要时选择调用。

安全和权限也是 MCP 关注的重点。MCP支持在协议层面对请求进行认证和授权，确保只有经过许可的 Host 才能访问Server的功能，并且每次操作都在用户授权的范围内进行。例如，一个企业内部的 MCPServer 可能要求 Host 使用有效的 API Key 或 OAuth令牌才能调用其工具，并且不同用户可能有不同的数据访问权限。通过标准化的安全机制，MCP保证了外部资源访问的可控和可靠。

MCP 的优势与应用场景

作为一项通用的 AI-外部系统连接协议，MCP 具有诸多优势：

• 标准化与兼容性：MCP 提供了统一的接口规范，使得各种工具和数据源的集成变得标准化。这意味着开发者不必为每个新工具编写定制代码，只需实现符合 MCP 规范的 Server 即可被任何支持 MCP 的 AI 应用使用。同样，AI 应用只要支持 MCP，就可以无缝对接所有兼容 MCP 的工具，大大提高了兼容性和互操作性。
• 灵活性与扩展性：MCP 协议本身不限制具体的功能类型，因此可以支持从简单文件读取到复杂业务流程的各种扩展。新的能力只需通过新增 MCP Server 即可加入系统，而无需修改 AI 应用本身。这种插件式的扩展方式使系统功能可以随需求不断增长。
• 安全可控：MCP 在设计中考虑了安全因素，通过集中的配置和认证机制，可以确保 AI 模型对外部资源的访问是经过授权和监控的。企业可以更放心地让 AI 连接内部系统，因为每个操作都可以记录和审核。此外，MCP
  支持在传输层使用加密通道（如 HTTPS），进一步保障数据安全。
• 提升开发效率：有了 MCP，开发者可以专注于实现具体工具的逻辑，而将与 AI 模型交互的细节交给标准协议处理。这降低了开发复杂 Agent 系统的门槛。同时，社区也涌现出各种 MCP Server 实现和工具库（例如后文将介绍的 FastMCP），加速了开发进程。

MCP 的应用场景非常广泛，凡是需要 AI模型与外部环境交互的地方都可以考虑使用 MCP：

• 本地应用集成：AI 助手可以通过 MCP 连接本地应用和数据。例如，Claude Desktop 支持通过 MCP
  访问用户本地的文件系统、日历、笔记等，实现如"读取我电脑上的某份报告并总结"这样的功能。开发者也可以为
  Photoshop、Excel 等本地软件编写 MCP Server，让 AI 能够直接操作这些软件完成任务。
• 企业系统对接：在企业环境中，MCP 可用于连接 AI 模型与内部业务系统（CRM、ERP、数据库等）。例如，一个客服 AI 可以通过 MCP Server 查询客户数据库获取订单信息，或调用内部 API 更新客户状态。由于 MCP 的标准化，企业可以将已有的各种系统逐步封装为 MCP 服务，供不同的 AI 应用共享使用。
• 开发工具与 IDE：AI 编程助手（如 GitHub Copilot、Cursor 等）可以利用 MCP 来增强功能。例如，IDE 可以内置 MCP Server，提供代码索引查询、项目文件导航、运行测试等工具，AI 助手通过 MCP 调用这些工具来获得更精确的代码上下文或执行代码相关操作。这使得 AI 能够深入参与开发流程，如根据项目文件内容生成注释、自动修复代码错误等。
• 专业软件与服务：许多专业领域的软件和云服务也可以通过 MCP 供 AI 使用。例如，GIS 地理信息系统可以提供 MCP Server 让 AI 查询地图数据，财务软件可以提供 MCP 接口让 AI 执行报表计算，等等。Anthropic 的官方示例中就展示了 Slack、Google Maps、AWS 知识库等服务的 MCP Server 实现，这意味着 AI 可以直接调用
  Slack API 发送消息，通过 Google Maps 查询路线，或在 AWS 文档中检索知识。
• 多智能体与复杂工作流：MCP 不仅可以连接 AI 与外部工具，也可以用于智能体之间的通信。例如，一个主智能体可以通过 MCP 调用另一个子智能体提供的"工具"，从而实现多智能体协作。每个智能体既可以作为
  Host 调用其他 MCP Server，也可以自身实现一个 MCP Server 暴露某些能力给其他智能体使用。这种机制使得构建多智能体系统变得灵活，智能体之间通过标准接口交互，方便组合成复杂的工作流。

MCP 为 AI应用打通了与外部世界连接的"最后一公里"。通过统一的协议，各种工具和数据能够即插即用于AI 系统，为构建强大的 Agentic RAG等智能应用奠定了基础。接下来，我们将介绍 MCP的一个优秀实现框架------FastMCP，并演示如何使用 FastMCP 快速开发 MCPServer，从而将自定义工具集成到 AI 应用中。

FastMCP 开发 MCP Server 实践

FastMCP 简介与安装

FastMCP 是一个用于构建 MCP Server 的Python框架，它以简洁、高效的方式封装了 MCP
协议的底层细节，使开发者能够专注于实现具体的工具逻辑。FastMCP的设计理念类似于 Web 开发中的
FastAPI------通过装饰器和类型提示，用极少的代码定义 MCP Server的资源和工具接口。它提供了高度 Pythonic的开发体验，开发者只需编写业务函数，剩下的协议消息处理、参数序列化、错误处理等都由框架自动完成。

FastMCP 最初由社区开发者（jlowin 等人）创建，并在 2024 年被纳入官方 MCPPython SDK，可见其影响力。目前 FastMCP 已经迭代到 2.0 版本，在保持与 MCP核心规范兼容的同时，增加了许多生产级特性。这些特性包括：

• 部署支持：提供简便的命令行工具来运行和部署 MCP Server，支持多种传输方式（如 stdio、HTTP）。
• 认证机制：内置对多种认证方式的支持（如 API Key、OAuth 等），方便在生产环境中保护 MCP Server 的安全。
• 客户端与代理：FastMCP 不仅可以用来写 Server，也提供了客户端库，方便在自定义 Host 中调用 MCP
  Server。此外还支持 Server 代理和组合，可以将多个 MCP Server 组合成一个提供统一接口。
• 自动生成：支持根据 OpenAPI 规范或 FastAPI 应用自动生成 MCP Server，使现有 REST API 快速转换为 MCP 服务。
• 动态工具重写：允许在运行时动态修改工具的定义或行为，以适应不同上下文需求。
• 测试工具：提供测试框架，方便对 MCP Server 的功能进行单元测试和集成测试。

FastMCP 提供了丰富的特性来加速 MCP服务器的开发与部署，其功能模块构成如下图所示：

要使用 FastMCP，首先需要安装它。在 Python 环境中，可以通过 pip直接安装最新版本：

pip install fastmcp

安装完成后，可以通过命令行检查 FastMCP 的版本：

fastmcp --version

如果显示出版本信息，则说明安装成功。接下来，我们将通过一个简单示例，演示如何使用FastMCP 开发一个 MCP Server。

MCP Server 开发流程概述

使用 FastMCP 开发 MCP Server 的一般流程包括以下步骤：

1. 导入 FastMCP 模块并创建服务器实例：在 Python 代码中导入 FastMCP 类，创建一个服务器实例并为其指定名称（该名称会在 MCP 发现过程中显示）。
2. 定义资源和工具：使用 FastMCP 提供的装饰器（如 @mcp.resource、@mcp.tool）来装饰自定义的函数，将其声明为 MCP 的资源或工具接口。通过函数的文档字符串和类型注解，FastMCP 可以自动生成这些接口的描述和参数模式，供 Host 端发现和使用。
3. 配置服务器参数（可选）：根据需要配置服务器的传输方式、端口、认证信息等。如果使用默认的 stdio 传输，通常无需额外配置即可运行。
4. 启动服务器：调用服务器实例的 run() 方法启动 MCP Server。此时服务器会监听指定的传输通道，等待来自 Host 的请求。
5. 测试与集成：使用支持 MCP 的 AI 应用或测试客户端连接该 Server，验证资源和工具能否正常工作。如果一切正常，就可以将该 Server 配置到实际的 Agentic RAG 系统中使用了。

下面，我们通过一个具体的例子来实践上述流程。假设我们要开发一个简单的**“计算器” MCPServer**，它提供两个功能：一是获取当前计算器的配置信息（资源），二是执行两个数的加法运算（工具）。

一个简单 MCP Server 的实现示例

首先，新建一个 Python 文件calculator_server.py。按照上述流程，我们逐步实现这个 MCP Server：

步骤 1：导入模块并创建 FastMCP 实例

from fastmcp import FastMCP

# 创建一个名为 "Calculator" 的 MCP Server 实例
mcp = FastMCP("Calculator")

这里我们导入了 FastMCP 类并实例化了一个服务器对象mcp，名称设置为"Calculator"。

步骤 2：定义资源

我们希望提供一个资源来获取计算器的配置信息，比如版本号或支持的操作。使用@mcp.resource 装饰器来定义资源，需要指定资源的 URI。例如，我们定义一个URI 为 config://calculator 的资源：

@mcp.resource("config://calculator")
def get_calculator_config():
    """Get calculator configuration info"""
    return {
        "name": "Simple Calculator",
        "version": "1.0",
        "supported_operations": ["addition"]
    }

上述代码中，@mcp.resource("config://calculator") 将函数get_calculator_config 注册为一个 MCP 资源，其访问路径为config://calculator。函数的返回值将作为该资源的内容返回给请求者。我们在这里返回了一个包含计算器名称、版本和支持操作的字典。函数的文档字符串"""Get calculator configuration info""" 会被 MCP用于描述该资源的作用。

步骤 3：定义工具

接下来定义一个加法工具。使用 @mcp.tool装饰器来注册工具，工具名默认为函数名，也可以在装饰器中指定 name参数自定义名称。这里我们直接使用函数名 add 作为工具名：

@mcp.tool
def add(a: float, b: float) -> float:
    """Add two numbers together"""
    return a + b

这个工具接受两个浮点数参数 a 和 b，返回它们的和。FastMCP会根据函数的类型注解自动生成该工具的参数模式（指明参数类型为浮点数，返回值也是浮点数）。文档字符串"""Add two numbers together""" 则作为工具的描述，Host端的智能体可以读取这个描述来决定何时使用该工具。

步骤 4：启动服务器

最后，添加主程序入口，启动 MCP Server：

if __name__ == "__main__":
    mcp.run()

当运行该脚本时，mcp.run() 会启动服务器。默认情况下，FastMCP 使用 stdio传输，即通过标准输入输出与 Host通信。这意味着我们可以在命令行中直接运行该脚本，然后通过其他支持 MCP的程序与之交互。

完整的示例代码如下：

from fastmcp import FastMCP

# 初始化 MCP Server，名称为 "Calculator"
mcp = FastMCP("Calculator")

# 定义一个资源：获取计算器配置
@mcp.resource("config://calculator")
def get_calculator_config():
    """Get calculator configuration info"""
    return {
        "name": "Simple Calculator",
        "version": "1.0",
        "supported_operations": ["addition"]
    }

# 定义一个工具：执行两数相加
@mcp.tool
def add(a: float, b: float) -> float:
    """Add two numbers together"""
    return a + b

# 启动 MCP Server
if __name__ == "__main__":
    mcp.run()

步骤 5：测试服务器

现在我们已经编写好了 MCPServer，接下来测试它是否正常工作。一种简单的方法是使用命令行手动发送 MCP
请求（虽然实际中通常由 AI Host自动完成）。例如，我们可以在终端运行服务器脚本：

python calculator_server.py

服务器启动后，会等待从标准输入读取 MCP请求。此时，我们可以通过另一个终端或工具向其发送 JSON-RPC
格式的请求。例如，要调用 add 工具，我们发送以下 JSON数据（换行符仅为了可读性）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tool/add",
  "params": {
    "a": 5,
    "b": 3
  }
}

其中，"method": "tool/add" 表示调用名称为 add 的工具，"params"是传递给该工具的参数。服务器接收到请求后，会执行 add(5, 3) 得到结果8，然后返回如下响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 8.0
}

类似地，我们可以发送获取资源的请求：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resource/get",
  "params": {
    "uri": "config://calculator"
  }
}

服务器将返回该资源的内容：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "name": "Simple Calculator",
    "version": "1.0",
    "supported_operations": ["addition"]
  }
}

通过以上测试，可以看到我们的 MCP Server正确响应了工具调用和资源获取请求。这证明 FastMCP
已经成功地将我们定义的函数暴露为 MCP 接口，并处理了底层的协议通信。

FastMCP 高级特性与最佳实践

除了上述基本用法，FastMCP 还提供了许多高级功能来简化 MCP Server的开发和部署：

• 异步支持：FastMCP
  支持定义异步函数作为资源或工具实现。对于耗时较长的操作（如网络请求），可以使用 async def 来定义函数，这样 MCP Server 能够以非阻塞方式处理请求，提高并发性能。
• 自定义参数校验：虽然 FastMCP
  会根据类型提示自动校验参数类型，但开发者也可以在函数内部添加自定义的业务逻辑校验。例如，检查数值范围、字符串格式等，不符合条件时抛出异常，FastMCP 会将异常转换为 MCP 错误响应返回给 Host。
• 错误处理：可以通过捕获特定异常并返回友好的错误信息，来提高系统的健壮性。FastMCP 允许注册错误处理函数，对未捕获的异常进行统一处理，避免服务器因异常而崩溃。
• 日志和调试：FastMCP 提供了日志接口，方便在开发过程中输出调试信息。可以通过配置日志级别来监控请求接收、处理过程和结果返回的详细情况，帮助定位问题。
• 配置文件：对于复杂的项目，可以使用配置文件（如 fastmcp.json）来管理服务器的参数，如传输方式、端口、认证信息等。这样在部署时无需修改代码，只需调整配置文件即可。
• 部署与集成：FastMCP 内置了对多种部署方式的支持。例如，可以通过指定 transport="http" 并提供端口号，将 MCP Server 运行在 HTTP 服务器上，使其可以通过网络被远程 Host 访问。也可以将 FastMCP Server
  打包为独立的可执行程序或 Docker 容器，方便在不同环境中部署。在企业环境中，还可以结合 FastMCP
  的认证功能，为每个 Server 设置访问密钥或 OAuth 2.0 认证，确保只有授权的 AI 应用才能调用。
• 与其他框架集成：FastMCP 能够与常用的 Agent 开发框架（如 LangChain 等）配合使用。例如，LangChain 提供了 MCP 工具包装器，可以将 MCP Server 的工具直接作为 LangChain Agent 的工具来使用。这意味着我们可以很容易地将刚才开发的计算器 MCP Server 集成到一个 LangChain Agent 中，让 Agent 在需要时调用 add 工具进行计算。这种集成大大扩展了 Agent 的能力边界。

在使用 FastMCP 开发 MCP Server 时，有一些最佳实践值得遵循：

• 保持单一职责：每个 MCP Server 应专注于提供一类功能或访问一种数据源，避免将过多不相关的工具塞到一个 Server 中。这样可以提高代码的可维护性，也方便根据需要启停或扩展特定功能。
• 良好的文档和描述：充分利用函数的文档字符串和类型提示，为每个资源和工具提供清晰的描述和参数说明。Host 端的智能体往往依赖这些元数据来决定如何使用工具，因此描述越准确，智能体越能正确调用。
• 输入输出校验：对工具接收到的参数进行适当校验，确保其范围和格式符合预期。同时对输出结果进行格式化，避免返回过大或无关的数据，以免撑爆模型的上下文窗口或干扰模型判断。
• 安全考虑：如果 MCP Server 要暴露在网络上或提供敏感数据访问，一定要启用认证和授权机制。FastMCP
  支持在 Server 端验证请求的凭证，或者在 Host 端配置只连接受信的 Server。另外，对于执行操作系统命令、写文件等危险操作的工具，应格外谨慎，最好限制其使用范围或在沙盒环境中运行。
• 测试与监控：在将 MCP Server 投入生产前，应对其进行充分测试，包括正常情况和异常情况（如参数错误、网络失败等）下的表现。可以编写自动化测试用例模拟 Host 的请求，验证 Server 的响应是否正确。部署后也应监控 Server 的运行状态和性能，及时发现并处理问题。

通过遵循以上实践，我们可以高效地开发出稳定、可靠的 MCP Server，为 AI应用提供强有力的外部能力支持。在掌握了 Agentic RAG 和 MCP 的原理以及FastMCP的使用方法后，接下来我们将进入实战环节------构建一个面向工业故障维修问答场景的智能系统，将上述技术融会贯通。

请见后文“基于FastMCP构建Agentic RAG：深度解析与代码实践（下）”

请访问我的微信公众号“大模型RAG和Agent技术实践”，有更丰富的内容。