Ferramenta de uso do navegador

A "browser use tool" (ferramenta de uso do navegador) permite que Claude navegue, leia e interaja com páginas web em um navegador que sua aplicação executa. Ela 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 pixels (capturas de tela e coordenadas da viewport), enquanto a ferramenta de uso do computador trabalha com uma área de trabalho inteira apenas por meio de capturas de tela e coordenadas. É um conjunto de ferramentas do cliente ("client toolset") definido pela Anthropic: uma entrada browser_toolset_20260801 no seu array tools dá a Claude 27 ferramentas membro por padrão, como navigate, read_page, left_click e screenshot, mais quatro outras (javascript_exec, file_upload, read_console e read_network) quando você as habilita. Sua aplicação executa cada chamada contra sua própria automação de navegador; nada é executado do lado da Anthropic. Atualmente ela não está disponível no Claude Managed Agents. Esta página diz "sua aplicação" para o loop de agente que chama a Messages API e "seu executor" para a parte dele que controla o navegador e produz os resultados das ferramentas.

Escolha o uso do navegador em vez do uso do computador quando a tarefa permanece dentro de páginas web: Claude pode ler a estrutura de uma página, agir sobre um elemento por referência além de por coordenada, definir valores de formulário diretamente e trabalhar entre abas, e você não precisa executar uma área de trabalho. Se Claude só precisa ler páginas que você pode indicar a ele, ou encontrar fontes na web, a ferramenta web fetch e a ferramenta web search são ainda mais leves, porque são ferramentas de servidor que a API executa para você sem nenhum navegador para operar. Escolha o uso do navegador, em vez delas, quando as páginas constroem seu conteúdo com JavaScript ou quando a tarefa significa agir sobre a página em vez de apenas lê-la.

Com o uso do navegador, Claude lê e age sobre páginas web ao vivo, 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",
    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",
  "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 executa navigate, depois read_page, e sua aplicação retorna um tool_result por bloco na próxima requisição, repetindo toolset_name em cada um. O resultado de navigate informa a aba que carregou em um bloco browser_state; o resultado de read_page é 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 necessidade de localizar o link em uma captura de tela primeiro.

Como funciona o uso do navegador

O uso do navegador é executado como um loop de agente: Claude retorna chamadas de ferramentas membro, seu executor as executa contra o 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 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 ação em lote, por exemplo, left_click, depois type, depois key.
   • O name de cada bloco é o nome do membro, cada um traz "toolset_name": "browser", e input contém apenas os parâmetros daquele membro, sem campo action. O stop_reason da resposta é tool_use.
3. 3

   Execute as chamadas em ordem e retorne os resultados

   • Itere sobre cada bloco 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 ou a próxima requisição é rejeitada.
   • Se uma chamada falhar, retorne is_error: true com uma descrição em texto para aquele bloco, depois aplique a regra de interrupção em Ações em lote a cada bloco posterior no turno.
4. 4

   Claude continua até que a tarefa esteja 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 ao passo 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 (stubs) substituem sua automação de navegador. Cinco membros (navigate, read_page, left_click, type e screenshot) retornam o texto, ou para 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 conjunto de ferramentas 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 pelo par (toolset_name, name) em vez de apenas por name, porque uma ferramenta personalizada na mesma requisição pode compartilhar o nome de um membro; Conjuntos de ferramentas do cliente descreve as partes desse contrato que ambos os conjuntos de ferramentas 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 da resposta, o input de cada membro chega como um único input_json_delta completo em vez de 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 que o uso paralelo de ferramentas; a diferença é que você executa os blocos em ordem em vez de concorrentemente. Aqui Claude clica na caixa de busca 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 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 de aba em outros resultados). Se, em vez disso, o clique tivesse falhado, seu resultado traria seu texto de erro e os outros dois resultados trariam o texto de interrupção, como mostrado em Retorne erros do seu executor.

Você não precisa retornar uma captura de tela após cada chamada. Claude normalmente encerra 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 recente ou árvore de acessibilidade, 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 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 em Ações em lote para a ferramenta de uso do computador se aplica, 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 Ferramentas membro nesta página: um resultado de new_tab, switch_tab, close_tab ou list_tabs é exatamente um bloco browser_state sem texto ou 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 de aba em outros resultados). Onde os pontos de interrupção 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 escrevem Target para um parâmetro que aceita qualquer um dos formatos.

Coordenadas são pixels da viewport, o espaço de pixels de um screenshot de viewport inteira com a origem no canto superior esquerdo da página renderizada; não há área de trabalho ou moldura de janela ao redor. O conjunto de ferramentas 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 muda o quadro de referência, então sua region e quaisquer coordenadas que Claude emita após ver a imagem ampliada ainda são pixels da viewport inteira.

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

Referências de elementos vêm de read_page e find. Cada elemento na saída deles 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 materialmente. A API não consegue detectar uma referência obsoleta ou desconhecida, então quando Claude passa 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 possui.

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 onde a página tem uma árvore de acessibilidade utilizável. Uma referência sobrevive a mudanças de layout e reflows que tornam coordenadas em pixels frágeis, e permite que Claude aja sobre controles difíceis de acertar com um ponteiro.
• Recorra a coordenadas para conteúdo que a árvore não descreve. Interfaces renderizadas em canvas, vídeo incorporado ou superfícies de área de trabalho remota, listas fortemente virtualizadas e elementos dentro de iframes de origem cruzada frequentemente não têm nó útil, então Claude trabalha a partir de screenshot e zoom e clica por coordenada; seu executor resolve 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 o ref de um contêiner retorna uma subárvore focada, e uma leitura da árvore de uma página típica frequentemente custa menos tokens de entrada do que uma captura de tela, ao mesmo tempo que dá a Claude referências sobre as quais pode agir imediatamente. Capturas de tela continuam sendo a observação correta quando layout visual, imagens ou 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 conflitam 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 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.

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 nos 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, onde 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 aparecem apenas quando você os habilita. Os limites de entrada e as convenções de saída indicados na linha de cada membro são declarados 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 tirada após a ação, para que Claude veja o resultado sem uma chamada screenshot separada; Ações em lote mostra onde anexar uma 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 destes retorna exatamente um bloco browser_state e nenhum texto ou imagem; consulte Resultados de gerenciamento de abas.

Configure o conjunto de ferramentas

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

Habilite ou desabilite ferramentas membro

Liste em configs apenas os membros que você deseja alterar; todo membro que você omitir mantém seu padrão. Por exemplo, um executor que implementa leituras de console, mas não controle de ponteiro de baixo nível ou 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 responde a tal chamada com um resultado de erro.

Combine 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 conjunto de ferramentas do navegador.

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

Habilite 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 pilha de automação de navegador consegue fornecer esses logs e eles ampliam o conteúdo controlado pela página que chega a Claude. Habilite cada uma com configs (por exemplo, "configs": {"file_upload": {"enabled": true}}) apenas quando seu executor a implementa e a tarefa precisa dela.

Envie arquivos

file_upload define os arquivos em um elemento <input type="file"> diretamente, 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 arquivos no sistema de arquivos do executor, para implantações em que o executor pode ler os arquivos da sua aplicação diretamente (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. Sua aplicação define o que os identificadores significam; delimite a resolução deles da mesma forma que você delimita 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 que a página controla. Habilite o membro apenas quando seu executor resolve cada caminho (seguindo links simbólicos e segmentos ..) e não aceita nada fora de um diretório de envio 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 o fizer, todo arquivo que uma página faça o navegador baixar se torna enviável.

Execute 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 os privilégios completos da página, incluindo seus cookies, armazenamento e requisições de mesma origem. Habilite o membro apenas 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 em log o código que Claude emite.

Leia 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 uma como texto com uma linha por entrada acumulada desde a leitura anterior daquela aba. Uma linha de console traz uma entrada de log, aviso ou erro; uma linha de rede traz o método, URL, status, tipo MIME e 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 comportamento (uma requisição com falha por trás de um indicador de carregamento, um erro de script por trás de um botão inoperante) sem capturas de tela repetidas. As entradas de console e de 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 quer no contexto de Claude e trunque entradas muito longas antes de retorná-las.

Rastreie abas com browser_state

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

{
  "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 de abas abertas após a chamada, não um delta. Pode estar vazio; sempre que não estiver, exatamente uma entrada carrega "active": true.
• state_changes (não mostrado aqui) reporta 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 reportar; um array vazio é rejeitado.
• Envie o bloco apenas em resultados que respondem a uma chamada de membro do navegador, no máximo uma vez por tool_result, e nunca em um resultado com is_error: true. Você expressa "nenhum estado de aba a reportar" omitindo o bloco.
• A API renderiza tabs em texto para Claude conforme as duas próximas seções descrevem; entradas de download em state_changes são validadas, mas não renderizadas.

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 deve ser não vazio, e nenhum pode conter caracteres de controle (incluindo quebras de linha) ou separadores de linha ou parágrafo Unicode.
• 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 ou imagem, e a API escreve o texto que Claude vê. O bloco de um resultado de new_tab também deve carregar 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 indentada com dois espaços e (current) anexado 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, a torna 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. Reporte a URL em que a aba foi aberta, como aqui, não uma para a qual ela redireciona depois; resultados posteriores reportam a URL então atual da aba.

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 URL de uma aba mudou, ou quando houver state_changes a reportar, e sempre inclua o inventário completo de tabs. Quando um resultado carrega tanto texto quanto um bloco browser_state, a API anexa 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 de 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 é seu input tab_id quando presente e, caso contrário, a aba ativa, e as linhas de aba do rodapé não carregam marcador (current). Não anexe 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 custa nada.

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 apenas com imagem, por exemplo). Nada é renderizado ou lembrado para esse resultado; o contexto de abas aparece no próximo resultado que carregar tanto texto quanto um bloco browser_state, então inclua um bloco de texto curto junto à imagem quando quiser que Claude veja uma mudança de aba nesse mesmo resultado.
• Um resultado cuja lista tabs está vazia em uma chamada que não carregava 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 solicitou, 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 nomeia a aba aberta, marcando qualquer aba que seu executor tenha deixado 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 carregam browser_state; 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 reportou o mesmo estado.

Reporte downloads

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

A API valida essas entradas, mas não as renderiza em texto que Claude vê, então quando Claude precisar agir sobre o arquivo, mencione também o nome do arquivo ou o path no bloco text do mesmo resultado.

Por exemplo, um clique em "Download price list (CSV)" (ref_8) na aba Pricing inicia um download, então o resultado do clique carrega 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. Download complete: /home/user/downloads/price-list.csv (48,213 bytes)., e este bloco browser_state reportando 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
    }
  ]
}

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 reporta apenas download_completed.
• Nunca envie state_changes em um resultado com is_error: true; reporte um evento de download que ocorreu durante uma chamada com falha no próximo resultado bem-sucedido.
• state_changes não é um inventário de downloads em andamento; reporte cada evento uma vez.
• Cada entrada carrega apenas os campos que seu type declara. size_bytes é um inteiro não negativo, download_id é não vazio, e download_id, url, path e error têm cada um no máximo 4.096 caracteres, sem caracteres de controle ou separadores de linha ou parágrafo Unicode. A url vem do servidor remoto e frequentemente carrega credenciais assinadas na query string após redirecionamentos, então remova parâmetros de query que você não quer no contexto de Claude e sanitize-a antes de reportá-la ou usá-la em um caminho do sistema de arquivos.

Trate erros

Reporte uma chamada com falha a Claude como um resultado de erro comum: is_error: true, conteúdo de texto que diz o que deu errado, toolset_name ecoado e nenhum bloco browser_state.

Retorne erros 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 sobre o 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 cada bloco tool_use e tool_result de membro na conversa. Quando um está malformado, a API retorna um invalid_request_error antes de Claude ser executado. Na tabela a seguir, a coluna da esquerda nomeia 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 de input completo: Quando você usa streaming, o input de cada membro chega como um único input_json_delta completo (Toolsets de cliente).
• Referências de elemento são de melhor esforço: Páginas altamente dinâmicas (listas virtualizadas, interfaces renderizadas em canvas, páginas que re-renderizam ao rolar) podem não expor referências estáveis, e Claude recorre a capturas de tela e cliques por coordenadas nesses casos.
• read_console e read_network dependem da sua automação de navegador: Eles reportam apenas o que ela consegue capturar, e apenas a partir do momento em que ela se anexou a uma aba.
• Limitações gerais de agentes se aplicam: "Latency" (latência), precisão de visão e riscos de injeção de prompt 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 prompting, Gerencie o histórico de capturas de tela e Siga as melhores práticas de implementação (atrasos de ação, validação de ação e logging) 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 de página e o estado de abas que você retorna fazem parte do conteúdo da sua requisição de API e seguem a política de retenção padrão, ou seu acordo de ZDR se você tiver um. A ferramenta de uso de navegador é elegível para ZDR; consulte API e retenção de dados para períodos de retenção e elegibilidade entre recursos.

Próximos passos

Compatibility