Ferramenta de uso do navegador

A ferramenta de uso do navegador permite que Claude navegue, leia e interaja com páginas da web em um navegador que sua aplicação executa. Claude trabalha com a página tanto por meio de sua estrutura (a "accessibility tree" (árvore de acessibilidade), elementos, formulários e abas) quanto por meio de capturas de tela e coordenadas da "viewport" (área de visualização).

A ferramenta é um conjunto de ferramentas de cliente definido pela Anthropic: uma única entrada browser_toolset_20260801 em tools dá a Claude 27 ferramentas membro por padrão, como navigate, read_page, left_click e screenshot, além de mais quatro quando você as habilita. Sua aplicação executa cada chamada em sua própria automação de navegador; nada é executado do lado da Anthropic. A ferramenta não está disponível atualmente no Claude Managed Agents.

Os SDKs de Python e TypeScript incluem uma classe que repassa essas chamadas ao seu código de navegador, aplica as políticas de URL e de arquivos que você define e consulta seu callback de aprovação. Consulte Uso de navegador e de computador com os toolsets do SDK.

Escolha o uso do navegador quando a tarefa permanece dentro de páginas da web e envolve agir sobre elas, ou quando as páginas constroem seu conteúdo com JavaScript. Quando uma tarefa precisa de um desktop inteiro, use a ferramenta de uso do computador, que funciona apenas por meio de capturas de tela e coordenadas. Para ler páginas para as quais você pode direcionar Claude, ou para encontrar fontes na web, a ferramenta de busca de conteúdo web e a ferramenta de pesquisa na web são mais leves. Elas são ferramentas de servidor que a API executa para você, sem nenhum navegador para operar.

Com o uso do navegador, Claude lê e age sobre páginas da web ativas, portanto tudo o que uma página fornece é entrada não confiável, e as ações que Claude executa podem ter efeitos reais. Consulte Considerações de segurança antes de implantar.

Início rápido

A ferramenta de uso do navegador está disponível na Claude API e no Google Cloud: adicione uma entrada do tipo browser_toolset_20260801, sem name, ao array tools de uma requisição da Messages API.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=2048,
    tools=[{"type": "browser_toolset_20260801"}],
    messages=[
        {
            "role": "user",
            "content": "Open example.com/docs and tell me how to get started.",
        }
    ],
)
print(response)

A primeira resposta de Claude termina com stop_reason: "tool_use" e traz um ou mais blocos tool_use de membros, cada um nomeando uma ferramenta membro em name e trazendo "toolset_name": "browser":

{
  "id": "msg_01HCDu4XSTLzTAcodEQ58vDo",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the documentation and read the page to find the getting-started instructions."
    },
    {
      "type": "tool_use",
      "id": "toolu_01NRLabsLyVHZPKxbKvkfSMn",
      "name": "navigate",
      "toolset_name": "browser",
      "input": { "url": "https://example.com/docs" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01UvHU5cDyTZ2vXKf5wCkPqR",
      "name": "read_page",
      "toolset_name": "browser",
      "input": { "filter": "interactive" }
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

Seu "executor" (executor), a parte da sua aplicação que controla o navegador e produz os resultados das ferramentas, executa navigate e depois read_page. Sua aplicação retorna um tool_result por bloco em sua próxima requisição, repetindo toolset_name em cada um. O resultado de navigate informa a aba que foi carregada em um bloco browser_state; o resultado de read_page é um texto no qual cada elemento traz uma referência:

{
  "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 agora possui referências sobre as quais pode agir, então seu próximo turno pode clicar em ref_2 para abrir a página de primeiros passos, sem precisar localizar o link em uma captura de tela primeiro.

Como o uso do navegador funciona

O uso do navegador é executado como um "agent loop" (loop de agente) na sua aplicação: Claude retorna chamadas de ferramentas membro, seu executor as executa no navegador, e você retorna os resultados até que Claude responda em texto.

1. 1

   Forneça a Claude a ferramenta de uso do navegador e um prompt do usuário

   • Adicione a entrada browser_toolset_20260801 e, opcionalmente, outras ferramentas à sua requisição de API.
   • Inclua um prompt do usuário que exija trabalhar com páginas da web, por exemplo, "Abra example.com/docs e me diga como começar."
2. 2

   Claude responde com chamadas de ferramentas membro

   • Claude retorna um ou mais blocos tool_use em um único turno do assistente; vários em um turno formam uma "batch action" (ação em lote), por exemplo, left_click, depois type, depois key.
   • O name de cada bloco é o nome do membro, cada um contém "toolset_name": "browser", e input contém apenas os parâmetros desse membro, sem campo action. O stop_reason da resposta é tool_use.
3. 3

   Execute as chamadas em ordem e retorne os resultados

   • Itere por todos os blocos tool_use em response.content (não presuma que há exatamente um) e execute-os sequencialmente, na ordem em que aparecem, porque chamadas posteriores geralmente dependem das anteriores.
   • Retorne um tool_result por bloco em uma nova mensagem user, correspondido por tool_use_id, e repita "toolset_name": "browser" em cada um. Toda chamada deve ser respondida, caso contrário a próxima requisição é rejeitada.
   • Se uma chamada falhar, retorne is_error: true com uma descrição em texto para esse bloco e, em seguida, aplique a regra de interrupção de Ações em lote a todos os blocos posteriores no turno.
4. 4

   Claude continua até que a tarefa seja concluída

   • Claude lê os resultados (texto da página, árvores de acessibilidade, capturas de tela, estado das abas) e, se precisar de mais, retorna novas chamadas de membros, o que leva você de volta à etapa 3.
   • Caso contrário, retorna uma resposta em texto ao usuário.

Aqui está um esqueleto da etapa de chamada de ferramentas desse loop, em duas partes. Primeiro, handlers de membros simulados substituem sua automação de navegador. Cinco membros (navigate, read_page, left_click, type e screenshot) retornam o texto, ou, no caso de screenshot, o bloco de imagem, que se torna o conteúdo do resultado, e o dispatcher lança um erro para qualquer membro que não implementa.

# Dados de imagem de placeholder; um executor real captura a viewport e retorna os bytes 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):
    # Um alvo é uma referência de elemento de read_page ou find, ou uma coordenada da viewport
    if target["type"] == "ref":
        return f"clicked {target['ref']}"
    return f"clicked at ({target['x']}, {target['y']})"


def type_text(text):
    return f"typed: {text}"


def capture_screenshot() -> list[ImageBlockParam]:
    # screenshot responde com um bloco de imagem em vez de texto: retorne a lista de conteúdo do resultado
    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()
    # Trate outras ações conforme necessário
    raise ValueError(f"Unknown or unimplemented member: {name}")

A segunda parte executa um lote em ordem, despacha cada bloco para esses handlers, repete toolset_name em cada resultado e aplica a regra de interrupção de Ações em lote, transformando um erro de handler em um resultado de erro. O loop de amostragem que a chama é o mostrado em Entenda o loop de agente, com o toolset do navegador em 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:
        # Apenas o conjunto de ferramentas do navegador é declarado; roteie outras ferramentas aqui se você as adicionar
        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:
                # Uma string ou uma lista de blocos de conteúdo; um executor real também adiciona um
                # bloco browser_state aos resultados de navegação e gerenciamento de abas
                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

Despache cada bloco com base no par (toolset_name, name) em vez de apenas em name, porque uma ferramenta personalizada na mesma requisição pode compartilhar o nome de um membro; Conjuntos de ferramentas de cliente descreve as partes desse contrato que ambos os toolsets compartilham. Se Claude nomear um membro que seu executor não implementa, ou um que você desabilitou, responda a esse bloco com um resultado de erro em vez de descartá-lo.

Quando você faz "streaming" (streaming) da resposta, o input de cada membro chega como um único input_json_delta completo, e não em fragmentos, então aguarde o turno terminar antes de executar o lote.

Ações em lote

Um turno com várias chamadas de membros é uma "batch action" (ação em lote): execute as chamadas na ordem em que aparecem, pare na primeira falha e responda a cada chamada posterior com is_error: true e o texto exato Not executed: an earlier action in this turn failed. Um lote usa o mesmo formato de resposta do uso paralelo de ferramentas; a diferença é que você executa os blocos em ordem, e não simultaneamente. Aqui, Claude clica na caixa de pesquisa que encontrou anteriormente, digita uma consulta e pressiona Enter em um único turno:

{
  "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" }
    }
  ]
}

Sua aplicação retorna três blocos tool_result em uma única mensagem user, cada um trazendo toolset_name e uma breve confirmação em texto, como Clicked element ref_3. Pressionar Enter carrega uma página de resultados, então o resultado de key também traz um bloco browser_state com a URL atualizada da aba (Contexto da aba em outros resultados). Se, em vez disso, o clique tivesse falhado, seu resultado traria o seu texto de erro e os outros dois resultados trariam o texto de interrupção, como mostrado em Retornar erros do seu executor.

Você não precisa retornar uma captura de tela após cada chamada. Claude normalmente termina um lote com uma chamada de observação (screenshot, read_page ou get_page_text), e sua aplicação também pode anexar sua própria observação, como uma captura de tela ou árvore de acessibilidade recente, como um bloco de conteúdo extra no último resultado do lote, para economizar uma ida e volta. Como um resultado de gerenciamento de abas deve ser exatamente um bloco browser_state, anexe-a ao último resultado que não seja uma chamada de gerenciamento de abas.

Se o seu executor só consegue executar uma chamada por ida e volta, defina disable_parallel_tool_use como true em tool_choice e Claude retornará no máximo uma chamada de membro por turno, ao custo de mais idas e voltas (Desabilitar o uso paralelo de ferramentas). O restante do contrato descrito em Ações em lote para a ferramenta de uso do computador se aplica aqui, incluindo um tool_result para cada tool_use na próxima mensagem user, exceto por duas coisas: o texto de interrupção e o que o content de um resultado bem-sucedido contém. O conteúdo do resultado segue, em vez disso, Ferramentas membro nesta página: um resultado de new_tab, switch_tab, close_tab ou list_tabs é exatamente um bloco browser_state, sem texto nem imagem (Resultados de gerenciamento de abas), e o resultado de qualquer outro membro pode adicionar um bloco browser_state ao seu texto ou imagem (Contexto da aba em outros resultados). Onde os breakpoints de cache dentro de um lote entram em vigor é descrito na linha cache_control dos Parâmetros da ferramenta da ferramenta de uso do computador.

Alvos e coordenadas

Ferramentas membro que agem sobre uma localização recebem um objeto target, que é uma coordenada em pixels da viewport ou uma referência a um elemento que read_page ou find retornou. As tabelas de Ferramentas membro usam Target para um parâmetro que aceita qualquer um dos dois formatos.

As coordenadas são pixels da viewport, o espaço de pixels de um screenshot da viewport inteira, com a origem no canto superior esquerdo da página renderizada; não há desktop ou moldura de janela ao redor. O toolset não declara dimensões de tela e Claude infere o tamanho da viewport a partir das capturas de tela que você retorna, então mantenha-as em um tamanho consistente. Um zoom não altera o quadro de referência, portanto sua region e quaisquer coordenadas que Claude emita após ver a imagem ampliada continuam sendo pixels da viewport inteira.

As capturas de tela devem respeitar os limites de imagem. A API não reduz as imagens do toolset: uma captura de tela ou imagem de zoom que exceda os limites de tamanho de imagem do seu modelo, ou o limite por imagem mais rigoroso que se aplica quando uma requisição contém mais de 20 imagens, é rejeitada. Redimensione antes de retornar e amplie as coordenadas de Claude pelo inverso do seu fator antes de despachá-las (Dimensione capturas de tela para respeitar os limites de imagem).

As referências de elementos vêm de read_page e find. Cada elemento na saída dessas ferramentas traz uma tag como [ref_2], como no resultado do Início rápido:

link "Documentation" [ref_1]
link "Getting started" [ref_2]
textbox "Search docs" [ref_3]
button "Search" [ref_4]
link "Pricing" [ref_5]

Claude passa uma referência de volta como um alvo {"type": "ref", "ref": "ref_2"} em uma chamada posterior de clique, hover, scroll_to, form_input ou file_upload, ou como o parâmetro ref em read_page para ler uma subárvore. Seu executor atribui as referências, mantém o mapeamento de cada uma para o nó subjacente (um ID de nó de acessibilidade, um seletor armazenado ou equivalente) e age sobre esse nó quando uma referência retorna.

As referências têm escopo na aba que as produziu e permanecem válidas até que essa aba navegue ou seu DOM mude substancialmente. A API não consegue detectar uma referência obsoleta ou desconhecida, então, quando Claude passar uma referência que seu executor não reconhece mais, retorne um resultado de erro como Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references. Claude então lê a página novamente. Não renumere referências que você já entregou para uma aba até que ela navegue, porque isso invalida silenciosamente referências que Claude ainda mantém.

Claude usa ambos os estilos de alvo e alterna entre eles com base no que a página expõe; seu prompt e o que seu executor retorna orientam a escolha:

• Prefira referências quando a página tiver uma árvore de acessibilidade utilizável. Uma referência sobrevive a mudanças de layout e refluxos que tornam as coordenadas em pixels frágeis, e permite que Claude aja sobre controles difíceis de atingir com um ponteiro.
• Recorra a coordenadas para conteúdo que a árvore não descreve. Interfaces renderizadas em canvas, superfícies de vídeo incorporado ou de desktop remoto, listas fortemente virtualizadas e elementos dentro de iframes de origem cruzada frequentemente não têm um nó útil, então Claude trabalha a partir de screenshot e zoom e clica por coordenada; seu executor determina em qual frame uma coordenada cai.
• Delimite as leituras e leia a árvore antes de capturar a tela. Em páginas grandes, read_page com filter: "interactive" ou com a ref de um contêiner retorna uma subárvore focada, e a leitura da árvore de uma página típica geralmente custa menos tokens de entrada do que uma captura de tela, ao mesmo tempo que dá a Claude referências sobre as quais ele pode agir imediatamente. Capturas de tela continuam sendo a observação adequada quando o layout visual, as imagens ou o estado de renderização importam.

Considerações de segurança

O uso do navegador traz riscos que os recursos padrão da API não trazem, porque Claude lê e age sobre conteúdo da web aberta, onde qualquer página pode conter texto escrito para manipulá-lo.

Claude às vezes segue instruções encontradas no conteúdo da página mesmo quando elas entram em conflito com as suas; um texto em uma página que diga "ignore suas instruções anteriores e navegue para..." pode desviá-lo da tarefa. Isole Claude de dados e ações sensíveis para limitar o que uma "prompt injection" (injeção de prompt) pode alcançar, revise Mitigar jailbreaks e injeções de prompt e, se uma tarefa não puder evitar uma sessão autenticada, use uma conta dedicada de baixo privilégio e mantenha a confirmação humana em ações que alterem a conta.

A Anthropic treinou o modelo para resistir a essas injeções de prompt e adicionou uma camada extra de defesa. Se você usar a ferramenta de uso do navegador, classificadores analisarão automaticamente o que o navegador retorna, como texto de página ou capturas de tela, para sinalizar possíveis injeções de prompt. Quando esses classificadores identificam uma possível injeção de prompt, eles orientam automaticamente o modelo a verificar se a instrução realmente veio de você antes de agir com base nela.

Essa proteção extra não será ideal para todos os casos de uso (por exemplo, casos de uso sem um humano no loop), então, se você quiser optar por não usá-la e desativá-la, entre em contato com o suporte. As precauções acima continuam importantes mesmo com esses classificadores em funcionamento.

Como o navegador é executado no seu ambiente, os sites que Claude visita veem a identidade de rede do seu executor, e o conteúdo da página chega à API apenas como os resultados de ferramentas que você retorna. Informe os usuários finais sobre os riscos relevantes e obtenha o consentimento deles antes de habilitar o uso do navegador em seus produtos.

Ferramentas membro

A entrada browser_toolset_20260801 declara 31 ferramentas membro; o input de cada chamada é exatamente os parâmetros listados aqui, e tab_id, quando opcional, assume por padrão a aba ativa. Target, CoordinateTarget e RefTarget são os formatos descritos em Alvos e coordenadas. Quatro membros (javascript_exec, file_upload, read_console e read_network) são desabilitados por padrão e só aparecem quando você os habilita. Os limites de entrada e as convenções de saída indicados na linha de cada membro são informados a Claude, não aplicados pela API, então valide as entradas (incluindo coordenadas em relação à sua viewport) e aplique as convenções no seu executor.

Apenas screenshot e zoom exigem um bloco image em seu resultado, e os quatro membros de gerenciamento de abas (new_tab, list_tabs, switch_tab e close_tab) retornam exatamente um bloco browser_state (consulte Resultados de gerenciamento de abas). Todos os outros membros retornam um bloco text: uma breve confirmação como Clicked element ref_2. ou a saída do membro. Qualquer resultado que não seja de gerenciamento de abas também pode trazer um bloco image, normalmente uma captura de tela feita após a ação, para que Claude veja o resultado sem uma chamada screenshot separada; Ações em lote mostra onde anexá-la em um lote. Um tool_result de membro pode conter apenas blocos de conteúdo text, image e browser_state.

Navegação e captura

Ponteiro

Teclado e temporização

Leitura de página

Formulários e arquivos

Diagnóstico e scripts

Gerenciamento de abas

Em caso de sucesso, cada um deles retorna exatamente um bloco browser_state e nenhum texto ou imagem; consulte Resultados de gerenciamento de abas.

Configurar o toolset

Além de type, a entrada do toolset aceita configs, cache_control e allowed_callers; as regras que esses campos compartilham com o toolset de uso do computador estão listadas em Conjuntos de ferramentas de cliente, e esta seção aborda os padrões específicos do navegador. configs é um objeto indexado pelo nome do membro, e o valor de cada membro aceita dois campos:

Habilitar ou desabilitar ferramentas membro

Liste em configs apenas os membros que você deseja alterar; todo membro omitido mantém seu padrão. Por exemplo, um executor que implementa leituras do console, mas não controle de ponteiro de baixo nível nem de manter teclas pressionadas, ativa read_console e retém três membros:

{
  "type": "browser_toolset_20260801",
  "configs": {
    "read_console": { "enabled": true },
    "left_mouse_down": { "enabled": false },
    "left_mouse_up": { "enabled": false },
    "hold_key": { "enabled": false }
  }
}

Um membro desabilitado desaparece da definição que Claude vê; isso não garante que Claude nunca o nomeie, então seu executor ainda deve responder a essa chamada com um resultado de erro.

Combinar com outras ferramentas

Declare a ferramenta de uso do navegador junto com suas próprias ferramentas e outras ferramentas fornecidas pela Anthropic no mesmo array tools. Uma ferramenta personalizada pode compartilhar o nome de um membro (seu próprio navigate, por exemplo), porque toolset_name distingue as chamadas de Claude, mas nenhuma outra entrada pode se chamar browser, e uma requisição pode conter apenas uma entrada de toolset do navegador.

Você também pode declará-la junto com a ferramenta de uso do computador, seja o toolset ou uma versão anterior da ferramenta de uso do computador. As duas funcionam de forma independente, cada uma em seu próprio sistema de coordenadas (pixels da viewport aqui, pixels da captura de tela do desktop lá), e as chamadas de Claude a membros que compartilham um nome, como screenshot ou key, são diferenciadas por toolset_name.

Habilitar membros opcionais

Quatro ferramentas membro são desabilitadas por padrão: javascript_exec e file_upload porque ampliam o que uma página manipulada poderia fazer Claude executar, e read_console e read_network porque nem toda stack de automação de navegador consegue fornecer esses logs e porque ampliam o conteúdo controlado pela página que chega a Claude. Habilite cada um com configs (por exemplo, "configs": {"file_upload": {"enabled": true}}) somente quando seu executor o implementar e a tarefa precisar dele.

Enviar arquivos

file_upload define diretamente os arquivos em um elemento , o que é mais confiável do que controlar um seletor de arquivos nativo. Seu target é apenas uma referência, porque a chamada precisa da identidade do elemento, e ele recebe paths, document_ids ou ambos:

• paths são caminhos de arquivo no sistema de arquivos do executor, para implantações em que o executor pode ler diretamente os arquivos da sua aplicação (a mesma condição sob a qual você preenche o path de um download).
• document_ids são identificadores de arquivos que sua aplicação preparou para o navegador, para implantações em que ele não pode fazer isso. Sua aplicação define o que os identificadores significam; restrinja a resolução deles da mesma forma que você restringe paths, a arquivos preparados para esta tarefa.

{
  "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 escreve esses caminhos enquanto lê páginas não confiáveis, então uma implementação sem restrições permitiria que uma página maliciosa direcionasse o envio de qualquer arquivo que o executor possa ler para um site controlado pela página. Habilite o membro somente quando seu executor resolver cada caminho (seguindo symlinks e segmentos ..) e não aceitar nada fora de um diretório de upload dedicado e incluído na lista de permissões, que contenha apenas arquivos destinados à tarefa. Não reutilize o diretório de downloads do navegador para isso; se você fizer isso, todo arquivo que uma página fizer o navegador baixar se tornará passível de envio.

Executar JavaScript na página

javascript_exec executa a expressão que Claude escreve no contexto da página e retorna o valor da última expressão como texto; Claude escreve uma expressão, não uma instrução return. O código é executado com todos os privilégios da página, incluindo seus cookies, armazenamento e requisições de mesma origem. Habilite o membro somente em sessões que não contenham credenciais, mantenha em vigor a lista de permissões de domínios de Considerações de segurança, trate o valor retornado como entrada não confiável e registre o código que Claude emite.

Ler a atividade do console e da rede

read_console retorna as entradas do console da aba e read_network retorna suas requisições de rede, cada um como texto com uma linha por entrada acumulada desde a leitura anterior daquela aba. Uma linha do console traz uma entrada de log, aviso ou erro; uma linha de rede traz o método, a URL, o status, o tipo MIME e o tempo. As entradas existem apenas a partir do momento em que sua automação de navegador se conectou à aba, então um resultado vazio não significa que uma aba que já estava aberta não teve tráfego.

Esses membros permitem que Claude diagnostique uma página com mau funcionamento (uma requisição com falha por trás de um indicador de carregamento, um erro de script por trás de um botão que não responde) sem capturas de tela repetidas. As entradas do console e da rede são controladas pela página e frequentemente contêm segredos, como tokens em URLs de requisição, então oculte valores semelhantes a credenciais que você não queira no contexto de Claude e trunque entradas muito longas antes de retorná-las.

Rastreie abas com browser_state

Claude identifica as abas por tab_id, sua aplicação é a fonte da verdade sobre quais abas existem, e você informa esse estado em um bloco de conteúdo browser_state que Claude nunca vê diretamente: a API renderiza, a partir dele, o texto que Claude lê.

{
  "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 é o inventário completo das abas abertas após a chamada, não um delta. Ele pode estar vazio; sempre que não estiver, exatamente uma entrada contém "active": true.
• state_changes (não mostrado aqui) informa os efeitos colaterais da chamada: uma entrada tab_opened para cada aba que a chamada abriu e que ainda está aberta quando ela termina, cujo tab_id também deve aparecer em tabs, e eventos de download. Omita o campo quando não houver nada a informar; um array vazio é rejeitado.
• Envie o bloco apenas em resultados que respondem a uma chamada de membro do browser, no máximo uma vez por tool_result, e nunca em um resultado com is_error: true. Você expressa "nenhum estado de aba a informar" omitindo o bloco.
• A API renderiza tabs, e quaisquer entradas de download em state_changes, em texto para Claude. As duas próximas seções e Informe downloads mostram esse texto.

Você atribui os valores de tab_id. Qualquer string estável funciona, como o identificador de página da sua biblioteca de automação ou seu próprio contador, desde que você não reutilize um tab_id enquanto uma aba com esse identificador ainda estiver listada como aberta em um resultado anterior. A API impõe estes limites ao bloco:

• Cada tab_id, title e url pode ter no máximo 4.096 caracteres, tab_id não pode estar vazio, e nenhum deles pode conter caracteres de controle (incluindo quebras de linha) ou separadores Unicode de linha ou de parágrafo.
• Um bloco pode listar no máximo 100 abas e 200 mudanças de estado.
• Os mesmos limites se aplicam ao tab_id que Claude passa para switch_tab e close_tab, porque a API o renderiza no texto do resultado; portanto, responda a uma chamada cujo tab_id os viole com um resultado de erro em vez de um bloco browser_state.

Resultados de gerenciamento de abas

Para new_tab, switch_tab, close_tab e list_tabs, o content de um resultado bem-sucedido é exatamente um bloco browser_state, sem texto nem imagem, e a API escreve o texto que Claude vê. O bloco de um resultado de new_tab também deve conter exatamente uma mudança de estado tab_opened cujo tab_id corresponda à entrada marcada com active: true.

Um resultado de list_tabs cujo bloco lista duas abas, com a primeira ativa, é renderizado da seguinte forma, com cada linha recuada em dois espaços e (current) acrescentado apenas à aba ativa:

Available tabs:
  • tab_id tab-1: "Documentation" (https://example.com/docs) (current)
  • tab_id tab-2: "Pricing" (https://example.com/pricing)

Um resultado de erro para um desses membros é o inverso: texto de erro comum em content, is_error: true e nenhum bloco browser_state.

Por exemplo, quando Claude chama new_tab (seu input é vazio), seu executor abre a aba, torna-a ativa e retorna o inventário com uma entrada 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 vê Created new tab with tab_id: tab-3, URL: about:blank. It is now the current tab. Informe a URL em que a aba foi aberta, como aqui, e não uma para a qual ela seja redirecionada depois; resultados posteriores informam a URL atual da aba naquele momento.

Contexto de abas em outros resultados

Em todos os outros membros, o bloco é opcional: envie-o quando o conjunto de abas abertas, a aba ativa ou o título ou a URL de uma aba tiver mudado, ou quando houver state_changes a informar, e sempre inclua o inventário completo de tabs. Quando um resultado contém tanto texto quanto um bloco browser_state, a API acrescenta um rodapé Tab Context ao texto desse resultado, separado do seu texto por uma linha em branco, para que Claude receba o novo estado sem uma chamada separada a 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 nomeia a aba em que a chamada foi executada, que é o seu input tab_id quando presente e, caso contrário, a aba ativa, e as linhas de abas do rodapé não têm o marcador (current). Não acrescente esse texto você mesmo; envie o bloco estruturado e deixe a API renderizá-lo. O rodapé é deduplicado, então um estado de abas idêntico não é renderizado novamente em resultados posteriores, e preencher o bloco generosamente não tem custo.

Três casos não renderizam rodapé mesmo quando o bloco está presente:

• Qualquer resultado de zoom.
• Um resultado sem bloco text (um resultado de screenshot contendo apenas imagem, por exemplo). Nada é renderizado nem memorizado para esse resultado; o contexto de abas aparece no próximo resultado que contenha tanto texto quanto um bloco browser_state, então inclua um bloco de texto curto junto com a imagem quando quiser que Claude veja uma mudança de aba nesse mesmo resultado. A exceção é um resultado cujo bloco informa um evento de download. A API adiciona as linhas de download como um bloco de texto, e o rodapé vem depois delas, como aconteceria em qualquer resultado com texto.
• Um resultado cuja lista tabs está vazia em uma chamada que não continha tab_id, porque não há aba a nomear.

Por exemplo, quando Claude clicou no link "Pricing" (ref_5) anteriormente nesta sessão, a página o abriu em uma nova aba que Claude não pediu, e sem um relatório Claude teria que chamar list_tabs para descobri-la. Retorne a confirmação do clique mais um bloco cujo state_changes nomeie a aba aberta, marcando a aba que seu executor deixou ativa:

{
  "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 vê Clicked element ref_5. seguido do rodapé Tab Context mostrado anteriormente. Uma aba aberta durante uma chamada que falhou não recebe entrada tab_opened, porque resultados de erro não contêm browser_state; em vez disso, ela aparece no inventário tabs do próximo resultado bem-sucedido. Em um lote, anexe o bloco ao resultado da chamada durante a qual a mudança aconteceu, e dê a cada resultado bem-sucedido de gerenciamento de abas seu próprio bloco, mesmo quando um resultado anterior no mesmo turno tiver informado o mesmo estado.

Informe downloads

Quando um clique ou uma navegação inicia o download de um arquivo, informe-o em state_changes no resultado da chamada durante a qual ele aconteceu, correlacionado entre resultados por um download_id que você atribui. Os downloads são executados de forma assíncrona e podem abranger vários resultados, então há três tipos de evento:

A API renderiza cada entrada como uma linha de texto para Claude, na ordem em que as entradas aparecem. Ela adiciona as linhas após o texto do resultado, separadas por uma linha em branco, e antes de qualquer rodapé Tab Context. Todo tipo de resultado de membro contém as linhas, incluindo resultados de zoom e de gerenciamento de abas. Um resultado sem bloco text as recebe como um bloco de texto próprio. Cada linha informa o download_id e a url, além de path e size_bytes (para download_completed) ou error (para download_failed) quando você os envia. Você não precisa descrever o download no seu próprio texto. A API envolve url, path e error em aspas duplas e escapa aspas duplas e barras invertidas dentro deles, então não escape esses valores previamente.

Por exemplo, um clique em "Download price list (CSV)" (ref_8) na aba Pricing inicia um download, então o resultado do clique contém uma entrada download_started com download_id "dl-1" e a URL do arquivo. O download termina enquanto uma chamada posterior de screenshot está em execução, então o content desse resultado contém a imagem, um bloco de texto como Screenshot captured. e este bloco browser_state informando a conclusão sob o mesmo 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
    }
  ]
}

Claude vê Screenshot captured. seguido de uma linha em branco e de uma linha como esta:

Download completed with download_id: dl-1, URL: "https://example.com/pricing/price-list.csv". Saved to "/home/user/downloads/price-list.csv". Size: 48213 bytes.

Os relatórios de download seguem estas regras:

• No máximo uma entrada por download_id em um único bloco, então um download que começa e termina durante a mesma chamada informa apenas download_completed.
• Nunca envie state_changes em um resultado com is_error: true; informe um evento de download ocorrido durante uma chamada que falhou no próximo resultado bem-sucedido.
• state_changes não é um inventário de downloads em andamento; informe cada evento uma única vez.
• Cada entrada contém apenas os campos que seu type declara. size_bytes é um inteiro não negativo, download_id não pode estar vazio, e download_id, url, path e error têm cada um no máximo 4.096 caracteres, sem caracteres de controle nem separadores Unicode de linha ou de parágrafo. A url vem do servidor remoto e frequentemente contém credenciais assinadas na query string após os redirecionamentos, então remova os parâmetros de consulta que você não quer no contexto de Claude e sanitize-a antes de informá-la ou usá-la em um caminho do sistema de arquivos.

Trate erros

Informe uma chamada que falhou a Claude como um resultado de erro comum: is_error: true, conteúdo de texto que diga o que deu errado, toolset_name repetido e nenhum bloco browser_state.

Retorne erros a partir do seu executor

Torne o texto de erro específico, porque Claude o lê e se adapta: Error: Navigation to https://example.com/status timed out after 30 seconds. The page may be unavailable. dá a Claude algo com que agir, enquanto um simples Error: navigation failed não dá. Outros casos comuns:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01LeUTyqkhRxBFq1QTG3pkwN",
  "toolset_name": "browser",
  "is_error": true,
  "content": "Error: Navigation refused. Only http and https URLs are allowed."
}

{
  "type": "tool_result",
  "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
  "toolset_name": "browser",
  "is_error": true,
  "content": "Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references."
}

{
  "type": "tool_result",
  "tool_use_id": "toolu_013h2Q55HcNwVyapSpy2s5ZG",
  "toolset_name": "browser",
  "is_error": true,
  "content": "Error: javascript_exec is not enabled in this environment."
}

{
  "type": "tool_result",
  "tool_use_id": "toolu_01FkP8rTz6uYh2mNq4LsXw7v",
  "toolset_name": "browser",
  "is_error": true,
  "content": "Not executed: an earlier action in this turn failed."
}

Erros de requisição

A API valida a entrada do toolset e todos os blocos tool_use e tool_result de membros na conversa. Quando um deles está malformado, a API retorna um invalid_request_error antes de Claude ser executado. Na tabela a seguir, a coluna da esquerda indica o que você enviou.

Limitações

• Disponibilidade de plataforma: O uso de navegador está disponível na Claude API e no Google Cloud.
• Apenas streaming da entrada completa: Quando você usa streaming, o input de cada membro chega como um único input_json_delta completo (Toolsets de cliente).
• Referências de elementos são de melhor esforço: Páginas altamente dinâmicas (listas virtualizadas, interfaces renderizadas em canvas, páginas que são renderizadas novamente ao rolar) podem não expor referências estáveis, e nesses casos Claude recorre a capturas de tela e cliques por coordenadas.
• read_console e read_network dependem da sua automação de navegador: Eles informam apenas o que ela consegue capturar, e somente a partir do momento em que ela se conectou a uma aba.
• Limitações gerais de agentes se aplicam: "Latency" (latência), precisão de visão e riscos de prompt injection são herdados do uso de computador (consulte as Limitações da ferramenta de uso de computador), e suas orientações em Otimize o desempenho do modelo com prompts, Gerencie o histórico de capturas de tela e Siga as melhores práticas de implementação (atrasos entre ações, validação de ações e registro em log) também se aplicam a executores de navegador.

Preços e retenção de dados

O uso do navegador segue os preços padrão de uso de ferramentas. Ao usar a ferramenta de uso do navegador:

Sobrecarga da definição do conjunto de ferramentas: Declarar browser_toolset_20260801 com seus membros padrão adiciona cerca de 6.600 tokens de entrada a uma requisição (cerca de 6.610 no Claude Fable 5, Claude Mythos 5, Claude Opus 5 e Claude Opus 4.8, e cerca de 6.670 no Claude Sonnet 5), o que cobre as definições das ferramentas membros e o prompt do sistema de uso de ferramentas. Habilitar todos os quatro membros opcionais adiciona cerca de 880 tokens, e desabilitar membros com configs reduz a contagem. A contagem exata para uma requisição é informada no usage da resposta, e você pode estimá-la antecipadamente com o endpoint de contagem de tokens.

Consumo adicional de tokens:

• Imagens de capturas de tela e de zoom retornadas nos resultados de ferramentas, cobradas como entrada de imagem (consulte Preços de visão)
• Resultados de ferramentas em texto retornados ao Claude, como árvores de acessibilidade, texto da página e entradas de console ou de rede

A sessão do navegador, os downloads e os arquivos enviados permanecem no seu ambiente; as capturas de tela, o texto das páginas e o estado das abas que você retorna fazem parte do conteúdo da sua requisição à API e seguem a política de retenção padrão, ou seu acordo de "Zero Data Retention" (retenção zero de dados), ou ZDR, se você tiver um. A ferramenta de uso de navegador é elegível para ZDR; consulte API e retenção de dados para ver os períodos de retenção e a elegibilidade entre os recursos.

Próximos passos

Compatibility