WebFetch

URL を HTTP GET してレスポンス本文を取得するツール。静的ページ向け。

基本

WebFetch({ url: "https://example.com/article", timeout: 30 })

HTML はテキスト化されて返る（タグ等は除去）
JSON / XML / プレーンテキストもそのまま取得可能
リダイレクトは自動で追従

いつ使うか

状況	使うツール
静的 HTML ページ	WebFetch
JS で動的レンダリングされる SPA	BrowseWeb
ボタン・フォーム操作が必要	BrowseWeb
ファイルダウンロード	DownloadFile
検索結果を一覧で取得	WebSearch

WebFetch は軽量で速い。BrowseWeb はブラウザ起動コストがかかるので、できる限り WebFetch を優先する。

レスポンス履歴

各 WebFetch 呼び出しは logs/webfetch-history.jsonl に記録される。後から「どの URL を取得したか」を振り返れる。

スクリーンショット添付（vlmEnabled 時のみ）

ワーカーが vlm=true（主 LLM が画像入力対応）の場合、WebFetch は成功時に Playwright でファーストビュー（1280×1600 viewport）のスクショを撮り、LLM の文脈に image_url として自動添付する。天気・ダッシュボード・地図など、HTML テキスト抽出では情報が欠落しやすいサイトの理解を補う目的。

保存先: logs/webfetch-screenshots/{timestamp}-{url-hash}.png
logs/webfetch-history.jsonl の各レコードに screenshotPath が記録される
Playwright 未インストール・CAPTCHA・タイムアウト等で失敗しても WebFetch 本体は成功扱い（テキストだけ返る）
無効化: config.yaml の tools.webfetch_screenshot: false
タイムアウト: tools.webfetch_screenshot_timeout_ms（デフォルト 15,000）

SSRF 保護

ローカル/プライベート IP（127.x.x.x, 10.x.x.x, 172.16-31.x.x, 192.168.x.x, ::1, fc00::/7 等）はデフォルトでブロックされる。社内ホストへアクセスする必要がある場合は Settings UI の「SSRF Allowed Hosts」に追加する。

トラブルシューティング

本文がほぼ空: SPA で JS レンダリングが必要 → BrowseWeb に切り替え
タイムアウト: timeout パラメータを増やす（デフォルト 30 秒）
403/404: User-Agent 制限・bot 検出の可能性 → BrowseWeb なら回避できる場合あり
SSRF blocked: ローカル/プライベート IP に向いている → 設定追加またはターゲット見直し

エラー時のフォールバック方針

WebFetch がエラーを返した場合、以下の原則で BrowseWeb にリトライする:

エラー	BrowseWeb で再試行すべきか
HTTP 403 / 429	する — bot 検出・レート制限。ブラウザ User-Agent で回避できる可能性
HTTP 502 / 503 / 504	する — CDN/upstream の一時的エラー。別の HTTP スタックで成功することがある
ネットワークエラー / タイムアウト	する — 動的ページが静的 fetch に応答しないケースが多い
HTTP 404 / 401 / 410	しない — 永続的なエラー。URL を見直すべき
`invalid_url`	しない — URL の記述ミス
`ssrf_blocked`	しない — セキュリティ設定。Settings で allowed hosts を追加
`pdf_blocked`	しない — `DownloadFile` + `ReadPdf` の組み合わせを使う
`binary_blocked`	しない — `DownloadFile` でバイナリ保存する
本文が極端に短い（< 200 chars）	する — SPA の空シェルを取得した可能性が高い
`Just a moment...` 等 Cloudflare challenge	する — ブラウザで JS challenge を通過できる

リトライ時は同じ URL を BrowseWeb({ url: "..." }) に渡すだけでよい。BrowseWeb はジョブ内で Cookie・セッションを保持するので、複数回呼んでもログイン状態は引き継がれる。

バイナリの扱い

WebFetch は取得 body の先頭 8KB を sniff し（magic byte / NUL / 不正 UTF-8 / 制御文字比率）、バイナリと判定したらコンテキストに展開せずブロックする。Content-Type が欠落・詐称（例: .xls を text/plain）していても実バイトで検出する。バイナリを処理したい場合は DownloadFile で input/ に保存し、ReadExcel / ReadPdf 等を使う。テキスト body は 5MB で打ち切られる（末尾に [truncated: body exceeded 5MB]）。

4.6 KiB Raw Blame History Unescape Escape