OpenAI Agents SDK でのウェブスクレイピング
OpenAI Agents SDK のエージェントを Spicrawl MCP サーバーに接続します。エージェントはウェブページを Markdown として読めるようになります。
セットアップする
openai-agentsをインストールします。SPICRAWL_API_KEYとOPENAI_API_KEYを設定します。MCPServerStreamableHttpを、URL とparams内のAuthorizationヘッダーで開きます。create_static_tool_filterでモデルに見せるツールを絞り込み、サーバーをAgentに渡します。
例: 料金ページを読む
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 を設定するよう指示すれば、想定以上の出費を防げます。