Uso do navegador com o toolset do SDK

Os SDKs Python e TypeScript incluem uma classe para a ferramenta de uso do navegador. Você cria uma subclasse dela e escreve um método por ferramenta membro, como navigate ou left_click, sobre sua própria automação de navegador. O SDK roteia cada chamada, verifica URLs e caminhos de arquivo, consulta seu callback de aprovação e constrói cada tool_result.

O SDK não inclui um navegador, um driver pronto nem uma "denylist" (lista de bloqueio). Drivers de exemplo para Playwright e para o Chrome DevTools Protocol, em Python e TypeScript, estão na pasta browser-toolset do repositório claude-quickstarts.

Início rápido

Um driver é sua subclasse de BetaAbstractBrowserToolset20260801. Este implementa navigate, screenshot e left_click, além de _browser_state (browserState em TypeScript), o relatório de estado de que todo driver precisa. No exemplo, backend representa seu próprio wrapper em torno de uma biblioteca de automação de navegador, como o 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 é uma URL que passou pela política de URLs, ou "back", "forward",
        # ou "reload". O SDK adiciona https:// quando Claude omite o esquema.
        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:
        # Nada a retornar: Claude lê "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)

Passe a própria instância do driver como a entrada de tools. Um membro que você não implementa é enviado à API como desabilitado. Se Claude o chamar mesmo assim, o SDK retorna um erro e a execução continua. Sobrescrever execute altera quais membros são enviados como desabilitados (Adicionar hooks antes e depois). O runner nunca fecha o toolset, então uma instância pode servir várias execuções. Feche-a quando terminar.

Personalizar um driver

Habilitar ou desabilitar membros

configs recebe as configurações por membro descritas em Configure o conjunto de ferramentas. Liste apenas os membros que você altera:

# Um MyBrowser que também implementa read_console
browser = MyBrowser(
    backend, configs={"read_console": {"enabled": True}, "navigate": {"enabled": False}}
)

O SDK recusa uma chamada a um membro desabilitado antes que seu código seja executado. Habilitar um membro que sua classe não implementa é um erro de configuração, a menos que a classe sobrescreva execute.

Adicionar hooks antes e depois

Sobrescreva execute e chame o execute da classe pai. O código antes dessa chamada é executado após a verificação de URL (Definir uma política de URL) e confirm (Controlar membros com consequências), e pode alterar a entrada. O SDK não verifica a entrada alterada novamente. O código após a chamada recebe o resultado e pode alterá-lo. Lance ToolError com raise (com throw em TypeScript) para recusar a chamada.

Sobrescrever execute altera quais membros são oferecidos a Claude. O SDK conta todo membro como implementado, então Claude recebe a oferta de todo membro que está ativado por padrão. O MyBrowser do início rápido atende três membros, então o TracedBrowser a seguir oferece a Claude membros que ele não consegue atender. Desative esses membros com configs antes de usá-lo.

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

Implementar um driver

Sobrescreva os membros que seu navegador suporta. Cada membro recebe o contexto da chamada e a entrada do membro como um objeto tipado, como BetaBrowserNavigateInput. Os tipos de entrada vêm de anthropic.types.beta (@anthropic-ai/sdk/resources/beta em TypeScript). Ferramentas membro lista os campos de cada entrada.

Em TypeScript, escreva os membros como métodos, não como campos de arrow function, porque o SDK os encontra no protótipo. Escreva o membro type como type_ em TypeScript. Em Python, é type.

Retornar resultados

O que um membro retorna determina o que Claude lê. Um resultado bem-sucedido termina com um bloco browser_state construído a partir do seu relatório de estado. Um resultado de erro não carrega nenhum bloco.

Relatar o estado do navegador

O SDK chama _browser_state (a opção browserState em TypeScript) após cada chamada, incluindo chamadas recusadas e com falha. Retorne todas as abas abertas e o que mudou desde o último relatório:

• Abas abertas e eventos de download.
• Um NavigationRefused para cada navegação que seu hook de requisição bloqueou.
• Um DialogDismissed para cada diálogo nativo que seu driver dispensou.

Coloque tudo isso em state_changes. Em Python, NavigationRefused(url=...) e DialogDismissed(kind=..., message=...) vêm de anthropic.tools.browser. Em TypeScript, eles são { type: "navigation_refused", url } e { type: "dialog_dismissed", kind, message }.

Os dois últimos não são mudanças de estado da API. O SDK os relata a Claude como texto fora do bloco browser_state: uma linha para todas as navegações recusadas, que não nomeia uma URL, e uma linha para cada um dos três primeiros diálogos dispensados, seguida de uma contagem de quaisquer outros.

Quando qualquer aba estiver aberta, exatamente uma deve estar ativa. Todo membro que recebe um tab_id deve agir na aba que ele nomeia. O SDK usa o relatório para determinar de qual página veio um resultado. Os limites da API para o relatório estão listados em Rastreie abas com browser_state.

Tratar erros

Antes que Claude leia o texto de erro de um membro, a linha que uma ação como left_click retorna, o erro de um download com falha ou a mensagem de um diálogo dispensado, o SDK substitui cada URL que a política recusa por (blocked). Ele substitui cada caminho local que a política de arquivos não expõe por (path hidden). A verificação pode deixar passar algumas URLs e caminhos. Um ToolError da sua política de URL, da sua política de arquivos ou do callable confirm chega a Claude como foi escrito, então deixe URLs recusadas e caminhos locais fora do texto dele. Capture exceções nos seus membros e lance ToolError com raise (com throw em TypeScript) com seu próprio texto.

Executar sem o tool runner

Passe a instância em tools (browser.toJSON() em TypeScript) e responda a cada chamada de membro com tool_result (toolResult em TypeScript). A ferramenta de uso do navegador exige que você pare na primeira chamada com falha (Ações em lote). Após uma chamada com falha, este loop responde às chamadas posteriores do turno sem executá-las:

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:
                # Após uma chamada com falha, o restante do turno é respondido, não executado.
                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})

Cada resposta a uma chamada ignorada carrega is_error, o toolset_name da chamada e o texto exato que Ações em lote exige. O tool runner envia a mesma resposta.

Executar o toolset com segurança

A próxima ação de Claude depende das páginas que ele lê. Uma página, ou um texto injetado nela, pode tentar alcançar serviços internos ou extrair arquivos do host. Também pode tentar acionar ações com efeitos reais. Antes de executar um driver contra qualquer coisa que não seja um navegador descartável, siga estas seis etapas:

1. Defina uma política de URL: allowed_domains, blocked_domains ou sua própria url_policy.
2. Intercepte requisições no driver e peça um veredito ao toolset.
3. Aplique uma política de "egress" (tráfego de saída) no contêiner, para que a rede bloqueie o que o driver não consegue ver.
4. Restrinja uploads e downloads, ou deixe os uploads desativados.
5. Controle membros com consequências com confirm.
6. Isole o host do navegador em um contêiner ou VM dedicado para cada sessão.

O SDK aplica as etapas 1, 4 e 5 conforme você as configura. As etapas 2, 3 e 6 dependem do seu driver e da sua implantação. As precauções em Considerações de segurança também se aplicam.

Definir uma política de URL

Defina allowed_domains (allowedDomains em TypeScript) com os sites de que a tarefa precisa. Uma entrada em qualquer uma das listas é um domínio (que também abrange seus subdomínios), um endereço IP ou uma rede CIDR. Com allowed_domains definido, o toolset recusa todos os outros hosts.

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

Se a tarefa precisar da web aberta, defina blocked_domains (blockedDomains) em vez disso. As listas comparam nomes de host sem resolvê-los. Uma entrada 127.0.0.0/8 na lista de bloqueio não bloqueia localhost, então liste hosts além de redes. Quando você define ambas as listas, blocked_domains prevalece.

Uma lista de bloqueio não consegue detectar um nome público que resolve para um endereço privado. Portanto, com blocked_domains, a política de egress do contêiner é o que impede que esse nome alcance um endereço privado.

# Liste os hosts e redes que o navegador alcança, mas que o Claude não deve acessar:
# intervalos loopback, link-local e privados em IPv4 e IPv6, 0.0.0.0/8, os
# endereços e nomes de metadados da sua nuvem (como metadata.google.internal),
# localhost e seus hostnames internos.
browser = MyBrowser(backend, blocked_domains=internal_networks)

Uma url_policy (urlPolicy) substitui ambas as listas, e passá-la junto com qualquer uma das listas é um erro de configuração. Sua política não retorna nada para permitir uma URL e lança ToolError (com raise, ou throw) para recusá-la. Para manter as regras padrão, construa a política padrão com default_url_policy (defaultURLPolicy) e chame-a primeiro a partir da sua:

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)

A política é executada em toda URL de navigate antes do seu código, na URL que um resultado relata e em toda URL de aba e de download em um relatório de estado. Em resultados e relatórios de estado, ela ignora endereços que não nomeiam nenhum host remoto: uma aba vazia, about:blank, a página chrome-error: do navegador e documentos data:.

Sob qualquer política, o toolset recusa um navigate para um esquema diferente de http ou https, exceto about:blank. url_policy="allow_all" (urlPolicy: "allow_all") desativa a política, mas não essa regra de esquema.

Passar url_policy=None (urlPolicy: null) faz o construtor lançar um erro de configuração, de modo que um None (null) lido da sua configuração não consiga desativar as verificações. Em TypeScript, undefined deixa a opção não definida, o mesmo que não passá-la.

Quando uma página chega a um endereço recusado, Claude lê que seu conteúdo foi retido, e a aba é listada como (blocked). Até que a aba esteja novamente em um endereço permitido, o toolset recusa chamadas nela. As exceções são navigate (mas não "reload"), new_tab, list_tabs, switch_tab e close_tab.

Interceptar requisições no driver

A política de URL julga apenas os endereços que o toolset vê: navegações, resultados e relatórios de estado. Ela não vê sub-recursos, chamadas fetch(), WebSockets nem para onde um nome de host resolve.

O toolset detecta um novo endereço apenas quando uma chamada termina, no resultado ou no relatório de estado da chamada. Assim, uma chamada ainda pode agir em uma página recusada antes disso, e o SDK pode, no máximo, reter o resultado dessa chamada. A menos que seu driver julgue cada requisição, incluindo os saltos de redirecionamento, uma página que redireciona para um endereço recusado ainda é carregada.

No hook de requisição do seu driver (a função que sua biblioteca de automação chama antes de cada requisição), chame check_url (checkURL). Ele aplica a própria política do toolset, para que você não escreva as regras duas vezes:

from anthropic.tools.browser import URLContext


class MyBrowser(BetaAbstractBrowserToolset20260801):
    ...

    # Registrado em um contexto de navegador do Playwright com 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 aplica a mesma regra de esquema e a mesma política que navigate. Um hook de requisição como este não vê handshakes de WebSocket, requisições de service worker nem saltos de redirecionamento. Bloqueie service workers. Julgue handshakes de WebSocket e saltos de redirecionamento com um hook que os veja.

Na fase de requisição, check_url permite apenas URLs http, https e about:blank. Portanto, para um WebSocket, altere ws:// para http:// e wss:// para https:// antes de chamá-lo.

Aplicar política de egress no contêiner

A interceptação não consegue ver todas as requisições que o navegador faz, e a política de URL não vê para onde um nome resolve. Uma política de egress que a rede do contêiner aplica cobre ambos:

• Bloqueie loopback, link-local e faixas de endereços privados em IPv4 e IPv6, e 0.0.0.0/8. Isso inclui o endereço de metadados da nuvem 169.254.169.254.
• Permita conexões de saída apenas para os hosts de que a tarefa precisa. Se suas regras corresponderem a endereços IP, resolva os nomes de host que você permite quando o contêiner iniciar.
• Permita DNS apenas para o resolvedor do contêiner.
• Se seu driver alcança o navegador por meio de uma porta local do DevTools, permita loopback apenas nessa porta. Uma regra para todo o loopback abriria todos os serviços locais para a página.

Restringir uploads e downloads

file_upload está desativado por padrão. Sem file_policy, o SDK recusa todo upload que nomeia um caminho ou um ID de documento. Para habilitar uploads, passe uma LocalFilePolicy (NodeFilePolicy em TypeScript) com um diretório de upload que contenha apenas os arquivos da tarefa:

from anthropic.tools.browser import LocalFilePolicy

# Um MyBrowser que também implementa 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,
    ),
)

O SDK resolve cada caminho de upload, seguindo symlinks, e recusa qualquer caminho fora das raízes de upload. A política de arquivos recusa um diretório de download dentro de uma raiz de upload. O caminho de um download chega a Claude apenas quando expose_download_paths (exposeDownloadPaths) é true e o arquivo está dentro do diretório de download.

As verificações de caminho incluídas resolvem caminhos no sistema de arquivos do processo que executa o SDK. Elas protegem apenas um navegador que compartilha esse sistema de arquivos. Para um navegador remoto, siga Navegadores remotos e hospedados em vez disso.

Configure os downloads desta forma:

• Crie você mesmo o diretório de download com o modo 0700 e monte-o com noexec,nosuid,nodev.
• Mantenha o diretório fora do alcance de outras ferramentas que Claude pode chamar, como um shell ou uma ferramenta de arquivos.
• Em uma mudança de estado download_failed, escreva error como uma frase fixa. O texto de uma exceção pode conter o caminho ou a URL.
• Não carregue um arquivo baixado na conversa, nem o execute, até que uma pessoa decida fazê-lo.

Controlar membros com consequências

javascript_exec e file_upload estão desativados por padrão. Se você habilitar qualquer um deles sem um callable confirm, o construtor lança um erro de configuração. Com um callable confirm, o SDK o chama antes de cada chamada que está prestes a ser executada. Sem um, nada é perguntado.

Retorne True para executar a chamada, ou False para recusá-la (true e false em TypeScript). Quando seu callable perguntar a uma pessoa, mostre a ela o membro, a URL da página e a entrada da chamada. Primeiro, faça o escape de todo caractere da entrada que esteja fora do ASCII imprimível, porque a entrada pode carregar texto da página.

Este exemplo pergunta sobre os dois membros controlados por meio da sua própria função ask_user (askUser em TypeScript) e aprova o restante:

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:"):
            # Sem origem, ou uma página de erro: pergunte sempre.
            return ask_user(
                f"Allow {name} on {page or 'a page with no origin'}?\n{detail}"
            )
        # Uma aprovação cobre apenas esta entrada exata nesta página.
        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


# Um MyBrowser que também implementa javascript_exec e file_upload
browser = MyBrowser(
    backend,
    configs={"javascript_exec": {"enabled": True}, "file_upload": {"enabled": True}},
    confirm=make_confirm(),
)

Cada chamada a make_confirm() (makeConfirm() em TypeScript) retorna um callable sem aprovações. Chame-a uma vez para cada toolset e dê a cada usuário seu próprio toolset.

Uma aprovação abrange a página como o último relatório de estado a mostrou, e a página pode mudar antes que a chamada seja executada. Compras, mensagens enviadas e termos aceitos acontecem por meio de membros comuns, como left_click e type, então confirm não consegue identificá-los pelo nome. Para que uma pessoa os aprove, pergunte também sobre esses membros.

Não habilite javascript_exec em um driver que não intercepta requisições. Um script executado em uma página recusada pode copiar o conteúdo dela para um lugar de onde uma leitura posterior o retorne.

Isolar o host do navegador

Execute o navegador em um contêiner ou VM dedicado e com privilégios mínimos para cada sessão:

• Execute como um usuário não root, com um sistema de arquivos raiz somente leitura onde o navegador permitir.
• Não monte nada do host além dos diretórios de upload e download que você configurou, se houver.
• Mantenha credenciais fora do ambiente e comece a partir de um perfil de navegador novo.
• Não compartilhe nenhum sistema de arquivos com outras ferramentas que Claude pode chamar.

Execute o código que chama a API fora do contêiner do navegador, porque esse código contém sua chave de API e a conversa. O tool runner e tool_result executam o toolset no processo desse código, então o navegador não compartilha o sistema de arquivos do toolset. Trate o navegador como remoto: Navegadores remotos e hospedados se aplica.

Trate tudo o que uma página retorna como não confiável, incluindo texto da página, capturas de tela, entradas de console e de rede, títulos de abas e nomes de downloads.

Navegadores remotos e hospedados

Alguns navegadores não compartilham um sistema de arquivos com o processo que executa o SDK. Exemplos são um navegador em outro contêiner, um que você acessa em uma URL do DevTools e um de um serviço de navegador hospedado. Com eles, a política de URL, a interceptação de requisições e confirm ainda são executados no seu processo.

Com um navegador hospedado, o provedor controla o egress e o isolamento do host. Sua própria política de egress não se aplica ali, então o hook de requisição do driver é sua única verificação sobre as requisições do navegador. Descubra o que a rede do navegador consegue alcançar.

As verificações de caminho incluídas não protegem um navegador remoto. LocalFilePolicy (NodeFilePolicy em TypeScript) verifica caminhos no sistema de arquivos do processo que executa o SDK, e o navegador lê e grava em seu próprio sistema de arquivos.

O SDK não consegue detectar que um navegador é remoto. Portanto, para um navegador remoto, mantenha file_upload desativado, a menos que seu driver verifique os caminhos de upload onde o navegador é executado, com uma FilePolicy própria. Uma FilePolicy examina os caminhos e IDs de documento de cada upload e decide se Claude vê o caminho de um download.

Faça um navegador remoto recusar downloads, a menos que seu próprio host tenha a configuração de download de Restringir uploads e downloads.

Os drivers de exemplo seguem essa regra. Em um navegador remoto, eles lançam um erro de configuração para uma file_policy (filePolicy) ou um file_upload habilitado, e configuram o navegador para recusar downloads.

Mantenha a chave de API do provedor e a URL de conexão da sessão, que pode conter uma chave, fora de logs, resultados de ferramentas e textos de erro. Se o provedor gravar sessões, a gravação é outra cópia de tudo o que Claude viu e digitou, e os termos de retenção do provedor se aplicam a ela.

Referência

As opções do construtor têm o mesmo significado em ambos os SDKs:

Você não pode alterar uma opção após a construção. Padrões, erros, campos de contexto e a classe Python assíncrona (BetaAsyncAbstractBrowserToolset20260801) estão documentados no SDK Python e no SDK TypeScript.

Limitações

• A política de URL verifica navegações, não todas as requisições: Consulte Interceptar requisições no driver.
• Uma aprovação se baseia no último relatório de estado: A página pode mudar após esse relatório. O SDK não verifica a página novamente antes que a chamada seja executada.
• Chamadas em um toolset são executadas uma de cada vez: Você não pode desativar isso.
• O SDK não verifica se os IDs de aba são únicos, se uma aba está ativa nem quantas abas existem: A API rejeita um relatório que viole essas regras.

Próximos passos