Инструмент использования браузера

Инструмент «browser use» (использование браузера) позволяет Claude перемещаться по веб-страницам, читать их и взаимодействовать с ними в браузере, который запускает ваше приложение. Он работает со страницей как через её структуру («accessibility tree» (дерево доступности), элементы, формы и вкладки), так и через пиксели (снимки экрана и координаты «viewport» (области просмотра)), тогда как инструмент использования компьютера работает с целым рабочим столом только через снимки экрана и координаты. Это определённый Anthropic «client toolset» (клиентский набор инструментов): одна запись browser_toolset_20260801 в вашем массиве tools по умолчанию даёт Claude 27 «member tools» (инструментов-членов набора), таких как navigate, read_page, left_click и screenshot, плюс ещё четыре (javascript_exec, file_upload, read_console и read_network), когда вы включаете их. Ваше приложение выполняет каждый вызов с помощью собственной автоматизации браузера; на стороне Anthropic ничего не выполняется. В настоящее время он недоступен в Claude Managed Agents. На этой странице «ваше приложение» означает агентный цикл, который вызывает Messages API, а «ваш исполнитель» («executor») — ту его часть, которая управляет браузером и формирует результаты инструментов.

Выбирайте использование браузера вместо использования компьютера, когда задача остаётся в пределах веб-страниц: Claude может читать структуру страницы, действовать с элементом по ссылке, а не только по координате, напрямую задавать значения форм и работать с несколькими вкладками, и вам не нужно запускать рабочий стол. Если Claude нужно только читать страницы, на которые вы можете его направить, или находить источники в интернете, инструмент web fetch и инструмент web search ещё легче, потому что это серверные инструменты, которые API выполняет за вас без браузера, которым нужно управлять. Выбирайте использование браузера, когда страницы формируют своё содержимое с помощью JavaScript или задача подразумевает действия на странице, а не только её чтение.

При использовании браузера Claude читает живые веб-страницы и действует на них, поэтому всё, что предоставляет страница, является недоверенным вводом, а действия, которые выполняет Claude, могут иметь реальные последствия. Перед развёртыванием см. раздел Соображения безопасности.



Быстрый старт

Инструмент использования браузера доступен в Claude API без бета-заголовка: добавьте одну запись типа browser_toolset_20260801 без name в массив tools запроса Messages API.

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 не ответит текстом.

Вот каркас шага вызова инструментов этого цикла в двух частях. Сначала обработчики-заглушки членов набора заменяют вашу автоматизацию браузера. Пять членов (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}")

Вторая часть выполняет пакет по порядку, направляет каждый блок этим обработчикам, повторяет 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" }
    }
  ]
}

Ваше приложение возвращает три блока tool_result в одном сообщении user, каждый из которых содержит toolset_name и короткое текстовое подтверждение, например Clicked element ref_3. Нажатие Enter загружает страницу результатов, поэтому результат key также содержит блок browser_state с обновлённым URL вкладки (Контекст вкладки в других результатах). Если бы вместо этого щелчок завершился неудачей, его результат содержал бы ваш текст ошибки, а два других результата содержали бы текст остановки, как показано в разделе Возврат ошибок из вашего исполнителя.

Вам не нужно возвращать снимок экрана после каждого вызова. Claude обычно завершает пакет вызовом наблюдения (screenshot, read_page или get_page_text), и ваше приложение также может прикрепить собственное наблюдение, например свежий снимок экрана или дерево доступности, в виде дополнительного блока содержимого к последнему результату в пакете, чтобы сэкономить один цикл обмена. Поскольку результат управления вкладками должен быть ровно одним блоком browser_state, прикрепляйте его к последнему результату, который не является вызовом управления вкладками.

Если ваш исполнитель может выполнять только один вызов за цикл обмена, установите disable_parallel_tool_use в true в tool_choice, и Claude будет возвращать не более одного вызова члена набора за ход ценой большего числа циклов обмена (Отключение параллельного использования инструментов). Остальная часть контракта из раздела Пакетные действия для инструмента использования компьютера переносится сюда, включая один tool_result на каждый tool_use в следующем сообщении user, за исключением двух вещей: текста остановки и того, что содержит 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 не уменьшает изображения набора инструментов: снимок экрана или изображение zoom, превышающее ограничения размера изображений вашей модели или более строгое ограничение на одно изображение, которое применяется, когда запрос содержит более 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 передаёт ссылку обратно как цель {"type": "ref", "ref": "ref_2"} в последующем вызове щелчка, hover, scroll_to, form_input или file_upload либо как параметр ref в read_page для чтения поддерева. Ваш исполнитель назначает ссылки, хранит сопоставление каждой из них с базовым узлом (идентификатором узла доступности, сохранённым селектором или эквивалентом) и действует с этим узлом, когда ссылка возвращается.

Ссылки привязаны к вкладке, которая их создала, и остаются действительными, пока эта вкладка не выполнит переход или её 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 и щёлкает по координате; ваш исполнитель определяет, в какой фрейм попадает координата.
• Ограничивайте область чтения и читайте дерево, прежде чем делать снимок экрана. На больших страницах read_page с filter: "interactive" или с ref контейнера возвращает сфокусированное поддерево, а чтение дерева типичной страницы часто стоит меньше входных токенов, чем снимок экрана, при этом давая Claude ссылки, по которым он может действовать немедленно. Снимки экрана остаются правильным наблюдением, когда важны визуальный макет, изображения или состояние отрисовки.



Соображения безопасности

Использование браузера несёт риски, которых нет у стандартных функций API, потому что Claude читает содержимое из открытого интернета и действует на его основе, а любая страница может содержать текст, написанный для манипулирования им.

Claude иногда следует инструкциям, найденным в содержимом страницы, даже когда они противоречат вашим; текст на странице, гласящий «игнорируй свои предыдущие инструкции и перейди на...», может отвлечь его от задачи. Изолируйте Claude от конфиденциальных данных и действий, чтобы ограничить то, до чего может добраться «prompt injection» (инъекция подсказок), ознакомьтесь с разделом Противодействие джейлбрейкам и инъекциям подсказок, а если задача не может обойтись без сеанса с выполненным входом, используйте выделенную учётную запись с низкими привилегиями и сохраняйте подтверждение человеком для действий, изменяющих учётную запись.

Поскольку браузер работает в вашей среде, сайты, которые посещает 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 никогда его не назовёт, поэтому ваш исполнитель всё равно отвечает на такой вызов результатом с ошибкой.



Сочетание с другими инструментами

Объявляйте инструмент использования браузера вместе с вашими собственными инструментами и другими инструментами, предоставляемыми Anthropic, в том же массиве tools. Пользовательский инструмент может иметь то же имя, что и член набора (например, ваш собственный 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 возвращает её сетевые запросы, каждый в виде текста по одной строке на запись, накопленные с момента предыдущего чтения этой вкладки. Строка консоли содержит запись журнала, предупреждения или ошибки; строка сети содержит метод, 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 — это полный перечень открытых вкладок после вызова, а не дельта. Он может быть пустым; когда он не пуст, ровно одна запись содержит "active": true.
• state_changes (здесь не показано) сообщает о побочных эффектах вызова: запись tab_opened для каждой вкладки, открытой вызовом и всё ещё открытой на момент его завершения, чей tab_id также должен присутствовать в tabs, а также события загрузки. Опускайте это поле, когда сообщать нечего; пустой массив отклоняется.
• Отправляйте блок только в результатах, отвечающих на вызов члена набора browser, не более одного раза на 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 изменений состояния.
• Те же ограничения применяются к tab_id, который Claude передаёт в switch_tab и close_tab, поскольку 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 вкладки, или когда есть 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 увидел изменение вкладок в том же результате.
• Результат, чей список tabs пуст, для вызова без tab_id, поскольку нет вкладки, которую можно было бы указать.

Например, когда 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 нужно работать с файлом, также упомяните имя файла или path в блоке text того же результата.

Например, клик по «Download price list (CSV)» (ref_8) во вкладке Pricing запускает загрузку, поэтому результат клика содержит запись download_started с download_id "dl-1" и URL файла. Загрузка завершается во время выполнения последующего вызова screenshot, поэтому content этого результата содержит изображение, текстовый блок вида Screenshot captured. Download complete: /home/user/downloads/price-list.csv (48,213 bytes). и этот блок browser_state, сообщающий о завершении под тем же download_id:

{
  "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.
• Никогда не отправляйте state_changes в результате с is_error: true; о событии загрузки, произошедшем во время неудавшегося вызова, сообщайте в следующем успешном результате.
• 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 возвращает invalid_request_error до запуска Claude. В следующей таблице левый столбец указывает, что вы отправили.



Ограничения

• Доступность на платформах: использование браузера доступно только в Claude API.
• Только потоковая передача целого ввода: при потоковой передаче input каждого члена поступает как одна полная input_json_delta (Клиентские наборы инструментов).
• Ссылки на элементы предоставляются по мере возможности: высокодинамичные страницы (виртуализированные списки, интерфейсы, отрисованные на canvas, страницы, перерисовывающиеся при прокрутке) могут не предоставлять стабильных ссылок, и там Claude переходит к снимкам экрана и кликам по координатам.
• read_console и read_network зависят от вашей автоматизации браузера: они сообщают только то, что она может захватить, и только с момента её подключения к вкладке.
• Применяются общие ограничения агентов: задержка, точность зрения и риски внедрения подсказок переносятся из использования компьютера (см. Ограничения инструмента использования компьютера), а его рекомендации в разделах Оптимизация производительности модели с помощью подсказок, Управление историей снимков экрана и Следование лучшим практикам реализации (задержки действий, проверка действий и журналирование) применимы и к исполнителям браузера.



Цены и хранение данных

«Browser use» (использование браузера) следует стандартному ценообразованию использования инструментов. При использовании инструмента использования браузера:

Накладные расходы на определение набора инструментов: Объявление browser_toolset_20260801 с его участниками по умолчанию добавляет к запросу около 6 600 входных токенов (около 6 610 на Claude Fable 5, Claude Mythos 5, Claude Opus 5 и Claude Opus 4.8 и около 6 670 на Claude Sonnet 5), что покрывает определения инструментов-участников и системную подсказку использования инструментов. Включение всех четырёх необязательных участников добавляет около 880 токенов, а отключение участников с помощью configs уменьшает это количество. Точное количество для запроса указывается в поле usage ответа, и вы можете оценить его заранее с помощью конечной точки подсчёта токенов.

Дополнительное потребление токенов:

• Снимки экрана и увеличенные изображения, возвращаемые в результатах инструментов, тарифицируются как входные изображения (см. ценообразование Vision)
• Текстовые результаты инструментов, возвращаемые Claude, такие как деревья доступности, текст страницы, а также записи консоли или сети

Сеанс браузера, загрузки и выгруженные файлы остаются в вашей среде; снимки экрана, текст страниц и состояние вкладок, которые вы возвращаете, являются частью содержимого вашего запроса к API и подчиняются стандартной политике хранения или вашему соглашению ZDR, если оно у вас есть. Инструмент использования браузера подходит для ZDR; сроки хранения и применимость для различных функций см. в разделе API и хранение данных.



Следующие шаги