1.概述

OpenAI Agents SDK 现已支持 MCP（模型上下文协议），这是 AI 互操作性的重大变革。这使开发人员能够高效地将 AI 模型连接到外部工具和数据源。本篇博客，笔者将指导使用 OpenAI Agents SDK 构建 MCP 服务器，以增强你的 AI 应用程序。

2.内容

2.1 什么是 MCP

MCP 服务器（Model Context Protocol Server）是**模型上下文协议（MCP）**的重要组成部分，它是一种专门设计的程序，使 AI 模型（如 Anthropic 的模型）能够安全、标准化地访问和使用外部数据与工具。自 2024 年 11 月推出以来，MCP 服务器扩展了 AI 的能力，使其不仅能生成文本，还能直接与计算机文件、数据库，甚至 GitHub 等服务进行交互。

可以将 MCP 服务器比作 AI 访问外部资源的"接口"，类似于 USB 端口让计算机与不同设备连接。例如，当用户请求 AI 总结一份文档时，AI 可以通过 MCP 服务器直接提取系统中的文件进行处理。同样，如果需要创建 GitHub 问题或查询数据库，MCP 服务器也能提供支持。

MCP 服务器的核心功能包括：

数据访问：让 AI 直接读取本地文件、数据库记录等信息。
工具调用：支持 AI 执行 API 调用，与外部系统交互。
交互提示：提供操作指南，优化 AI 在编程、研究、项目管理等任务中的表现。

借助 MCP 服务器，AI 的应用场景进一步拓展，使其能够更高效地完成复杂任务，提升生产力和用户体验。

2.2 MCP 服务器如何工作

MCP 采用客户端-服务器架构运行，确保 AI 高效、安全地访问和利用外部数据。其结构由以下核心组件组成：

MCP 主机：希望利用外部数据的应用程序，如 Claude Desktop、IDE 或 AI 辅助工具。
MCP 客户端：负责与 MCP 服务器建立安全、稳定的连接，充当通信桥梁。
MCP 服务器：轻量级程序，通过标准化的模型上下文协议（MCP）公开特定功能，使 AI 能够访问外部资源并执行任务。

该架构支持主机通过客户端连接多个 MCP 服务器，每个服务器都提供独立的功能，实现模块化、灵活的集成。MCP 服务器主要提供以下三种类型的公开接口：

资源访问：允许 AI 加载数据源，如本地文件、文档或数据库查询。例如，文件系统服务器可让 AI 访问和读取计算机上的文档。
工具调用：支持 AI 执行特定操作，如 API 调用或命令执行。例如，GitHub 服务器可让 AI 进行代码库管理，包括创建 issue、提交代码等。
交互提示：提供可重复使用的 LLM 交互模板，指导 AI 在特定场景下的行为，提升任务执行的准确性与效率。

2.3 MCP 实际上能做什么？

1.核心特性

灵活部署：支持本地或远程运行，适应不同应用场景。
安全优先：采用严格的权限管理，确保连接安全，防止数据泄露。
独立资源管理：每个服务器控制自身的数据和工具，防止越权访问。

2.技术架构

MCP 服务器通过 JSON-RPC 端点公开功能，允许客户端查询和调用可用的资源、工具和提示。

例如：

资源访问："readFile" 方法可返回指定文件内容，使 AI 能够直接读取本地或远程文档。
工具调用："createIssue" 方法支持与 GitHub API 交互，自动创建 Issue 或管理存储库。
动态交互：支持服务器发起的递归与动态 AI 交互，例如基于任务自动调整操作流程，提高 AI 代理的自主性。

这种标准化协议不仅提升了 AI 在数据处理、自动化工作流等场景的能力，还保证了高度的安全性与可控性，使其成为 AI 生态中的关键组件。

2.4 MCP 服务器和 API 之间有什么区别？

MCP 服务器与传统 API 都能让软件与外部服务交互，但它们在 AI 环境中的用途和运作方式存在显著差异：

1. 适用场景

传统 API：作为通用通信接口，主要用于让软件访问外部服务，例如 AI 通过 API 查询数据库或获取实时数据。
MCP 服务器：专门为 AI 设计，提供标准化的上下文信息，包括数据、工具和交互提示，使 AI 能更高效地理解和利用外部资源。

2. 交互方式

传统 API：AI 需要知道 API 的调用方式、参数格式，并解析响应数据，再将其整合到上下文中。
MCP 服务器：直接处理数据源或工具交互，并将结果以 AI 友好的方式呈现，屏蔽底层数据格式的复杂性，让 AI 无需额外解析即可使用。

3. 标准化与扩展性

传统 API：不同服务的 API 可能采用不同的协议（如 REST、GraphQL），需要针对每个 API 进行定制集成。
MCP 服务器：采用标准化协议，支持即插即用，可无缝集成到各种 AI 应用中，无需针对每个服务单独适配。

4. 安全性

传统 API：通常依赖外部身份验证（如 OAuth、API Key），安全性取决于具体实现。
MCP 服务器：内置身份验证和访问控制，专门优化 AI 访问权限管理，确保数据安全。

5.示例对比

在传统 API 方案中，AI 想获取天气数据需要：

发送 REST API 请求。
解析 JSON 响应。
提取温度、湿度等信息，并整合到上下文中。

使用 MCP 服务器，AI 只需调用 get_weather 工具，服务器会直接返回格式化的天气信息，简化流程，提高效率。

3.OpenAI Agents SDK

OpenAI Agents SDK 是一个 Python 库，旨在简化由 OpenAI 语言模型支持的 AI 代理的开发。它为开发人员提供了创建特定于任务的代理、集成外部功能、管理代理间任务委托、执行输入/输出验证和监控执行流程的工具。

OpenAI Agents SDK 提供了一个结构化的框架，用于构建多代理系统，其中每个代理都经过定制以执行特定任务。这些代理可以与用户交互，通过集成工具执行操作，并通过将任务传递给其他代理进行协作。SDK 的关键组件包括：

代理：配置了特定指令和角色的语言模型实例。
工具：扩展代理功能的功能或服务（例如，网络搜索，自定义 Python 代码）。
交接：使代理能够无缝地将任务委派给其他代理的机制。
护栏：验证层，确保输入和输出符合定义的标准。
跟踪：用于调试和性能分析的执行日志。

3.1 安装和配置

正确设置对于有效使用 OpenAI Agents SDK 至关重要。介绍先决条件、环境设置、安装和验证。

Python 3.8+：使用验证你的 Python 版本python --version。如果需要，请从python.org安装。

OpenAI API 密钥：从你的帐户设置下的platform.openai.com获取密钥。此密钥用于验证对 OpenAI 服务器的请求。

3.1.1 设置虚拟环境

虚拟环境隔离了项目依赖关系，防止与其他 Python 项目发生冲突。要创建并激活虚拟环境，请执行以下操作：

Linux / macOS：

复制代码

python -m venv agents_env
source agents_env/bin/activate

Windows：

复制代码

python -m venv agents_env
agents_env\Scripts\activate

一旦激活，你的终端提示符应该反映环境（例如(agents_env)）。此步骤是 Python 开发的最佳实践，可确保工作空间干净。

3.1.2 安装 SDK

在虚拟环境处于活动状态的情况下，使用 pip 安装 SDK：

复制代码

pip install openai-agents

此命令从 PyPI 获取最新版本的 SDK 及其依赖项。要确认安装，请运行：

复制代码

pip show openai-agents-python

这将显示元数据，包括版本号，确认包已安装。

3.1.3 配置 API 密钥

SDK 需要 OpenAI API 密钥才能运行。将其设置为环境变量以避免将其嵌入到代码中，从而增强安全性：

Linux / macOS：

复制代码

export OPENAI_API_KEY='your-api-key'

Windows：

复制代码

set OPENAI_API_KEY='your-api-key'

要使其在会话间持久化，请将命令添加到 shell 配置文件中（例如，.bashrc在.zshrcUnix 系统上）。或者，你可以在 Python 中以编程方式设置它，比如：

复制代码

import os
os.environ["OPENAI_API_KEY"] = "your-api-key"

3.1.4 验证安装

使用最小代理测试设置以确保一切正常：

复制代码

from agents import Agent, Runner

agent = Agent(name="TestAgent", instructions="Return 'Setup successful'")
result = Runner.run_sync(agent, "Run test")
print(result.final_output)  # Expected output: "Setup successful"

如果显示"安装成功"，则表示您的安装已正常运行。常见问题包括：

无效的 API 密钥：仔细检查密钥并确保没有多余的空格或拼写错误。
网络错误：验证你的互联网连接和 OpenAI 的服务器状态。

3.2 创建代理

代理是 SDK 的基本构建块，每个代理都由独特的角色和行为定义。

3.2.1 代理初始化

该类Agent用于实例化代理。关键参数包括：

name：字符串标识符（例如"MathAgent"）。
instructions：指定代理目的的字符串（例如"解决数学问题"）。
model：要使用的 OpenAI 模型（默认值gpt-4）。
temperature：0 到 1 之间的浮点数，控制输出随机性（默认值：0.7）。

3.2.2 基本代理

这是一个简单的算术代理：

复制代码

from agents import Agent, Runner

agent = Agent(
    name="MathAgent",
    instructions="Solve arithmetic expressions."
)
result = Runner.run_sync(agent, "Calculate 10 * 2")
print(result.final_output)  # Output: "20"

该Runner.run_sync方法同步执行代理，返回带有final_output属性的结果对象。

3.3 高级配置

通过调整参数来定制满足特定需求的代理：

复制代码

agent = Agent(
    name="CreativeWriter",
    instructions="Write a short story based on the prompt.",
    model="gpt-4",
    temperature=0.9
)
result = Runner.run_sync(agent, "A robot in a distant galaxy")
print(result.final_output)  # Output: A creative story

模型：gpt-4提供更优越的推理能力，同时gpt-3.5-turbo对于更简单的任务来说更快、更便宜。
温度：较低的值（例如 0.2）产生可预测的输出；较高的值（例如 0.9）可增强创造力。

4.使用 OpenAI MCP 集成的步骤

使用 OpenAI Agents SDK 构建 MCP 服务器的先决条件，在开始之前，请确保您已：

你的系统上已安装 Python 3.8 或更高版本
通过 pip 安装 OpenAI Agents SDK：pip install openai-agents
Node.js 设置为运行 MCP 服务器命令，例如npx某些示例
带有初始化虚拟环境的项目目录，用于依赖管理
对 Python 中的异步编程有基本的了解，因为 SDK 使用 async/await

4.1 为 MCP 服务器设置开发环境

复制代码

# Create a new directory for your project
mkdir mcp-agent-project && cd mcp-agent-project

# Initialize a Python virtual environment
python -m venv venv && source venv/bin/activate

# Install the required dependencies
pip install openai-agents pyyaml

设置一个配置文件，用于mcp_agent.config.yaml定义 MCP 服务器。此配置指向用于访问本地文件的文件系统 MCP 服务器。

4.2 了解 OpenAI Agents SDK 中的 MCP 服务器类型

根据 MCP 规范定义，MCP 服务器有两种类型：

stdio 服务器：作为应用程序的子进程在本地运行
HTTP SSE 服务器：远程操作并通过 URL 连接

OpenAI Agents SDK 提供了两个类来处理这些服务器：

MCPServerStdio：对于基于本地子进程的服务器
MCPServerSse：适用于远程 HTTP over SSE 服务器

根据应用程序的架构和延迟要求选择服务器类型。Stdio 服务器是本地开发的理想选择，而 SSE 服务器更适合分布式系统。

4.3 将 MCP 服务器连接到 OpenAI 代理

从 OpenAI Agents SDK 导入必要的类并定义您的 MCP 服务器：

复制代码

from openai_agents import Agent, MCPServerStdio

# Define path to your sample files
samples_dir = "/path/to/your/files"

# Use async context manager to initialize the server
async with MCPServerStdio(
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
    }
) as server:
    # List tools provided by the MCP server
    tools = await server.list_tools()

    # Create an agent that uses the MCP server
    agent = Agent(
        name="Assistant",
        instructions="Use the filesystem tools to help the user with their tasks.",
        mcp_servers=[server]
    )

    # Run the agent
    result = await agent.run("List the files in the directory.")

此设置允许代理在执行期间动态使用文件系统工具。

4.4 使用工具缓存优化性能

list_tools()每次代理运行时，MCP 服务器都会调用，这可能会导致延迟，尤其是使用远程服务器时。为了减少这种开销，你可以启用工具缓存：

复制代码

# Enable caching when initializing the server
async with MCPServerStdio(
    params={
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
    },
    cache_tools_list=True  # Enable caching
) as server:
    # The tools list will be cached after the first call
    tools = await server.list_tools()

缓存的重要注意事项：

仅当您确定工具列表在运行时不会改变时才使用缓存
如果工具需要更新，请使缓存无效：await server.invalidate_tools_cache()
缓存适用于 stdio 和 SSE 服务器，可为远程服务器带来更大的性能优势

4.5 实现 MCP 服务器与代理工作流程的集成

要将 MCP 服务器与你的代理完全集成：

复制代码

from openai_agents import Agent, MCPServerStdio, MCPServerSse

async def run_agent_with_mcp_servers():
    # Initialize local stdio MCP server
    local_server = MCPServerStdio(
        params={
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "./local_files"],
        },
        cache_tools_list=True
    )

    # Initialize remote SSE MCP server (if needed)
    remote_server = MCPServerSse(
        url="<https://your-remote-mcp-server.com/stream>",
        cache_tools_list=True
    )

    async with local_server, remote_server:
        # Create agent with both servers
        agent = Agent(
            name="MultiToolAgent",
            instructions="Use the available tools to accomplish tasks.",
            mcp_servers=[local_server, remote_server]
        )

        # Run the agent
        result = await agent.run("Complete the requested task using appropriate tools.")
        return result

这种方法使您的代理可以通过标准化 MCP 接口访问本地和远程工具。

4.6 调试和监控你的 MCP 服务器

有效的调试和监控策略包括：

检查 MCP 服务器日志中是否存在工具执行过程中的错误
使用 OpenAI Agents SDK 的跟踪仪表板监控工具调用
测试诸如无效工具名称或服务器停机等边缘情况以确保稳健性
监控使用远程 SSE 服务器时的延迟，并在必要时通过缓存进行优化
利用 SDK 的内置跟踪功能，可以自动捕获：
- 调用 MCP 服务器列出工具
- MCP 函数调用相关信息

5.总结

使用 OpenAI Agents SDK 构建 MCP 服务器为使用外部工具和数据源增强 AI 代理开辟了新的可能性。标准化的 MCP 接口使跨不同环境的集成更简单、更可靠。

本篇博客作为参考，你可以创建功能强大的代理，通过模型上下文协议利用本地和远程资源。随着 MCP 生态系统的不断发展，您的代理将能够访问不断扩展的工具和功能。

6.结束语

这篇博客就和大家分享到这里，如果大家在研究学习的过程当中有什么问题，可以加群进行讨论或发送邮件给我，我会尽我所能为您解答，与君共勉！

另外，博主出新书了《深入理解Hive 》、同时已出版的《Kafka并不难学 》和《Hadoop大数据挖掘从入门到进阶实战 》也可以和新书配套使用，喜欢的朋友或同学，可以在公告栏那里点击购买链接购买博主的书进行学习，在此感谢大家的支持。关注下面公众号，根据提示，可免费获取书籍的教学视频。

如何使用 OpenAI Agents SDK 构建 MCP

1.概述

2.内容

2.1 什么是 MCP

2.2 MCP 服务器如何工作

2.3 MCP 实际上能做什么？

2.4 MCP 服务器和 API 之间有什么区别？

3.OpenAI Agents SDK

3.1 安装和配置

3.1.1 设置虚拟环境

3.1.2 安装 SDK

3.1.3 配置 API 密钥

3.1.4 验证安装

3.2 创建代理

3.2.1 代理初始化

3.2.2 基本代理

3.3 高级配置

4.使用 OpenAI MCP 集成的步骤

4.1 为 MCP 服务器设置开发环境

4.2 了解 OpenAI Agents SDK 中的 MCP 服务器类型

4.3 将 MCP 服务器连接到 OpenAI 代理

4.4 使用工具缓存优化性能

4.5 实现 MCP 服务器与代理工作流程的集成

4.6 调试和监控你的 MCP 服务器

5.总结

6.结束语