Spicrawl は、OpenAI Agents SDK、LangChain、Codex、Claude Code などに対応しました。連携を見る
コンテンツへスキップ

OpenAI Agents SDK でのウェブスクレイピング

OpenAI Agents SDK のエージェントを Spicrawl MCP サーバーに接続します。エージェントはウェブページを Markdown として読めるようになります。

セットアップする

  1. openai-agents をインストールします。

  2. SPICRAWL_API_KEY と OPENAI_API_KEY を設定します。

  3. MCPServerStreamableHttp を、URL と params 内の Authorization ヘッダーで開きます。

  4. create_static_tool_filter でモデルに見せるツールを絞り込み、サーバーを Agent に渡します。

例: 料金ページを読む

openai_agents_example.py
import asyncio
import os

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


async def main() -> None:
    async with MCPServerStreamableHttp(
        name="spicrawl",
        params={
            "url": "https://mcp.spicrawl.com/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['SPICRAWL_API_KEY']}"},
        },
        cache_tools_list=True,
        tool_filter=create_static_tool_filter(
            allowed_tool_names=["spicrawl_scrape", "spicrawl_batch_submit"]
        ),
    ) as server:
        agent = Agent(
            name="Page reader",
            instructions="Use the Spicrawl tools to read web pages.",
            mcp_servers=[server],
        )
        result = await Runner.run(
            agent,
            "Read https://example.com/pricing as markdown and list the plans.",
        )
        print(result.final_output)


asyncio.run(main())

サーバーに OAuth はないため、キーは必ず headers で送ってください。401 が返る場合は、エージェントを実行するプロセスで SPICRAWL_API_KEY が設定されているか確認してください。

ツールの一覧を短く保つ

25 個のツールスキーマすべてが、モデル呼び出しのたびに送られます。spicrawl_scrape を残し、多数の URL には spicrawl_batch_submit、spicrawl_batch_status、spicrawl_batch_results を追加してください。

コードがすでにどの URL を取得するか分かっているなら、POST /v1/scrape を呼び出す単純な関数のほうがシンプルです。ツールスキーマのトークンはかからず、テストもしやすくなります。

できること

このサーバーは、エージェントに spicrawl_* ツールを 25 個提供します。各呼び出しはお客様の API キーのもとで実行され、API の直接呼び出しと同じ制限とクレジットが適用されます。

  • ページを一つ読み取る: spicrawl_scrape は Markdown(デフォルト)、テキスト、HTML、JSON、PDF を返します。
  • 多数のページを読み取る: spicrawl_batch_submit は最大 10,000 件の URL をキューに入れます。続けて spicrawl_batch_status と spicrawl_batch_results を使います。
  • ログインが必要なページ: spicrawl_session_create は、呼び出しをまたいで Cookie とストレージを保持します。
  • 失敗をデバッグする: spicrawl_requests_list と spicrawl_request_get。
  • 使用量を確認: spicrawl_usage_summary とその他の使用量ツール。これらには read スコープを持つキーが必要です。
  • 調べる: spicrawl_docs_search と spicrawl_docs_read で Spicrawl のドキュメントを検索して読めます。

ツール spicrawl_browser_connect_url は一覧にありますが、近日公開です。spicrawl_scrape では、レンダリングの引数は API の js_render ではなく render です。

知っておくべきこと

  • クロールはありません。 Spicrawl はリンクをたどったり、ページを探したりしません。エージェントに URL を渡してください。
  • リクエストごとのクレジット。 通常のフェッチは 1 クレジット、JavaScript レンダリングは 3、フルブラウザレンダリングは 8 です。
  • 失敗は無料です。 失敗したリクエストは 0 クレジットです。
  • キャッシュで節約できるのは時間であり、クレジットではありません。 キャッシュヒットの料金は、それを保存したフェッチと同じです。
  • 呼び出しごとに上限を設けてください。 max_cost を設定すると、より高くなる可能性のあるリクエストは実行前に拒否されます。
  • 近日公開: マネージドプロキシ、ステルスモード、リモートブラウザ、自然な言葉で書いたプロンプトからの AI 抽出。現時点では、ご自身のプロキシを使えます。

よくある質問

どのパッケージが必要ですか?

openai-agents。例を実行する前に、SPICRAWL_API_KEY と OPENAI_API_KEY を設定してください。

モデルに見せるツールを制限するにはどうすればいいですか?

Pass tool_filter=create_static_tool_filter(allowed_tool_names=[...]). The example keeps spicrawl_scrape and spicrawl_batch_submit.

エージェントの接続時に 401 が返るのはなぜですか?

ヘッダーがないか、キーが誤っています。SPICRAWL_API_KEY からコードでヘッダーを組み立て、その変数が、エージェントを実行するプロセスで設定されていることを確認してください。

ツール呼び出しが失敗するとどうなりますか?

エラーは、API のコード付きの MCP ツールエラーとしてモデルに届きます。失敗した呼び出しは 0 クレジットです。

1 ページの料金はいくらですか?

通常のフェッチは 1 クレジット、JavaScript レンダリングは 3、フルブラウザレンダリングは 8 です。失敗したリクエストは 0 クレジットです。キャッシュヒットは、それを保存したフェッチと同じ料金です。エージェントに各リクエストで max_cost を設定するよう指示すれば、想定以上の出費を防げます。