OpenAIエージェントSDK + Scrapeless：MCPを通じてエージェントのためのウェブツール

TL;DR:

• OpenAIエージェントSDKは、エンドポイントとx-api-tokenヘッダーを持つオブジェクトMCPServerStreamableHttpを通じてScrapeless MCPサーバーに接続します。
• 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エージェントSDKのエージェントに本物のウェブツールを与えましょう。

OpenAIエージェントSDKは、Pythonでエージェントアプリを構築するためのOpenAIの軽量フレームワークであり、エージェントは与えられたツールによってのみ有用です。基本インストールにはライブウェブへのアクセスはありません。モデルコンテキストプロトコルがこれを解決します：SDKをMCPサーバーに向けると、そのサーバーが公開するすべてのツールが手書き関数ツールと同じインターフェースを通じてエージェントによって呼び出されるようになります。

このガイドは、SDKをScrapeless MCPサーバーに接続し、その21のツールをリストし、実際に1つを呼び出し、全体のサーバーを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"

シェルで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 chars:", len(text))
        print("contains a quote:", "Einstein" in text)


asyncio.run(main())

呼び出しはページをMarkdownとして返し、コンテンツのチェックで実際のテキストが返ってきたことが確認されます。

markdown chars: 4308
contains a quote: True

それがエージェントが同じツールから受け取る形であり、推論できるページの内容です。OpenAIエージェント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="Use the Scrapeless tools to fetch and read pages.",
            mcp_servers=[server],
        )
        result = await Runner.run(
            agent,
            "Use scrape_markdown to fetch https://quotes.toscrape.com/ and list the first three quotes with authors.",
        )
        print(result.final_output)


asyncio.run(main())

実行時にモデルはタスクを読み取り、URLでscrape_markdownを呼び出し、直接呼び出しで既に返されたMarkdownを受け取り、答えを書きます。ツールはどちらの方法でも同じですが、唯一新しい要素はそれらを呼び出すべきタイミングを決定するモデルです。

結論

OpenAIエージェントSDKとScrapeless MCPサーバーを組み合わせることで、簡単に素のエージェントから実際のウェブを読むエージェントへと進化させることができます。1つのMCPServerStreamableHttpオブジェクトが接続を開き、list_toolsがすべての21ツールを返し、call_toolが1つの動作を証明し、単一のmcp_servers=[server]引数がセットをエージェントに渡します。生成ステップのみがモデルキーを必要とし、最初にツールサーフェス全体を配線してテストできます。上記のスクリプトから始め、タスクに必要なツールの範囲を設定し、モデルに運転させましょう。

無料のScrapelessアカウントを作成してAPIキーを取得し、再帰的なエージェントを計画する際にはScrapelessの価格を確認してください。

FAQ

Q: OpenAIエージェントSDKはMCPツールをロードするのにモデルキーが必要ですか？

いいえ。MCPServerStreamableHttpはハンドシェイクを実行し、list_toolsはScrapeless APIキーのみを設定してツールを返し、call_toolはそれらのいずれかを直接呼び出します。モデルプロバイダキーは、サーバーをAgentに渡し、Runner.runを呼び出すときにのみ必要です。なぜなら、それがモデルがどのツールを呼び出すかを決定する時だからです。
Q: エージェントを構築せずに1つのMCPツールを呼び出すにはどうすればよいですか？

サーバーを非同期コンテキストマネージャーとして開き、await server.call_tool(name, arguments)を呼び出します。これにより、contentがブロックのリストであるCallToolResultが返されます。テキストブロックからテキストを読み取ります。これは、接続を確認し、モデルが関与する前にツールの出力を検査する最も迅速な方法です。

Q: ツールのリストではなくサーバーを渡す理由は何ですか？

SDKはMCPサーバーをライブ接続として維持し、実行中にクエリを実行するため、各ツールを変換するのではなく、mcp_servers=[server]で接続します。ツールセットが安定している場合は、サーバーでcache_tools_list=Trueを設定し、毎回ハンドシェイクを再実行しないようにします。

Q: 代わりにローカルMCPサーバーに接続できますか？

はい。MCPServerStreamableHttpをMCPServerStdioに置き換え、ローカルサーバーを起動するコマンドを与え、同様にエージェントに渡します。Scrapeless MCPサーバーはホストされたHTTPエンドポイントであるため、このガイドではストリーミングHTTPクラスを使用しています。

Q: ツールを介したスクレイピングはターゲットのルールに制約されていますか？

はい。ツールは公開ページを取得し、各ターゲットの条件とそのロボット排除プロトコルの指示を尊重する責任があります。ボリュームを制限し、データは公開し、エージェントはタスクで実際に必要なツールにスコープを限定してください。