OpenAI代理SDK + Scrapeless：通过MCP为您的代理提供网络工具

TL;DR:

• OpenAI Agents SDK通过一个对象MCPServerStreamableHttp连接到Scrapeless MCP服务器，该对象携带端点和x-api-token头。
• await server.list_tools()返回所有21个工具——scrape_markdown、scrape_html、google_search、google_trends、scrape_screenshot以及一个包含16个工具的browser_*集合——仅设置了Scrapeless密钥。
• 与将MCP工具转换为独立对象的框架不同，SDK保持服务器作为一流连接：你将整个server交给代理，它会为你调用list_tools和call_tool。
• 你可以在代理介入之前直接调用任何工具，通过await server.call_tool("scrape_markdown", {"url": ...})——调用工具不需要模型密钥。
• 只有Runner.run需要一个模型提供者密钥，因为这是模型决定调用哪些工具的步骤。
• 从Scrapeless免费计划开始，让你的OpenAI Agents SDK代理使用真实的Web工具。

OpenAI Agents SDK是OpenAI用于在Python中构建自主应用的轻量级框架，代理的有效性仅取决于你提供的工具。基本安装没有访问实时网络的能力。模型上下文协议解决了这个问题：将SDK指向一个MCP服务器，该服务器暴露的每个工具都可以通过与手写功能工具相同的接口被你的代理调用。

本指南将SDK连接到Scrapeless MCP服务器，列出了其21个工具，实际调用了一个，然后将整个服务器附加到一个Agent上——经过实时端点验证。唯一需要模型提供者密钥的步骤是代理的生成调用，本文正是标注了这一界线所在的位置。

Scrapeless MCP服务器为代理提供的内容

Scrapeless MCP服务器直接暴露了代理可以调用的网络抓取和浏览器工具，因此抓取层并不是你构建或托管的东西。一个连接提供21个工具：scrape_markdown和scrape_html用于页面内容，google_search和google_trends用于搜索数据，scrape_screenshot用于截图，以及一个包含16个工具的browser_*集合，通过点击、输入、滚动和等待驱动云浏览器。

browser_*工具在Scrapeless云浏览器上运行，因此代理可以在没有本地浏览器的情况下导航互动页面，并读取实际渲染的内容。如果你想在不同的技术栈中连接同一服务器，LangChain + Scrapeless MCP指南涵盖了这一方面，而什么是MCP则解释了协议本身。

先决条件

• Python 3.10或更高版本。
• 从仪表板获取的Scrapeless API密钥，导出为SCRAPELESS_API_KEY。
• 仅用于代理运行的模型提供者密钥，例如OPENAI_API_KEY。加载和调用工具不需要密钥。

安装

安装 SDK。MCP 客户端包含在其中，所以没有额外需要添加的部分。

pip install "openai-agents==0.18.3"

在 shell 中设置你的 Scrapeless 密钥，并将占位符保留在源代码之外。

export SCRAPELESS_API_KEY="sk_your_key_here"

连接并加载工具

MCPServerStreamableHttp接受一个包含端点和头部的params字典，并且它是一个异步上下文管理器，因此连接在with块周围打开和关闭。list_tools执行握手并返回服务器的工具。

import asyncio
import os

from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    params = {
        "url": "https://api.scrapeless.com/mcp",
        "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    }
    async with MCPServerStreamableHttp(
        params=params, name="scrapeless", client_session_timeout_seconds=60
    ) as server:
        tools = await server.list_tools()
        names = sorted(tool.name for tool in tools)
        print("tool count:", len(names))
        print("tools:", ", ".join(names))


asyncio.run(main())

实时服务器返回21个工具，仅设置了Scrapeless密钥。

tool count: 21
tools: browser_click, browser_close, browser_create, browser_get_html, browser_get_text, browser_go_back, browser_go_forward, browser_goto, browser_press_key, browser_screenshot, browser_scroll, browser_scroll_to, browser_snapshot, browser_type, browser_wait, browser_wait_for, google_search, google_trends, scrape_html, scrape_markdown, scrape_screenshot

传输和消息层遵循模型上下文协议规范，该规范依赖于JSON-RPC 2.0规范。SDK还提供了MCPServerStdio，用于本地子进程服务器；Scrapeless服务器是一个托管的HTTP端点，因此可流式传输的HTTP类是这里的合适选择。

直接调用工具

在代理存在之前，您可以自己在服务器上调用任何工具。call_tool接受工具名称和参数字典，并返回CallToolResult，其content是一个块的列表；文本位于文本块中。

import asyncio
import os

from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    params = {
        "url": "https://api.scrapeless.com/mcp",
        "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    }
    async with MCPServerStreamableHttp(
        params=params, name="scrapeless", client_session_timeout_seconds=60
    ) as server:
        result = await server.call_tool("scrape_markdown", {"url": "https://quotes.toscrape.com/"})
        text = "".join(block.text for block in result.content if block.type == "text")
        print("markdown 字符数:", len(text))
        print("包含引用:", "爱因斯坦" in text)


asyncio.run(main())

调用返回页面的Markdown，内容检查确认返回了真实的文本。

markdown 字符数: 4308
包含引用: True

这就是代理从同一工具返回的形状：它可以推理的页面内容。OpenAI Agents SDK MCP文档覆盖了list_tools、call_tool和在工具集稳定时跳过重复握手的cache_tools_list选项。

将工具交给代理

在这里，SDK与工具适配器框架有所不同。您不需要转换工具并传递列表；您将整个server传递给代理的mcp_servers参数，代理在运行时调用list_tools和call_tool。这是需要模型提供商密钥的步骤。

注意：Runner.run需要像OPENAI_API_KEY这样的模型提供商密钥，而此处未设置。加载21个工具和上述直接的scrape_markdown调用在没有它的情况下运行良好。此块以其确切的形状显示；只有模型往返是先决条件的缺口。

import asyncio
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    params = {
        "url": "https://api.scrapeless.com/mcp",
        "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    }
    async with MCPServerStreamableHttp(
        params=params, name="scrapeless", client_session_timeout_seconds=60
    ) as server:
        agent = Agent(
            name="web_agent",
            instructions="使用Scrapeless工具来获取和读取页面。",
            mcp_servers=[server],
        )
        result = await Runner.run(
            agent,
            "使用scrape_markdown获取https://quotes.toscrape.com/并列出前三个引用及其作者。",
        )
        print(result.final_output)


asyncio.run(main())

在运行时，模型读取任务，使用URL调用scrape_markdown，接收直接调用已经返回的Markdown，并写出答案。无论哪种方式，工具都是相同的——唯一的新成分是决定何时调用它们的模型。

结论

OpenAI Agents SDK加上Scrapeless MCP服务器是从裸代理到能够读取实时网络的短路径。一个MCPServerStreamableHttp对象打开连接，list_tools返回所有21个工具，call_tool证明某个工具可用，而一个单一的mcp_servers=[server]参数将工具集交给代理。只有生成步骤需要模型密钥，因此您可以首先连接和测试整个工具表面。从上面的脚本开始，将工具范围限定为任务所需的内容，并让模型驱动。

创建一个免费的Scrapeless账户以获取API密钥，并在计划常规代理时查看Scrapeless定价。

常见问题

问：OpenAI Agents SDK在加载MCP工具时需要模型密钥吗？

不需要。MCPServerStreamableHttp运行握手，list_tools仅用Scrapeless API密钥返回工具，call_tool直接调用其中的任何工具。只有在将服务器传递给Agent并调用Runner.run时，模型提供商密钥才是必要的，因为那时模型决定调用哪些工具。
问：如何在不构建代理的情况下调用一个 MCP 工具？

将服务器作为异步上下文管理器打开，并调用 await server.call_tool(name, arguments)。它返回一个 CallToolResult，其 content 是一个块的列表；从文本块中读取文本。这是确认连接并检查工具输出的最快方法，在涉及任何模型之前。

问：为什么传递服务器而不是工具列表？

SDK 将 MCP 服务器保持为实时连接，并在运行期间查询它，因此您将其与 mcp_servers=[server] 关联，而不是转换每个工具。如果工具集是稳定的，请在服务器上设置 cache_tools_list=True，这样它在每次回合中就不会重新运行握手。

问：我可以连接到本地 MCP 服务器吗？

可以。将 MCPServerStreamableHttp 替换为 MCPServerStdio，并提供启动您的本地服务器的命令，然后以相同的方式将其传递给代理。Scrapeless MCP 服务器是一个托管的 HTTP 端点，因此本指南使用可流式传输的 HTTP 类。

问：通过工具抓取是否受目标规则的限制？

是的。工具获取公共页面，您需负责遵循每个目标的条款及其 机器人排除协议 指令。保持抓取量有限，数据应为公共，并且代理应局限于任务实际需要的工具。