Claude Platform Docs
MessagesИнструменты

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

Запускайте инструмент использования браузера из SDK для Python или TypeScript. SDK выполняет цикл и настроенные вами проверки URL, файлов и подтверждений, а браузер предоставляете вы.

В «software development kits» (наборах средств разработки), или SDK, для Python и TypeScript есть класс для «browser use tool» (инструмента использования браузера). Вы создаёте его подкласс и пишете по одному методу для каждого «member tool» (инструмента-члена), например navigate или left_click, поверх собственной автоматизации браузера. SDK маршрутизирует каждый вызов, проверяет URL и пути к файлам, обращается к вашему «approval callback» (обратному вызову подтверждения) и формирует каждый tool_result.

SDK не включает браузер, готовый «driver» (драйвер) или «denylist» (список запрещённых). Примеры драйверов для Playwright и Chrome DevTools Protocol на Python и TypeScript находятся в папке browser-toolset репозитория claude-quickstarts.

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

Драйвер — это ваш подкласс BetaAbstractBrowserToolset20260801. Этот драйвер реализует navigate, screenshot и left_click, а также _browser_state (browserState в TypeScript) — отчёт о состоянии, который нужен каждому драйверу. В примере backend обозначает вашу собственную обёртку над библиотекой автоматизации браузера, например Playwright.

from anthropic import Anthropic
from anthropic.tools.browser import (
    BetaAbstractBrowserToolset20260801,
    BetaBrowserNavigateResult,
    BetaBrowserScreenshotResult,
    BrowserState,
    ToolsetCallContext,
)
from anthropic.types.beta import (
    BetaBrowserLeftClickInput,
    BetaBrowserNavigateInput,
    BetaBrowserScreenshotInput,
    BetaBrowserStateTabEntryParam,
)


class MyBrowser(BetaAbstractBrowserToolset20260801):
    def __init__(self, backend, **options):
        super().__init__(**options)
        self.backend = backend

    def _browser_state(self, context: ToolsetCallContext) -> BrowserState:
        return BrowserState(
            tabs=[
                BetaBrowserStateTabEntryParam(
                    tab_id=tab.id,
                    title=tab.title,
                    url=tab.url,
                    active=tab.id == self.backend.active,
                )
                for tab in self.backend.tabs()
            ],
            state_changes=self.backend.drain_changes(),
        )

    def navigate(
        self, context: ToolsetCallContext, input: BetaBrowserNavigateInput
    ) -> BetaBrowserNavigateResult:
        # input.url — это URL, прошедший проверку политики URL, либо "back", "forward",
        # либо "reload". SDK добавляет https://, если Claude не указывает схему.
        page = self.backend.goto(input.url, input.tab_id)
        return BetaBrowserNavigateResult(
            url=page.url, status=page.status, title=page.title
        )

    def screenshot(
        self, context: ToolsetCallContext, input: BetaBrowserScreenshotInput
    ) -> BetaBrowserScreenshotResult:
        data = self.backend.png_base64(input.tab_id)
        return BetaBrowserScreenshotResult(data=data, media_type="image/png")

    def left_click(
        self, context: ToolsetCallContext, input: BetaBrowserLeftClickInput
    ) -> None:
        # Возвращать нечего: Claude получает "Clicked."
        self.backend.click(input.target, input.tab_id)

    def close(self) -> None:
        super().close()  # first, so no call is still using the browser when it closes
        if not self.backend.closed:
            self.backend.close()


client = Anthropic()
with MyBrowser(backend, allowed_domains=["example.com", "iana.org"]) as browser:
    runner = client.beta.messages.tool_runner(
        model="claude-opus-5-5",
        max_tokens=1024,
        tools=[browser],
        messages=[
            {
                "role": "user",
                "content": "Open example.com and tell me the page heading.",
            }
        ],
    )
    for message in runner:
        print(message)

Передайте сам экземпляр драйвера в качестве элемента tools. Член, который вы не реализуете, отправляется в API как отключённый. Если Claude всё равно вызовет его, SDK вернёт ошибку, и выполнение продолжится. Переопределение execute меняет то, какие члены отправляются как отключённые (Добавление хуков до и после). Исполнитель инструментов никогда не закрывает набор инструментов, поэтому один экземпляр может обслуживать несколько запусков. Закройте его, когда закончите.

Настройка драйвера

Включение и отключение членов

configs принимает настройки для каждого члена, описанные в разделе Настройка набора инструментов. Перечислите только те члены, которые вы меняете:

# MyBrowser, который также реализует read_console
browser = MyBrowser(
    backend, configs={"read_console": {"enabled": True}, "navigate": {"enabled": False}}
)

SDK отклоняет вызов отключённого члена до того, как выполнится ваш код. Включение члена, которого ваш класс не реализует, является ошибкой конфигурации, если только класс не переопределяет execute.

Добавление хуков до и после

Переопределите execute и вызовите execute родительского класса. Код перед этим вызовом выполняется после проверки URL (Задание политики URL) и confirm (Контроль значимых членов), и он может изменить входные данные. SDK не проверяет изменённые входные данные повторно. Код после вызова получает результат и может его изменить. Чтобы отклонить вызов, выбросьте исключение ToolError (raise в Python, throw в TypeScript).

Переопределение execute меняет то, какие члены предлагаются Claude. SDK считает каждый член реализованным, поэтому Claude предлагаются все члены, включённые по умолчанию. MyBrowser из быстрого старта обслуживает три члена, поэтому следующий TracedBrowser предлагает Claude члены, которые он не может обслужить. Отключите эти члены с помощью configs, прежде чем использовать его.

import time


class TracedBrowser(MyBrowser):
    def execute(self, context, name, input):
        started = time.monotonic()
        result = super().execute(context, name, input)
        elapsed_ms = (time.monotonic() - started) * 1000
        call_id = context.tool_use.id if context.tool_use else "-"
        log.info("%s %s %.0fms", call_id, name, elapsed_ms)
        return redact(result) if name == "get_page_text" else result

Реализация драйвера

Переопределите члены, которые поддерживает ваш браузер. Каждый член получает контекст вызова и входные данные члена в виде типизированного объекта, например BetaBrowserNavigateInput. Типы входных данных берутся из anthropic.types.beta (@anthropic-ai/sdk/resources/beta в TypeScript). В разделе Инструменты-члены перечислены поля каждого типа входных данных.

В TypeScript пишите члены как методы, а не как поля со стрелочными функциями, потому что SDK находит их в прототипе. В TypeScript член type пишется как type_. В Python — type.

Возврат результатов

То, что возвращает член, определяет, что прочитает Claude. Успешный результат заканчивается блоком browser_state, построенным из вашего отчёта о состоянии. Результат с ошибкой не содержит этого блока.

ЧленВозвращаетClaude читает
screenshot, zoomBetaBrowserScreenshotResultОдин блок изображения
navigateBetaBrowserNavigateResultNavigated to {url} — {title} (HTTP {status})
new_tab, switch_tab, list_tabs, close_tabЗапись вкладки (new_tab, switch_tab), список записей вкладок (list_tabs) или ничего (close_tab)Только блок browser_state
read_page, get_page_text, find, read_console, read_network, javascript_execСтрокуЭту строку
Любой другой членНичего или одну строку текстаКраткое подтверждение, например Clicked., а затем возвращённую строку в отдельном текстовом блоке

Отчёт о состоянии браузера

SDK вызывает _browser_state (параметр browserState в TypeScript) после каждого вызова, включая отклонённые и неудавшиеся вызовы. Возвращайте все открытые вкладки и то, что изменилось с момента последнего отчёта:

  • Открытые вкладки и события скачивания.
  • NavigationRefused для каждой навигации, которую заблокировал ваш «request hook» (хук запросов).
  • DialogDismissed для каждого нативного диалога, который закрыл ваш драйвер.

Поместите всё это в state_changes. В Python NavigationRefused(url=...) и DialogDismissed(kind=..., message=...) берутся из anthropic.tools.browser. В TypeScript это { type: "navigation_refused", url } и { type: "dialog_dismissed", kind, message }.

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

Когда открыта хотя бы одна вкладка, ровно одна должна быть активной. Каждый член, принимающий tab_id, должен действовать на вкладке, которую он указывает. SDK использует отчёт, чтобы определить, с какой страницы получен результат. Ограничения API на отчёт перечислены в разделе Отслеживание вкладок с помощью browser_state.

Обработка ошибок

Вызвано членом или SDKClaude читаетВыполнение
ToolErrorЕго сообщение в виде результата с ошибкойПродолжается
Любое другое исключениеЕго текст в виде результата с ошибкойПродолжается
ToolsetUsageError — при ошибке конфигурации, неправильном использовании SDK во время вызова или вызове после closeНичегоОстанавливается

Прежде чем Claude прочитает текст ошибки члена, строку, которую возвращает действие вроде left_click, ошибку неудавшегося скачивания или сообщение закрытого диалога, SDK заменяет каждый URL, который отклоняет политика, на (blocked). Каждый локальный путь, который «file policy» (файловая политика) не раскрывает, он заменяет на (path hidden). Проверка может пропустить некоторые URL и пути. ToolError из вашей политики URL, файловой политики или вызываемого объекта confirm доходит до Claude в исходном виде, поэтому не включайте в его текст отклонённые URL и локальные пути. Перехватывайте исключения в своих членах и выбрасывайте ToolError с собственным текстом (raise в Python, throw в TypeScript).

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

Передайте экземпляр в tools (browser.toJSON() в TypeScript) и отвечайте на каждый вызов члена с помощью tool_result (toolResult в TypeScript). Инструмент использования браузера требует остановиться на первом неудавшемся вызове (Пакетные действия). После неудавшегося вызова этот цикл отвечает на последующие вызовы хода, не выполняя их:

from anthropic.types.beta import BetaToolResultBlockParam

NOT_EXECUTED = "Not executed: an earlier action in this turn failed."
MAX_TURNS = 10

with MyBrowser(backend, allowed_domains=["example.com"]) as browser:
    messages = [{"role": "user", "content": "Open example.com"}]
    for _ in range(MAX_TURNS):
        response = client.beta.messages.create(
            model="claude-opus-5-5",
            max_tokens=1024,
            tools=[browser],
            messages=messages,
        )
        messages.append({"role": "assistant", "content": response.content})
        calls = [
            block
            for block in response.content
            if block.type == "tool_use" and block.toolset_name == browser.toolset_name
        ]
        if not calls:
            break
        results: list[BetaToolResultBlockParam] = []
        failed = False
        for call in calls:
            if failed:
                # После неудачного вызова остальные вызовы в этом ходе получают ответ, но не выполняются.
                results.append(
                    {
                        "type": "tool_result",
                        "tool_use_id": call.id,
                        "toolset_name": call.toolset_name,
                        "content": NOT_EXECUTED,
                        "is_error": True,
                    }
                )
                continue
            result = browser.tool_result(call)
            failed = bool(result.get("is_error"))
            results.append(result)
        messages.append({"role": "user", "content": results})

Каждый ответ на пропущенный вызов содержит is_error, toolset_name вызова и точный текст, которого требует раздел Пакетные действия. Исполнитель инструментов отправляет такой же ответ.

Безопасный запуск набора инструментов

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

  1. Задайте политику URL: allowed_domains, blocked_domains или собственную url_policy.
  2. Перехватывайте запросы в драйвере и запрашивайте вердикт у набора инструментов.
  3. Примените «egress policy» (политику исходящего трафика) к контейнеру, чтобы сеть блокировала то, чего не видит драйвер.
  4. Ограничьте загрузки и скачивания или оставьте загрузки отключёнными.
  5. Контролируйте значимые члены с помощью confirm.
  6. Изолируйте хост браузера в выделенном контейнере либо в «virtual machine» (виртуальной машине), или VM, для каждого сеанса.

SDK обеспечивает выполнение шагов 1, 4 и 5 в соответствии с вашей настройкой. Шаги 2, 3 и 6 зависят от вашего драйвера и вашего развёртывания. Меры предосторожности из раздела Соображения безопасности также применяются.

Задание политики URL

Укажите в allowed_domains (allowedDomains в TypeScript) сайты, необходимые для задачи. Элемент любого из списков — это домен (который также охватывает свои поддомены), IP-адрес или сеть в нотации «Classless Inter-Domain Routing» (бесклассовой междоменной маршрутизации), или CIDR. Если задан allowed_domains, набор инструментов отклоняет все остальные хосты.

browser = MyBrowser(backend, allowed_domains=["example.com", "iana.org"])

Если задаче нужен открытый интернет, задайте вместо этого blocked_domains (blockedDomains). Списки сравнивают имена хостов, не выполняя их разрешение. Элемент 127.0.0.0/8 в списке запрещённых не блокирует localhost, поэтому указывайте как хосты, так и сети. Если заданы оба списка, приоритет имеет blocked_domains.

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

# Перечислите хосты и сети, доступные браузеру, к которым Claude обращаться не должен:
# петлевые (loopback), link-local и частные диапазоны IPv4 и IPv6, 0.0.0.0/8, адреса
# и имена сервиса метаданных вашего облака (например, metadata.google.internal),
# localhost и ваши внутренние имена хостов.
browser = MyBrowser(backend, blocked_domains=internal_networks)

url_policy (urlPolicy) заменяет оба списка, и передача её вместе с любым из списков является ошибкой конфигурации. Чтобы разрешить URL, ваша политика ничего не возвращает, а чтобы отклонить его, выбрасывает ToolError (raise в Python, throw в TypeScript). Чтобы сохранить правила по умолчанию, создайте политику по умолчанию с помощью default_url_policy (defaultURLPolicy) и вызывайте её первой из своей:

from urllib.parse import urlsplit

from anthropic.tools.browser import ToolError, URLContext, default_url_policy

listed = default_url_policy(allowed_domains=["example.com"])


def url_policy(context: URLContext, url: str) -> None:
    listed(context, url)  # the default rules first
    if context.phase == "request" and urlsplit(url).scheme != "https":
        raise ToolError("Only https navigation is allowed.")


browser = MyBrowser(backend, url_policy=url_policy)

Политика применяется к каждому URL navigate до вашего кода, к URL, о котором сообщает результат, и к каждому URL вкладки и скачивания в отчёте о состоянии. В результатах и отчётах о состоянии она пропускает адреса, которые не указывают на удалённый хост: пустую вкладку, about:blank, страницу chrome-error: браузера и документы data:.

При любой политике набор инструментов отклоняет navigate на схему, отличную от http или https, за исключением about:blank. url_policy="allow_all" (urlPolicy: "allow_all") отключает политику, но не это правило для схем.

Передача url_policy=None (urlPolicy: null) приводит к тому, что конструктор вызывает ошибку конфигурации, поэтому None (null), прочитанное из вашей конфигурации, не может отключить проверки. В TypeScript undefined оставляет параметр незаданным — так же, как если бы вы его не передавали.

Когда страница попадает на отклонённый адрес, Claude читает, что её содержимое было скрыто, а вкладка отображается как (blocked). Пока вкладка снова не окажется на разрешённом адресе, набор инструментов отклоняет вызовы для неё. Исключения — navigate (но не "reload"), new_tab, list_tabs, switch_tab и close_tab.

Перехват запросов в драйвере

Политика URL оценивает только адреса, которые видит набор инструментов: навигации, результаты и отчёты о состоянии. Она не видит подресурсы, вызовы fetch(), WebSocket или то, во что разрешается имя хоста.

Набор инструментов обнаруживает новый адрес только по завершении вызова — в результате вызова или отчёте о состоянии. Поэтому до этого момента вызов всё ещё может действовать на отклонённой странице, и SDK может в лучшем случае скрыть результат этого вызова. Если ваш драйвер не оценивает каждый запрос, включая шаги перенаправления, страница, которая перенаправляет на отклонённый адрес, всё равно загрузится.

В хуке запросов вашего драйвера (функции, которую ваша библиотека автоматизации вызывает перед каждым запросом) вызывайте check_url (checkURL). Он применяет собственную политику набора инструментов, поэтому вам не нужно писать правила дважды:

from anthropic.tools.browser import URLContext


class MyBrowser(BetaAbstractBrowserToolset20260801):
    ...

    # Регистрируется в контексте браузера Playwright через context.route("**/*", self._guard)
    def _guard(self, route):
        url_context = URLContext(
            member="navigate", phase="request", tab_id=self.backend.active
        )
        if not self.check_url(url_context, route.request.url).allowed:
            return route.abort("blockedbyclient")
        route.continue_()

check_url применяет то же правило для схем и ту же политику, что и navigate. Подобный хук запросов не видит рукопожатия WebSocket, запросы service worker или шаги перенаправления. Блокируйте service worker. Оценивайте рукопожатия WebSocket и шаги перенаправления с помощью хука, который их видит.

На этапе запроса check_url разрешает только URL http, https и about:blank. Поэтому для WebSocket замените ws:// на http:// и wss:// на https://, прежде чем вызывать его.

Применение политики исходящего трафика к контейнеру

Перехват не может увидеть каждый запрос, который делает браузер, а политика URL не видит, во что разрешается имя. Политика исходящего трафика, которую обеспечивает сеть контейнера, покрывает и то, и другое:

  • Блокируйте loopback, link-local и частные диапазоны адресов в IPv4 и IPv6, а также 0.0.0.0/8. Это включает адрес облачных метаданных 169.254.169.254.
  • Разрешайте исходящие соединения только к хостам, необходимым для задачи. Если ваши правила сопоставляют IP-адреса, выполняйте разрешение допускаемых вами имён хостов при запуске контейнера.
  • Разрешайте DNS только к резолверу контейнера.
  • Если ваш драйвер обращается к браузеру через локальный порт DevTools, разрешайте loopback только на этом порту. Правило для всего loopback открыло бы странице доступ ко всем локальным сервисам.

Ограничение загрузок и скачиваний

file_upload по умолчанию отключён. Без file_policy SDK отклоняет каждую загрузку, в которой указан путь или идентификатор документа. Чтобы включить загрузки, передайте LocalFilePolicy (NodeFilePolicy в TypeScript) с одним каталогом загрузки, который содержит только файлы задачи:

from anthropic.tools.browser import LocalFilePolicy

# MyBrowser, который также реализует file_upload
browser = MyBrowser(
    backend,
    configs={"file_upload": {"enabled": True}},
    confirm=make_confirm(),  # required for file_upload; see Gate consequential members
    file_policy=LocalFilePolicy(
        upload_roots=["/task/uploads"],
        download_dir="/task/downloads",
        expose_download_paths=False,
    ),
)

SDK вычисляет реальный путь каждой загрузки, следуя по символическим ссылкам, и отклоняет любой путь за пределами корневых каталогов загрузки. Файловая политика отклоняет каталог скачивания, находящийся внутри корневого каталога загрузки. Путь скачанного файла доходит до Claude, только если expose_download_paths (exposeDownloadPaths) имеет значение true и файл находится внутри каталога скачивания.

Поставляемые проверки путей вычисляют пути в файловой системе процесса, который запускает SDK. Они защищают только браузер, который использует ту же файловую систему. Для удалённого браузера вместо этого следуйте разделу Удалённые и размещённые браузеры.

Настройте скачивания следующим образом:

  • Создайте каталог скачивания самостоятельно с режимом 0700 и смонтируйте его с noexec,nosuid,nodev.
  • Держите каталог вне досягаемости других инструментов, которые может вызывать Claude, например оболочки или файлового инструмента.
  • В изменении состояния download_failed записывайте error как фиксированную фразу. Текст исключения может содержать путь или URL.
  • Не считывайте скачанный файл в разговор и не запускайте его, пока это не решит человек.

Контроль значимых членов

javascript_exec и file_upload по умолчанию отключены. Если вы включите любой из них без вызываемого объекта confirm, конструктор вызовет ошибку конфигурации. При наличии вызываемого объекта confirm SDK вызывает его перед каждым вызовом, который вот-вот будет выполнен. Без него ничего не запрашивается.

Верните True, чтобы выполнить вызов, или False, чтобы отклонить его (true и false в TypeScript). Когда ваш вызываемый объект спрашивает человека, покажите ему имя члена, URL страницы и входные данные вызова. Сначала экранируйте каждый символ во входных данных, выходящий за пределы печатаемых символов ASCII, потому что входные данные могут содержать текст со страницы.

В этом примере о двух контролируемых членах спрашивается через вашу собственную функцию ask_user (askUser в TypeScript), а остальные одобряются:

import json
from collections.abc import Callable

from anthropic.tools.browser import ConfirmContext

GATED = {"javascript_exec", "file_upload"}


def shown(context: ConfirmContext) -> str:
    """The call's input as JSON, with every character outside printable
    ASCII escaped."""
    return json.dumps(context.input.to_dict(), ensure_ascii=True, indent=2)


def make_confirm() -> Callable[[ConfirmContext], bool]:
    granted: set[tuple[str, str, str]] = set()

    def confirm(context: ConfirmContext) -> bool:
        name = context.member
        if name not in GATED:
            return True
        detail = shown(context)
        page = context.tab_url
        origin = context.origin
        if page is None or origin is None or origin.startswith("chrome-error:"):
            # Нет источника или это страница ошибки: запрашивать каждый раз.
            return ask_user(
                f"Allow {name} on {page or 'a page with no origin'}?\n{detail}"
            )
        # Одобрение распространяется только на этот конкретный ввод на этой странице.
        key = (name, page, detail)
        if key not in granted and ask_user(f"Allow {name} on {page}?\n{detail}"):
            granted.add(key)
        return key in granted

    return confirm


# MyBrowser, который также реализует javascript_exec и file_upload
browser = MyBrowser(
    backend,
    configs={"javascript_exec": {"enabled": True}, "file_upload": {"enabled": True}},
    confirm=make_confirm(),
)

Каждый вызов make_confirm() (makeConfirm() в TypeScript) возвращает вызываемый объект без одобрений. Вызывайте его один раз для каждого набора инструментов и выделяйте каждому пользователю собственный набор инструментов.

Одобрение распространяется на страницу в том виде, в каком её показал последний отчёт о состоянии, а страница может измениться до выполнения вызова. Покупки, отправленные сообщения и принятые условия происходят через обычные члены, такие как left_click и type, поэтому confirm не может выделить их по имени. Чтобы их одобрял человек, спрашивайте и об этих членах.

Не включайте javascript_exec в драйвере, который не перехватывает запросы. Скрипт, выполняющийся на отклонённой странице, может скопировать её содержимое туда, откуда его вернёт последующее чтение.

Изоляция хоста браузера

Запускайте браузер в выделенном контейнере или VM с минимальными привилегиями для каждого сеанса:

  • Запускайте от имени пользователя без прав root, с корневой файловой системой только для чтения, если браузер это допускает.
  • Не монтируйте с хоста ничего, кроме настроенных вами каталогов загрузки и скачивания, если они есть.
  • Не допускайте учётных данных в окружении и начинайте со свежего профиля браузера.
  • Не используйте общую файловую систему с другими инструментами, которые может вызывать Claude.

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

Считайте недоверенным всё, что возвращает страница, включая текст страницы, снимки экрана, записи консоли и сети, заголовки вкладок и имена скачанных файлов.

Удалённые и размещённые браузеры

Некоторые браузеры не используют общую файловую систему с процессом, который запускает SDK. Примеры — браузер в другом контейнере, браузер, к которому вы обращаетесь по URL DevTools, и браузер из сервиса размещённых браузеров. В этих случаях политика URL, перехват запросов и confirm по-прежнему выполняются в вашем процессе.

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

Поставляемые проверки путей не защищают удалённый браузер. LocalFilePolicy (NodeFilePolicy в TypeScript) проверяет пути в файловой системе процесса, который запускает SDK, а браузер читает и записывает данные в собственной файловой системе.

SDK не может определить, что браузер удалённый. Поэтому для удалённого браузера оставляйте file_upload отключённым, если только ваш драйвер не проверяет пути загрузки там, где работает браузер, с помощью собственной FilePolicy. FilePolicy проверяет пути и идентификаторы документов каждой загрузки и решает, видит ли Claude путь скачанного файла.

Настройте удалённый браузер так, чтобы он отклонял скачивания, если только на его собственном хосте нет настройки скачиваний из раздела Ограничение загрузок и скачиваний.

Примеры драйверов следуют этому правилу. На удалённом браузере они вызывают ошибку конфигурации при наличии file_policy (filePolicy) или включённого file_upload и настраивают браузер на отклонение скачиваний.

Не допускайте попадания ключа API провайдера и URL подключения сеанса, который может содержать ключ, в журналы, результаты инструментов и текст ошибок. Если провайдер записывает сеансы, запись является ещё одной копией всего, что Claude видел и вводил, и к ней применяются условия хранения данных провайдера.

Справочник

Параметры конструктора имеют одинаковое значение в обоих SDK:

PythonTypeScriptЗадаёт
configsconfigsКакие члены включены
confirmconfirmВызываемый объект, который одобряет или отклоняет каждый вызов
allowed_domains, blocked_domainsallowedDomains, blockedDomainsСписки политики URL по умолчанию
url_policyurlPolicyВашу собственную политику URL
file_policyfilePolicyКорневые каталоги загрузки и раскрытие путей скачивания
tool_configstoolConfigsПоля для элемента tools, например cache_control
Метод _browser_statebrowserStateОтчёт о состоянии

Изменить параметр после создания нельзя. Значения по умолчанию, ошибки, поля контекста и асинхронный класс Python (BetaAsyncAbstractBrowserToolset20260801) описаны в Python SDK и TypeScript SDK.

Ограничения

  • Политика URL проверяет навигации, а не каждый запрос: См. Перехват запросов в драйвере.
  • Одобрение основано на последнем отчёте о состоянии: Страница может измениться после этого отчёта. SDK не проверяет страницу повторно перед выполнением вызова.
  • Вызовы в одном наборе инструментов выполняются по одному: Это нельзя отключить.
  • SDK не проверяет уникальность идентификаторов вкладок, то, что активна одна вкладка, или количество вкладок: API отклоняет отчёт, нарушающий эти правила.

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

Инструменты-члены, блок browser_state и соображения безопасности инструмента.

Как SDK выполняет цикл и как изменить отправляемые им сообщения.

Защитные механизмы для любого приложения, которое читает недоверенное содержимое.

Was this page helpful?