ブラウザ使用ツール

ブラウザ使用ツールを使うと、Claudeはお客様のアプリケーションが実行するブラウザ内でWebページを移動、読み取り、操作できます。Claudeは、ページの構造（「accessibility tree」（アクセシビリティツリー）、要素、フォーム、タブ）と、スクリーンショットおよびビューポート座標の両方を通じてページを扱います。

このツールはAnthropicが定義する「client toolset」（クライアントツールセット）です。toolsにbrowser_toolset_20260801エントリを1つ追加すると、Claudeはデフォルトでnavigate、read_page、left_click、screenshotなどの27個のメンバーツールを利用でき、さらに有効化すると4つのツールが追加されます。すべての呼び出しはお客様のアプリケーションが独自のブラウザ自動化に対して実行し、Anthropic側では何も実行されません。このツールは現在、Claude Managed Agentsでは利用できません。

PythonおよびTypeScript SDKには、これらの呼び出しをお客様のブラウザコードに渡し、設定したURLポリシーとファイルポリシーを実行し、承認コールバックに確認を求めるクラスが含まれています。SDKツールセットによるブラウザ使用とコンピュータ使用を参照してください。

タスクがWebページ内で完結し、ページ上での操作を伴う場合、またはページがJavaScriptでコンテンツを構築する場合は、ブラウザ使用を選択してください。タスクにデスクトップ全体が必要な場合は、スクリーンショットと座標のみで動作するコンピュータ使用ツールを使用してください。Claudeに指定できるページを読み取る場合や、Web上で情報源を探す場合は、WebフェッチツールとWeb検索ツールのほうが軽量です。これらはAPIが代わりに実行するサーバーツールであり、操作するブラウザは不要です。

ブラウザ使用では、Claudeはライブのページを読み取って操作するため、ページが提供するものはすべて信頼できない入力であり、Claudeが行う操作は実際の影響を及ぼす可能性があります。デプロイする前にセキュリティに関する考慮事項を確認してください。

クイックスタート

ブラウザ使用ツールはClaude APIとGoogle Cloudで利用できます。Messages APIリクエストのtools配列に、nameなしでbrowser_toolset_20260801型のエントリを1つ追加します。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=2048,
    tools=[{"type": "browser_toolset_20260801"}],
    messages=[
        {
            "role": "user",
            "content": "Open example.com/docs and tell me how to get started.",
        }
    ],
)
print(response)

Claudeの最初のレスポンスはstop_reason: "tool_use"で終了し、1つ以上のメンバーtool_useブロックを含みます。各ブロックはnameでメンバーツールを指定し、"toolset_name": "browser"を持ちます：

{
  "id": "msg_01HCDu4XSTLzTAcodEQ58vDo",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the documentation and read the page to find the getting-started instructions."
    },
    {
      "type": "tool_use",
      "id": "toolu_01NRLabsLyVHZPKxbKvkfSMn",
      "name": "navigate",
      "toolset_name": "browser",
      "input": { "url": "https://example.com/docs" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01UvHU5cDyTZ2vXKf5wCkPqR",
      "name": "read_page",
      "toolset_name": "browser",
      "input": { "filter": "interactive" }
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

「executor」（エグゼキューター：ブラウザを操作してツール結果を生成するアプリケーションの部分）がnavigateを実行し、次にread_pageを実行します。アプリケーションは次のリクエストでブロックごとに1つのtool_resultを返し、それぞれにtoolset_nameをエコーします。navigateの結果は読み込んだタブをbrowser_stateブロックで報告し、read_pageの結果はすべての要素が参照を持つテキストです：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01NRLabsLyVHZPKxbKvkfSMn",
      "toolset_name": "browser",
      "content": [
        { "type": "text", "text": "Navigated to https://example.com/docs" },
        {
          "type": "browser_state",
          "tabs": [
            {
              "tab_id": "tab-1",
              "title": "Documentation",
              "url": "https://example.com/docs",
              "active": true
            }
          ]
        }
      ]
    },
    {
      "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]\nbutton \"Search\" [ref_4]\nlink \"Pricing\" [ref_5]"
        }
      ]
    }
  ]
}

Claudeは操作可能な参照を保持しているため、次のターンではref_2をクリックして入門ページを開くことができ、最初にスクリーンショットでリンクの位置を特定する必要はありません。

ブラウザ使用の仕組み

ブラウザ使用は、お客様のアプリケーション内で「agent loop」（エージェントループ）として実行されます。Claudeがメンバーツールの呼び出しを返し、エグゼキューターがそれをブラウザに対して実行し、Claudeがテキストで回答するまで結果を返し続けます。

1. 1

   Claudeにブラウザ使用ツールとユーザープロンプトを提供する

   • browser_toolset_20260801エントリと、必要に応じて他のツールをAPIリクエストに追加します。
   • Webページの操作を必要とするユーザープロンプトを含めます。例：「example.com/docsを開いて、始め方を教えてください。」
2. 2

   Claudeがメンバーツールの呼び出しで応答する

   • Claudeは1つのアシスタントターンで1つ以上のtool_useブロックを返します。1つのターン内の複数のブロックは「batch action」（バッチアクション）を構成します。例：left_click、次にtype、次にkey。
   • 各ブロックのnameはメンバー名で、それぞれが"toolset_name": "browser"を持ち、inputにはそのメンバーのパラメータのみが含まれ、actionフィールドはありません。レスポンスのstop_reasonはtool_useです。
3. 3

   呼び出しを順番に実行して結果を返す

   • response.content内のすべてのtool_useブロックを反復処理し（ちょうど1つだと仮定しないでください）、後の呼び出しは通常前の呼び出しに依存するため、出現順に逐次実行します。
   • 新しいuserメッセージで、tool_use_idで対応付けたブロックごとに1つのtool_resultを返し、それぞれに"toolset_name": "browser"をエコーします。すべての呼び出しに応答しないと、次のリクエストは拒否されます。
   • 呼び出しが失敗した場合は、そのブロックに対してテキストの説明付きでis_error: trueを返し、そのターン内の後続のすべてのブロックにバッチアクションの停止ルールを適用します。
4. 4

   タスクが完了するまでClaudeが続行する

   • Claudeは結果（ページテキスト、アクセシビリティツリー、スクリーンショット、タブの状態）を読み取り、さらに必要な場合は追加のメンバー呼び出しを返します。その場合はステップ3に戻ります。
   • それ以外の場合は、ユーザーにテキストレスポンスを返します。

以下は、そのループのツール呼び出しステップの骨組みを2つの部分に分けたものです。まず、スタブのメンバーハンドラーがブラウザ自動化の代わりを務めます。5つのメンバー（navigate、read_page、left_click、type、screenshot）は、結果のコンテンツとなるテキスト（screenshotの場合は画像ブロック）を返し、ディスパッチャーは実装されていないメンバーに対してエラーを発生させます。

# プレースホルダーの画像データ。実際のエグゼキューターはビューポートをキャプチャしてPNGバイトを返します
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="


def navigate(url):
    return f"navigated to {url}"


def read_page():
    return 'link "Docs" [ref_1]\nbutton "Search" [ref_2]'


def click(target):
    # ターゲットは read_page または find からの要素参照、またはビューポート座標です
    if target["type"] == "ref":
        return f"clicked {target['ref']}"
    return f"clicked at ({target['x']}, {target['y']})"


def type_text(text):
    return f"typed: {text}"


def capture_screenshot() -> list[ImageBlockParam]:
    # screenshot はテキストではなく画像ブロックで応答します。結果のコンテンツリストを返します
    return [
        {
            "type": "image",
            "source": {"type": "base64", "media_type": "image/png", "data": PLACEHOLDER_PNG},
        }
    ]


def handle_browser_action(name, tool_input):
    if name == "navigate":
        return navigate(tool_input["url"])
    elif name == "read_page":
        return read_page()
    elif name == "left_click":
        return click(tool_input["target"])
    elif name == "type":
        return type_text(tool_input["text"])
    elif name == "screenshot":
        return capture_screenshot()
    # 必要に応じて他のアクションを処理します
    raise ValueError(f"Unknown or unimplemented member: {name}")

2つ目の部分は、バッチを順番に実行し、各ブロックをそれらのハンドラーにディスパッチし、すべての結果にtoolset_nameをエコーし、バッチアクションの停止ルールを適用して、ハンドラーのエラーをエラー結果に変換します。これを呼び出すサンプリングループは、エージェントループを理解するで示されているもので、toolsにブラウザツールセットを含めたものです。

NOT_EXECUTED = "Not executed: an earlier action in this turn failed."


def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
    """
    Run the browser actions in Claude's response in order and answer each
    one. After the first failure the rest are skipped, because Claude planned
    them assuming the earlier actions succeeded.
    """
    tool_results: list[ToolResultBlockParam] = []
    failed = False
    for block in response.content:
        # ブラウザツールセットのみ宣言されています。他のツールを追加する場合はここでルーティングします
        if block.type != "tool_use" or block.toolset_name != "browser":
            continue
        result: ToolResultBlockParam = {
            "type": "tool_result",
            "tool_use_id": block.id,
            "toolset_name": "browser",
        }
        if failed:
            result["content"] = NOT_EXECUTED
            result["is_error"] = True
        else:
            try:
                # 文字列またはコンテンツブロックのリスト。実際のエグゼキューターはさらに
                # ナビゲーションとタブ管理の結果に browser_state ブロックを追加します
                result["content"] = handle_browser_action(block.name, block.input)
            except Exception as err:
                result["content"] = f"Error: {err}"
                result["is_error"] = True
                failed = True
        tool_results.append(result)
    return tool_results

同じリクエスト内のカスタムツールがメンバーと同じ名前を持つ可能性があるため、各ブロックはnameだけでなく（toolset_name、name）のペアでディスパッチしてください。両方のツールセットが共有するこの契約の部分については、クライアントツールセットで説明しています。エグゼキューターが実装していないメンバーや、無効にしたメンバーをClaudeが指定した場合は、そのブロックを破棄せずにエラー結果で応答してください。

レスポンスをストリーミングする場合、各メンバーのinputは断片ではなく1つの完全なinput_json_deltaとして届くため、バッチを実行する前にターンが終了するのを待ってください。

バッチアクション

複数のメンバー呼び出しを含むターンはバッチアクションです。呼び出しを出現順に実行し、最初の失敗で停止し、後続のすべての呼び出しにis_error: trueと正確なテキストNot executed: an earlier action in this turn failed.で応答します。バッチは並列ツール使用と同じレスポンス形式を使用しますが、違いはブロックを並行ではなく順番に実行することです。ここでは、Claudeが以前に見つけた検索ボックスをクリックし、クエリを入力し、Enterキーを押す操作を1つのターンで行います：

{
  "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" }
    }
  ]
}

アプリケーションは1つのuserメッセージで3つのtool_resultブロックを返します。それぞれがtoolset_nameと、Clicked element ref_3.のような短いテキストの確認応答を持ちます。Enterキーを押すと結果ページが読み込まれるため、keyの結果にはタブの更新されたURLを含むbrowser_stateブロックも含まれます（他の結果におけるタブコンテキスト）。代わりにクリックが失敗していた場合、その結果にはエラーテキストが含まれ、他の2つの結果には停止テキストが含まれます。これはエグゼキューターからエラーを返すに示されているとおりです。

呼び出しのたびにスクリーンショットを返す必要はありません。Claudeは通常、観察呼び出し（screenshot、read_page、またはget_page_text）でバッチを終了します。また、アプリケーションは往復を節約するために、新しいスクリーンショットやアクセシビリティツリーなどの独自の観察結果を、バッチ内の最後の結果に追加のコンテンツブロックとして添付することもできます。タブ管理の結果は正確に1つのbrowser_stateブロックでなければならないため、タブ管理呼び出しではない最後の結果に添付してください。

エグゼキューターが1回の往復で1つの呼び出ししか実行できない場合は、tool_choiceでdisable_parallel_tool_useをtrueに設定すると、Claudeはターンごとに最大1つのメンバー呼び出しを返しますが、往復の回数は増えます（並列ツール使用を無効にする）。コンピュータ使用ツールのバッチアクションの規約の残りの部分は、次のuserメッセージですべてのtool_useに対して1つのtool_resultを返すことを含めてそのまま適用されますが、停止テキストと、成功した結果のcontentに含まれる内容の2点は例外です。結果のコンテンツは、代わりにこのページのメンバーツールに従います。new_tab、switch_tab、close_tab、またはlist_tabsの結果は、テキストや画像を含まない正確に1つのbrowser_stateブロックであり（タブ管理の結果）、その他のメンバーの結果は、テキストまたは画像にbrowser_stateブロックを追加できます（他の結果におけるタブコンテキスト）。バッチ内のキャッシュブレークポイントがどこで有効になるかは、コンピュータ使用ツールのツールパラメータのcache_control行で説明されています。

ターゲットと座標

場所に対して動作するメンバーツールはtargetオブジェクトを受け取ります。これはビューポートピクセル座標、またはread_pageやfindが返した要素への参照のいずれかです。メンバーツールの表では、どちらの形式も受け付けるパラメータをTargetと表記しています。

座標はビューポートピクセルです。これは、レンダリングされたページの左上を原点とする、ビューポート全体のscreenshotのピクセル空間です。周囲のデスクトップやウィンドウフレームはありません。ツールセットは表示サイズを宣言せず、Claudeは返されたスクリーンショットからビューポートサイズを推測するため、スクリーンショットは一貫した1つのサイズに保ってください。zoomはフレームを変更しないため、そのregionと、ズームされた画像を見た後にClaudeが出力する座標は、引き続きビューポート全体のピクセルです。

スクリーンショットは画像の制限内に収める必要があります。 APIはツールセットの画像を縮小しません。モデルの画像サイズの制限を超えるスクリーンショットやズーム画像、またはリクエストに20枚を超える画像が含まれる場合に適用される、より厳しい画像ごとの制限を超えるものは拒否されます。返す前にサイズを変更し、Claudeの座標をディスパッチする前に、縮小率の逆数を掛けて元のスケールに戻してください（画像の制限に合わせてスクリーンショットのサイズを調整する）。

要素参照はread_pageとfindから取得されます。 それらの出力の各要素には、クイックスタートの結果のように[ref_2]などのタグが付いています：

link "Documentation" [ref_1]
link "Getting started" [ref_2]
textbox "Search docs" [ref_3]
button "Search" [ref_4]
link "Pricing" [ref_5]

Claudeは、後続のクリック、hover、scroll_to、form_input、またはfile_upload呼び出しで参照を{"type": "ref", "ref": "ref_2"}ターゲットとして渡すか、サブツリーを読み取るためにread_pageのrefパラメータとして渡します。エグゼキューターは参照を割り当て、各参照から基になるノード（アクセシビリティノードID、保存されたセレクター、または同等のもの）へのマッピングを保持し、参照が返されたときにそのノードに対して操作を行います。

参照は、それを生成したタブにスコープされ、そのタブがナビゲートするか、DOMが大幅に変更されるまで有効です。APIは古い参照や不明な参照を検出できないため、エグゼキューターが認識できなくなった参照をClaudeが渡した場合は、Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references.のようなエラー結果を返してください。するとClaudeはページを再度読み取ります。タブがナビゲートするまでは、そのタブに対してすでに渡した参照の番号を振り直さないでください。振り直すと、Claudeがまだ保持している参照が暗黙的に無効になります。

Claudeは両方のターゲット指定方式を使用し、ページが公開する内容に基づいてそれらを切り替えます。プロンプトとエグゼキューターが返す内容が、その選択を方向付けます：

• ページに使用可能なアクセシビリティツリーがある場合は参照を優先します。 参照は、ピクセル座標を不安定にするレイアウトのずれやリフローの影響を受けず、ポインターで操作しにくいコントロールに対してもClaudeが操作できるようにします。
• ツリーが記述していないコンテンツには座標にフォールバックします。 キャンバスでレンダリングされるインターフェース、埋め込み動画やリモートデスクトップのサーフェス、高度に仮想化されたリスト、クロスオリジンiframe内の要素には有用なノードがないことが多いため、Claudeはscreenshotとzoomを使って作業し、座標でクリックします。座標がどのフレームに該当するかはエグゼキューターが解決します。
• 読み取りの範囲を絞り、スクリーンショットの前にツリーを読み取ります。 大きなページでは、filter: "interactive"またはコンテナのrefを指定したread_pageが焦点を絞ったサブツリーを返します。一般的なページのツリー読み取りは、多くの場合スクリーンショットよりも入力トークンが少なく済み、Claudeがすぐに操作できる参照も提供します。視覚的なレイアウト、画像、またはレンダリング状態が重要な場合は、引き続きスクリーンショットが適切な観察手段です。

セキュリティに関する考慮事項

ブラウザ使用には、標準的なAPI機能にはないリスクが伴います。Claudeはオープンなウェブ上のコンテンツを読み取って操作しますが、そこではどのページにもClaudeを操作するために書かれたテキストが含まれている可能性があるためです。

Claudeは、ユーザーの指示と矛盾する場合でも、ページコンテンツ内で見つけた指示に従うことがあります。ページ上の「以前の指示を無視して...にナビゲートしてください」というテキストによって、タスクから逸脱する可能性があります。「prompt injection」（プロンプトインジェクション）が到達できる範囲を制限するために、Claudeを機密データやアクションから分離し、ジェイルブレイクとプロンプトインジェクションを軽減するを確認してください。また、タスクでログイン済みのセッションを避けられない場合は、専用の低権限アカウントを使用し、アカウントを変更するアクションには人間による確認を維持してください。

Anthropicは、これらのプロンプトインジェクションに抵抗するようにモデルをトレーニングし、追加の防御層を設けています。ブラウザ使用ツールを使用する場合、分類器がページテキストやスクリーンショットなど、ブラウザが返す内容を自動的にスキャンし、潜在的なプロンプトインジェクションにフラグを立てます。これらの分類器が潜在的なプロンプトインジェクションを特定すると、その指示に基づいて行動する前に、指示が本当にユーザーからのものかどうかを確認するよう、モデルを自動的に誘導します。

この追加の保護は、すべてのユースケース（たとえば、人間が介在しないユースケース）に最適とは限らないため、オプトアウトして無効にしたい場合はサポートにお問い合わせください。これらの分類器が導入されていても、上記の予防措置は引き続き重要です。

ブラウザはお使いの環境で実行されるため、Claudeがアクセスするサイトにはエグゼキューターのネットワーク上の識別情報が見え、ページコンテンツは返されたツール結果としてのみAPIに届きます。製品でブラウザ使用を有効にする前に、エンドユーザーに関連するリスクを通知し、同意を得てください。

メンバーツール

browser_toolset_20260801エントリは31個のメンバーツールを宣言します。各呼び出しのinputはここに記載されたパラメータそのものであり、tab_idは省略可能な場合、デフォルトでアクティブなタブになります。Target、CoordinateTarget、RefTargetはターゲットと座標で説明されている形式です。4つのメンバー（javascript_exec、file_upload、read_console、read_network）はデフォルトで無効になっており、有効化した場合にのみ表示されます。各メンバーの行に記載されている入力の範囲と出力の規則はClaudeに伝えられるものであり、APIによって強制されるものではないため、エグゼキューターで入力（ビューポートに対する座標を含む）を検証し、規則を適用してください。

結果にimageブロックが必要なのはscreenshotとzoomのみで、4つのタブ管理メンバー（new_tab、list_tabs、switch_tab、close_tab）は正確に1つのbrowser_stateブロックを返します（タブ管理の結果を参照）。その他のすべてのメンバーはtextブロックを返します。これはClicked element ref_2.のような短い確認応答か、メンバーの出力のいずれかです。タブ管理の結果以外の結果には、imageブロック（通常はアクション後に撮影されたスクリーンショット）を含めることもでき、これによりClaudeは別途screenshotを呼び出さずに結果を確認できます。バッチ内のどこに添付するかはバッチアクションで示しています。メンバーのtool_resultには、text、image、browser_stateのコンテンツブロックのみを含めることができます。

ナビゲーションとキャプチャ

ポインター

キーボードとタイミング

ページの読み取り

フォームとファイル

診断とスクリプト

タブ管理

成功すると、これらはそれぞれテキストや画像を含まない正確に1つのbrowser_stateブロックを返します。タブ管理の結果を参照してください。

ツールセットを設定する

typeに加えて、ツールセットエントリはconfigs、cache_control、allowed_callersを受け付けます。これらのフィールドがコンピュータ使用ツールセットと共有するルールはクライアントツールセットに記載されており、このセクションではブラウザ固有のデフォルトについて説明します。configsはメンバー名をキーとするオブジェクトで、各メンバーの値は2つのフィールドを受け付けます：

メンバーツールを有効または無効にする

configsには変更したいメンバーのみを記載してください。省略したメンバーはすべてデフォルトのままです。たとえば、コンソールの読み取りは実装しているが、低レベルのポインター操作やキーの長押し操作は実装していないエグゼキューターでは、read_consoleを有効にし、3つのメンバーを除外します：

{
  "type": "browser_toolset_20260801",
  "configs": {
    "read_console": { "enabled": true },
    "left_mouse_down": { "enabled": false },
    "left_mouse_up": { "enabled": false },
    "hold_key": { "enabled": false }
  }
}

無効にしたメンバーはClaudeが参照する定義から消えますが、Claudeがそのメンバーを指定しないことが保証されるわけではないため、エグゼキューターはそのような呼び出しにもエラー結果で応答する必要があります。

他のツールと組み合わせる

ブラウザ使用ツールは、独自のツールや他のAnthropic提供ツールと同じtools配列で宣言できます。toolset_nameによってClaudeの呼び出しが区別されるため、カスタムツールはメンバーと同じ名前（たとえば独自のnavigate）を持つことができますが、他のエントリにbrowserという名前を付けることはできず、1つのリクエストに含めることができるブラウザツールセットエントリは1つだけです。

コンピュータ使用ツールと一緒に宣言することもできます。ツールセットと以前のバージョンのコンピュータ使用ツールのどちらでも構いません。この2つはそれぞれ独自の座標系（こちらはビューポートピクセル、あちらはデスクトップのスクリーンショットピクセル）で独立して動作し、screenshotやkeyなど名前を共有するメンバーへのClaudeの呼び出しはtoolset_nameによって区別されます。

オプションのメンバーを有効にする

4つのメンバーツールはデフォルトで無効になっています。javascript_execとfile_uploadは、操作されたページがClaudeに実行させ得る範囲を広げるためです。read_consoleとread_networkは、すべてのブラウザ自動化スタックがこれらのログを提供できるわけではなく、ページが制御するコンテンツがClaudeに届く範囲を広げるためです。エグゼキューターが実装しており、タスクで必要な場合にのみ、configsでそれぞれを有効にしてください（例："configs": {"file_upload": {"enabled": true}}）。

ファイルをアップロードする

file_uploadは<input type="file">要素にファイルを直接設定します。これはネイティブのファイル選択ダイアログを操作するよりも信頼性が高い方法です。呼び出しには要素の識別情報が必要なため、そのtargetは参照のみであり、paths、document_ids、またはその両方を受け取ります：

• pathsはエグゼキューターのファイルシステム上のファイルパスで、エグゼキューターがアプリケーションのファイルを直接読み取れるデプロイメント向けです（ダウンロードのpathを設定するのと同じ条件です）。
• document_idsは、アプリケーションがブラウザ用にステージングしたファイルの識別子で、直接読み取れないデプロイメント向けです。識別子の意味はアプリケーションが定義します。pathsと同様に、その解決範囲をこのタスク用にステージングされたファイルに限定してください。

{
  "type": "tool_use",
  "id": "toolu_01N7gVzFEfZjLjgsYwnrPgrF",
  "name": "file_upload",
  "toolset_name": "browser",
  "input": {
    "target": { "type": "ref", "ref": "ref_12" },
    "paths": ["/home/user/uploads/summary.pdf"],
    "tab_id": "tab-2"
  }
}

Claudeは信頼できないページを読み取りながらこれらのパスを書き込むため、制限のない実装では、悪意のあるページが、エグゼキューターが読み取れる任意のファイルを、そのページが制御するサイトにアップロードさせることができてしまいます。エグゼキューターが各パスを（シンボリックリンクと..セグメントをたどって）解決し、タスク用のファイルのみを保持する専用の許可リスト登録済みアップロードディレクトリ以外のものを一切受け付けない場合にのみ、このメンバーを有効にしてください。この目的でブラウザのダウンロードディレクトリを再利用しないでください。再利用すると、ページがブラウザにダウンロードさせたすべてのファイルがアップロード可能になります。

ページでJavaScriptを実行する

javascript_execは、Claudeが書いた式をページのコンテキストで実行し、最後の式の値をテキストとして返します。Claudeが書くのは式であり、return文ではありません。コードは、Cookie、ストレージ、同一オリジンリクエストを含むページの完全な権限で実行されます。このメンバーは、認証情報を保持しないセッションでのみ有効にし、セキュリティに関する考慮事項のドメイン許可リストを適用し続け、返された値を信頼できない入力として扱い、Claudeが出力するコードをログに記録してください。

コンソールとネットワークのアクティビティを読み取る

read_consoleはタブのコンソールエントリを、read_networkはタブのネットワークリクエストを返します。いずれも、そのタブの前回の読み取り以降に蓄積されたエントリを、1エントリにつき1行のテキストとして返します。コンソールの行にはログ、警告、またはエラーのエントリが含まれ、ネットワークの行にはメソッド、URL、ステータス、MIMEタイプ、タイミングが含まれます。エントリはブラウザ自動化がタブにアタッチした時点以降のものしか存在しないため、結果が空であっても、すでに開いていたタブにトラフィックがなかったことを意味するわけではありません。

これらのメンバーにより、Claudeはスクリーンショットを繰り返し撮ることなく、不具合のあるページ（スピナーの背後にある失敗したリクエスト、反応しないボタンの背後にあるスクリプトエラー）を診断できます。コンソールとネットワークのエントリはページによって制御され、リクエストURL内のトークンなどのシークレットを含むことが多いため、Claudeのコンテキストに含めたくない認証情報のような値は編集して除去し、非常に長いエントリは返す前に切り詰めてください。

browser_stateでタブを追跡する

Claudeはtab_idでタブを指定します。どのタブが存在するかについては、アプリケーションが「source of truth」（信頼できる唯一の情報源）となります。その状態はbrowser_stateコンテンツブロックで報告しますが、Claudeがこのブロックを直接見ることはありません。Claudeが読むテキストは、APIがこのブロックからレンダリングします。

{
  "type": "browser_state",
  "tabs": [
    {
      "tab_id": "tab-1",
      "title": "Documentation",
      "url": "https://example.com/docs",
      "active": true
    },
    { "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" }
  ]
}

• tabsは、呼び出し後に開いているタブの完全な一覧であり、差分ではありません。空でもかまいませんが、空でない場合は、ちょうど1つのエントリが"active": trueを持ちます。
• state_changes（ここでは示していません）は、呼び出しの副作用を報告します。報告する内容は2種類です。1つはtab_openedエントリで、呼び出しによって開かれ、呼び出し終了時にまだ開いている各タブについて1つずつ含めます。そのtab_idはtabsにも含まれている必要があります。もう1つはダウンロードイベントです。報告するものがない場合は、このフィールドを省略してください。空の配列は拒否されます。
• ブロックは、ブラウザメンバーの呼び出しに応答する結果にのみ送信してください。送信できるのはtool_resultごとに最大1回で、is_error: trueの結果には決して送信しないでください。「報告するタブ状態がない」ことは、ブロックを省略することで表現します。
• APIは、tabsとstate_changes内のダウンロードエントリを、Claude向けのテキストにレンダリングします。そのテキストは、次の2つのセクションとダウンロードを報告するで示します。

tab_idの値はアプリケーション側で割り当てます。 自動化ライブラリのページ識別子や独自のカウンターなど、安定した文字列であれば何でも使用できます。ただし、あるtab_idを持つタブが以前の結果でまだ開いているとして一覧に含まれている間は、そのtab_idを再利用しないでください。APIはブロックに対して次の制限を適用します。

• tab_id、title、urlはそれぞれ最大4,096文字です。tab_idは空にできません。また、いずれにも制御文字（改行を含む）やUnicodeの行区切り文字・段落区切り文字を含めることはできません。
• 1つのブロックに列挙できるのは、最大100個のタブと200個の状態変更です。
• Claudeがswitch_tabとclose_tabに渡すtab_idにも、同じ制限が適用されます。APIがこの値を結果テキストにレンダリングするためです。したがって、tab_idがこれらの制限に違反する呼び出しには、browser_stateブロックではなくエラー結果で応答してください。

タブ管理の結果

new_tab、switch_tab、close_tab、list_tabsが成功した場合、結果のcontentはbrowser_stateブロックちょうど1つとし、テキストや画像は含めません。Claudeが見るテキストはAPIが書き込みます。new_tabの結果のブロックには、tab_opened状態変更もちょうど1つ含める必要があります。そのtab_idは、active: trueとマークされたエントリと一致している必要があります。

たとえば、ブロックに2つのタブが列挙され、最初のタブがアクティブなlist_tabsの結果は、次のようにレンダリングされます。各行は2スペースでインデントされ、アクティブなタブにのみ (current)が付加されます。

Available tabs:
  • tab_id tab-1: "Documentation" (https://example.com/docs) (current)
  • tab_id tab-2: "Pricing" (https://example.com/pricing)

これらのメンバーのエラー結果は、その逆になります。contentには通常のエラーテキストを含め、is_error: trueを設定し、browser_stateブロックは含めません。

たとえば、Claudeがnew_tabを呼び出すと（そのinputは空です）、エグゼキューターはタブを開いてアクティブにします。そして、tab_openedエントリを1つ含む一覧を返します。

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01WvHSbQVV9j5nWGvTmk4vNL",
      "toolset_name": "browser",
      "content": [
        {
          "type": "browser_state",
          "tabs": [
            { "tab_id": "tab-1", "title": "Documentation", "url": "https://example.com/docs" },
            { "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" },
            { "tab_id": "tab-3", "title": "", "url": "about:blank", "active": true }
          ],
          "state_changes": [{ "type": "tab_opened", "tab_id": "tab-3" }]
        }
      ]
    }
  ]
}

ClaudeにはCreated new tab with tab_id: tab-3, URL: about:blank. It is now the current tab.と表示されます。この例のように、報告するのはタブを開いたときのURLです。その後のリダイレクト先のURLは報告しないでください。以降の結果では、その時点でのタブのURLを報告します。

その他の結果におけるタブコンテキスト

その他のすべてのメンバーでは、ブロックは任意です。次のいずれかに該当する場合に送信してください。

• 開いているタブの集合が変更された
• アクティブなタブが変更された
• タブのタイトルまたはURLが変更された
• 報告するstate_changesがある

送信する際は、常に完全なtabs一覧を含めてください。結果にテキストとbrowser_stateブロックの両方が含まれる場合、APIはその結果のテキストにTab Contextフッターを追加します。フッターは、元のテキストとは空行で区切られます。これにより、Claudeはlist_tabsを別途呼び出さなくても新しい状態を受け取れます。

Tab Context:
- Executed on tab_id: tab-1
- Available tabs:
  • tab_id tab-1: "Documentation" (https://example.com/docs)
  • tab_id tab-2: "Pricing" (https://example.com/pricing)

Executed onは、呼び出しが実行されたタブを示します。tab_id入力がある場合はその値、ない場合はアクティブなタブです。フッターのタブ行には(current)マーカーは付きません。このテキストを自分で追加しないでください。構造化されたブロックを送信し、レンダリングはAPIに任せてください。フッターは重複排除されるため、同一のタブ状態が以降の結果で再びレンダリングされることはありません。したがって、ブロックを積極的に設定してもコストはかかりません。

次の3つのケースでは、ブロックが存在してもフッターはレンダリングされません。

• すべてのzoomの結果。
• textブロックを含まない結果（たとえば、画像のみのscreenshotの結果）。この場合、その結果については何もレンダリングされず、記憶もされません。タブコンテキストは、テキストとbrowser_stateブロックの両方を含む次の結果に表示されます。同じ結果でタブの変更をClaudeに伝えたい場合は、画像と一緒に短いテキストブロックを含めてください。ただし、ブロックがダウンロードイベントを報告する結果は例外です。この場合、APIはダウンロードの行をテキストブロックとして追加し、テキストを含む他の結果と同様に、その後にフッターが続きます。
• tab_idを含まない呼び出しで、tabsリストが空の結果。示すべきタブが存在しないためです。

たとえば、このセッションの前半で、Claudeが「Pricing」リンク（ref_5）をクリックしたとします。ページはそのリンクを、Claudeが要求していない新しいタブで開きました。報告がなければ、Claudeはこのタブを見つけるためにlist_tabsを呼び出す必要があります。そこで、クリックの確認応答に加えて、開かれたタブをstate_changesで示すブロックを返します。その際、エグゼキューターがアクティブにしたままのタブをマークしてください。

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01EgTXj1FjE2FCTt2zNFWLao",
      "toolset_name": "browser",
      "content": [
        { "type": "text", "text": "Clicked element ref_5." },
        {
          "type": "browser_state",
          "tabs": [
            {
              "tab_id": "tab-1",
              "title": "Documentation",
              "url": "https://example.com/docs",
              "active": true
            },
            { "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" }
          ],
          "state_changes": [{ "type": "tab_opened", "tab_id": "tab-2" }]
        }
      ]
    }
  ]
}

Claudeには、Clicked element ref_5.の後に、前述のTab Contextフッターが表示されます。

失敗した呼び出し中に開かれたタブには、tab_openedエントリは付きません。エラー結果にはbrowser_stateが含まれないためです。そのタブは、次に成功した結果のtabs一覧に表示されます。

バッチでは、次のようにブロックを添付してください。

• 変更が発生した呼び出しの結果にブロックを添付します。
• 成功したタブ管理の結果には、それぞれ独自のブロックを付けます。同じターン内の以前の結果が同じ状態を報告していた場合も同様です。

ダウンロードを報告する

クリックやナビゲーションによってファイルのダウンロードが開始された場合は、それが発生した呼び出しの結果のstate_changesで報告します。結果間の関連付けには、アプリケーション側で割り当てたdownload_idを使用します。ダウンロードは非同期で実行され、複数の結果にまたがる可能性があるため、イベントタイプは3つあります。

APIは各エントリを、Claude向けの1行のテキストとしてレンダリングします。行の順序は、エントリが出現する順序と同じです。

• 配置： これらの行は、結果のテキストの後に空行で区切って追加され、Tab Contextフッターがある場合はその前に配置されます。
• 対象となる結果： zoomやタブ管理の結果を含め、あらゆる種類のメンバー結果にこれらの行が含まれます。textブロックを含まない結果では、これらの行が独立したテキストブロックとして追加されます。
• 各行の内容： download_idとurlが含まれます。送信した場合は、pathとsize_bytes（download_completedの場合）、またはerror（download_failedの場合）も含まれます。

ダウンロードについて、独自のテキストで説明する必要はありません。APIはurl、path、errorをダブルクォートで囲み、その中のダブルクォートとバックスラッシュをエスケープします。そのため、これらの値を事前にエスケープしないでください。

たとえば、Pricingタブで「Download price list (CSV)」（ref_8）をクリックすると、ダウンロードが開始されます。そのため、クリックの結果にはdownload_startedエントリが含まれます。このエントリのdownload_idは"dl-1"で、ファイルのURLも含まれます。ダウンロードは、後続のscreenshot呼び出しの実行中に完了します。そのため、その結果のcontentには次のものが含まれます。

• 画像
• Screenshot captured.などのテキストブロック
• 同じdownload_idで完了を報告する、次のbrowser_stateブロック

{
  "type": "browser_state",
  "tabs": [
    { "tab_id": "tab-1", "title": "Documentation", "url": "https://example.com/docs" },
    {
      "tab_id": "tab-2",
      "title": "Pricing",
      "url": "https://example.com/pricing",
      "active": true
    }
  ],
  "state_changes": [
    {
      "type": "download_completed",
      "download_id": "dl-1",
      "url": "https://example.com/pricing/price-list.csv",
      "path": "/home/user/downloads/price-list.csv",
      "size_bytes": 48213
    }
  ]
}

Claudeには、Screenshot captured.の後に空行が入り、続いて次のような行が表示されます。

Download completed with download_id: dl-1, URL: "https://example.com/pricing/price-list.csv". Saved to "/home/user/downloads/price-list.csv". Size: 48213 bytes.

ダウンロードの報告は、次のルールに従います。

• 1つのブロック内では、download_idごとに最大1つのエントリとします。そのため、同じ呼び出し中に開始して完了したダウンロードは、download_completedのみを報告します。
• is_error: trueの結果には、決してstate_changesを送信しないでください。失敗した呼び出し中に発生したダウンロードイベントは、次に成功した結果で報告してください。
• state_changesは、進行中のダウンロードの一覧ではありません。各イベントは1回だけ報告してください。
• 各エントリには、そのtypeが宣言するフィールドのみを含めます。各フィールドの制約は次のとおりです。
  • size_bytesは非負の整数です。
  • download_idは空にできません。
  • download_id、url、path、errorはそれぞれ最大4,096文字で、制御文字やUnicodeの行区切り文字・段落区切り文字を含めることはできません。
• urlはリモートサーバーから取得され、リダイレクト後には署名付きのクエリ文字列による認証情報を含むことがよくあります。報告したりファイルシステムのパスで使用したりする前に、Claudeのコンテキストに含めたくないクエリパラメータを削除し、URLをサニタイズしてください。

エラーを処理する

失敗した呼び出しは、通常のエラー結果としてClaudeに報告します。エラー結果には次のものを含め、browser_stateブロックは含めません。

• is_error: true
• 何が問題だったかを説明するテキストコンテンツ
• エコーしたtoolset_name

エグゼキューターからエラーを返す

Claudeはエラーテキストを読んで対応を調整するため、エラーテキストは具体的にしてください。たとえば、Error: Navigation to https://example.com/status timed out after 30 seconds. The page may be unavailable.であれば、Claudeは次の行動の手がかりを得られます。一方、単なるError: navigation failedでは手がかりになりません。その他の一般的なケースは次のとおりです。

{
  "type": "tool_result",
  "tool_use_id": "toolu_01LeUTyqkhRxBFq1QTG3pkwN",
  "toolset_name": "browser",
  "is_error": true,
  "content": "Error: Navigation refused. Only http and https URLs are allowed."
}

{
  "type": "tool_result",
  "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
  "toolset_name": "browser",
  "is_error": true,
  "content": "Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references."
}

{
  "type": "tool_result",
  "tool_use_id": "toolu_013h2Q55HcNwVyapSpy2s5ZG",
  "toolset_name": "browser",
  "is_error": true,
  "content": "Error: javascript_exec is not enabled in this environment."
}

{
  "type": "tool_result",
  "tool_use_id": "toolu_01FkP8rTz6uYh2mNq4LsXw7v",
  "toolset_name": "browser",
  "is_error": true,
  "content": "Not executed: an earlier action in this turn failed."
}

リクエストエラー

APIは、ツールセットエントリと、会話内のすべてのメンバーのtool_useおよびtool_resultブロックを検証します。いずれかの形式が不正な場合、APIはClaudeが実行される前にinvalid_request_errorを返します。次の表では、左の列に送信した内容を示します。

制限事項

• プラットフォームの提供状況： ブラウザ使用は、Claude APIとGoogle Cloudで利用できます。
• 入力全体単位のストリーミングのみ： ストリーミングする場合、各メンバーのinputは、1つの完全なinput_json_deltaとして届きます（クライアントツールセット）。
• 要素参照はベストエフォート： 非常に動的なページ（仮想化リスト、canvasでレンダリングされるインターフェース、スクロール時に再レンダリングされるページなど）では、安定した参照が公開されない場合があります。その場合、Claudeはスクリーンショットと座標によるクリックにフォールバックします。
• read_consoleとread_networkはブラウザ自動化に依存： これらが報告するのは、ブラウザ自動化がキャプチャできる内容のみです。また、ブラウザ自動化がタブにアタッチした時点以降の内容に限られます。
• 一般的なエージェントの制限が適用される： レイテンシ、視覚認識の精度、プロンプトインジェクションのリスクは、コンピューター使用から引き継がれます（コンピューター使用ツールの制限事項を参照）。また、コンピューター使用ツールの次のガイダンスは、ブラウザエグゼキューターにも適用されます。
  • プロンプトによるモデルパフォーマンスの最適化
  • スクリーンショット履歴の管理
  • 実装のベストプラクティスに従う（アクションの遅延、アクションの検証、ログ記録）

料金とデータ保持

ブラウザ使用は標準のツール使用の料金に従います。ブラウザ使用ツールを使用する場合：

ツールセット定義のオーバーヘッド： browser_toolset_20260801 をデフォルトのメンバーとともに宣言すると、リクエストに約6,600入力トークンが追加されます（Claude Fable 5、Claude Mythos 5、Claude Opus 5、Claude Opus 4.8では約6,610、Claude Sonnet 5では約6,670）。これにはメンバーツールの定義とツール使用のシステムプロンプトが含まれます。4つのオプションメンバーをすべて有効にすると約880トークンが追加され、configs でメンバーを無効にするとトークン数が減少します。リクエストの正確なトークン数はレスポンスの usage で報告され、トークンカウントエンドポイントを使用して事前に見積もることができます。

追加のトークン消費：

• ツール結果で返されるスクリーンショットおよびズーム画像。画像入力として課金されます（Visionの料金を参照）
• Claudeに返されるテキストのツール結果（アクセシビリティツリー、ページテキスト、コンソールまたはネットワークのエントリなど）

ブラウザセッション、ダウンロード、アップロードされたファイルは、お使いの環境内に留まります。一方、返されるスクリーンショット、ページテキスト、タブ状態はAPIリクエストコンテンツの一部です。これらには標準の保持ポリシーが適用されます。ZDR契約がある場合は、その契約が適用されます。ブラウザ使用ツールはZDRの対象です。各機能の保持期間と対象については、APIとデータ保持を参照してください。

次のステップ

Compatibility