Pydantic AI + Scrapeless: エージェントにMCPを通じてライブウェブツールを提供する

TL;DR:

• Pydantic AIは、ストリーミングHTTPを介してScrapeless MCPサーバーに接続し、scrape_markdownから完全なブラウザ自動化セットまでの21のライブウェブツールをエージェントに提供します。
• 接続には、pydantic_ai.mcpの3つのクラスを使用します：StreamableHttpTransport、FastMCPClient、およびAgentに添付するMCPToolsetです。
• ハンドシェイク、ツールリスト、および実際のscrape_markdown呼び出しはすべてモデルプロバイダーキーなしで実行可能です。最終的なagent.runの生成時のみが必要です。
• defer_model_check=Trueを使用すると、モデルキーが存在する前にAgentを構築できるので、ツールセットを最初に配線して検査できます。
• 1回のscrape_markdown呼び出しは、ターゲットページをクリーンなMarkdownとして返し、モデルに文脈として戻す準備が整います。
• Scrapelessの無料プランから始めて、最初のエージェントを接続してください。

Pydantic AIはエージェントに構造を提供します：型付き出力、検証されたツール引数、およびツールを構成するためのクリーンな方法。エージェントには、ライブウェブにアクセスする手段は提供していませんが、そのギャップを埋めるのがモデルコンテキストプロトコルです。Pydantic AIをMCPサーバーに向けることで、そのサーバーが公開するすべてのツールはエージェントが呼び出せるツールになり、引数スキーマはPydantic AIコードの他の部分と同じ方法で検証されます。

このガイドでは、Pydantic AIをScrapeless MCPサーバーに接続し、提供するツールのリストを表示し、実際に1つを呼び出し、すべてのセットをAgentに添付します—すべてがライブサーバーに対して検証されます。モデルプロバイダーキーが必要なのは最後の生成呼び出しだけであり、この投稿ではそのラインがどこにあるのかを明示しています。

なぜScrapeless MCPなのか

Scrapeless MCPサーバーは、エージェントが直接呼び出すことができるウェブスクレイピングおよびブラウザツールを公開するため、スクレイピング層を自分で構築またはホストする必要がありません。単一の接続で21のツールを提供します：ページコンテンツ用のscrape_markdownおよびscrape_html、検索データ用のgoogle_searchおよびgoogle_trends、キャプチャ用のscrape_screenshot、およびクリック、入力、スクロール、ナビゲーションを行うクラウドブラウザを駆動する完全なbrowser_*セットです。 Scrapeless MCPサーバーの投稿がサーバー自体をカバーしますが、このガイドはそれをPydantic AIに接続することに関するものです。

ツールはScrapelessのインフラストラクチャ上で実行されるため、エージェントはローカルブラウザやプロキシプールなしでレンダリングされたページや検索結果を取得します。browser_*ツールは、Scrapelessクラウドブラウザを駆動するため、エージェントはインタラクティブページをナビゲートし、レンダーされた内容を読み取ることができます。

前提条件

• Python 3.10以上。
• ダッシュボードからのScrapeless APIキーをSCRAPELESS_API_KEYとしてエクスポート。
• 最終生成ステップのためだけにモデルプロバイダーキー（例：OPENAI_API_KEY）。ハンドシェイク、ツールリスト、およびツール呼び出しには必要ありません。

インストール

MCPクライアントクラスを取り込むMCPエクストラ付きでPydantic AIをインストールします。

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

シェルでScrapelessキーを設定します。実際のキーを実行時に使用し、プレースホルダーをソースから除外してください。

export SCRAPELESS_API_KEY="sk_your_key_here"

接続とツールのリスト

接続は3つのオブジェクトです。StreamableHttpTransportはエンドポイントの名前を付け、APIキーをx-api-tokenヘッダーに持ちます。FastMCPClientはそのトランスポート経由でプロトコルを話し、MCPToolsetはクライアントをラップしてPydantic AIがそれを使用できるようにします。ツールセットの非同期コンテキストに入るとハンドシェイクが実行され、list_toolsはサーバーが提供するものを返します。

import asyncio
import os

from pydantic_ai.mcp import FastMCPClient, MCPToolset, StreamableHttpTransport

transport = StreamableHttpTransport(
    url="https://api.scrapeless.com/mcp",
    headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
)
scrapeless = MCPToolset(FastMCPClient(transport))


async def main() -> None:
    async with scrapeless:
        tools = await scrapeless.list_tools()
        names = sorted(t.name for t in tools)
        print("tool count:", len(names))
        print("tools:", ", ".join(names))


asyncio.run(main())

ライブサーバーは21のツールを返し、ここに到達するためにモデルプロバイダーキーは設定されていません。

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

ツール名はフラットで、サーバープレフィックスはなく、scrape_markdownは正確にその名前でアドレス指定できます。トランスポート層とメッセージ層は、Model Context Protocol仕様に従っており、これはさらにJSON-RPC 2.0仕様に基づいています。

ツールを直接呼び出す

エージェントにツールを渡す前に、自分で一度呼び出してその戻り値を確認してください。direct_call_toolは名前と引数を指定してツールを呼び出します。これは、ツールが機能していることを確認し、その出力を検査する最も迅速な方法です。

import asyncio
import os

from pydantic_ai.mcp import FastMCPClient, MCPToolset, StreamableHttpTransport

transport = StreamableHttpTransport(
    url="https://api.scrapeless.com/mcp",
    headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
)
scrapeless = MCPToolset(FastMCPClient(transport))


async def main() -> None:
    async with scrapeless:
        result = await scrapeless.direct_call_tool("scrape_markdown", {"url": "https://quotes.toscrape.com/"})
        markdown = result if isinstance(result, str) else str(result)
        print("markdown chars:", len(markdown))
        print("contains a quote:", "The world as we have created it" in markdown)


asyncio.run(main())

この呼び出しはページをMarkdown形式で返し、コンテンツチェックによりターゲットページから実際の引用が存在することを確認します。

markdown chars: 4308
contains a quote: True

これがエージェントが受け取る形です：生のHTMLを剥ぎ取る必要のある代わりに、推論できるクリーンなMarkdownです。Pydantic AI MCPクライアントドキュメントではツールセットメソッドが詳細に説明されています。

ツールをエージェントに付ける

付ける際には1つの引数：toolsetsにツールセットを渡します。通常のAgent構築はすぐにモデルを検証するため、defer_model_check=Trueを設定するとモデルキーが設定される前に構築ができるので、最初にツールセットを配線し、検査することができます。

import asyncio
import os

from pydantic_ai import Agent
from pydantic_ai.mcp import FastMCPClient, MCPToolset, StreamableHttpTransport

transport = StreamableHttpTransport(
    url="https://api.scrapeless.com/mcp",
    headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
)
scrapeless = MCPToolset(FastMCPClient(transport))

# defer_model_checkでモデルキーが設定される前にエージェントが構築できるようにし、
# そのために最初にツールセットを配線して検査できるようにします。
agent = Agent("openai:gpt-4o", toolsets=[scrapeless], defer_model_check=True)


async def main() -> None:
    async with scrapeless:
        names = sorted(t.name for t in await scrapeless.list_tools())
    web = [n for n in names if n.startswith(("scrape_", "google_"))]
    print("agent wired with", len(names), "Scrapeless tools")
    print("web tools:", web)


asyncio.run(main())

エージェントは今やすべてのScrapelessツールを持ち、ウェブスクレイピングのサブセットは最初に多くのチュートリアルが手に取る部分です。

agent wired with 21 Scrapeless tools
web tools: ['google_search', 'google_trends', 'scrape_html', 'scrape_markdown', 'scrape_screenshot']

エージェントに21の全ツールの代わりにわずか数ツールしか渡したくない場合、MCPToolsetはfilteredとrenamedを公開しているので、エージェントをscrape_markdownとgoogle_searchだけにスコープできます。

プロンプトを実行する

ツールセットが接続された状態で、エージェントはツールを呼び出すタイミングを決定します。これがモデルプロバイダキーを必要とする唯一のステップです。

注：agent.runにはOPENAI_API_KEYのようなモデルプロバイダキーが必要です。それ以外のすべて — ハンドシェイク、21のツールリスト、scrape_markdown呼び出し、および接続 — はそれなしで動作します。この生成呼び出しのみが前提となるギャップです。ここでは、取得結果としてではなく、正確な形を示しています。

async def run_prompt() -> None:
    async with agent:
        result = await agent.run(
            "Use scrape_markdown to fetch https://quotes.toscrape.com/ "
            "and list the first three quotes with their authors."
        )
    print(result.output)


asyncio.run(run_prompt())

実行時にモデルはプロンプトを読み、URLを使ってscrape_markdownを呼び出し、先ほどの呼び出しで示したMarkdownを受け取り、答えを記述します。ツール層は、直接呼び出すかモデルに呼び出させるかで同じです。

結論

Pydantic AIとScrapeless MCPサーバーは、ベアエージェントからライブウェブを読むエージェントへの短い道です。3つのクラスが接続を形成し、list_toolsが21のツールを表示し、direct_call_toolが1つの機能が動作することを証明し、1つのtoolsets引数がすべてを接続します。生成ステップだけがモデルキーを必要とし、プロバイダにコミットする前に全体の統合を探求可能に保ちます。上記のスクリプトから始めて、ツールセットをエージェントに必要なツールにスコープし、残りはモデルに任せましょう。
無料のScrapelessアカウントを作成してAPIキーを取得し、定期的なエージェントを計画する際はScrapelessの料金を確認してください。

FAQ

Q: Pydantic AIはMCPツールをリストするためにモデルキーが必要ですか？

いいえ。ハンドシェイク、list_tools、およびdirect_call_toolはすべてScrapeless APIキーのみで動作します。モデルプロバイダキーはagent.runのみに必要で、モデル自体が呼び出すツールを決定する際にのみ使用されるため、プロバイダを決定する前にツール全体のテストと探索が可能です。

Q: FastMCPClientとMCPToolsetの違いは何ですか？

FastMCPClientはMCPプロトコルをトランスポート越しに扱い、list_toolsのような低レベルの操作を公開します。MCPToolsetはそのクライアントをラップし、Pydantic AIがサーバーのツールをエージェントツールとして扱えるようにし、filteredやrenamedなどのツールセット機能を追加します。Agentに接続するのはクライアントではなくMCPToolsetです。

Q: HTTPではなくstdio MCPサーバーに接続するにはどうすればよいですか？

トランスポートを交換します。URLの代わりにサーバーコマンドとともにStdioTransportを使用し、それを同じFastMCPClientとMCPToolsetにラップします。Scrapeless MCPサーバーはホスティングされたHTTPエンドポイントであるため、このガイドではStreamableHttpTransportを使用します。

Q: エージェントを構築する際になぜdefer_model_checkを使用するのですか？

通常、Agentを構築するとすぐにモデルプロバイダの検証が行われ、キーが設定されていない場合は失敗します。defer_model_check=Trueはそのチェックを実行時まで延期し、モデルキーなしでエージェントを構築し、ツールセットを接続し、利用可能なツールを検査できるようにします。

Q: エージェントに特定のツールのみを与えるにはどうすればよいですか？

MCPToolset.filteredを使用してサブセットを公開したり、renamedを使用してツールのモデルに対する表示を変更します。エージェントをscrape_markdownとgoogle_searchに絞る方が、タスクがコンテンツと検索だけを必要とする場合に全21ツールを渡すよりも安全です。

Q: scrape_markdownは何を返しますか？

ターゲットページをMarkdownとしてレンダリングし、確認された呼び出しでは引用ページは4,308文字で、そのページの実際のテキストが含まれていました。Markdownは生のHTMLよりもモデルが検討しやすいため、ページコンテンツをプロンプトに返すデフォルト設定として良い選択です。

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

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