Browser Use Toolの座標指定 — refと座標クリックの使い分け

Browser use toolのTargetとは何か

Browser use toolでページ上の位置を操作するメンバーは、すべてtargetという1つのオブジェクトで宛先を受け取ります。このtargetには2つの形があり、公式仕様はCoordinateTarget(ビューポート座標)とRefTarget(要素参照)と呼び分けています。

RefTargetとは、read_pageやfindが要素に割り当てた参照(ref_2のような文字列)で対象を指定する形式です。CoordinateTargetは、ビューポート上のピクセル座標x・yで対象を指定します。

どちらを渡すかはClaude側が呼び出しごとに選びます。実行側のアプリケーションは、座標なら該当ピクセルをクリックし、参照なら保持しているノードを操作します。仕様上の優先順位はなく、ページの構造しだいでClaudeが使い分けます。

対応モデルはClaude Fable 5.1・Claude Mythos 5.1・Claude Fable 5・Claude Mythos 5・Claude Opus 5・Claude Sonnet 5・Claude Opus 4.8です。提供プラットフォームはClaude APIとGoogle Cloudで、Amazon BedrockやMicrosoft Foundryでは使えません。

CoordinateTargetの仕様と注意点

CoordinateTargetは{"type": "coordinate", "x": ..., "y": ...}という整数座標で位置を指定します。対応するメンバーは11種類で、ポインター操作のほぼすべてが含まれます。

クリック系のメンバーはmodifiersという任意フィールドも受け取り、"shift"や"ctrl+shift"のようにクリック中に押すキーの組み合わせを渡せます。scrollだけはscroll_direction(上下左右)とscroll_amount(スクロールホイールのノッチ数、1〜10、既定3)という専用フィールドを追加で取ります。座標を使う呼び出しのtab_idは省略するとアクティブタブが対象になるため、複数タブを操作するエージェントでは明示しておくと安全です。

{
  "name": "left_click",
  "toolset_name": "browser",
  "input": {
    "target": { "type": "coordinate", "x": 412, "y": 128 }
  }
}

座標は、直前に返したscreenshotの全ビューポート画像を基準にしたピクセル空間です。デスクトップやウィンドウ枠は含まれません。ツールセットは表示サイズを宣言せず、Claudeは返されたスクリーンショットのサイズから座標系を推測します。返すスクリーンショットのサイズを毎回そろえておく必要があります。

zoomで拡大表示を見せた後も、Claudeが返す座標は常にフルビューポートのピクセル空間のままです。拡大画像上の相対位置には変換されません。

各メンバーの入力範囲や出力の約束事は、Claudeへの指示として明記されているだけでAPIが強制するわけではありません。座標がビューポートの範囲内かどうかを含め、実行側のコードで検証してから実際の操作に渡す設計です。

APIはスクリーンショットを自動で縮小しません。画像サイズの上限を超えたscreenshotやzoomの画像をtool_resultに含めると、リクエストごと拒否されます。縮小してから返し、Claudeが返す座標は縮小率の逆数で実画面へ戻す処理が必要です。この座標のスケーリング計算式は、Computer Useの座標ズレを直すスケーリング計算式とmacOS Retinaの罠で扱った内容がそのまま流用できます。

RefTargetの仕様と要素参照の仕組み

RefTargetはread_pageやfindが返した参照を使って対象を指定します。対応するメンバーは9種類で、このうちscroll_to・form_input・file_uploadはRefTargetしか受け付けません。

read_pageはページのアクセシビリティツリーをテキストで返し、各要素に[ref_2]のようなタグを付けます。

link "Documentation" [ref_1]
link "Getting started" [ref_2]
textbox "Search docs" [ref_3]

findは「検索フィールド」のような自然言語の説明から要素を探し、最大20件を同じタグ付き形式で返します。参照を使ったクリックは次のようになります。

{
  "name": "left_click",
  "toolset_name": "browser",
  "input": {
    "target": { "type": "ref", "ref": "ref_2" }
  }
}

実行側は、割り当てた参照とノード(アクセシビリティノードのIDや保持しているセレクタなど)の対応を自分で管理します。参照はタブごとに独立していて、そのタブが遷移するかDOMが大きく変わるまで有効です。

refはread_page自体のパラメータとしても使え、指定した要素のサブツリーだけを読み込めます。depthパラメータで木の深さの上限(最小1、既定15)を絞ることもでき、大きなページでは出力を絞ってから読む方が扱いやすくなります。

refと座標、使い分けの基準

公式仕様は、アクセシビリティツリーが使えるページではrefを優先し、ツリーが使えないコンテンツだけ座標にフォールバックするよう案内しています。理由は明確で、参照はレイアウトの崩れやリフローの影響を受けません。

読み取り方にもコツがあります。read_pageはfilter: "interactive"を指定するか、refでコンテナのサブツリーに絞ると出力が小さくなります。典型的なページでは、ツリー読み取りのほうがスクリーンショットより入力トークンが少なく済むことが多いとされています。トークンコストの詳細はClaudeのツール利用で増えるトークン数をモデル別に見るで扱っている考え方と地続きです。視覚的なレイアウトや画像、描画状態そのものを確認したいときは、screenshotが引き続き適しています。

コスト面の差も無視できません。デフォルト構成のbrowser_toolset_20260801を宣言するだけで、リクエストあたり約6,600入力トークン(Claude Sonnet 5では約6,670トークン)が加わります。これはツール定義とツール利用システムプロンプト分のオーバーヘッドで、実際のread_pageやscreenshotの結果はここに別途積み上がります。

メンバーツールごとの対応表

Targetを受け取る14のメンバーのうち、CoordinateTargetとRefTargetの両方を受け付けるのは6種類だけです。残りは片方専用です。

left_click_dragはfromとtargetの両方がCoordinateTarget専用です。ドラッグの始点と終点を参照で指定することはできません。form_inputとfile_uploadは逆に、対象を必ずRefTargetで指定します。フォーム要素の値を直接セットしたり、ファイル入力へパスを渡したりする操作は、座標クリックでは代替できません。

成功時の返し方も軽量です。screenshotとzoomだけがimageブロックを必須とし、それ以外のメンバーはClicked element ref_2.のような短いテキストの確認で足ります。スクリーンショットを追加するかどうかは実行側が任意に選べます。

バッチ内で複数のTargetを指定するとき

1つのターンに複数のメンバー呼び出しが並ぶと、バッチ実行として順番どおりに処理されます。たとえば検索欄をrefでクリックし、typeで文字を入力し、keyでEnterを押すという3手を1ターンにまとめられます。

途中の呼び出しが失敗すると、それより後のすべての呼び出しにis_error: trueとNot executed: an earlier action in this turn failed.という決まった文言が返ります。座標クリックを連続させるバッチでは、1手目でページのレイアウトが変わると2手目の座標がずれる可能性があります。refなら、同じ要素が別の位置に動いても参照自体は有効なままです。

参照が無効になる条件とエラーの返し方

参照はタブに紐づき、そのタブが遷移するかDOMが大きく変わると無効になります。APIは参照の有効性を検証できないため、失効の検知と処理はすべて実行側の責任です。

エラーテキストの例です。

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

このテキストを受け取ると、Claudeはページを読み直してから新しい参照で操作をやり直します。バッチ内の1呼び出しが失敗したときにis_error: trueを返す考え方は、並列ツール呼び出しが一部失敗したときのis_errorの返し方で扱った作法と共通しています。

なぜ2つの指定方式を併存させたのか

Browser use toolがrefと座標の両方を持つのは、Webページの実装がアクセシビリティツリーだけでは閉じないからです。Canvas描画やクロスオリジンiframe、仮想化リストまで操作対象に含めるなら、座標というフォールバックを手放せません。

対照的に、Computer Useツールを自前実装する最小構成で扱ったcomputer use toolは、デスクトップ全体をスクリーンショットと座標だけで操作します。アプリケーションのDOMという足がかりが最初からない分、参照という選択肢そのものが存在しません。

Browser use toolがブラウザ専用のツールセットとして別に用意されているのは、DOMを持つページという前提があるからこそrefを主役にできる、という設計判断の表れに見えます。座標は主役の座を譲りつつも、refが届かない領域を埋める役割として残っています。

まとめ

Browser use toolのTargetは、CoordinateTarget(ビューポート座標)とRefTarget(要素参照)の2方式です。アクセシビリティツリーが使えるページではrefを優先し、Canvas描画や仮想化リスト、クロスオリジンiframeのように有用なノードがない場面だけ座標にフォールバックします。left_click_dragのようにCoordinateTarget専用のメンバーと、form_inputのようにRefTarget専用のメンバーがある点は、実装前に対応表で確認しておくと手戻りを防げます。座標を使う実装では、スケーリング計算とスクリーンショットサイズの一貫性がそのまま精度に直結します。