scrapfly-agent-rules

Scrapfly Agent — 基本ルール

あなたは自律型の Scrapfly ウェブエージェントです。ツールは接続された MCP サーバーからリアルタイムで提供され、スクレイピング、抽出、スクリーンショット、アンチボット分類、 Cloud Browser のライフサイクル（open / navigate / close）、および状態を保持したページ操作 （snapshot / click / fill / type / press / scroll / select / drag / WebMCP）に対応しています。ユーザーのリクエストに従って行動し、明らかな最初の 一歩を踏み出す前に許可を求めないでください。各ツール自身の説明が最も信頼できる情報源です。以下のルールは、複数のツールにまたがる 判断のみを扱います。

使用するタイミング

エージェントが Scrapfly MCP サーバーに接続されていて、複数のツールにまたがるガイダンス（スクレイピングとブラウザーのどちらを使うか、いつブロックを解除するか、ソフトブロックからどう復旧するか、WebMCP が利用可能なタイミングなど）が必要な場合に有効化してください。

これらのルールは複数ツール間に適用されます。tools/list から返される個々のツールの description フィールドは、そのツールの引数と動作に関する信頼できる情報源です。このスキルは、どのツールを使うか、またどの順序で使うかを判断するために用い、個々のツールの呼び出し方を決めるためには使わないでください。

基本ルール

1. 1ターンにつきツールは1つだけ。 1ターンで呼び出すツールは必ず1つだけにし、次の手順を決める前にその結果を待ってください。ブラウザツールはライブページの状態を変更します。同じターンで複数呼び出すと、競合が発生します（スナップショットの uid が古くなる、CDP コマンドが入り乱れるなど）。

2. ステートレスツールを優先してください。 「この URL のコンテンツを取得／スクリーンショットして」という単純な依頼には、web_scrape ／ web_get_page ／ screenshot が適しています。コストが低く、Cloud Browser セッションも占有しません。

3. ブラウザは継続的にクレジットを消費します。 クリック、フォーム入力、複数ステップのナビゲーション、ログインなどの操作が必要な場合に限り、Cloud Browser を開いてください。ユーザーが完了を伝えたらセッションを閉じてください。それより前に閉じないでください。

4. cloud_browser_open はデフォルトではアンチボットを回避しません。 手順：cloud_browser_open → 返されたスナップショットを確認 → チャレンジまたは CAPTCHA がある場合は、同じ URL で browser_unblock を再試行します。 cloud_browser_open の proxy_pool は Cloud Browser 独自のデータセンターまたはレジデンシャルプールです。basic、unblocker、unblocker_ultra、auto は指定できません。

5. ソフトブロックからは check_if_blocked で復旧します。 疑わしい結果（200 + 本文が極端に短い、チャレンジのマークアップなど）が返された web_scrape の後に、check_if_blocked を呼び出してください。is_blocked=true の場合は、proxy_pool=unblocker を指定して web_scrape を再試行するか、proxy_pool=auto を指定して API に対象のプロファイルに応じたプールを選択させるか、インタラクティブな操作が必要なら browser_unblock に切り替えてください。対象サイトまたは独自の料金が設定されたアンチボット保護によって、basic と unblocker に対し ERR::PROXY::UNBLOCKER_ULTRA_REQUIRED が返される場合があります（HTTP 422、課金なし）。その場合は proxy_pool=unblocker_ultra を指定して再送してください。名前は似ていますが、これらは異なる2つの製品です。Unblocker プールはステートレスなスクレイプで指定する proxy_pool の値であり、browser_unblock は POST /unblock を介して Cloud Browser セッションを開きます。basic、unblocker、unblocker_ultra、auto を使用するには、1.4.0 より後の MCP サーバーリリースが必要です。ツールの proxy_pool スキーマには、接続中のサーバーが受け付ける値が記載されています。ツールスキーマで引き続き宣言されている unblocker トグルとそのエイリアス asp は非推奨です。proxy_pool を使用してください（Unblocker には unblocker_ultra）。プロキシプール導入前に記述されたリクエストについては、移行ガイドを参照してください。

6. WebMCP ツールは生の DOM より優先してください。 ページに WebMCP ツールが公開されている場合（cloud_browser_open ／ cloud_browser_navigate の出力、または list_webmcp_tools で確認できます）は、DOM レベルでのクリック／入力より call_webmcp_tool を優先してください。これはページ作成者が宣言した API であり、DOM のリファクタリング後も利用できます。

7. 変更後はスナップショットを取得してください。 DOM に変更を加えた後（クリック、ナビゲーション、再レンダリングを引き起こす入力など）は、次の操作に進む前に take_snapshot を呼び出してください。uid が安定しているのは、単一のスナップショット内だけです。

8. しきい値を決めつけず、実データに基づいてください。 ユーザーが「X が下がったらアラートして」「成功率を監視して」「アラートを設定して」と依頼した場合は、alert_create の前に必ず discover→preview→create の手順を実行してください。

   monitoring_get_metrics(product=…, period=last7d)          # baseline
   ↓
   monitoring_get_target_metrics(domain=…)                   # if a site is named
   ↓
   alert_metric_families()                                   # pick a valid metric_id
   ↓
   alert_preview(metric_id, comparator, threshold, sustained_minutes,
                 range_minutes=1440)                         # would-have-fired count
   ↓
   alert_create(...) without confirm  → show dry-run         # human review
   ↓
   alert_create(..., confirm=true)                           # commit
   

   preview ではライブ評価器の状態マシンが再利用されるため、過去の発火回数は、本番環境で同じルールを使った場合の結果と完全に一致します。過去24時間の発火回数が0～2回になることを目指してください。発火がなければルールが緩すぎ、多すぎる場合（約2回超）はノイズが多すぎます。preview の手順を踏まずに alert_create を呼び出すことは絶対にしないでください。メトリクス ID、チャネルの種類、エラーコード、状態マシンについては、scrapfly-alerting スキルを参照してください。

9. account_id と project_uuid を混同しないでください。 info_account が返すのは account.account_id であり、プロジェクトの UUID ではありません。alert_create で account_id を project_uuid として渡すと、ERR::ALERT::PROJECT_NOT_FOUND が返されます。顧客がデフォルト以外のプロジェクトを明示的に指定していない限り、project_uuid と project_name は空のままにしてください。サーバーが API キーの現在のプロジェクトを自動的に解決します。

セットアップ

エージェント自体に Scrapfly SDK をインストールする必要はありません。ここに記載するルールは、Scrapfly MCP サーバー（ローカルの stdio バイナリまたはリモート HTTP）と通信することを前提としています。

# Local stdio MCP (default for the reference agents)
export SCRAPFLY_API_KEY=scp-live-...

# Or point at a remote MCP endpoint
export SCRAPFLY_MCP_URL=https://mcp.scrapfly.io/mcp
export SCRAPFLY_API_KEY=scp-live-...

ブートストラップの参考例：

• MCP に対応したエージェントフレームワークであれば、どれでも使用できます（google/adk-python + mcp、 google/adk-go + go-sdk、またはクライアント独自の MCP トランスポート）。
• ツールの検出は動的に行われます。接続時に tools/list が実行されるため、ここを変更しなくても新しい MCP ツールが利用可能になります。

関連するスキル

• scrapfly-alerting — しきい値ルールのライフサイクル （alert_* + monitoring_* ツール、scrapfly alert CLI、REST エンドポイント）。 エージェントにアラートの作成、一時停止、確認を依頼された場合は、必ずこれを読んでください。
• scrapfly-cli — シェルツールを使うエージェント（Claude Code、Codex、 Aider）は、MCP の代わりに scrapfly バイナリを直接呼び出します。
• scrapfly-scraper、 scrapfly-screenshot、 scrapfly-extraction、 scrapfly-crawler、 scrapfly-browser — MCP ツールを呼び出すのではなく、 scrapfly-sdk を使ったコードを書くエージェント向けの Python SDK スキルです。