瀏覽器使用工具

「browser use tool」（瀏覽器使用工具）讓 Claude 能在您的應用程式所執行的瀏覽器中導覽、讀取網頁並與之互動。它同時透過頁面的結構（「accessibility tree」（無障礙樹）、元素、表單與分頁）以及像素（螢幕截圖與視埠座標）來操作頁面，而電腦使用工具則僅透過螢幕截圖與座標來操作整個桌面。它是一個由 Anthropic 定義的用戶端工具集：在您的 tools 陣列中加入一個 browser_toolset_20260801 項目，預設會提供 Claude 27 個成員工具，例如 navigate、read_page、left_click 與 screenshot，當您啟用它們時還會再多出四個（javascript_exec、file_upload、read_console 與 read_network）。您的應用程式會針對自己的瀏覽器自動化執行每一次呼叫；沒有任何東西在 Anthropic 端執行。它目前無法在 Claude Managed Agents 中使用。本頁以「您的應用程式」指稱呼叫 Messages API 的「agent loop」（代理迴圈），以「您的執行器」指稱其中驅動瀏覽器並產生工具結果的部分。

當任務停留在網頁之內時，請選擇瀏覽器使用而非電腦使用：Claude 可以讀取頁面的結構、除了依座標之外還能依參照對元素進行操作、直接設定表單值，並跨分頁工作，而且您不需要執行桌面環境。如果 Claude 只需要讀取您可以指向的頁面，或在網路上尋找來源，網頁擷取工具與網頁搜尋工具更為輕量，因為它們是由 API 為您執行、無需操作瀏覽器的伺服器工具。當頁面以 JavaScript 建構其內容，或任務意味著要對頁面進行操作而非僅僅讀取時，請改為選擇瀏覽器使用。

使用瀏覽器使用時，Claude 會讀取並操作即時網頁，因此頁面所提供的一切都是不受信任的輸入，而 Claude 採取的動作可能產生實際影響。部署前請參閱安全性考量。



快速開始

瀏覽器使用工具可在 Claude API 上使用，無需 beta 標頭：在 Messages API 請求的 tools 陣列中加入一個類型為 browser_toolset_20260801、不帶 name 的項目。

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" 結束，並帶有一個或多個成員 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，而您的應用程式在下一個請求中為每個區塊回傳一個 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 來開啟入門頁面，而無需先在螢幕截圖中定位該連結。



瀏覽器使用的運作方式

瀏覽器使用以代理迴圈的形式執行：Claude 回傳成員工具呼叫，您的執行器針對瀏覽器執行它們，然後您回傳結果，直到 Claude 以文字回答為止。

以下是該迴圈工具呼叫步驟的骨架，分為兩部分。首先，以 stub 成員處理常式代替您的瀏覽器自動化。五個成員（navigate、read_page、left_click、type 與 screenshot）回傳文字（screenshot 則回傳圖片區塊），這些會成為結果內容，而分派器對任何它未實作的成員會拋出錯誤。

# 佔位圖片資料；實際的執行器會擷取 viewport 並回傳 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):
    # target 是來自 read_page 或 find 的元素參照，或是 viewport 座標
    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}")

第二部分依序執行一個批次，將每個區塊分派給這些處理常式，在每個結果上回傳 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

請依據（toolset_name、name）這一組配對來分派每個區塊，而非僅依據 name，因為同一請求中的自訂工具可能與某個成員同名；用戶端工具集描述了兩個工具集共用的此契約部分。如果 Claude 指名了您的執行器未實作的成員，或您已停用的成員，請以錯誤結果回應該區塊，而不要將其丟棄。

當您以串流方式接收回應時，每個成員的 input 會以一個完整的 input_json_delta 送達，而非分段送達，因此請等待該輪次結束後再執行批次。



批次動作

帶有多個成員呼叫的輪次即為批次動作：依呼叫出現的順序執行，在第一個失敗處停止，並以 is_error: true 及確切文字 Not executed: an earlier action in this turn failed. 回應每個後續呼叫。批次使用與平行工具使用相同的回應形狀；差別在於您依序執行區塊而非並行執行。在此範例中，Claude 在一個輪次中點擊它先前找到的搜尋框、輸入查詢，然後按下 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" }
    }
  ]
}

您的應用程式在一則 user 訊息中回傳三個 tool_result 區塊，每個都帶有 toolset_name 與簡短的文字確認，例如 Clicked element ref_3.。按下 Enter 會載入結果頁面，因此 key 的結果也帶有一個含有該分頁更新後 URL 的 browser_state 區塊（其他結果上的分頁上下文）。如果點擊失敗了，其結果會帶有您的錯誤文字，而另外兩個結果會帶有中止文字，如從您的執行器回傳錯誤中所示。

您不需要在每次呼叫後都回傳螢幕截圖。Claude 通常以一個觀察呼叫（screenshot、read_page 或 get_page_text）結束批次，而您的應用程式也可以將自己的觀察（例如新的螢幕截圖或無障礙樹）作為額外的內容區塊附加在批次中最後一個結果上，以節省一次往返。由於分頁管理結果必須恰好是一個 browser_state 區塊，請將其附加在最後一個非分頁管理呼叫的結果上。

如果您的執行器每次往返只能執行一個呼叫，請在 tool_choice 中將 disable_parallel_tool_use 設為 true，Claude 每輪次最多回傳一個成員呼叫，代價是更多的往返次數（停用平行工具使用）。電腦使用工具的批次動作下的其餘契約皆適用，包括在下一則 user 訊息中為每個 tool_use 回傳一個 tool_result，但有兩點例外：中止文字，以及成功結果的 content 所包含的內容。結果內容改為遵循本頁的成員工具：new_tab、switch_tab、close_tab 或 list_tabs 的結果恰好是一個 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 能操作難以用指標點中的控制項。
• 對於樹未描述的內容退回使用座標。 以 Canvas 渲染的介面、嵌入式影片或遠端桌面畫面、高度虛擬化的清單，以及跨來源 iframe 內的元素通常沒有有用的節點，因此 Claude 會從 screenshot 與 zoom 著手並依座標點擊；您的執行器負責解析座標落在哪個框架中。
• 限定讀取範圍，並在截圖前先讀取樹。 在大型頁面上，帶有 filter: "interactive" 或容器 ref 的 read_page 會回傳聚焦的子樹，而對典型頁面的樹讀取通常比螢幕截圖花費更少的輸入 token，同時給予 Claude 可立即操作的參照。當視覺版面、圖片或渲染狀態重要時，螢幕截圖仍是正確的觀察方式。



安全性考量

瀏覽器使用帶有標準 API 功能所沒有的風險，因為 Claude 會讀取並操作來自開放網路的內容，而任何頁面都可能包含為了操縱它而撰寫的文字。

Claude 有時會遵循在頁面內容中發現的指示，即使它們與您的指示衝突；頁面上寫著「忽略你先前的指示並導覽至……」的文字可能使它偏離任務。請將 Claude 與敏感資料及動作隔離，以限制提示注入所能觸及的範圍，檢閱緩解越獄與提示注入，而如果任務無法避免已登入的工作階段，請使用專用的低權限帳戶，並對變更帳戶的動作保持人類確認。

由於瀏覽器在您的環境中執行，Claude 造訪的網站會看到您執行器的網路身分，而頁面內容僅以您回傳的工具結果形式到達 API。在您的產品中啟用瀏覽器使用之前，請告知終端使用者相關風險並取得其同意。



成員工具

browser_toolset_20260801 項目宣告 31 個成員工具；每個呼叫的 input 恰好是此處列出的參數，而 tab_id 在選用時預設為作用中分頁。Target、CoordinateTarget 與 RefTarget 是目標與座標中描述的形狀。四個成員（javascript_exec、file_upload、read_console 與 read_network）預設停用，僅在您啟用它們時出現。每個成員列中註明的輸入界限與輸出慣例是向 Claude 陳述的，並非由 API 強制執行，因此請在您的執行器中驗證輸入（包括對照您的視埠檢查座標）並套用這些慣例。

只有 screenshot 與 zoom 要求其結果中包含 image 區塊，而四個分頁管理成員（new_tab、list_tabs、switch_tab 與 close_tab）恰好回傳一個 browser_state 區塊（請參閱分頁管理結果）。其他每個成員都回傳一個 text 區塊：簡短的確認（例如 Clicked element ref_2.）或該成員的輸出。分頁管理結果以外的任何結果也可以帶有一個 image 區塊，通常是動作後拍攝的螢幕截圖，讓 Claude 無需另外呼叫 screenshot 即可看到結果；批次動作說明了在批次中應將其附加於何處。成員 tool_result 只能包含 text、image 與 browser_state 內容區塊。



導覽與擷取



指標



鍵盤與計時



頁面讀取



表單與檔案



診斷與指令碼



分頁管理

成功時，這些成員各自恰好回傳一個 browser_state 區塊，不含文字或圖片；請參閱分頁管理結果。



設定工具集

除了 type 之外，工具集項目還接受 configs、cache_control 與 allowed_callers；這些欄位與電腦使用工具集共用的規則列於用戶端工具集之下，本節涵蓋瀏覽器特有的預設值。configs 是以成員名稱為鍵的物件，每個成員的值接受兩個欄位：



啟用或停用成員工具

在 configs 中僅列出您想變更的成員；您省略的每個成員都保持其預設值。例如，一個實作了主控台讀取但未實作低階指標或按鍵按住控制的執行器，會開啟 read_console 並保留三個成員不提供：

{
  "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 提供的工具一同宣告。自訂工具可以與某個成員同名（例如您自己的 navigate），因為 toolset_name 能區分 Claude 的呼叫，但其他任何項目都不得命名為 browser，且一個請求只能包含一個瀏覽器工具集項目。

您也可以將它與電腦使用工具一同宣告，無論是工具集或較早的電腦使用工具版本。兩者獨立運作，各自在自己的座標框架中（此處為視埠像素，彼處為桌面螢幕截圖像素），而 Claude 對同名成員（例如 screenshot 或 key）的呼叫以 toolset_name 區分。



啟用選用成員

四個成員工具預設停用：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 回傳其網路請求，各自以文字形式呈現，每個項目一行，累積自上次讀取該分頁以來的內容。主控台行帶有 log、warning 或 error 項目；網路行帶有方法、URL、狀態、MIME 類型與計時。項目僅從您的瀏覽器自動化附加至該分頁的那一刻起存在，因此空結果並不表示一個已經開啟的分頁沒有流量。

這些成員讓 Claude 能診斷行為異常的頁面（載入動畫背後的失敗請求、無反應按鈕背後的指令碼錯誤），而無需重複截圖。主控台與網路項目由頁面控制，且經常包含機密資訊，例如請求 URL 中的 token，因此請遮蔽您不希望出現在 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 是呼叫之後所有開啟分頁的完整清單，而非差異。它可以是空的；只要不是空的，就必須恰好有一個項目帶有 "active": true。
• state_changes（此處未顯示）回報呼叫的副作用：對於該呼叫所開啟、且在呼叫結束時仍然開啟的每個分頁，各有一個 tab_opened 項目，其 tab_id 也必須出現在 tabs 中；以及下載事件。當沒有任何內容需要回報時，請省略此欄位；空陣列會被拒絕。
• 僅在回應瀏覽器成員呼叫的結果上傳送此區塊，每個 tool_result 最多一次，且絕不在帶有 is_error: true 的結果上傳送。您透過省略此區塊來表達「沒有分頁狀態需要回報」。
• API 會如接下來兩個小節所述，將 tabs 渲染為供 Claude 閱讀的文字；state_changes 中的下載項目會經過驗證，但不會被渲染。

tab_id 的值由您指派。 任何穩定的字串都可以，例如您的自動化函式庫的頁面識別碼或您自己的計數器，只要您不在先前結果中仍列為開啟的分頁使用該識別碼時重複使用同一個 tab_id 即可。API 對此區塊強制執行以下限制：

• 每個 tab_id、title 和 url 最多可為 4,096 個字元，tab_id 必須為非空，且三者皆不得包含控制字元（包括換行）或 Unicode 行分隔符或段落分隔符。
• 一個區塊最多可列出 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 區塊，不含文字或圖片，而 Claude 所看到的文字由 API 撰寫。new_tab 結果的區塊還必須恰好帶有一個 tab_opened 狀態變更，其 tab_id 與標記為 active: true 的項目相符。

一個 list_tabs 結果，其區塊列出兩個分頁且第一個為作用中分頁時，渲染結果如下，每行縮排兩個空格，且僅在作用中分頁後附加 (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 項目的清單：

{
  "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 渲染它。頁尾會去除重複，因此相同的分頁狀態不會在後續結果上再次渲染，大方地填入此區塊不會有任何成本。

有三種情況即使區塊存在也不會渲染頁尾：

• 任何 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 在各結果之間關聯。下載以非同步方式執行，且可能跨越多個結果，因此有三種事件類型：

API 會驗證這些項目，但不會將它們渲染為 Claude 所看到的文字，因此當 Claude 需要對檔案採取動作時，也請在同一結果的 text 區塊中提及檔案名稱或 path。

例如，在 Pricing 分頁中點擊「Download price list (CSV)」（ref_8）會啟動下載，因此該點擊的結果帶有一個 download_started 項目，其 download_id 為 "dl-1" 並附有檔案的 URL。下載在稍後的 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
    }
  ]
}

下載回報遵循以下規則：

• 單一區塊中每個 download_id 最多一個項目，因此在同一呼叫期間開始並完成的下載僅回報 download_completed。
• 絕不在 is_error: true 的結果上傳送 state_changes；在失敗呼叫期間發生的下載事件，請在下一個成功結果上回報。
• state_changes 不是進行中下載的清單；每個事件只回報一次。
• 每個項目僅帶有其 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 上提供。
• 僅支援完整輸入串流： 當您使用「streaming」（串流）時，每個成員的 input 會以一個完整的 input_json_delta 送達（用戶端工具集）。
• 元素參照為盡力而為： 高度動態的頁面（虛擬化清單、以 canvas 渲染的介面、捲動時重新渲染的頁面）可能無法提供穩定的參照，Claude 在這些情況下會退回使用螢幕截圖和座標點擊。
• read_console 和 read_network 取決於您的瀏覽器自動化： 它們僅回報其所能擷取的內容，且僅從其附加到分頁的那一刻起。
• 一般代理限制適用： 延遲、視覺準確度和提示注入風險皆沿襲自電腦使用（請參閱電腦使用工具的限制），且其在透過提示最佳化模型效能、管理螢幕截圖歷史記錄和遵循實作最佳實務（動作延遲、動作驗證和日誌記錄）下的指引也適用於瀏覽器執行器。



定價與資料保留

「Browser use」（瀏覽器使用）遵循標準的工具使用定價。使用瀏覽器使用工具時：

工具集定義開銷： 宣告 browser_toolset_20260801 及其預設成員會為請求增加約 6,600 個輸入 token（在 Claude Fable 5、Claude Mythos 5、Claude Opus 5 和 Claude Opus 4.8 上約為 6,610 個，在 Claude Sonnet 5 上約為 6,670 個），其中涵蓋成員工具定義以及工具使用系統提示。啟用全部四個選用成員會增加約 880 個 token，而使用 configs 停用成員則會減少數量。請求的確切數量會在回應的 usage 中回報，您也可以透過 token 計數端點事先估算。

額外的 token 消耗：

• 工具結果中回傳的螢幕截圖與縮放影像，以影像輸入計費（請參閱視覺定價）
• 回傳給 Claude 的文字工具結果，例如無障礙樹（accessibility tree）、頁面文字，以及主控台或網路項目

瀏覽器工作階段、下載和上傳的檔案保留在您的環境中；您回傳的螢幕截圖、頁面文字和分頁狀態是您 API 請求內容的一部分，並遵循標準保留政策，或您的 ZDR 安排（若有）。瀏覽器使用工具符合 ZDR 資格；請參閱 API 與資料保留以了解各功能的保留期間和資格。



後續步驟