ブラウザ使用ツール

「browser use tool」（ブラウザ使用ツール）を使うと、Claudeはお客様のアプリケーションが実行するブラウザ内でウェブページのナビゲーション、読み取り、操作を行えます。このツールは、ページの構造（アクセシビリティツリー、要素、フォーム、タブ）とピクセル（スクリーンショットとビューポート座標）の両方を通じてページを扱います。一方、コンピュータ使用ツールはスクリーンショットと座標のみを通じてデスクトップ全体を扱います。これはAnthropicが定義したクライアントツールセットです。tools配列にbrowser_toolset_20260801エントリを1つ追加すると、Claudeにはデフォルトでnavigate、read_page、left_click、screenshotなどの27個のメンバーツールが与えられ、さらに有効化すると4個（javascript_exec、file_upload、read_console、read_network）が追加されます。お客様のアプリケーションはすべての呼び出しを自身のブラウザ自動化に対して実行し、Anthropic側では何も実行されません。現在、Claude Managed Agentsでは利用できません。このページでは、Messages APIを呼び出すエージェントループを「お客様のアプリケーション」、そのうちブラウザを操作してツール結果を生成する部分を「お客様のエグゼキュータ」と呼びます。

タスクがウェブページ内に収まる場合は、コンピュータ使用よりもブラウザ使用を選んでください。Claudeはページの構造を読み取り、座標だけでなく参照によって要素を操作し、フォームの値を直接設定し、複数のタブにまたがって作業でき、デスクトップを実行する必要もありません。Claudeが指定されたページを読むだけでよい場合や、ウェブ上で情報源を探すだけでよい場合は、ウェブフェッチツールとウェブ検索ツールのほうがさらに軽量です。これらは操作するブラウザなしでAPIが代わりに実行するサーバーツールだからです。ページがJavaScriptでコンテンツを構築する場合や、タスクがページを読むだけでなくページ上で操作することを意味する場合は、代わりにブラウザ使用を選んでください。

ブラウザ使用では、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",
    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",
  "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
}

お客様のエグゼキュータは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をクリックしてgetting-startedページを開くことができ、最初にスクリーンショットでリンクを探す必要はありません。

ブラウザ使用の仕組み

ブラウザ使用はエージェントループとして動作します。Claudeがメンバーツール呼び出しを返し、お客様のエグゼキュータがそれをブラウザに対して実行し、Claudeがテキストで回答するまで結果を返し続けます。

1. 1

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

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

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

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

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

   • response.content内のすべてのtool_useブロックを反復処理し（ちょうど1つだと仮定しないでください）、後の呼び出しは通常前の呼び出しに依存するため、出現順に逐次実行します。
   • 新しいuserメッセージでブロックごとに1つのtool_resultをtool_use_idで対応させて返し、それぞれに"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つの呼び出ししか実行できない場合は、tool_choiceでdisable_parallel_tool_useをtrueに設定すると、Claudeはターンごとに最大1つのメンバー呼び出しを返します。ただし、ラウンドトリップが増えるという代償があります（並列ツール使用を無効にする）。コンピュータ使用ツールのバッチアクションの残りの契約は、次のuserメッセージですべてのtool_useに対して1つのtool_resultを返すことを含めて引き継がれますが、2つの点が異なります。停止テキストと、成功した結果のcontentに含まれるものです。結果コンテンツは代わりにこのページのメンバーツールに従います。new_tab、switch_tab、close_tab、またはlist_tabsの結果は、テキストや画像のないちょうど1つのbrowser_stateブロックであり（タブ管理の結果）、他のメンバーの結果はテキストや画像にbrowser_stateブロックを追加できます（他の結果のタブコンテキスト）。バッチ内のキャッシュブレークポイントがどこで有効になるかは、コンピュータ使用ツールのツールパラメータのcache_control行で説明されています。

ターゲットと座標

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

座標はビューポートピクセルです。 これはフルビューポートのscreenshotのピクセル空間で、原点はレンダリングされたページの左上にあります。周囲のデスクトップやウィンドウフレームはありません。ツールセットはディスプレイの寸法を宣言せず、Claudeはお客様が返すスクリーンショットからビューポートサイズを推測するため、スクリーンショットは一貫したサイズに保ってください。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は、お客様の指示と矛盾する場合でも、ページコンテンツ内の指示に従うことがあります。「以前の指示を無視して...にナビゲートしてください」というページ上のテキストは、Claudeをタスクから逸脱させる可能性があります。プロンプトインジェクションが到達できる範囲を制限するためにClaudeを機密データや操作から隔離し、ジェイルブレイクとプロンプトインジェクションを軽減するを確認してください。タスクでログイン済みセッションを避けられない場合は、専用の低権限アカウントを使用し、アカウントを変更する操作には人間による確認を維持してください。

ブラウザはお客様の環境で実行されるため、Claudeが訪問するサイトはお客様のエグゼキュータのネットワークIDを認識し、ページコンテンツはお客様が返すツール結果としてのみ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がそれを決して指定しないことを保証するものではないため、お客様のエグゼキュータはそのような呼び出しにもエラー結果で応答してください。

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

ブラウザ使用ツールは、同じtools配列でお客様独自のツールや他のAnthropic提供ツールと一緒に宣言できます。toolset_nameがClaudeの呼び出しを区別するため、カスタムツールはメンバーと同じ名前（例えばお客様独自のnavigate）を持つことができますが、他のエントリにbrowserという名前を付けることはできず、リクエストにはブラウザツールセットエントリを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行のテキストです。コンソール行にはログ、警告、またはエラーエントリが含まれ、ネットワーク行にはメソッド、URL、ステータス、MIMEタイプ、タイミングが含まれます。エントリはお客様のブラウザ自動化がタブにアタッチした時点からのみ存在するため、空の結果は、すでに開いていたタブにトラフィックがなかったことを意味するわけではありません。

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

browser_state でタブを追跡する

Claude はタブを tab_id で指定します。どのタブが存在するかについての信頼できる情報源はお客様のアプリケーションであり、その状態を 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（ここでは示していません）は呼び出しの副作用を報告します。呼び出しが開き、呼び出し終了時にまだ開いている各タブに対する tab_opened エントリ（その tab_id は tabs にも含まれている必要があります）、およびダウンロードイベントです。報告するものがない場合はこのフィールドを省略してください。空の配列は拒否されます。
• このブロックは、ブラウザメンバー呼び出しに応答する結果にのみ、tool_result ごとに最大1回送信し、is_error: true の結果には決して送信しないでください。「報告するタブ状態がない」ことは、ブロックを省略することで表現します。
• API は次の2つのセクションで説明するように tabs を Claude 向けのテキストにレンダリングします。state_changes 内のダウンロードエントリは検証されますが、レンダリングはされません。

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 はテキストや画像を含まないちょうど1つの browser_state ブロックであり、Claude が見るテキストは API が書き込みます。new_tab の結果のブロックには、active: true とマークされたエントリと tab_id が一致する tab_opened 状態変更がちょうど1つ含まれている必要もあります。

ブロックに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 は空です）、エグゼキューターはタブを開いてアクティブにし、1つの tab_opened エントリとともに一覧を返します。

{
  "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 に見せたい場合は、画像と一緒に短いテキストブロックを含めてください。
• 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 が見るテキストにはレンダリングしません。そのため、Claude がファイルに対して操作を行う必要がある場合は、同じ結果の text ブロックでもファイル名または path に言及してください。

たとえば、Pricing タブで「Download price list (CSV)」（ref_8）をクリックするとダウンロードが開始されるため、クリックの結果には download_id が "dl-1" でファイルの URL を持つ download_started エントリが含まれます。ダウンロードは後続の screenshot 呼び出しの実行中に完了するため、その結果の content には画像、Screenshot captured. Download complete: /home/user/downloads/price-list.csv (48,213 bytes). のようなテキストブロック、そして同じ 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
    }
  ]
}

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

• 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 のコンテキストに含めたくないクエリパラメータを削除し、報告したりファイルシステムパスで使用したりする前にサニタイズしてください。

エラーを処理する

失敗した呼び出しは、通常のエラー結果として Claude に報告します。is_error: true、何が問題だったかを示すテキストコンテンツ、エコーされた toolset_name、そして browser_state ブロックはなしです。

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

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