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 ("screenshots" (capturas de tela) e coordenadas do 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 client toolset (conjunto de ferramentas de cliente) definido pela Anthropic: uma entrada browser_toolset_20260801 no seu array tools dá a Claude 27 "member tools" (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 em 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 "agent loop" (loop de agente) que chama a Messages API e "seu executor" para a parte dele que controla o navegador e produz resultados de 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, ou encontrar fontes na web, a ferramenta de web fetch e a ferramenta de 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 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, então tudo o que uma página fornece é entrada não confiável e as ações que Claude realiza 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 sem cabeçalho beta: 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 carrega um ou mais blocos tool_use de membros, cada um nomeando uma ferramenta membro em name e carregando "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 em sua próxima requisição, ecoando 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 carrega 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 o uso do navegador funciona

O uso do navegador é executado como um loop de agente: Claude retorna chamadas de ferramentas membro, seu executor as executa no navegador, e você retorna os resultados até que Claude responda em texto.

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 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, ecoa 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; Client toolsets 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 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 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 carregando 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 carrega um bloco browser_state com a URL atualizada da aba (Contexto de aba em outros resultados). Se o clique tivesse falhado, seu resultado carregaria seu texto de erro e os outros dois resultados carregariam 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 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 nova 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 retorna 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 do 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 do viewport, o espaço de pixels de um screenshot de viewport completo 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 exibição e Claude infere o tamanho do 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 do viewport completo.

Capturas de tela devem caber nos 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 caber nos limites de imagem).

Referências de elementos vêm de read_page e find. Cada elemento em sua saída carrega 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.

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 de pixel 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 de árvore de uma página típica frequentemente custa menos tokens de entrada do que uma captura de tela, enquanto 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 carrega riscos que recursos padrão da API não carregam, 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; texto em uma página que diz "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 alteram contas.

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 seu consentimento 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, 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) estão desabilitados por padrão e aparecem apenas quando você os habilita. Os limites de entrada e convenções de saída anotados 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 ao seu 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 carregar 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ósticos e scripts



Gerenciamento de abas

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



Configurar 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 Client toolsets, 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:



Habilitar ou desabilitar ferramentas membro

Liste em configs apenas os membros que você quer alterar; cada membro que você omite 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.



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 ser nomeada 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 independentemente, cada uma em seu próprio quadro de coordenadas (pixels do viewport aqui, pixels de 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.



Habilitar membros opcionais

Quatro ferramentas membro estão desabilitadas por padrão: javascript_exec e file_upload porque ampliam o que uma página manipulada poderia fazer Claude fazer, 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.



Enviar 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 onde 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 para arquivos que sua aplicação preparou para o navegador, para implantações onde ele não pode. Sua aplicação define o que os identificadores significam; delimite sua resolução 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 está lendo 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 você fizer, cada arquivo que uma página faz o navegador baixar se torna enviável.



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 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 a lista de permissões de domínios de Considerações de segurança em vigor, trate o valor retornado como entrada não confiável e registre o código que Claude emite.



Ler atividade de console e rede

read_console retorna as entradas de 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 carrega uma entrada de log, aviso ou erro; uma linha de rede carrega o método, URL, status, tipo MIME e temporização. 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 falha por trás de um spinner, um erro de script por trás de um botão inoperante) sem capturas de tela repetidas. Entradas de console e 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ê informa 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) informa 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 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 informar" 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 não pode ser vazio, e nenhum deles 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) 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, 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. Informe a URL em que a aba foi aberta, como aqui, não uma para a qual ela redireciona depois; resultados posteriores informam 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 informar, e sempre inclua o inventário completo de tabs. Quando um resultado carrega 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 list_tabs separada:

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 abas do rodapé não carregam 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 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 com a 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; 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 informou o mesmo estado.



Informe downloads

Quando um clique ou 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. 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ê; portanto, 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 screenshot posterior 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 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
    }
  ]
}

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 que ocorreu durante uma chamada com falha no próximo resultado bem-sucedido.
• state_changes não é um inventário de downloads em andamento; informe 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 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 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:



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 deles 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 apenas na Claude API.
• 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 elementos 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 informam 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 prompts, 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 "browser use" (uso do navegador) segue a precificação 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 Precificação 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