如何使用 OpenAI Agents SDK 构建 MCP

news/2025/4/1 11:44:18/文章来源:https://www.cnblogs.com/smartloli/p/18801374

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, Runneragent = 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, Runneragent = 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 servertools = await server.list_tools()# Create an agent that uses the MCP serveragent = Agent(name="Assistant",instructions="Use the filesystem tools to help the user with their tasks.",mcp_servers=[server])# Run the agentresult = 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 calltools = await server.list_tools()

缓存的重要注意事项：

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

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

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

from openai_agents import Agent, MCPServerStdio, MCPServerSseasync def run_agent_with_mcp_servers():# Initialize local stdio MCP serverlocal_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 serversagent = Agent(name="MultiToolAgent",instructions="Use the available tools to accomplish tasks.",mcp_servers=[local_server, remote_server])# Run the agentresult = 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大数据挖掘从入门到进阶实战》也可以和新书配套使用，喜欢的朋友或同学， 可以在公告栏那里点击购买链接购买博主的书进行学习，在此感谢大家的支持。关注下面公众号，根据提示，可免费获取书籍的教学视频。

 

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.hqwc.cn/news/908432.html

如若内容造成侵权/违法违规/事实不符，请联系编程知识网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

C语言打卡学习第11天（2025.3.30）（补发）

C语言打卡学习第11天（2025.3.30）（补发）

冒泡排序的一个学习。还了解了一个快速排序的“挖坑法”，能省变量位置，但挺难写的，挺有意思：把数组第一个元素放一个空作为一个标准值，第一个位置就空了出来，然后将第一个“暂时标准值”从最后一个数开始比较，后面小就放到第一个“坑”，然后“坑”又到后面了，再从前面…
阅读更多...
C语言打卡学习第10天（2025.3.29）（补发）

C语言打卡学习第10天（2025.3.29）（补发）

指针和数组的学习，数组现在能做到基本掌握和简单运用，指针有些难，还是得练
阅读更多...
C语言打卡学习第8、9天（2025.3.27、8）（补发）

C语言打卡学习第8、9天（2025.3.27、8）（补发）

做了些题
阅读更多...
FastAPI中的Pydantic密码验证机制与实现

FastAPI中的Pydantic密码验证机制与实现

title: FastAPI中的Pydantic密码验证机制与实现 date: 2025/03/31 00:04:51 updated: 2025/03/31 00:04:51 author: cmdragon excerpt: FastAPI 中通过 Pydantic 模型实现密码验证，采用分层机制确保高效与灵活扩展。验证流程包括基础类型检查、长度验证、复杂度验证和泄露检…
阅读更多...
PicGo+Github图床配置

PicGo+Github图床配置

PicGo+Github图床配置 参考 PicGo指南 PicGo+Github图床配置配置 Github 图床 创建 Github 仓库登录 Github，新建一个公开（Public）或私有（Private）仓库 (我个人选择新建公开仓库) 用于存储图片，仓库名任意取，例如 image-host​，进入新建的仓库，点击 Create a codespac…
阅读更多...
独立按键控制 LCD1602 显示不同的谚语

独立按键控制 LCD1602 显示不同的谚语

前言 今天我又学到了一句话 “好的开始是成功的一半” 英语就是 “Well Begun Is Half Done” 所以希望能够通过独立按键，来控制LCD1602显示不同的谚语 演示函数数组的使用 错误用法 void (*sayings)(void)[MAX_SAYING] = {attitude,well_begun};报错正确用法 void (*sayings[…
阅读更多...
OpenEuler RISC-V 上跑bitcoin（实战版）

OpenEuler RISC-V 上跑bitcoin（实战版）

不久前刚在OpenEuler 24.09 RISC-V上部署了 bitcoin，不过还没跑起来，这次我打算在这个环境下面运行一些应用服务，体验一下 OERV 的开发感觉。编译出来的 bitcoin 主要有几个命令，bitcoin-cli、bitcoind、bitcoin-util、bitcoin-wallet、bitcoin-tx和test_bitcoin。bitcoind…
阅读更多...
javawebDay3-Maven框架

javawebDay3-Maven框架

1.添加依赖 eg<dependencies><dependency><groupId></groupId><artifactId></artifactId></dependency></dependencies>从外部导入jar包等无需手动添加依赖 2.集成度高,eclipse和intellIDEA都能使用,在不同的操作系统也可以使…
阅读更多...
Five Hundred Miles

Five Hundred Miles

一百英里 是自由，是初出茅庐的憧憬。 二百英里 是快乐，是逃离故里的喜悦。 三百英里 是忧伤，是萦绕心间的挂念。 四百英里 是思恋，是莺歌燕舞的家乡。 五百英里 是乡愁，是一去不返的凄凉。
阅读更多...
昆明理工大学25届研究生奖学金覆盖范围

昆明理工大学25届研究生奖学金覆盖范围

阅读更多...
day8华为机试题库继续

day8华为机试题库继续

HJ3思路1：冒泡排序思路2：哈希表HJ4public String substring(int beginIndex) public String substring(int beginIndex, int endIndex)
阅读更多...
Vue3管理系统开发个人信息，修改密码页面

Vue3管理系统开发个人信息，修改密码页面

把默认路由先重定向到/login，用户每次启动项目重新登录{path:/,redirect:/login},个人中心页面 子组件发送请求更新父组件内容const emit =defineEmits([updateUser])//更新缓存数据localStorage.setItem(pro1-user,JSON.stringify(data.form))emit(updateUser) 父级const upd…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023