瀏覽器使用工具

「Browser use tool」（瀏覽器使用工具）讓 Claude 能在您的應用程式所執行的瀏覽器中瀏覽、讀取網頁並與之互動。Claude 會同時透過頁面的結構（「accessibility tree」（無障礙樹）、元素、表單和分頁）以及螢幕截圖和「viewport」（檢視區）座標來處理頁面。

此工具是 Anthropic 定義的 client toolset（用戶端工具集）：在 tools 中加入一個 browser_toolset_20260801 項目，預設即可為 Claude 提供 27 個成員工具，例如 navigate、read_page、left_click 和 screenshot，當您啟用它們時還會再多出四個。您的應用程式會針對自己的瀏覽器自動化執行每一次呼叫；Anthropic 端不會執行任何內容。此工具目前無法在 Claude Managed Agents 中使用。

Python 和 TypeScript SDK 包含一個類別，可將這些呼叫傳遞給您的瀏覽器程式碼、執行您設定的 URL 和檔案政策，並詢問您的核准回呼函式。請參閱使用 SDK 工具集進行瀏覽器與電腦操作。

當任務停留在網頁內且需要對網頁採取動作，或頁面以 JavaScript 建構其內容時，請選擇瀏覽器使用。當任務需要整個桌面時，請使用電腦使用工具，它僅透過螢幕截圖和座標運作。若要讀取您可以指引 Claude 前往的頁面，或在網路上尋找來源，網頁擷取工具和網頁搜尋工具較為輕量。它們是由 API 為您執行的伺服器工具，無需操作瀏覽器。

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

快速入門

瀏覽器使用工具可在 Claude API 和 Google Cloud 上使用：在 Messages API 請求的 tools 陣列中，加入一個類型為 browser_toolset_20260801 且不含 name 的項目。

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" 結束，並帶有一個或多個成員 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。您的應用程式會在下一個請求中為每個區塊回傳一個 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 請求。
   • 包含一個需要操作網頁的使用者提示，例如「開啟 example.com/docs 並告訴我如何開始使用。」
2. 2

   Claude 以成員工具呼叫回應

   • Claude 在單一助理輪次中回傳一個或多個 tool_use 區塊；同一輪中的多個區塊構成一個批次動作，例如 left_click，接著 type，再接著 key。
   • 每個區塊的 name 是成員名稱，每個區塊都帶有 "toolset_name": "browser"，而 input 僅包含該成員的參數，沒有 action 欄位。回應的 stop_reason 為 tool_use。
3. 3

   依序執行呼叫並回傳結果

   • 逐一處理 response.content 中的每個 tool_use 區塊（不要假設只有一個），並依照它們出現的順序依序執行，因為後面的呼叫通常依賴前面的呼叫。
   • 在新的 user 訊息中為每個區塊回傳一個 tool_result，以 tool_use_id 對應，並在每個結果上回傳 "toolset_name": "browser"。每個呼叫都必須得到回應，否則下一個請求會被拒絕。
   • 如果某個呼叫失敗，請為該區塊回傳 is_error: true 及文字說明，然後對該輪中所有後續區塊套用批次動作中的中止規則。
4. 4

   Claude 持續進行直到任務完成

   • Claude 會閱讀結果（頁面文字、無障礙樹、螢幕截圖、分頁狀態），如果需要更多資訊，會回傳更多成員呼叫，這會讓您回到步驟 3。
   • 否則，它會向使用者回傳文字回應。

以下是該迴圈中工具呼叫步驟的骨架，分為兩部分。首先，以虛設的成員處理常式代替您的瀏覽器自動化。五個成員（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 指名了您的執行器未實作的成員，或您已停用的成員，請以錯誤結果回應該區塊，而不是將其捨棄。

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

批次動作

包含多個成員呼叫的輪次就是一個「batch action」（批次動作）：依呼叫出現的順序執行，在第一個失敗處停止，並以 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 物件，它可以是 viewport 像素座標，也可以是 read_page 或 find 所回傳元素的參照。成員工具表格中以 Target 表示可接受任一形狀的參數。

座標是 viewport 像素，即完整 viewport screenshot 的像素空間，原點位於所呈現頁面的左上角；周圍沒有桌面或視窗框架。工具集不宣告顯示尺寸，Claude 會從您回傳的螢幕截圖推斷 viewport 大小，因此請讓截圖保持一致的尺寸。zoom 不會改變座標框架，因此其 region 以及 Claude 在看到放大圖片後發出的任何座標，仍然是完整 viewport 的像素。

螢幕截圖必須符合圖片限制。 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 與敏感資料和動作隔離，以限制「prompt injection」（提示注入）所能觸及的範圍，並參閱減輕越獄和提示注入；如果任務無法避免使用已登入的工作階段，請使用專用的低權限帳戶，並對會變更帳戶的動作保留人員確認。

Anthropic 已訓練模型抵禦這些提示注入，並增加了一層額外的防禦。如果您使用瀏覽器使用工具，分類器會自動掃描瀏覽器回傳的內容（例如頁面文字或螢幕截圖），以標記潛在的提示注入。當這些分類器識別出潛在的提示注入時，會自動引導模型在據以行動之前，先確認該指示是否真的來自您。

這項額外保護並非適用於所有使用情境（例如沒有人員參與流程的使用情境），因此如果您想選擇退出並將其關閉，請聯絡支援團隊。即使有這些分類器，上述預防措施仍然很重要。

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

成員工具

browser_toolset_20260801 項目宣告了 31 個成員工具；每個呼叫的 input 恰好是此處列出的參數，而 tab_id 在為選用時預設為作用中的分頁。Target、CoordinateTarget 和 RefTarget 是目標與座標中所述的形狀。四個成員（javascript_exec、file_upload、read_console 和 read_network）預設為停用，只有在您啟用它們時才會出現。各成員列中註明的輸入範圍和輸出慣例是告知 Claude 的，並非由 API 強制執行，因此請在您的執行器中驗證輸入（包括根據您的 viewport 驗證座標）並套用這些慣例。

只有 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，且一個請求只能包含一個瀏覽器工具集項目。

您也可以將它與電腦使用工具一起宣告，無論是工具集或較早的電腦使用工具版本皆可。兩者各自獨立運作，各有自己的座標框架（此處為 viewport 像素，那裡為桌面螢幕截圖像素），而 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 回傳其網路請求，兩者都以文字形式呈現，每行一個自該分頁上次讀取以來累積的項目。主控台行包含一個記錄、警告或錯誤項目；網路行包含方法、URL、狀態、MIME 類型和時間。項目只從您的瀏覽器自動化附加到分頁的那一刻起才存在，因此空的結果並不代表先前已開啟的分頁沒有任何流量。

這些成員讓 Claude 無需反覆截圖即可診斷行為異常的頁面（例如載入圖示背後失敗的請求，或無反應按鈕背後的指令碼錯誤）。主控台和網路項目由頁面控制，且經常包含機密資訊，例如請求 URL 中的 token，因此請在回傳前遮蔽您不希望出現在 Claude 上下文中的類憑證值，並截斷過長的項目。

使用 browser_state 追蹤分頁

Claude 透過 tab_id 指定分頁，而哪些分頁存在則以您的應用程式為準（即「source of truth」（事實來源））。您會在 browser_state 內容區塊中回報該狀態，Claude 永遠不會直接看到這個區塊：Claude 讀取的文字是由 API 從中轉譯（render）而來。

{
  "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 是呼叫完成後所有已開啟分頁的完整清單，而非差異（delta）。它可以是空的；只要不是空的，就必須恰好有一個項目帶有 "active": true。
• state_changes（此處未顯示）回報呼叫的副作用：對於呼叫所開啟、且在呼叫結束時仍開啟的每個分頁，各有一個 tab_opened 項目，其 tab_id 也必須出現在 tabs 中；此外還有下載事件。沒有任何內容需要回報時，請省略此欄位；空陣列會被拒絕。
• 僅在回應瀏覽器成員呼叫的結果上傳送此區塊，每個 tool_result 最多一次，且絕不在帶有 is_error: true 的結果上傳送。若要表達「沒有分頁狀態需要回報」，請省略此區塊。
• API 會將 tabs 以及 state_changes 中的任何下載項目轉譯為供 Claude 閱讀的文字。接下來的兩個章節以及回報下載會展示該文字。

tab_id 值由您指派。 任何穩定的字串都可以，例如您的自動化函式庫的頁面識別碼或您自己的計數器，只要在先前結果中仍列為開啟的分頁使用某個 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 在同一個結果上看到分頁變更，請在圖片旁附上一個簡短的文字區塊。例外情況是區塊回報了下載事件的結果。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 在各結果之間建立關聯。下載是非同步執行的，可能跨越多個結果，因此有三種事件類型：

API 會依項目出現的順序，將每個項目轉譯為一行供 Claude 閱讀的文字。這些行會加在結果文字之後（以一個空白行分隔），並位於任何 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.

下載回報遵循以下規則：

• 單一區塊中每個 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 則不行。其他常見情況：

{
  "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 會以一個完整的 input_json_delta 送達（用戶端工具集）。
• 元素參照為盡力而為： 高度動態的頁面（虛擬化清單、以 canvas 轉譯的介面、捲動時重新轉譯的頁面）可能無法提供穩定的參照，此時 Claude 會改用螢幕截圖和座標點擊。
• read_console 和 read_network 取決於您的瀏覽器自動化： 它們只會回報瀏覽器自動化能擷取的內容，且僅限於其附加到分頁之後的內容。
• 一般代理程式限制同樣適用： 「latency」（延遲）、視覺準確度和提示注入風險皆沿用自電腦使用（請參閱電腦使用工具的限制），而其在透過提示最佳化模型效能、管理螢幕截圖歷史記錄和遵循實作最佳實務（動作延遲、動作驗證和記錄）中的指引也適用於瀏覽器執行器。

定價與資料保留

瀏覽器使用遵循標準的工具使用定價。使用瀏覽器使用工具時：

工具集定義開銷： 宣告 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 與資料保留，了解各功能的保留期限和資格。

後續步驟

Compatibility