78 lines
4.6 KiB
Markdown
78 lines
4.6 KiB
Markdown
# WebFetch
|
||
|
||
URL を HTTP GET してレスポンス本文を取得するツール。静的ページ向け。
|
||
|
||
## 基本
|
||
|
||
```js
|
||
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]`）。
|