ブラウザ使用ツール

「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で利用できます。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がテキストで回答するまで結果を返し続けます。

以下は、そのループのツール呼び出しステップのスケルトンを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">要素にファイルを直接設定します。これはネイティブのファイル選択ダイアログを操作するよりも信頼性が高い方法です。呼び出しには要素のIDが必要なため、その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 で指定します。どのタブが存在するかについてはアプリケーションが信頼できる情報源であり、その状態を browser_state コンテンツブロックで報告します。Claude はこのブロックを直接見ることはなく、API がそこから Claude が読むテキストをレンダリングします。

{
  "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 では与えられません。その他の一般的なケースは次のとおりです。



リクエストエラー

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



制限事項

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



料金とデータ保持

「browser use」（ブラウザ使用）は、標準のツール使用の料金に従います。ブラウザ使用ツールを使用する場合：

ツールセット定義のオーバーヘッド： 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 とデータ保持を参照してください。



次のステップ