Browser use toolのバッチアクション — 1ターンで複数操作をまとめる実装
browser_toolsetのバッチアクションで、クリック・入力・Enterを1回のtool_useにまとめ往復回数を減らす実装を解説します。
browser_toolsetは、独立した複数の操作を1回のtool_useにまとめてClaudeに返させる設計を持ちます。これがバッチアクションです。検索ボックスをクリックし、クエリを入力し、Enterを押すといった一連の操作を1ターンで返せるため、Messages APIとの往復回数を減らせます。
tool_useバッチの実行順序依存・失敗時のis_error処理・disable_parallel_tool_useによる抑止は、Computer Useツールを自前実装する最小構成の「バッチアクションでつまずきやすい3つの落とし穴」にまとまっています。ここではbrowser_toolset特有の設計と、ブラウザ操作の具体例に絞ります。
バッチアクションで往復回数が減る仕組み
バッチアクションとは、Claudeが独立した複数のメンバーツール呼び出しを1回の応答にまとめて返す仕組みです。応答の形はparallel tool useと同じで、違いはブロックを並列ではなく順番に実行する点だけです。
browser_toolset_20260801を1エントリ宣言すると、Claudeはnavigate・read_page・left_click・screenshotを含む27個のメンバーツールを既定で使えます。個々のメンバーは1操作しか表しませんが、Claudeは複数のメンバー呼び出しを1つのtool_use配列にまとめて返せます。ストリーミング時も各メンバーのinputは1つの完全なinput_json_deltaとして届くため、実行前にターンの完了を待つ設計にします。
検索ボックスへの入力を例にすると、クリック・入力・Enterの3操作を1ターンで返すことで、本来なら3往復かかるところを1往復に圧縮できます。ページのクロールや繰り返しの多いフォーム入力ほど、この往復削減の効果は大きくなります。
クリック・入力・Enterを1回のtool_useにまとめる例
Claudeが返すバッチは、toolset_name: "browser"を持つtool_useブロックが複数並んだ配列です。先に見つけた検索ボックスをクリックし、クエリを入力し、Enterを押す例は次の形になります。
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"name": "left_click",
"toolset_name": "browser",
"input": { "target": { "type": "ref", "ref": "ref_3" } }
},
{
"type": "tool_use",
"id": "toolu_01Ez4kLb1nQ2vXo8sJ9pWm3c",
"name": "type",
"toolset_name": "browser",
"input": { "text": "install" }
},
{
"type": "tool_use",
"id": "toolu_01FkP8rTz6uYh2mNq4LsXw7v",
"name": "key",
"toolset_name": "browser",
"input": { "text": "Enter" }
}
]
}実行後、アプリケーションは3つのtool_resultブロックを1つのuserメッセージにまとめて返します。それぞれがtoolset_name: "browser"と、Clicked element ref_3.のような短い実行確認テキストを持ちます。Enterでページ遷移が起きた場合、そのkeyの結果にはタブの最新URLを示すbrowser_stateブロックも添えます。
エグゼキュータ側でどのメンバーを実行するかはnameだけでなく(toolset_name, name)の組で振り分けます。同じリクエストに自前のツールがnavigateのような名前を持っていても、toolset_nameが異なるため衝突しません。ループの中身を1つの関数として組み立てる実装パターンは、Python SDKのtool_runnerでツール呼び出しの自動実行ループを組む節にまとまっています。
観察結果を最後の結果に添えて往復をもう1回減らす
Claudeは通常、バッチの最後をscreenshot・read_page・get_page_textのいずれかで締めくくり、実行結果を目視してから次のアクションを決めます。締めくくりの呼び出しが無いバッチが返ってきた場合、アプリケーション側からスクリーンショットや最新のアクセシビリティツリーを最後の結果に追加のコンテンツブロックとして添えられます。
この一手間で、Claudeが改めてscreenshotを要求する往復を1回省けます。ただし添える先は選びます。タブ管理系の結果はbrowser_stateブロック1つだけに固定されているため、観察結果はタブ管理呼び出し以外の最後の結果に添えます。
タブ管理呼び出しをバッチに混ぜるときの制約
new_tab・list_tabs・switch_tab・close_tabの4つは、成功時にbrowser_stateブロックをちょうど1つだけ返し、テキストや画像は持てません。これは27個のメンバーのうちタブ管理系の4つだけに課された制約です。
クリックやスクリーンショットの結果には短い確認テキストや画像を添えられますが、タブ管理の結果はタブの一覧・アクティブタブ・URLといった状態だけを運びます。バッチの中に新規タブを開く操作と通常の操作を混在させるときは、この形の違いを踏まえてエグゼキュータの分岐を書きます。
disable_parallel_tool_useを使うとバッチの形はどう変わるか
エグゼキュータが1往復につき1呼び出ししか処理できない設計なら、tool_choiceにdisable_parallel_tool_use: trueを指定します。Claudeは1ターンにつきメンバー呼び出しを1つしか返さなくなり、往復回数は増える代わりに実行順序や失敗時の後始末を考える必要自体がなくなります。このオプション自体の詳しい使いどころは、前段でリンクした落とし穴の記事にまとまっています。
このオプションを有効にしても、成功した結果のcontentが何を持つかは通常のバッチと同じ規約に従います。Member toolsの表のとおり、new_tab・switch_tab・close_tab・list_tabsの結果はbrowser_stateブロック1つのみで、それ以外のメンバーの結果はテキストや画像にbrowser_stateを添えられます。
要素参照と座標、2つのターゲット指定をバッチ内で使い分ける
バッチ内のleft_clickやhoverのようなポインタ系メンバーは、targetにviewportピクセルの座標(CoordinateTarget)か、read_pageやfindが返した要素参照(RefTarget)のどちらかを渡します。アクセシビリティツリーが使えるページでは参照を優先すると、レイアウトのずれに強く、座標では狙いにくい要素にも作用できます。
キャンバス描画のUIや埋め込み動画、クロスオリジンのiframe内の要素はツリーに現れないことがあり、その場合Claudeはscreenshotやzoomを見て座標クリックに切り替えます。1つのバッチの中で参照クリックと座標クリックが混在しても構いません。エグゼキュータ側はtarget.typeが"ref"か"coordinate"かで分岐すれば足ります。
参照は発行したタブに閉じたスコープを持ち、そのタブが遷移するかDOMが大きく変わるまでだけ有効です。Claudeが認識していない参照を渡してきた場合は、Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references.のようなエラー結果を返すと、Claudeはページを読み直してから参照を作り直します。バッチの途中でこのエラーが起きると、そこから先のブロックは打ち切りの対象になります。
Computer use toolのバッチアクションとの違い
browser_toolsetのバッチアクションは、computer use toolのバッチアクションと同じ「順番に実行し、最初の失敗で残りを打ち切る」という骨格を共有します。ただし細部は2点で異なります。
| 項目 | Computer use tool | Browser use tool |
|---|---|---|
| 打ち切り後の文言 | Computer use toolNot executed: an earlier computer action in this turn failed. | Browser use toolNot executed: an earlier action in this turn failed. |
| 成功時の結果の中身 | Computer use toolscreenshot・zoomは画像、他のメンバーはOKのような短いテキストで足りる | Browser use toolMember toolsの規約に従い、タブ管理系はbrowser_stateブロック1つに固定 |
打ち切り後に返すテキストは両ツールで1語違います。実装を使い回すときは、この文言をtoolset側で切り替える必要があります。
自前のツールやcomputer use toolと組み合わせる場合
browser use toolは、自前のカスタムツールやcomputer use toolと同じtools配列の中に宣言して組み合わせられます。自前のツールがnavigateのようなメンバーと同じ名前を持っていてもtoolset_nameで区別されるため衝突しませんが、1回のリクエストにbrowserという名前のツールセットは1つしか置けません。
computer use toolと併用すると、両者は別々の座標系で動きます。browser use toolはビューポートピクセル、computer use toolはデスクトップのスクリーンショットピクセルが基準で、screenshotやkeyのように名前が重なるメンバーもtoolset_nameで見分けます。1つのバッチに両方のツールセットのブロックが混ざることもあるため、エグゼキュータのディスパッチはname単独ではなくtoolset_name込みで組みます。
Message Batches APIと混同しないために
「バッチ」という語は、Anthropic APIのもう1つの機能であるMessage Batches APIとも重なります。両者は別の仕組みです。
browser use toolのバッチアクションは、1回のターンに複数のtool_use呼び出しをまとめて往復回数を減らす仕組みです。一方でMessage Batches APIは、多数の独立したMessagesリクエストをまとめて非同期に処理する機能で、リアルタイムの会話ではなく大量データの一括処理に向きます。実装の作法はClaudeのMessage Batches SDKをPython・TypeScript・Ruby・Javaで実装するにまとめています。
料金への影響
browser_toolset_20260801を既定のメンバーで宣言すると、ツール定義とツール使用のシステムプロンプト分として約6,600入力トークンが加わります(Claude Sonnet 5では約6,670トークン)。バッチアクション自体はこの宣言コストを下げる仕組みではなく、あくまで往復の回数を減らす設計です。
4つの追加メンバー(javascript_exec・file_upload・read_console・read_network)をすべて有効にすると約880トークンが加わり、configsでメンバーを無効化すればその分だけ減ります。正確なトークン数はレスポンスのusageに返るため、事前に見積もる場合はtoken counting endpointを使います。
対応モデルとプラットフォーム、セキュリティ上の注意
browser use toolは、Claude APIとGoogle Cloud(Vertex AI)経由で使え、Claude API on AWS・Amazon Bedrock・Microsoft Foundryでは提供されていません。対応モデルは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は開いたウェブページの内容をそのまま読み取ります。ページ側に操作を誘導する文言が仕込まれていることもあるため、専用のコンテナや仮想マシンで、資格情報を持たないプロフィールを使って隔離する運用が前提になります。
まとめ
browser_toolsetのバッチアクションは、クリック・入力・Enterのような一連の操作を1回のtool_useにまとめ、Messages APIとの往復を減らす設計です。バッチの最後に観察結果を添える工夫や、タブ管理系の結果がbrowser_stateブロック1つに固定される制約を押さえておくと、エグゼキュータの実装で迷いにくくなります。
エグゼキュータが1往復に1呼び出ししか処理できない場合は、disable_parallel_tool_use: trueでバッチそのものを止められます。実行順序への依存や失敗時のis_error処理まで踏み込んで実装する際は、Computer Useツールを自前実装する最小構成の落とし穴の節を合わせて確認してください。