Browser Useツールの実装 — navigateとread_pageの使い方

Browser Useツールとは

Browser Useツールは、Claudeにブラウザの操作を許可するAnthropic定義のクライアントツールセットです。tools配列にbrowser_toolset_20260801を1つ追加するだけで、navigateやread_pageを含む27個のメンバーツールがデフォルトで使えます。オプションの4個を有効にすると合計31個です。

navigateはURLを開く、または履歴を戻る・進む・再読み込みするための呼び出しです。read_pageはページの構造をアクセシビリティツリーとして文字列で返し、各要素に[ref_1]のような参照タグを付けます。Claudeはこの参照を次のクリックや入力の対象として指定でき、スクリーンショットから座標を読み取る手間を省けます。ブラウザ操作の実行環境は完全に自分のアプリケーション側にあり、Anthropicはtool_useブロックを返すだけです。

デスクトップ全体の操作が必要なタスクにはComputer Useツールの方が向きます。Browser Useツールが対象にするのは、ブラウザ内で完結するタスクと、JavaScriptでコンテンツを構築するページの操作です。

対応モデルとプラットフォーム

Browser Useツールが使えるのは、claude-fable-5-1・claude-mythos-5-1・claude-fable-5・claude-mythos-5・claude-opus-5・claude-sonnet-5・claude-opus-4-8の7モデルに限られます。Opus 4.7以前やSonnet 4.6は対象外です。

プラットフォームの対応状況も一様ではありません。

AWSとBedrock、Microsoft FoundryではBrowser Useツールを呼び出せません。対応モデルの範囲(7モデル)はComputer Useツールの新ツールセットと同じですが、プラットフォームの対応はComputer Use側がAWS・Bedrock・Microsoft Foundryをbetaで対応しており、Browser Useとは異なります。導入前にこの面ごとの対応状況を確認しておくと、実装後に環境を作り直す手戻りを避けられます。

navigate/read_pageの基本ラウンドトリップ

実装の骨格は、Claudeがtool_useを返し、アプリケーションが実行してtool_resultを返す往復です。最小構成のリクエストは次の通りです。

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 2048,
    "tools": [{"type": "browser_toolset_20260801"}],
    "messages": [
      {"role": "user", "content": "example.com/docsを開いて要点を教えて"}
    ]
  }'

Claudeの最初の応答はstop_reason: "tool_use"で終わり、navigateとread_pageのtool_useブロックを含みます。各ブロックには"toolset_name": "browser"が必ず付き、これがカスタムツールとの名前衝突を防ぎます。アプリケーションはnavigateを実行してからread_pageを実行し、結果を1つのuserメッセージにまとめて返します。

{
  "type": "tool_result",
  "tool_use_id": "toolu_01UvHU5cDyTZ2vXKf5wCkPqR",
  "toolset_name": "browser",
  "content": [
    {
      "type": "text",
      "text": "link \"Documentation\" [ref_1]\nlink \"Getting started\" [ref_2]\ntextbox \"Search docs\" [ref_3]"
    }
  ]
}

Claudeはこのref_2をそのまま次のleft_clickの対象として渡せます。スクリーンショットから座標を目視で読み取る処理が不要になる分、実装は軽くなります。

read_pageとref参照の仕組み

read_pageのfilterパラメータは3種類あります。省略時は表示中の全要素、interactiveは表示中の操作可能要素のみ、allはビューポート外の要素まで含みます。depthは木の深さの上限で最小1・既定15、refを指定すると特定要素配下のサブツリーだけを読めます。出力は50,000文字で打ち切られ、超過時はその旨がテキストに添えられます。

参照は発行元のタブに紐づき、そのタブが別ページへ遷移するかDOMが大きく変わるまで有効です。アプリケーション側は参照とノード(アクセシビリティノードIDやセレクタ)の対応表を保持します。Claudeが古い参照を渡してきたら、次のようなエラー結果を返して再読み込みを促します。

Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references.

すでに配布済みの参照は、タブが遷移するまで採番し直さないようにします。番号を使い回すと、Claudeが保持している参照が気づかないうちに無効化されるためです。

read_page以外に、要素を探すfindと本文を読むget_page_textがあります。使い分けの目安は次の通りです。

大きなページではスクリーンショットよりread_pageの方が入力トークンを抑えられる場合が多く、Claudeはすぐ操作できる参照も同時に得られます。視覚的なレイアウトや画像そのものを確認したいときだけ、screenshotとzoomを使います。

navigate/read_pageのexecutor実装

executorはメンバー名で処理を振り分けるディスパッチャです。navigateとread_pageの最小実装は次のようになります。

def handle_browser_action(name, tool_input):
    if name == "navigate":
        return navigate(tool_input["url"])
    elif name == "read_page":
        return read_page(
            filter=tool_input.get("filter"),
            depth=tool_input.get("depth", 15),
            ref=tool_input.get("ref"),
        )
    raise ValueError(f"Unknown or unimplemented member: {name}")
 
 
def navigate(url):
    parsed = urlparse(url if "://" in url else f"https://{url}")
    if parsed.scheme not in ("http", "https"):
        raise BrowserToolError("Navigation refused. Only http and https URLs are allowed.")
    page.goto(parsed.geturl())
    return f"navigated to {parsed.geturl()}"

navigateの実装で見落としやすいのがスキーム検証です。ドキュメントは、文字列の前方一致でなくURLパーサーでスキームを確認することを明示しています。javascript:やfile:、data:のようなスキームは、文字列prefixチェックだと迂回されるケースがあるためです。スキームなしのURLはhttps://として扱い、http・https以外はエラー結果で拒否します。

PythonやTypeScriptでエージェントループごと組む場合は、Python SDKの非同期実行とtool_runner実装やTypeScript SDKのStreaming・Tool実装が土台として使えます。

バッチアクションとbrowser_state

1回のターンに複数のメンバー呼び出しが含まれる場合、それはバッチアクションです。呼び出しは出現順に実行し、最初の失敗で停止します。以降のブロックはすべてis_error: trueにし、返すテキストはNot executed: an earlier action in this turn failed.という決まった文言にします。

navigateやleft_clickでタブの状態が変わったときは、結果にbrowser_stateブロックを添えます。

• tabsはその時点で開いている全タブの一覧で、active: trueのタブが必ず1つ含まれます
• state_changesは新規タブや保留中のダウンロードのような副作用の報告で、報告することが無ければフィールドごと省略します(空配列は拒否されます)
• browser_stateは1つの結果につき最大1ブロックで、is_error: trueの結果には付けられません

new_tab・switch_tab・close_tab・list_tabsの4つのタブ管理メンバーは、成功時のcontentがbrowser_stateブロック1つだけという決まりです。テキストや画像は含めず、Claudeが読む文言はAPI側がtabsの中身から自動生成します。

よくあるつまずき

参照の再利用による不整合: タブが同じページのまま新しいread_pageを呼ぶと、既存の参照番号を維持する実装と、毎回振り直す実装が混在しがちです。番号を振り直すと、Claudeが古いターンで受け取った参照が別要素を指してしまいます。

スキーム検証の抜け: javascript:スキームの拒否を文字列の前方一致だけで実装すると、大文字化や空白混入で迂回されます。URLパーサーでスキームを取り出してから比較します。

toolset_nameの付け忘れ: メンバー結果に"toolset_name": "browser"を付け忘れると、そのブロックが不正なリクエストとして扱われます。自作ツールと名前が重複するメンバーがあるときは特に見落としやすい点です。

画像サイズ超過: screenshotとzoomの画像はAPI側で縮小されません。モデルの画像サイズ上限、またはリクエスト内の画像が20枚を超えた場合のより厳しい上限を超えると拒否されます。返す前にリサイズし、Claudeが返してきた座標はリサイズ倍率の逆数で元に戻してから使います。

javascript_execとfile_uploadの有効化しすぎ: この2つはデフォルトで無効です。ページに操作されたときの影響が大きいため、実装が必要な場合だけconfigsで個別に有効化します。

セキュリティ考慮事項

Browser Useツールは開かれたWeb全体を対象にするため、標準的なAPI機能には無いリスクを伴います。ページが返す文字列はすべて未検証の入力として扱う前提で設計します。

推奨される対策は6点です。

1. ブラウザとexecutorは、最小権限の専用コンテナかVMで、認証情報を持たないプロファイルで動かす
2. 到達できるホストをドメイン許可リストで絞り、タスクに不要ならループバックやプライベートアドレス帯も遮断する
3. タブのタイトルやURL、ダウンロードの情報はページ由来の未検証データとして扱い、生のDOMではなく描画結果からページを読む
4. navigateハンドラでは履歴キーワードを受け付けつつ、URLパーサーでスキームを検証する
5. javascript_execとfile_uploadは必要なときだけ有効化する
6. 購入や規約への同意のような重大な操作は、実行前に人間の確認を挟む

Anthropicはプロンプトインジェクションに抵抗するようモデルを学習させたうえで、ページ内容やスクリーンショットを自動でスキャンする分類器を追加しています。疑わしい指示を検知すると、実行前に指示の出所を確認するようClaudeを誘導する仕組みです。人間の確認を挟めないユースケースでこの保護が合わない場合は、サポート経由でオプトアウトを依頼できます。

tool result clearingの設定を併用すると、read_pageやget_page_textが返す長いテキストが古いターンにたまり続ける事態を避けられます。ブラウザ操作は何十往復にもわたることがあり、コンテキストウィンドウの圧迫はBrowser Use系ツール特有の課題です。

既知の制限

Browser Useツールにはいくつか既知の制限があります。ストリーミング時、各メンバーのinputは完全な1つのinput_json_deltaとして届くため、ターンの完了を待ってからバッチを実行する必要があります。

仮想化されたリストやcanvas描画のページでは、要素参照が安定して取得できないことがあります。その場合、Claudeはスクリーンショットと座標クリックにフォールバックします。read_consoleとread_networkは自分のブラウザ自動化スタックが対応した範囲でしか情報を返せず、タブにアタッチした時点より前のログは取得できません。レイテンシーやビジョン精度、プロンプトインジェクションのリスクは、Computer Useツールと共通する一般的なエージェントの制約として引き継がれます。

料金とデータ保持

Browser Useツールの課金は通常のツール使用料金と同じ体系です。browser_toolset_20260801をデフォルト構成で宣言すると、メンバー定義とツール使用のシステムプロンプト分として、次のトークン数が入力側に加算されます。

オプションの4メンバーをすべて有効にすると、ここに約880トークンが追加されます。正確な値はレスポンスのusageに毎回返るため、事前見積もりが必要ならトークンカウントAPIで確認できます。

これに加えて、tool_resultとして返すスクリーンショットやzoom画像は画像入力として、read_pageやget_page_textが返すテキストは通常の入力トークンとして、それぞれ別途課金されます。ブラウザセッションやダウンロードファイルは自分の環境に残り、Anthropicへ送るのはtool_resultとして返した内容だけです。Browser UseツールはZDR対象で、Covered Modelsを使う場合を除き保持期間の適用対象になります。

まとめ

navigateとread_pageの組み合わせは、Browser Useツールの中核です。read_pageが返すアクセシビリティツリーとref参照によって、Claudeはスクリーンショットを介さずに要素を直接指定できます。

実装で押さえるべき点は4つです。スキーム検証をURLパーサーで行うこと、参照の使い回しを避けること、browser_stateのルールを守ること、そして未検証のページ内容を適切に隔離することです。

デスクトップ全体の操作が必要なタスクはComputer Useツールの守備範囲です。ブラウザ内で完結するタスクにBrowser Useツールを選んだら、まずはnavigateとread_pageの往復から実装を始めるのが近道です。