将 Pydantic AI 与 Bright Data 的 Web MCP 集成

在本指南中，你将学到：

什么是 Pydantic AI，以及它作为 AI 代理框架的独特之处。
为什么 Pydantic AI 与 Bright Data 的 Web MCP 服务端很适合搭配，用于构建可访问 Web 的代理。
如何将 Pydantic 与 Bright Data 的 Web MCP 集成，创建一个由真实数据支撑的 AI 代理。

让我们开始吧！

什么是 Pydantic AI？

Pydantic AI 是由 Pydantic（Python 最广泛使用的数据验证库）的作者开发的 Python 代理框架。

与其他AI 代理框架相比，Pydantic AI 更强调类型安全、结构化输出，以及与真实世界数据与工具的集成。具体而言，其主要特性包括：

支持 OpenAI、Anthropic、Gemini、Cohere、Mistral、Groq、HuggingFace、Deepseek、Ollama 等多家 LLM 提供商。
通过 Pydantic 模型进行结构化输出验证。
通过 Pydantic Logfire 进行调试与监控。
可选的工具、提示与验证器的依赖注入。
流式 LLM 响应与即时数据验证。
支持多代理和图式工作流，适配复杂任务。
通过 MCP 进行工具集成，包括 HTTP 调用。
符合直觉且熟悉的 Python 式开发流程，像写标准 Python 应用一样构建 AI 代理。
内置支持单元测试与迭代式开发。

该库为开源项目，GitHub 上已获得1.1 万+ Star。

为何将 Pydantic AI 与 MCP 服务器结合以进行 Web 数据检索

用 Pydantic AI 构建的 AI 代理会继承底层 LLM 的局限性，例如无法访问实时信息，从而可能导致不准确的回答。幸运的是，这个问题可以通过为代理配备最新数据与实时 Web 探索能力来轻松解决。

这正是Bright Data 的 Web MCP派上用场的地方。它基于 Node.js 构建，并与 Bright Data 的一系列面向 AI 的数据检索工具集成。这些工具可使你的代理访问网页内容、查询结构化数据集、搜索全网，并即时与网页交互。

目前，服务器中可用的 MCP 工具包括：

工具	说明
`scrape_as_markdown`	使用高级提取选项从单个网页 URL 抓取内容，并以 Markdown 返回结果。可绕过机器人检测与 CAPTCHA。
`search_engine`	从 Google、Bing 或 Yandex 提取搜索结果，并以 Markdown 格式返回 SERP 数据（URL、标题、摘要）。
`scrape_as_html`	使用高级提取选项从 URL 获取网页内容，并返回完整 HTML。可绕过机器人检测与 CAPTCHA。
`session_stats`	提供当前会话中工具使用情况的统计信息。
`scraping_browser_go_back`	在抓取浏览器会话中后退到前一页面。
`scraping_browser_go_forward`	在抓取浏览器会话中前进到下一页面。
`scraping_browser_click`	通过选择器对特定元素执行点击操作。
`scraping_browser_links`	检索当前页面上的所有链接，包括文本与选择器。
`scraping_browser_type`	向抓取浏览器中的指定元素输入文本。
`scraping_browser_wait_for`	在继续之前，等待页面上的特定元素变为可见。
`scraping_browser_screenshot`	捕获当前浏览器页面的截图。
`scraping_browser_get_html`	获取浏览器当前页面的 HTML 内容。
`scraping_browser_get_text`	提取当前页面的可见文本内容。

此外，还提供 40 多个专用工具，可使用Web Scraper API从各类网站（如 Amazon、Yahoo Finance、TikTok、LinkedIn 等）收集结构化数据。例如，web_data_amazon_product 工具可通过输入一个有效的产品 URL 来采集亚马逊的详细结构化产品信息。

现在，来看一下如何在 Pydantic AI 中使用这些 MCP 工具！

如何在 Python 中将 Pydantic AI 与 Bright MCP 服务器集成

本节将介绍如何使用 Pydantic AI 构建一个 AI 代理。该代理将通过 Web MCP 服务器具备实时的数据抓取、检索与交互能力。

作为示例，我们会演示代理如何即时检索 Amazon 的产品数据。请记住，这只是众多可能用例之一。通过 MCP 服务器提供的 50+ 工具，AI 代理可以执行各种任务。

按照以下分步指南，使用 Pydantic AI 构建你的 Gemini + Bright Data MCP 驱动的 AI 代理！

先决条件

要复现实例代码，请确保本地已安装：

Python 3.10 或更高版本。
Node.js（推荐最新 LTS 版本）。

你还需要：

一个 Bright Data 账号。
一个 Gemini API Key（或其他受支持的 LLM 提供商的 API Key，例如 OpenAI、Anthropic、Deepseek、Ollama、Groq、Cohere、Mistral）。

暂时不用担心设置 API Key。后续步骤会指导你配置 Bright Data 与 Gemini 的凭据。

虽然不是严格要求，但以下背景知识将有助于你更好地理解本教程：

对 MCP 工作原理的基本了解。
对AI 代理如何运作的基本认识。
对 Web MCP 服务器及其可用工具有所了解。
对 Python 异步编程有基本认识。

步骤一：创建你的 Python 项目

打开终端，为项目创建一个新文件夹：

mkdir pydantic-ai-mcp-agent

pydantic-ai-mcp-agent 文件夹将保存你的 Python AI 代理的全部代码。

进入新建文件夹，并在其中创建一个虚拟环境：

cd pydantic-ai-mcp-agent
python -m venv venv

现在在你偏好的 Python IDE 中打开项目文件夹。我们推荐安装了 Python 扩展的 Visual Studio Code或PyCharm 社区版。

在项目根目录创建一个名为 agent.py 的文件。此时你的目录结构应如下所示：

pydantic-ai-mcp-agent/
├── venv/
└── agent.py

agent.py 目前还是空的，但很快就会写入将 Pydantic AI 与 Bright Data MCP 服务器集成的主要逻辑。

在 IDE 的终端中激活虚拟环境。在 Linux 或 macOS 上执行：

source venv/bin/activate

在 Windows 上则运行：

venv/Scripts/activate

准备就绪！你已经搭建好用于构建具备 Web 数据访问能力的 AI 代理的 Python 开发环境。

步骤二：安装 Pydantic AI

在已激活的虚拟环境中，安装所需的 Pydantic AI 相关包：

pip install "pydantic-ai-slim[google,mcp]"

这将安装 pydantic-ai-slim，这是 pydantic-ai 的轻量版本，避免引入不必要依赖。

在本例中，由于你计划将代理与 Bright Data MCP 服务器集成，需要启用 mcp 扩展。而因为我们将使用 Gemini 作为 LLM 提供商，还需要 google 扩展。

注意：对于其他模型或提供商，请参阅模型文档了解所需的可选依赖。

接着，在 agent.py 文件中加入这些导入：

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio
from pydantic_ai.models.google import GoogleModel
from pydantic_ai.providers.google import GoogleProvider

很好！你现在可以使用 Pydantic AI 来构建代理了。

步骤三：设置环境变量读取

你的 AI 代理将通过 API 与 Bright Data 与 Gemini 等第三方服务交互。不要将 API Key 硬编码在 Python 代码中。请通过环境变量加载它们，以提升安全性与可维护性。

为简化流程，可以使用 python-dotenv。在激活的虚拟环境中运行：

pip install python-dotenv

然后在 agent.py 中导入该库并通过 load_dotenv() 加载环境变量：

from dotenv import load_dotenv

load_dotenv()

这样脚本就能从本地 .env 文件读取环境变量。现在，在项目文件夹中创建一个 .env 文件：

pydantic-ai-mcp-agent/
├── venv/
├── agent.py
└── .env     # <---------------

你可以像这样访问环境变量：

env_value = os.getenv("<ENV_NAME>")

别忘了从 Python 标准库导入 os 模块：

import os

搞定！你现在已经可以从 .env 文件中安全加载 API Key 了。

步骤四：开始使用 Bright Data MCP 服务器

如果你还没有账户，请创建一个 Bright Data 账号。如果已有，直接登录。

然后按照官方说明设置你的 Bright Data API Key。为简单起见，本节假设你使用具有 Admin 权限的 Token。

通过 npm 全局安装 Bright Data 的 Web MCP：

npm install -g @brightdata/mcp

然后使用以下 Bash 命令测试是否工作正常：

API_TOKEN="<YOUR_BRIGHT_DATA_API>" npx -y @brightdata/mcp

在 Windows 上，对应的 PowerShell 命令为：

$env:API_TOKEN="<YOUR_BRIGHT_DATA_API>"; npx -y @brightdata/mcp

在上述命令中，将 <YOUR_BRIGHT_DATA_API> 占位符替换为之前获取的实际 Bright Data API。两条命令都会设置所需的 API_TOKEN 环境变量，并通过 @brightdata/mcp npm 包启动 MCP 服务器。

如果一切正常，你的终端会显示类似如下的日志：

首次启动 MCP 服务器时，它会在你的 Bright Data 账户中自动创建两个默认 Zone：

mcp_unlocker：用于 Web Unlocker。
mcp_browser：用于 Browser API。

这两个 Zone 使 MCP 服务器能够运行其所暴露的全部工具。

要验证这一点，请登录 Bright Data 控制台并导航至“Proxies & Scraping Infrastructure”页面。你将看到以下 Zone 已自动创建：

MCP 服务器在启动时创建的 mcp_unlocker 与 mcp_browser 区域

注意：如果你未使用具有 Admin 权限的 API Token，则需要手动创建这些 Zone。无论如何，你也可以按官方文档所述，通过环境变量指定 Zone 名称。

默认情况下，Web MCP 仅暴露 search_engine 与 scrape_as_markdown 工具。要解锁浏览器自动化和结构化数据抽取等高级能力，请将环境变量 PRO_MODE=true 设置为开启专业模式。

太棒了！Web MCP 运行顺畅。

步骤五：连接到 Web MCP

既然你已经确认本机能运行 Web MCP，那就将它连接到你的代理！

先将 Bright Data API Key 添加到 .env 文件：

BRIGHT_DATA_API_KEY="<YOUR_BRIGHT_DATA_API_KEY>"

将 <YOUR_BRIGHT_DATA_API_KEY> 替换为你之前获取的实际 API Key。

然后在 agent.py 中读取它：

BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")

请记住，Pydantic AI 支持三种连接 MCP 服务器的方法：

使用 Streamable HTTP 传输。
使用 HTTP SSE 传输。
将服务器作为子进程运行，并通过 stdio 连接。

如果你对前两种方式不熟悉，可参考我们的SSE 与 Streamable HTTP指南。

在本例中，我们选择第 3 种方式：将服务器作为子进程运行。为此，按如下方式初始化 MCPServerStdio 实例：

server = MCPServerStdio(
    "npx",
    args=[
        "-y",
        "@brightdata/mcp",
    ],
    env={
        "API_TOKEN": BRIGHT_DATA_API_KEY,
        "PRO_MODE": "true" # Enable the Pro Mode to access all Bright Data tools
    },
)

上述代码本质上使用与你先前相同的 npx 命令来启动 Web MCP。它通过你的 Bright Data API Key 设置 API_TOKEN 环境变量以完成认证，并开启 PRO_MODE 以便访问所有可用工具（包括高级工具）。

很好！你已经在代码中成功配置了与本地 Web MCP 的连接。

步骤六：配置 LLM

注意：本节以 Gemini 为例。但你可以很容易地适配至 OpenAI 或其他受支持的 LLM，方法请参考官方文档。

首先获取你的 Gemini API Key，并将其添加到 .env：

GOOGLE_API_KEY="<YOUR_GOOGLE_API_KEY>"

将 <YOUR_GOOGLE_API_KEY> 替换为你的实际 Key。

接着导入用于集成 Gemini 的 Pydantic AI 库：

from pydantic_ai.models.google import GoogleModel
from pydantic_ai.providers.google import GoogleProvider

这些导入使你能够连接 Google API 并配置 Gemini 模型。注意你不需要手动从 .env 读取 GOOGLE_API_KEY，因为 GoogleProvider 底层使用了 google-genai，它会自动从 GOOGLE_API_KEY 环境变量读取 Key。

现在，初始化 Provider 与 Model 实例：

provider = GoogleProvider()
model = GoogleModel("gemini-2.5-flash", provider=provider)

太棒了！这将使 Pydantic AI 代理能够通过 Google API 连接到 gemini-2.5-flash 模型（可免费使用）。

步骤七：定义 Pydantic AI 代理

定义一个使用前述 LLM 并连接到 Web MCP 服务器的 Pydantic AI 代理：

agent = Agent(model, toolsets=[server])

完美！只需一行代码，你就实例化了一个 Agent 对象。该对象代表一个能够使用 Web MCP 服务器所暴露工具来处理任务的 AI 代理。

步骤八：启动你的代理

为了测试你的 AI 代理，你需要编写一个包含网页数据提取（或交互）任务的提示词。这有助于验证代理是否如预期使用了 Bright Data 的工具。

一个不错的起点是让它从某个 Amazon 页面获取产品数据，例如：

“请从 https://www.amazon.com/AmazonBasics-Pound-Neoprene-Dumbbells-Weights/dp/B01LR5S6HK/ 获取该产品的数据”

通常，如果你将这样的请求直接发送给 Gemini，可能会发生两种情况之一：

请求会由于 Amazon 的反爬系统（如 Amazon CAPTCHA）而失败，导致 Gemini 无法访问页面内容。
由于无法访问实时页面，它会返回虚构或错误的产品信息。

不妨直接在 Gemini 中尝试这个提示。你很可能会看到它无法访问该 Amazon 页面，然后给出捏造的产品细节，如下所示：

得益于与 Web MCP 服务器的集成，你的设置中不会出现这种情况。你的代理不会失败或凭空猜测，而是会使用 web_data_amazon_product 工具从 Amazon 页面检索实时的结构化产品数据，并以干净、可读的格式返回。

由于调用 Pydantic AI 代理的方法是异步的，请将执行逻辑包装在一个 async 函数中：

async def main():
    async with agent:
       result = await agent.run("Give me product data from https://www.amazon.com/AmazonBasics-Pound-Neoprene-Dumbbells-Weights/dp/B01LR5S6HK/")

    output = result.output
    print(output)

if __name__ == "__main__":
    asyncio.run(main())

别忘了从 Python 标准库导入 asyncio：

import asyncio

任务完成！接下来只需运行完整代码，看看代理的表现是否符合预期。

步骤九：整合所有内容

这是 agent.py 的最终代码：

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio
from pydantic_ai.models.google import GoogleModel
from pydantic_ai.providers.google import GoogleProvider
from dotenv import load_dotenv
import os
import asyncio

# Load the environment variables from the .env file
load_dotenv()

# Read the API key from the envs for integration with the Bright Data Web MCP server
BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")

# Connect to the Bright Data Web MCP server
server = MCPServerStdio(
    "npx",
    args=[
        "-y",
        "@brightdata/mcp",
    ],
    env={
        "API_TOKEN": BRIGHT_DATA_API_KEY,
        "PRO_MODE": "true" # Enable the Pro Mode to access all Bright Data tools
    },
)

# Configure the Google LLM model
provider = GoogleProvider()
model = GoogleModel("gemini-2.5-flash", provider=provider)

# Initialize the AI agent with Gemini and Bright Data's Web MCP server integration
agent = Agent(model, toolsets=[server])

async def main():
    async with agent:
       # Ask the AI Agent to perform a scraping task
       result = await agent.run("Give me product data from https://www.amazon.com/AmazonBasics-Pound-Neoprene-Dumbbells-Weights/dp/B01LR5S6HK/")
    # Get the result produced by the agent and print it
    output = result.output
    print(output)

if __name__ == "__main__":
    asyncio.run(main())

哇！借助 Pydantic AI 与 Bright Data，你仅用大约 50 行代码就构建了一个强大的、基于 MCP 的 AI 代理。

使用以下命令运行代理：