AI导哈

AI代理SDK工具包

一个基于Model Context Protocol (MCP)的AI代理开发工具包，利用OpenAI Agents SDK和Google Gemini API，提供工具、资源和提示模板，用于构建能够执行实时操作、访问数据和生成高质量输出的AI助手。

  • by beyg1
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 beyg1/agents-sdk-mcp

使用说明

代理SDK MCP项目

这个项目是（对……的）实施/实现 模型上下文协议（MCP） 使用OpenAI Agents SDK，但配置为利用Google AI提供的免费Gemini API。

为什么MCP对初学者很重要

作为一名学生，可以把MCP（假设为某人工智能框架或平台）视为将你的AI从一个简单的聊天机器人转变为强大助手的“桥梁”。没有MCP，像Gemini或GPT这样的AI模型只能基于它们被训练过的数据生成文本。但是，借助MCP的核心基本构件——工具， 资源，以及 提示（词/语）—你的AI可以：

  • 执行操作使用工具实时读取、编辑或处理数据。
  • 访问数据获取如文档或数据库等资源，以获得准确的回复。
  • 遵循模板使用提示（PROMPTS）来确保常见任务的一致性和高质量输出。 这一设计至关重要，因为它使人工智能能够处理现实世界中的场景，例如自动化文档处理或与应用程序编程接口（API）集成，从而成为构建高级人工智能应用的基础技能。

先决条件

在开始之前，请确保您已具备：

  • Python 3.13 或更高版本
  • uv 包管理器（用于管理依赖项和虚拟环境）
  • 一个Google AI API密钥（Gemini模型提供免费层级）

设置与初始化

  1. 创建一个新项目：

    uv init agents-sdk-mcp
cd agents-sdk-mcp

  2. 激活虚拟环境：

    source .venv/bin/activate

  3. 在VS Code中设置Python解释器：

    • 新闻界；媒体 Ctrl + Shift + P 或者 Cmd + Shift + P （在Mac上）
    • 选择“Python：选择解释器”
    • 选择通往你（目的地/目标）的路径 .venv 文件夹（例如。， /path/to/agents-sdk-mcp/.venv/bin/python)

  4. 安装依赖项：

    uv add mcp uvicorn openai-agents prompt-toolkit

  5. 设置环境变量： 创建一个 .env 在项目根目录中创建以下文件：

    LLM_MODEL_API_KEY=your_gemini_api_key_here
LLM_CHAT_COMPLETION_URL=https://generativelanguage.googleapis.com/v1beta/openai/
LLM_MODEL=models/gemini-flash-latest

项目架构

该项目由三个主要部分组成：

  • **CLI 聊天机器人main.py)**与AI代理交互的面向用户的界面。
  • **MCP 服务器（mcp_server.py）**为代理提供工具和资源。
  • **MCP 客户端 (mcp_client.py）**将聊天机器人连接到MCP服务器。

视觉建筑概览

以下是一个美人鱼图，展示了数据流以及MCP原语（工具、资源、提示）是如何集成的：

graph TD
    A[User Input] --> B["CLI Chatbot\n(main.py)"]
    B --> C["MCP Client\n(mcp_client.py)"]
    C --> D["MCP Server\n(mcp_server.py)"]
    D --> E["Tools\n(e.g., read_docs, edit_docs)"]
    D --> F["Resources\n(e.g., docs://documents)"]
    D --> G["Prompts\n(e.g., /summarize)"]
    E --> H["AI Model\n(Gemini via OpenAI SDK)"]
    F --> H
    G --> H
    H --> I["Response back to User"]

    subgraph "MCP Primitives"
        E
        F
        G
    end

MCP服务器运行在 http://localhost:8000/mcp/ 并且为了使集成正常工作，必须在聊天机器人之前启动。

执行项目

  1. 启动MCP服务器：

    uv run uvicorn mcp_server:mcp_app --reload
    • 这会在后台运行服务器。请保持这个终端窗口打开。

  2. 运行CLI聊天机器人：

    uv run main.py
    • 这将启动一个交互式聊天会话，您可以在其中向智能助手提问。

  3. 测试MCP客户端（可选）：

    uv run mcp_client.py
    • 这将列出可用的工具，并演示如何调用其中一个（例如，读取文档）。

设计细节

本节将详细分解核心组件及其协同工作方式，重点介绍MCP（多上下文处理）原语。每个部分都包含示例，帮助您理解如何实现类似的设置。

main.py：程序的入口点

这个文件是项目的“指挥者”。它

  1. 从（指定位置）加载环境变量 .env （例如，API密钥）。
  2. 连接到MCP服务器（运行于 http://localhost:8000/mcp/）。
  3. 通过OpenAI Agents SDK，使用Gemini模型初始化AI代理。
  4. 启动CLI聊天界面以供用户交互。

示例当你跑步时 uv run main.py它会检查你的 .env 文件，设置代理，并启动聊天。然后，AI可以根据您的查询决定是否使用工具，比如，如果您要求摘要，它会决定阅读文档。

`mcp_server.py`：工具与资源提供者

此服务器提供MCP（管理控制协议）原语：

  • 工具可由AI调用的可执行函数（例如。， read_docs 读取文件）。
  • 资源数据访问点（例如。， docs://documents （用于列出文件）。
  • 提示用于生成一致回复的模板（例如，总结提示）。 它使用了 FastMCP 库用于作为无状态HTTP服务器运行。

示例如果人工智能需要编辑文档，它会调用 edit_docs 通过服务器调用工具，服务器执行操作并返回结果。

mcp_client.py：连接服务器的桥梁

这个客户端负责管理通信：

  • 通过HTTP连接到MCP服务器。
  • 列出并调用工具，读取资源，并获取提示。
  • 处理响应和错误，以实现无缝集成。

示例当你在聊天中输入“@docs://deposition.md”时，客户端会从服务器获取文档内容，并将其注入到AI的上下文中。

工具实施

工具是你的AI可以执行的“操作”，就像程序中的函数一样。AI会根据用户输入来决定何时调用这些工具。以下是分步分解的示例。

示例工具： read_docs

  • 描述读取文档并将其内容作为文本返回，以便人工智能处理。
  • 参数： doc_id （例如，“deposition.md”）。
  • 它是如何运作的 （逐步进行）：
    1. 用户问：“请总结一下deposition.md的内容。”
    2. AI判定需要文档内容。
    3. AI通话 read_docs 通过MCP服务器。
    4. 服务器获取并返回文本。
    5. 人工智能利用这些内容生成摘要。
  • 在聊天中的使用如果相关，AI会自动调用它——无需您直接调用。
  • 学习小贴士这个工具展示了人工智能如何“读取”外部数据，从而能够执行如总结或分析等任务。

示例工具： edit_docs

  • 描述通过替换文本来修改文档。
  • 参数： doc_id， old_str， new_str。
  • 它是如何工作的 （逐步进行）：
    1. 用户说：“在report.md中将‘old text’更改为‘new text’。”
    2. AI识别出需要编辑。
    3. AI通话 edit_docs （与）参数一起。
    4. 服务器更新文档并确认。
    5. AI 以更新后的内容作出回应。
  • 在聊天中的使用AI根据您的指示无缝处理编辑工作。
  • 学习小贴士展示了由人工智能驱动的修改功能，对自动化处理（如法律文件中的修正）非常有用。

这些工具由大型语言模型（Gemini）驱动，使人工智能能够进行动态推理和执行操作。

资源

资源就像“数据端点”，使人工智能能够访问信息，如文件或数据库，而无需将所有内容硬编码。

服务器端实现mcp_server.py）

  • list_docs() 可以翻译为“列出文档列表”或“显示文档列表”，具体取决于上下文和语境。在编程或技术文档中，这个函数通常用于返回或展示一系列文档的名称或标识列出所有可用文档（通过 docs://documents）。
  • **获取文档（doc_id）**获取特定文档的内容（例如。， docs://deposition.md）。

示例服务器将样本文档存储在内存中。当人工智能需要数据时，它会调用这些资源来“查询”信息。

客户端使用（mcp_client.py)

  • **读取资源(uri)**检索并格式化资源数据（例如，文本或JSON）。

它是如何工作的 （逐步进行）：

  1. 用户在聊天中输入：“@docs://deposition.md”。
  2. CLI 识别“@”前缀并触发资源获取。
  3. 客户端向服务器发送对该URI的请求。
  4. 服务器返回文档内容。
  5. 为人工智能添加了上下文内容，以便提供更全面的回应。
  • 在聊天中的使用在消息前加上“@”以访问资源（例如，“@docs://documents”以列出所有文档）。

学习小贴士资源使人工智能能够“记住”或访问外部数据，从而使响应更加准确——就像参考真实文档来总结一样。

测试技巧:

  • 使用Postman（从...导入） postman/ 文件夹）以直接测试端点。
  • 在命令行界面（CLI）中，使用“@”进行聊天时的快速访问。

提示

提示是可重复使用的模板，用于引导人工智能为常见任务生成一致且高质量的回复，从而减少了用户编写详细指令的需求。

服务器端定义mcp_server.py)

  • 服务器定义了标准提示（例如，用于摘要生成或Markdown转换）。

客户端使用（mcp_client.py)

  • 获取并应用提示以增强人工智能交互体验。

它是如何工作的 （逐步进行）：

  1. 用户在聊天中输入：“/summarize”。
  2. CLI 识别“/”前缀并加载摘要提示。
  3. 查询（例如，“使用以下模板总结以下文档。”）和提示一同发送给AI。
  4. AI根据模板生成结构化回复。
  • 在聊天中的使用在命令前加上“/”以列出或使用提示（例如，输入“/list_prompts”查看可用提示）。

示例一个提示可能会指示AI“先概述，再列出要点，最后以结论结尾”来进行总结，以确保输出的可靠性。

学习小贴士提示语使人工智能行为标准化，从而更容易获得专业成果——就像在商业应用中使用模板来生成报告一样。

学习成果与设置指南

通过按照本README文件设置此项目，您获得了使用MCP（可能指某种软件或系统）的实践经验，使您能够建立自己的系统。关键收获：

  • 理解MCP原语了解工具（操作）、资源（数据访问）和提示（模板）如何赋能人工智能执行实际任务。
  • 构建人工智能代理练习将大型语言模型（LLMs）与外部系统集成以实现自动化。
  • CLI（命令行界面）和网络技术设置服务器、客户端和交互界面。
  • 实际应用了解这如何适用于文档管理、API集成等。

您个人MCP（Microsoft Certified Professional，微软认证专业人员）的下一步行动：

  1. 扩展服务器通过修改添加更多工具（例如，网络爬虫） mcp_server.py.
  2. 定制资源与数据库或API进行集成 mcp_server.py。
  3. 创建提示根据您的需求定义模板，并将其添加到服务器中。
  4. 测试并迭代使用命令行界面（CLI）或Postman进行实验，然后构建你自己的客户端。

快乐编码！如果您遇到任何问题，请检查控制台输出，查找与API密钥或服务器连接相关的错误。

相关 MCP