agent-browser-scrape

データ抽出 — 実行プロトコル

内部テンプレート。 エントリーポイント：agent-browser スキル。

---

禁止事項

NEVER `eval` before `wait --load networkidle` — JS-rendered content won't exist yet
NEVER assume lightpanda handles JS-heavy pages — always have a --engine chrome fallback ready
NEVER scrape without checking `get count` first — validates that your selector found items

---

実行手順

# 1. Try lightpanda first (fastest, no JS overhead)
AGENT_BROWSER_ENGINE=lightpanda agent-browser open <url>
AGENT_BROWSER_ENGINE=lightpanda agent-browser wait --load networkidle

# 2. Understand structure
AGENT_BROWSER_ENGINE=lightpanda agent-browser snapshot -c

# 3. Verify selector finds items before extracting
AGENT_BROWSER_ENGINE=lightpanda agent-browser get count ".item"

# 4. Extract
AGENT_BROWSER_ENGINE=lightpanda agent-browser eval "[...document.querySelectorAll('.item')].map(el => ({
  name: el.querySelector('h2')?.textContent?.trim(),
  price: el.querySelector('.price')?.textContent?.trim()
}))"

# 5. If empty/wrong → fallback to chrome engine
agent-browser open <url>
agent-browser wait --load networkidle
agent-browser get count ".item"    # verify selector still works
agent-browser eval "<same query>"

AGENT_BROWSER_NATIVE=1 に関する注意： この環境変数は、以前のワークフローで Rust デーモンを簡潔に指定するために使われていました。0.22 以降ではデーモンは常に有効です。代わりに AGENT_BROWSER_ENGINE=chrome（またはデフォルト）を使用してください。AGENT_BROWSER_NATIVE=1 も引き続き受け付けられますが、現在はドキュメントに記載されていません。

---

ページネーションの処理

# Scroll-based infinite scroll
agent-browser scroll down
agent-browser wait --load networkidle
agent-browser get count ".item"    # check if count increased
agent-browser eval "<extract again>"
# Repeat until count stops increasing

# Click-based pagination
agent-browser find role button click --name "Next"
agent-browser wait --load networkidle

# Wait for specific text to confirm page loaded
agent-browser wait --text "Page 2 of"

---

出力の解析に関するヒント

# Add --content-boundaries to help parse output when using --max-output
AGENT_BROWSER_CONTENT_BOUNDARIES=1 agent-browser eval "<query>" --max-output 50000

# JSON output for structured parsing
agent-browser get text @e1 --json
agent-browser snapshot -i --json

---

ボット対策の回避

# Level 1: custom user-agent
agent-browser --user-agent "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" open <url>

# Level 2: disable automation detection (combine with level 1)
agent-browser \
  --user-agent "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
  --args "--disable-blink-features=AutomationControlled" \
  open <url>

---

復旧パターン

失敗	復旧方法
lightpanda が空の結果を返す	--engine chrome（またはデフォルト）に切り替える
ボットとして検出される	--user-agent を追加し、その後 --args と組み合わせる
コンテンツの読み込み前に eval を実行する	eval の前に毎回 wait --load networkidle を実行する
無限スクロールが処理されない	scroll down と eval の再実行を繰り返し、get count で進行状況を確認する
出力が切り詰められる	--max-output 100000 または AGENT_BROWSER_MAX_OUTPUT 環境変数を追加する

---

判断ゲート

次の場合は一時停止します：

• すべての方法がボット対策によってブロックされる（CAPTCHA の解決に人間の対応が必要）
• フォールバック後も get count が 0 を返す場合 — ユーザーに snapshot -c を表示し、項目の特定方法を尋ねる

---

注意点

間違い	修正方法
lightpanda が空の結果を返す	--engine chrome に切り替える
読み込み前に eval を実行する	最初に wait --load networkidle を実行する
--user-agent を指定してもボットとして検出される	--args "--disable-blink-features=AutomationControlled" を追加する
項目を 0 件抽出したまま何も表示されない	eval の前に必ず get count "<selector>" を実行する
出力が JSON の途中で切れる	--max-output を増やすか、--content-boundaries を使用する