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

Browser use toolのTargetとは何か

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

どちらを渡すかはClaude側が呼び出しごとに選びます。Claudeはページが公開する構造に応じて両方を使い分けます。アクセシビリティツリーが使えるページではrefを優先する方針です(詳細は後述)。

対応モデルは、Claude Fable 5.1・Claude Mythos 5.1・Claude Fable 5・Claude Mythos 5・Claude Opus 5.5・Claude Opus 5・Claude Sonnet 5.5・Claude Sonnet 5・Claude Opus 4.8の9つです。提供プラットフォームはClaude APIとGoogle Cloudで、Claude Platform on AWS・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に含めると、リクエストごと拒否されます。1リクエストに画像が20枚を超えると、1枚あたりの上限がより厳しくなります。その上限を超えた画像も拒否されます。縮小してから返し、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)も絞れます。

filterを省くと見えている要素すべてが返り、"interactive"なら操作できる要素だけ、"all"なら画面外の要素まで含みます。実行側は出力を50,000文字までに抑え、打ち切ったことをテキストに添える決まりです。Claudeはdepthを小さくするかrefで範囲を絞って読み直します。

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

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

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

この数字はツール定義とツール利用システムプロンプトの分で、read_pageやscreenshotの結果は別に積み上がります。configsでメンバーを無効にすると減り、正確な値はレスポンスのusageか、トークンカウントのエンドポイントで事前に見積もれます。

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

ツールセットは既定で27のメンバーを持ちます。javascript_exec・file_upload・read_console・read_networkを有効にすると最大31です。Targetを受け取る14のメンバーのうち、両方を受け付けるのは6種類だけです。残りは片方専用です。なおfile_uploadは既定で無効のメンバーです。

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

成功時の返し方も軽量です。screenshotとzoomだけがimageブロックを必須とし、タブ管理の4メンバー(new_tab・list_tabs・switch_tab・close_tab)はbrowser_stateブロックだけを返します。残りはClicked element ref_2.のような短い確認文か、そのメンバー自身の出力(read_pageならツリー)をテキストで返します。スクリーンショットを追加するかどうかは実行側が任意に選べます。

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

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

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

実行側が1往復で1呼び出ししか処理できないときは、tool_choiceにdisable_parallel_tool_use: trueを指定します。Claudeは1ターンに最大1つのメンバー呼び出しだけを返すので、その代わり往復は増えます。

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

APIは参照の有効性を検証できないため、失効の検知と処理はすべて実行側の責任です。

バッチ内の1呼び出しが失敗したときにis_error: trueを返す考え方は、並列ツール呼び出しが一部失敗したときのis_errorの返し方で扱った作法と共通しています。

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

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

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

2つのツールは同じリクエストに併せて宣言することもできます。座標系は別々で、browser側はビューポートのピクセル、computer use側はデスクトップのスクリーンショットのピクセルです。screenshotやkeyのように同名のメンバーは、呼び出しに付くtoolset_nameで見分けます。

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

まとめ

実装の順序としては、refとノードの対応表の管理と、失効した参照へのエラー応答を先に作るのが堅実です。座標のほうは、スクリーンショットの縮小率を換算する処理を必ず通します。ここを外すと、refで届かない場面の操作が一斉にずれます。