Claude Agent SDK + Bright Data Web MCP 集成指南

在这篇博客文章中，你将看到：

什么是 Claude Agent SDK，以及它的独特之处。
为什么通过 Bright Data 的 Web MCP 来扩展它，是构建更强大 AI 智能体的理想方式。
如何将使用 Claude Agent SDK 构建的 AI 智能体，通过 Web MCP 连接到 Bright Data 的 Web 工具。

让我们开始吧！

什么是 Claude Agent SDK？

Claude Agent SDK 是 Anthropic 推出的开源框架，使你能够基于 Claude Code 构建自主 AI 智能体。它允许智能体读取文件、运行命令、搜索网页、编辑代码，并与工具交互，而无需编写自定义的编排逻辑。

该 SDK 提供了一个稳健的智能体循环（agent loop），可以收集上下文、采取行动并验证结果，从而让你的智能体能够可靠地执行复杂工作流。该 SDK 可用于：

Python：该库在 GitHub 上拥有超过 4.5k 个星标。
TypeScript：该库在 GitHub 上拥有 720+ 个星标。

Claude Agent SDK 支持内置工具、子智能体（subagents），并可与 MCP（Model Context Protocol）进行原生集成，以对接外部服务。它的目标是让 AI 智能体开发变得简单，通过一个简洁的 API 构建专用助手、研究型智能体和自动化机器人，充分利用 Claude 的推理能力与工具执行能力。

为什么要用 Bright Data 的 Web 数据能力扩展 Claude Agent SDK

深入了解 Claude 智能体的限制，以及如何应对这些限制！

关于 Claude Agent SDK 工具的一些背景

即便最强大的 Claude AI 模型也存在所有 LLM 都固有的限制。这些限制源于 AI 模型训练数据本质上是对过去的快照。

因此，LLM 只能生成基于其训练内容的答案。当被问到它不知道的事情（或非常近期的事件）时，它可能直接失败，或者更糟，产生幻觉（hallucinations）。此外，它们也无法自行与外部世界交互。

由于 AI 智能体由 LLM 驱动，因此会继承这些限制。同时，智能体有一个关键优势：它们可以使用工具！工具允许智能体调用外部服务和系统，从而扩展其原本仅依赖 LLM 的有限能力。

Claude Agent SDK 为智能体提供了一组默认的内置工具，用于处理文件、运行命令、搜索网页、编辑代码等。

它还引入了一种独特的自定义工具定义方式。在 Claude Agent SDK 中，自定义工具以进程内（in-process）MCP 服务器的形式实现。这并不令人意外，因为 MCP 由 Anthropic（Claude 背后的公司）定义。

尽管 Claude Agent SDK 的默认工具很有用，但对于生产级用例而言并不总是足够。实践中，更好的方式是集成专门的第三方服务提供商，用来解决常见的 LLM 限制，例如知识过时以及与实时 Web 的交互能力有限。

这就是 Bright Data Web MCP 登场的地方！

介绍 Bright Data Web MCP

Claude Agent SDK 的自定义工具在幕后运行于 MCP 之上。因此，用一个已经提供丰富、可直接用于生产的工具集的 MCP 来扩展智能体构建，是非常合理的。

Bright Data 的 Web MCP 提供 60+ 个 AI 就绪工具，用于自动化 Web 数据采集、结构化数据提取以及浏览器级交互。它既可作为远程服务使用，也可作为本地服务器使用，并且有一个公开仓库（GitHub 星标 2k+）作为支撑。

即使在免费层，MCP 服务器也会开放两个特别有用的工具（以及它们的批处理版本）：

工具	说明
`search_engine`	以 JSON 或 Markdown 格式获取 Google、Bing 或 Yandex 的搜索结果。
`scrape_as_markdown`	将任意网页抓取为干净的 Markdown，并绕过反爬措施。

Web MCP 真正大放异彩之处在于 Pro 模式。它解锁了用于从 Amazon、LinkedIn、Yahoo Finance、YouTube、TikTok、Zillow、Google Maps 等众多平台提取结构化数据的高级工具。此外，它还能让任何 AI 智能体具备像真人用户一样浏览网页并与网页交互的能力。

现在，让我们看看如何将 Bright Data Web MCP 集成到 Claude Agent SDK 中！

如何通过 Web MCP 将 Claude Agent SDK 连接到 Bright Data 工具

在这份分步指南中，你将学习如何通过 MCP，将 Bright Data 服务集成到使用 Claude Agent SDK 构建的 AI 智能体中。具体来说，你将把 Bright Data 的 Web MCP 连接到一个 Claude Agent SDK AI 智能体，使其能够访问所有可用的 Web 数据工具。

注意：Claude Agent SDK 也提供 TypeScript 版本。下面的章节可以通过参考官方文档，很容易从 Python 转换为 JavaScript 或 TypeScript。

按照以下说明操作即可！

前置条件

要跟随本教程，请确保你满足以下要求：

本地已安装 Python 3.10 或更高版本。
你的机器上已安装 Claude Code。
一个有可用额度的 Claude API key。
一个带 API key 的 Bright Data 账号。

注意：本教程后面会有专门章节，引导你完成为 Web MCP 使用而设置 Bright Data 账号的过程。

请记住，Claude Agent SDK 使用 Claude Code 作为运行时，这也是为什么必须在本地安装 Claude Code。分步说明请参考我们关于 Claude Code + Bright Data Web MCP 集成的指南。

最后，对 MCP 协议的基本了解以及对 Web MCP 提供的工具的熟悉，会有所帮助。

步骤 #1：在 Python 中搭建 Claude Agent SDK 项目

首先，验证你的机器上是否已安装 Claude Code。运行以下命令：

claude --version

你应该会看到类似下面的输出：

2.1.29 (Claude Code)

如果看到了，说明很好！这确认了使用 Claude Agent SDK 的主要前置条件已经就绪。

接下来，创建一个项目目录，然后在终端进入该目录：

mkdir claude-agent-sdk-bright-data-ai-agent cd claude-agent-sdk-bright-data-ai-agent

现在，在项目中初始化一个虚拟环境：

python -m venv .venv

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

claude-agent-sdk-bright-data-ai-agent/ ├── .venv/ └── agent.py

agent.py 文件将包含你的 AI 智能体逻辑：使用 Claude Agent SDK 构建，并与 Bright Data Web MCP 交互。

用你喜欢的 Python IDE 打开项目文件夹。例如在 PyCharm Community Edition 或安装了 Python 扩展的 Visual Studio Code 中打开。

现在，激活你刚才创建的虚拟环境。在 Linux 或 macOS 上运行：

source .venv/bin/activate

在 Windows 上则执行：

.venv/Scripts/activate

虚拟环境激活后，安装所需依赖：

pip install claude-agent-sdk python-dotenv

该应用的依赖包括：

claude-agent-sdk：用于通过 Claude Agent SDK 在 Python 中构建 AI 智能体。
python-dotenv：用于从本地 .env 文件加载密钥（例如你的 Claude API key 和 Bright Data API key）。

全部就绪！你的 Python 环境现在已准备好使用 Claude Agent SDK 构建 AI 智能体。

步骤 #2：为加载环境变量做准备

你的 AI 智能体将连接到第三方服务，例如 Bright Data，以及（显然的）Claude。为此，你需要使用这些服务账号对应的 API key。最佳实践是：不要把凭据直接硬编码在源代码中。

相反，你应该从 .env 文件加载所需的 API key。这正是你在上一步安装 python-dotenv 的原因。先在 agent.py 中导入该库：

from dotenv import load_dotenv

然后，在项目根目录创建一个 .env 文件：

claude-agent-sdk-bright-data-ai-agent/
├─── .venv/
├─── agent.py
└─── .env # <-----

.env 文件将存储你的 Claude API key 和 Bright Data API key，这两个是本项目所需的密钥。

现在，通过在 agent.py 中调用以下函数，从 .env 文件加载环境变量：

load_dotenv()

很好！你的脚本现在可以从环境变量中安全读取敏感凭据，从而避免将它们放入代码库。

步骤 #3：开始使用 Claude Agent SDK

在 agent.py 中添加以下代码，使用 Claude Agent SDK 构建一个简单的 AI 智能体：

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.types import StreamEvent

async def main():
    # Configure the Claude agent
    options = ClaudeAgentOptions(
        model="claude-haiku-4-5",     # Replace with your preferred Claude model
        include_partial_messages=True # Enable streaming responses
    )

    # The prompt sent to the agent
    prompt = "Hey! How is it going?"

    # Agentic loop: Streams events returned by the Claude Agent SDK
    async for message in query(prompt=prompt, options=options):
        # Intercept only streaming events
        if isinstance(message, StreamEvent):
            event = message.event
            event_type = event.get("type")

            # Handle incremental text output
            if event_type == "content_block_delta":
                delta = event.get("delta", {})

                if delta.get("type") == "text_delta":
                    # Print streamed text as it arrives
                    print(delta.get("text", ""), end="", flush=True)

asyncio.run(main())

该脚本有三个主要组成部分：

options：用于配置智能体。在这个例子中，智能体使用 Claude Haiku 4.5 模型并启用流式响应，从而可以逐步打印输出。
prompt：定义你希望 Claude AI 智能体做什么。Claude 会基于该输入自动决定如何处理任务。
query：启动智能体循环的主要入口点。它返回一个异步迭代器，因此你使用 async for 在 Claude 推理、调用工具、观察结果并生成输出时流式接收消息。

async for 循环会在 Claude “思考”期间持续运行。每次迭代可能产生不同类型的消息，例如推理步骤、工具调用、工具结果或最终答案。在这个例子中，你只是在将最终文本输出流式打印到终端。

要成功运行，Claude Agent SDK 需要访问 Claude API。默认情况下，它会从 ANTHROPIC_API_KEY 环境变量读取 API key。因此，将其加入你的 .env 文件，如下：

ANTHROPIC_API_KEY="<YOUR_ANTHROPIC_API_KEY>"

将 <YOUR_ANTHROPIC_API_KEY> 替换为你实际的 Anthropic Claude API key。

注意：如果你的 Claude Agent SDK 智能体无法访问该 API key，它会报以下错误：

Your organization does not have access to Claude. Please login again or contact your administrator.

在考虑并包含上一步的代码后，通过运行以下命令启动智能体：

python agent.py

在终端中，你应该会看到类似下面的流式响应：
AI 智能体生成的流式响应
太棒了！响应与输入提示相匹配，这意味着由 Claude Agent SDK 驱动的 AI 智能体工作正常。

步骤 #4：从 Bright Data Web MCP 开始

请记住，Claude Agent SDK 中的自定义工具是通过进程内 MCP 服务器实现的。基于这个原因，直接将你的 AI 智能体连接到一个 Bright Data Web MCP 服务器实例是合理的。

毕竟，如果你通过直接集成 Bright Data 服务来定义自定义工具，再通过 MCP 暴露出来，就不太有意义。因为已经有一个官方（而且被广泛使用！）的 MCP 服务器。

在本节中，我们将展示如何连接到一个本地实例。同时，你也可以连接到远程 Web MCP 服务器，以实现更可扩展、企业级的部署。

在将 Claude Agent SDK 连接到 Bright Data 的 Web MCP 之前，先确认该 MCP 服务器可以在你的机器上运行！

首先，创建一个 Bright Data 账号。或者如果你已经有账号，直接登录即可。为了快速完成设置，请在控制台的 “MCP” 区域按向导操作：
Bright Data 账号中的 “MCP” 区域
否则，如需更多指导，请参考下方说明。

首先生成你的 Bright Data API key。你将很快使用该 API key 让本地 Web MCP 实例与 Bright Data 账号完成认证。由于你需要在代码中访问它，将其加入你的 .env 文件：

BRIGHT_DATA_API_KEY="<YOUR_BRIGHT_DATA_API_KEY>"

然后，在你的 agent.py 文件中读取它：

import os BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")

接着，通过 @brightdata/mcp 包全局安装 Web MCP：

npm install -g @brightdata/mcp

在 Linux/macOS 上，通过以下命令检查 MCP 服务器是否能在本地运行：

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

或者，在 PowerShell 中等效执行：

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

将占位符 <YOUR_BRIGHT_DATA_API> 替换为你实际的 Bright Data API token。这些（等效的）命令会设置所需的 API_TOKEN 环境变量，并在本地启动 Web MCP 服务器。

如果成功，你应该会看到类似下面的日志：
Bright Data Web MCP 启动日志

在首次启动时，Web MCP 包会自动在你的 Bright Data 账号中创建两个 zone：

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

这两个 zone 为 Web MCP 中的 60+ 工具提供支撑。请注意，你也可以覆盖这两个 zone 的默认名称，文档中有说明。

如果你想确认它们已创建，请进入 Bright Data 控制台中的 “代理与采集基础设施” 页面。你会看到这两个 zone 出现在 “My Zones” 表格中：
Web MCP 启动时创建的 mcp_unlocker 与 mcp_browser zones

现在，请记住 Web MCP 免费层仅允许你使用 search_engine 与 scrape_as_markdown 工具（以及它们的 batch 版本）。

要解锁全部 60+ 工具，你必须通过设置 PRO_MODE="true" 环境变量启用 Pro 模式：

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

或在 Windows 上：

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

重要：Pro 模式不包含在免费层中，并且会产生额外费用。

非常棒！你现在已确认 Web MCP 服务器能在你的机器上运行。接下来，你将配置 Claude Agent SDK 自动启动该服务器并连接到它。

步骤 #5：将 Claude Agent SDK 连接到 Web MCP

Claude Agent SDK 支持 MCP 连接，通过 ClaudeAgentOptions 类的 mcp_servers 选项实现。这让你的智能体能够直接与 Bright Data 的 Web MCP 通信。

要连接 Web MCP，按如下方式更新你的 options 变量：

options = ClaudeAgentOptions(
    # Connect to Bright Data's Web MCP
    mcp_servers={
        "bright_data": {
            "command": "npx",
            "args": ["-y", "@brightdata/mcp"],
            "env": {
                "API_TOKEN": BRIGHT_DATA_API_KEY,
                "PRO_MODE": "true" # To enable Pro mode
            }
        }
    },
    allowed_tools=["mcp__bright_data__*"], # Enable all Bright Data Web MCP tools 
    model="claude-haiku-4-5", # Replace with your preferred Claude model
    include_partial_messages=True, # Enable streaming responses
)

该设置与之前测试的 npx 命令一致，通过环境变量传递凭据与配置：

API_TOKEN：用于认证（必需）。将其设置为你的 Bright Data API key。
PRO_MODE：用于启用 Pro 模式（必需）。

重要：allowed_tools 字段使用通配符以允许来自所配置 bright_data 服务器的全部工具。否则，Claude 驱动的智能体虽然能看到工具，但无法使用它们。

如果你不想在代码中指定 mcp_servers 选项，也可以在项目根目录创建一个 .mcp.json 文件，结构如下：

{
  "mcpServers": {
    "bright_data": {
        "command": "npx",
        "args": ["-y", "@brightdata/mcp"],
        "env": {
            "API_TOKEN": "<YOUR_BRIGHT_DATA_API_KEY>",
            "PRO_MODE": "true"
        }
    }
  }
}

为验证 Web MCP 连接，用一个简单提示测试智能体：

prompt = "Which Bright Data MCP tool do you have access to?"

在 Pro 模式（PRO_MODE="true"）下，响应应列出全部可用的 60+ 工具，类似如下：
AI 智能体列出的 Web MCP 工具
现在，你的智能体可以看到并使用 Web MCP 服务器中的所有高级工具。任务完成！你使用 Claude Agent SDK 构建的 AI 智能体，现已通过 Web MCP 工具扩展了 Bright Data 的 Web 数据能力。

步骤 #6：运行智能体

为了展示集成 Bright Data Web MCP 后 AI 智能体能变得多有效，你需要一个合适的 prompt。尤其是，该 prompt 应涉及 Web 数据获取和/或 Web 交互。

例如，假设你想构建一个 AI 智能体来监控竞争对手网站：自动截图并提取页面文本。这是标准 AI 智能体在没有合适工具的情况下无法独立完成的任务。

假设 Nike 是你的竞争对手。你可以写一个 prompt：

prompt = """
Open a scraping-browser session and navigate to the following web page:
"https://www.nike.com/"
Wait for the page to fully load, then capture a full-page screenshot. Also, extract the entire page text. Save the screenshot to a local `screenshot.png` file and the page text to a local `text.txt` file.
"""

借助 Bright Data Web MCP 高级工具提供的浏览能力，AI 智能体现在可以：

通过 Browser API 在云端打开远程浏览器会话，绕过常见反爬保护并访问几乎任意网页。
等待页面完全加载。
截取整页截图并提取所有可见文本。

最后，智能体使用 Claude Agent SDK 提供的内置工具将输出按要求保存到磁盘。

请注意，要启用图像处理与写入磁盘，你还需要以下两个额外选项：

options = ClaudeAgentOptions(
    # ...
    permission_mode="acceptEdits", # To enable the agent to write files to disk
    max_buffer_size=10 * 1024 * 1024, # Increase to 10MB for image handling
)

由于智能体运行会涉及工具使用，因此也应更新流式输出逻辑，以便同时拦截与工具调用相关的事件。按如下方式更新你的 async for 循环：

# Track the current tool and accumulate its input JSON
current_tool = None
tool_input = ""

# Agentic loop: Streams events returned by the Claude Agent SDK
async for message in query(prompt=prompt, options=options):
     # Intercept only streaming events
    if isinstance(message, StreamEvent):
        event = message.event
        event_type = event.get("type")

        if event_type == "content_block_start":
            # New tool call is starting
            content_block = event.get("content_block", {})
            if content_block.get("type") == "tool_use":
                current_tool = content_block.get("name")
                tool_input = ""
                print(f"\nStarting tool: {current_tool}")

        # Handle incremental text output
        elif event_type == "content_block_delta":
            delta = event.get("delta", {})
            if delta.get("type") == "text_delta":
                 # Print streamed text as it arrives
                print(delta.get("text", ""), end="", flush=True)
            elif delta.get("type") == "input_json_delta":
                # Accumulate JSON input as it streams in
                chunk = delta.get("partial_json", "")
                tool_input += chunk

        elif event_type == "content_block_stop":
            # Tool call complete (show final input)
            if current_tool:
                print(f"Tool {current_tool} called with: {tool_input}")
                current_tool = None

该逻辑将帮助你更好地理解智能体调用了哪些工具以及各自的输入。很棒！剩下的就是对智能体进行测试。

步骤 #7：测试 AI 智能体

最终你的 agent.py 文件将包含：

from dotenv import load_dotenv
import os
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
from claude_agent_sdk.types import StreamEvent

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

# Access the Bright Data API key environemnt variable
BRIGHT_DATA_API_KEY = os.getenv("BRIGHT_DATA_API_KEY")

async def main():
    options = ClaudeAgentOptions(
        # Connect to Bright Data's Web MCP
        mcp_servers={
            "bright_data": {
                "command": "npx",
                "args": ["-y", "@brightdata/mcp"],
                "env": {
                    "API_TOKEN": BRIGHT_DATA_API_KEY,
                    "PRO_MODE": "true"  # To enable Pro mode
                }
            }
        },
        allowed_tools=["mcp__bright_data__*"],  # Enable all Bright Data Web MCP tools
        model="claude-haiku-4-5",     # Replace with your preferred Claude model
        include_partial_messages=True, # Enable streaming responses
        permission_mode="acceptEdits", # To enable the agent to write files to disk
        max_buffer_size=10 * 1024 * 1024, # Increase to 10MB for image handling
    )

     # The prompt sent to the agent
    prompt = """
    Open a scraping-browser session and navigate to the following web page:
    "https://www.nike.com/"
    Wait for the page to fully load, then capture a full-page screenshot. Also extract the entire page text. Save the screenshot to a local `screenshot.png` file and the page text to a local `text.txt` file.
    """

    # Track the current tool and accumulate its input JSON
    current_tool = None
    tool_input = ""

    # Agentic loop: Streams events returned by the Claude Agent SDK
    async for message in query(prompt=prompt, options=options):
         # Intercept only streaming events
        if isinstance(message, StreamEvent):
            event = message.event
            event_type = event.get("type")

            if event_type == "content_block_start":
                # New tool call is starting
                content_block = event.get("content_block", {})
                if content_block.get("type") == "tool_use":
                    current_tool = content_block.get("name")
                    tool_input = ""
                    print(f"\nStarting tool: {current_tool}")

            # Handle incremental text output
            elif event_type == "content_block_delta":
                delta = event.get("delta", {})
                if delta.get("type") == "text_delta":
                     # Print streamed text as it arrives
                    print(delta.get("text", ""), end="", flush=True)
                elif delta.get("type") == "input_json_delta":
                    # Accumulate JSON input as it streams in
                    chunk = delta.get("partial_json", "")
                    tool_input += chunk

            elif event_type == "content_block_stop":
                # Tool call complete (show final input)
                if current_tool:
                    print(f"Tool {current_tool} called with: {tool_input}")
                    current_tool = None

asyncio.run(main())

通过以下命令启动：

python agent.py

如果你运行该智能体，你应该会看到类似如下输出：
AI 智能体生成的初始输出

如你所见，智能体连接到 Web MCP 并使用了以下工具：

mcp__bright_data__scraping_browser_screenshot：用于截取整页截图
mcp__bright_data__scraping_browser_get_text：用于从网页中提取所有文本

然后它使用 “Write” 工具将输出保存到请求的文件中。运行后，你的项目根目录应包含 screenshot.png 和 text.txt：
智能体生成的文件
打开 screenshot.png，即可查看目标 Nike 首页的整页截图：
注意：由智能体截取的 Nike 首页截图

打开 text.txt，查看从上述页面提取的文本：
从页面中提取的文本
瞧！通过 Claude Agent SDK 编排，并借助 Bright Data Web MCP 扩展后，你的 AI 智能体现在已经能够处理网页浏览以及更多能力！

结论

在本教程中，你学习了如何在 Claude Agent SDK 中通过 MCP 集成来利用自定义工具，从而构建扩展型 AI 智能体。具体来说，你了解了为什么以及如何通过将由 Claude Agent Python SDK 驱动的 AI 智能体连接到 Bright Data 的 Web MCP 来增强其能力。

该集成为你的 Claude 驱动型 AI 智能体提供了强大的能力，例如网页搜索、结构化数据提取、实时 Web 数据获取与自动化 Web 交互——从而支持广泛的智能体用例。

立即免费注册 Bright Data 账号，亲自体验 AI 就绪的 Web 数据工具吧！

联系销售开始免费试用