---
title: Ferramenta de uso do navegador
url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool
description: Permita que Claude navegue, leia e interaja com páginas da web no seu próprio ambiente de navegador com a ferramenta de uso do navegador.
featureMetadata:
status: ga
zdr:
eligibility: eligible
note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements).
supportedModels:
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-sonnet-5
- claude-opus-4-8
- claude-haiku-5-5
supportedPlatforms:
Claude API: ga
Google Cloud: ga
---
**Comece com os toolsets do SDK:** Os SDKs de Python e TypeScript têm uma classe de toolset de navegador, em beta. Comece a partir de [uma integração de parceiro](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-sdk#partner-integrations) ou consulte [Uso de navegador e de computador com os toolsets do SDK](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-sdk). Use esta página como referência da ferramenta ou quando você mesmo lidar com as chamadas de ferramenta.
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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools). 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](https://platform.claude.com/docs/pt-BR/managed-agents/tools).
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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool), 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-fetch-tool) e a [ferramenta de pesquisa na web](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/web-search-tool) são mais leves. Elas são [ferramentas de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#security-considerations) antes de implantar.
## Início rápido
A ferramenta de uso do navegador está disponível na Claude API e no [Google Cloud](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-vertex-ai): adicione uma entrada do tipo `browser_toolset_20260801`, sem `name`, ao array `tools` de uma requisição da [Messages API](https://platform.claude.com/docs/pt-BR/api/messages/create).
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"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."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
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.
YAML
```
```python Python
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)
```
```typescript TypeScript
const client = new Anthropic();
const response = await 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."
}
]
});
console.log(response);
```
```csharp C#
var client = new AnthropicClient();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 2048,
Tools = [new BrowserToolset20260801()],
Messages =
[
new MessageParam
{
Role = Role.User,
Content = "Open example.com/docs and tell me how to get started.",
},
],
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 2048,
Tools: []anthropic.ToolUnionParam{
{OfBrowserToolset20260801: &anthropic.BrowserToolset20260801Param{}},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Open example.com/docs and tell me how to get started.")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
```
```java Java
import com.anthropic.models.messages.BrowserToolset20260801;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(2048L)
.addTool(BrowserToolset20260801.builder().build())
.addUserMessage("Open example.com/docs and tell me how to get started.")
.build();
Message response = client.messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$response = $client->messages->create(
maxTokens: 2048,
messages: [
['role' => 'user', 'content' => 'Open example.com/docs and tell me how to get started.'],
],
model: 'claude-opus-5-5',
tools: [
['type' => 'browser_toolset_20260801'],
],
);
echo $response;
```
```ruby Ruby
client = Anthropic::Client.new
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."
}
]
)
puts 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"`:
```json Output
{
"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:
```json
{
"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.
* 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."
* 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`.
* 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#batch-actions) a todos os blocos posteriores no turno.
* 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.
```python Python
# 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}")
```
```typescript TypeScript
// Dados de imagem de placeholder; um executor real captura a viewport como bytes PNG
const PLACEHOLDER_PNG =
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
function navigate(url: string): string {
return `navigated to ${url}`;
}
function readPage(): string {
return 'link "Docs" [ref_1]\nbutton "Search" [ref_2]';
}
function clickElement(ref: string): string {
return `clicked ${ref}`;
}
function clickAt(x: number, y: number): string {
return `clicked at (${x}, ${y})`;
}
function typeText(text: string): string {
return `typed: ${text}`;
}
function captureScreenshot(): Anthropic.ImageBlockParam[] {
// screenshot responde com um bloco de imagem em vez de texto
return [
{
type: "image",
source: {
type: "base64",
media_type: "image/png",
data: PLACEHOLDER_PNG
}
}
];
}
function handleBrowserAction(
action: string,
input: unknown
): string | Anthropic.ImageBlockParam[] {
const params: object = typeof input === "object" && input !== null ? input : {};
if (action === "navigate" && "url" in params) {
return navigate(String(params.url));
} else if (action === "read_page") {
return readPage();
} else if (action === "left_click" && "target" in params) {
// target é uma referência de elemento de read_page ou uma coordenada da viewport
const target: object =
typeof params.target === "object" && params.target !== null ? params.target : {};
if ("type" in target && target.type === "ref" && "ref" in target) {
return clickElement(String(target.ref));
} else if ("x" in target && "y" in target) {
return clickAt(Number(target.x), Number(target.y));
}
} else if (action === "type" && "text" in params) {
return typeText(String(params.text));
} else if (action === "screenshot") {
return captureScreenshot();
}
// Trate outras ações conforme necessário
throw new Error(`Unknown or unimplemented member: ${action}`);
}
```
```csharp C#
// Dados de imagem de placeholder; um executor real captura a viewport e retorna os bytes PNG
const string PlaceholderPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
string Navigate(string url) => $"navigated to {url}";
string ReadPage() =>
"""
link "Docs" [ref_1]
button "Search" [ref_2]
""";
string ClickRef(string elementRef) => $"clicked {elementRef}";
string ClickAt(int x, int y) => $"clicked at ({x}, {y})";
// target é {"type": "ref", "ref": "ref_1"} ou {"type": "coordinate", "x": 640, "y": 380}
string Click(JsonElement target) =>
target.GetProperty("type").GetString() == "ref"
? ClickRef(target.GetProperty("ref").GetString()!)
: ClickAt(target.GetProperty("x").GetInt32(), target.GetProperty("y").GetInt32());
string TypeText(string text) => $"typed: {text}";
// screenshot responde com um bloco de imagem em vez de texto: retorne a lista de conteúdo do resultado
List CaptureScreenshot() =>
[
new ImageBlockParam(
new Base64ImageSource { Data = PlaceholderPng, MediaType = MediaType.ImagePng }
),
];
ToolResultBlockParamContent HandleBrowserAction(
string action,
IReadOnlyDictionary input
) =>
action switch
{
"navigate" => Navigate(input["url"].GetString()!),
"read_page" => ReadPage(),
"left_click" => Click(input["target"]),
"type" => TypeText(input["text"].GetString()!),
"screenshot" => CaptureScreenshot(),
// Trate outras ações conforme necessário
_ => throw new NotSupportedException($"Unknown or unimplemented member: {action}"),
};
```
```go Go
// placeholderPNG substitui uma captura real: um executor retorna a
// viewport como dados PNG codificados em base64.
const placeholderPNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
// textContent encapsula texto como conteúdo de tool_result.
func textContent(text string) []anthropic.ToolResultBlockParamContentUnion {
return []anthropic.ToolResultBlockParamContentUnion{
{OfText: &anthropic.TextBlockParam{Text: text}},
}
}
func navigate(url string) string {
return fmt.Sprintf("navigated to %s", url)
}
func readPage() string {
return "link \"Docs\" [ref_1]\nbutton \"Search\" [ref_2]"
}
func clickRef(ref string) string {
return fmt.Sprintf("clicked %s", ref)
}
func clickAt(x, y int) string {
return fmt.Sprintf("clicked at (%d, %d)", x, y)
}
func typeText(text string) string {
return fmt.Sprintf("typed: %s", text)
}
// captureScreenshot retorna um bloco de imagem em vez de texto.
func captureScreenshot() []anthropic.ToolResultBlockParamContentUnion {
return []anthropic.ToolResultBlockParamContentUnion{{
OfImage: &anthropic.ImageBlockParam{
Source: anthropic.ImageBlockParamSourceUnion{
OfBase64: &anthropic.Base64ImageSourceParam{
MediaType: anthropic.Base64ImageSourceMediaTypeImagePNG,
Data: placeholderPNG,
},
},
},
}}
}
func handleBrowserAction(action string, params map[string]any) ([]anthropic.ToolResultBlockParamContentUnion, error) {
switch action {
case "navigate":
if url, ok := params["url"].(string); ok {
return textContent(navigate(url)), nil
}
case "read_page":
return textContent(readPage()), nil
case "left_click":
// target é uma referência de elemento de read_page ou uma coordenada da viewport
target, _ := params["target"].(map[string]any)
if ref, ok := target["ref"].(string); ok && target["type"] == "ref" {
return textContent(clickRef(ref)), nil
}
x, xok := target["x"].(float64)
y, yok := target["y"].(float64)
if xok && yok {
return textContent(clickAt(int(x), int(y))), nil
}
case "type":
if text, ok := params["text"].(string); ok {
return textContent(typeText(text)), nil
}
case "screenshot":
return captureScreenshot(), nil
// Trate outras ações conforme necessário
default:
return nil, fmt.Errorf("unknown or unimplemented member: %s", action)
}
// Alcançado quando a entrada de um membro não tem um campo ou um campo tem o tipo errado
return nil, fmt.Errorf("invalid input for %s", action)
}
```
```java Java
/** Placeholder pixels; a real executor captures the viewport and base64-encodes the PNG. */
static final String PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
ToolResultBlockParam.Content captureScreenshot() {
ImageBlockParam image = ImageBlockParam.builder()
.source(Base64ImageSource.builder()
.mediaType(Base64ImageSource.MediaType.IMAGE_PNG)
.data(PLACEHOLDER_PNG)
.build())
.build();
return ToolResultBlockParam.Content.ofBlocks(
List.of(ToolResultBlockParam.Content.Block.ofImage(image)));
}
String navigate(String url) {
return "navigated to " + url;
}
String readPage() {
return """
link "Docs" [ref_1]
button "Search" [ref_2]""";
}
String clickRef(String ref) {
return "clicked " + ref;
}
String clickAt(long x, long y) {
return "clicked at (" + x + ", " + y + ")";
}
String typeText(String text) {
return "typed: " + text;
}
/** Runs one browser toolset member; {@code action} is the tool_use block's name. */
ToolResultBlockParam.Content handleBrowserAction(String action, Map input) {
if (action.equals("screenshot")) {
return captureScreenshot(); // the one member here that answers with an image block
}
String output = switch (action) {
case "navigate" -> navigate(input.get("url").asStringOrThrow());
case "read_page" -> readPage();
case "left_click" -> {
// target é {"type": "ref", "ref": "ref_1"} ou {"type": "coordinate", "x": 640, "y": 380}
Map target =
(Map) input.get("target").asObject().get();
if (target.get("type").asStringOrThrow().equals("ref")) {
yield clickRef(target.get("ref").asStringOrThrow());
}
long x = ((Number) target.get("x").asNumber().get()).longValue();
long y = ((Number) target.get("y").asNumber().get()).longValue();
yield clickAt(x, y);
}
case "type" -> typeText(input.get("text").asStringOrThrow());
// Trate outras ações conforme necessário
default -> throw new UnsupportedOperationException("Unknown or unimplemented member: " + action);
};
return ToolResultBlockParam.Content.ofString(output);
}
```
```php PHP
// Substituto para bytes PNG reais; um executor real captura a viewport
const PLACEHOLDER_PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
function navigateTo(string $url): string
{
return "navigated to {$url}";
}
function readPage(): string
{
return <<<'TEXT'
link "Docs" [ref_1]
button "Search" [ref_2]
TEXT;
}
function clickTarget(array $target): string
{
// Um alvo é uma referência de elemento de read_page ou find, ou uma coordenada de pixel da viewport
if ($target['type'] === 'ref') {
return "clicked {$target['ref']}";
}
return "clicked at ({$target['x']}, {$target['y']})";
}
function typeText(string $text): string
{
return "typed: {$text}";
}
function captureScreenshot(): array
{
// screenshot responde com um bloco de imagem em vez de texto, então retorne a lista de conteúdo do resultado
$image = [
'type' => 'image',
'source' => ['type' => 'base64', 'media_type' => 'image/png', 'data' => PLACEHOLDER_PNG],
];
return [$image];
}
function handleBrowserAction(string $name, array $input): string|array
{
return match ($name) {
'navigate' => navigateTo($input['url']),
'read_page' => readPage(),
'left_click' => clickTarget($input['target']),
'type' => typeText($input['text']),
'screenshot' => captureScreenshot(),
// Trate outras ações conforme necessário
default => throw new \RuntimeException("Unknown or unimplemented member: {$name}"),
};
}
```
```ruby Ruby
# Dados de imagem substitutos; um executor real captura a viewport como PNG.
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
def navigate(url)
"navigated to #{url}"
end
def read_page
<<~TREE
link "Docs" [ref_1]
button "Search" [ref_2]
TREE
end
def click(target)
return "clicked #{target[:ref]}" if target[:type] == "ref"
"clicked at (#{target[:x]}, #{target[:y]})"
end
def type_text(text)
"typed: #{text}"
end
def capture_screenshot
[
{
type: "image",
source: { type: "base64", media_type: "image/png", data: PLACEHOLDER_PNG }
}
]
end
def handle_browser_action(name, input)
case name
when "navigate"
navigate(input[:url])
when "read_page"
read_page
when "left_click"
# target é uma referência de elemento (de read_page ou find) ou uma coordenada
click(input[:target])
when "type"
type_text(input[:text])
when "screenshot"
capture_screenshot
# Trate outras ações conforme necessário
else
raise ArgumentError, "Unknown or unimplemented member: #{name}"
end
end
```
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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#batch-actions), 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#understanding-the-agentic-loop), com o toolset do navegador em `tools`.
```python Python
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
```
```typescript TypeScript
const HALT_TEXT = "Not executed: an earlier action in this turn failed.";
function browserResult(
toolUseId: string,
content: string | Anthropic.ImageBlockParam[],
isError?: boolean
): Anthropic.ToolResultBlockParam {
return {
type: "tool_result",
tool_use_id: toolUseId,
toolset_name: "browser",
content,
is_error: isError
};
}
function processToolCalls(response: Anthropic.Message): Anthropic.ToolResultBlockParam[] {
const toolResults: Anthropic.ToolResultBlockParam[] = [];
let failed = false;
for (const block of response.content) {
if (block.type !== "tool_use") {
continue;
}
if (block.toolset_name !== "browser") {
// Este exemplo declara apenas o conjunto de ferramentas do navegador; roteie outras ferramentas
// aqui se você as adicionar.
continue;
}
if (failed) {
// Um lote para na primeira falha; responda às ações posteriores como não executadas
toolResults.push(browserResult(block.id, HALT_TEXT, true));
continue;
}
try {
// Uma string ou uma lista de blocos de imagem; um executor real também adiciona um
// bloco browser_state aos resultados de navegação e gerenciamento de abas
const result = handleBrowserAction(block.name, block.input);
toolResults.push(browserResult(block.id, result));
} catch (error) {
failed = true;
const message = error instanceof Error ? error.message : String(error);
toolResults.push(browserResult(block.id, `Error: ${message}`, true));
}
}
return toolResults;
}
```
```csharp C#
const string HaltText = "Not executed: an earlier action in this turn failed.";
List ProcessToolCalls(Message response)
{
List toolResults = [];
var failed = false;
foreach (var block in response.Content)
{
if (!block.TryPickToolUse(out var toolUse))
{
continue;
}
if (toolUse.ToolsetName != "browser")
{
// Este exemplo declara apenas o conjunto de ferramentas do navegador; roteie outras ferramentas
// aqui se você as adicionar.
continue;
}
if (failed)
{
// Um lote para na primeira falha; responda às ações posteriores sem executá-las
toolResults.Add(
new ToolResultBlockParam(toolUse.ID)
{
Content = HaltText,
IsError = true,
ToolsetName = "browser",
}
);
continue;
}
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
var result = HandleBrowserAction(toolUse.Name, toolUse.Input);
toolResults.Add(
new ToolResultBlockParam(toolUse.ID) { Content = result, ToolsetName = "browser" }
);
}
catch (Exception e)
{
failed = true;
toolResults.Add(
new ToolResultBlockParam(toolUse.ID)
{
Content = $"Error: {e.Message}",
IsError = true,
ToolsetName = "browser",
}
);
}
}
return toolResults;
}
```
```go Go
const notExecuted = "Not executed: an earlier action in this turn failed."
// browserToolResult monta o resultado de uma ação do navegador. Diferente de um
// tool result comum, ele deve repetir o nome do toolset. Um executor real também
// adiciona um bloco browser_state aos resultados de navegação e gerenciamento de abas.
func browserToolResult(toolUseID string, content []anthropic.ToolResultBlockParamContentUnion, isError bool) anthropic.ContentBlockParamUnion {
result := anthropic.ToolResultBlockParam{
ToolUseID: toolUseID,
ToolsetName: anthropic.String("browser"),
Content: content,
}
if isError {
result.IsError = anthropic.Bool(true)
}
return anthropic.ContentBlockParamUnion{OfToolResult: &result}
}
// processToolCalls executa em ordem as ações do navegador na resposta do Claude e
// monta um tool_result por bloco tool_use. Após a primeira falha, ele pula
// o restante: o Claude as planejou supondo que as ações anteriores tiveram sucesso.
func processToolCalls(response *anthropic.Message) []anthropic.ContentBlockParamUnion {
var toolResults []anthropic.ContentBlockParamUnion
failed := false
for _, block := range response.Content {
switch variant := block.AsAny().(type) {
case anthropic.ToolUseBlock:
// Este exemplo declara apenas o toolset do navegador; roteie outras ferramentas aqui se você adicioná-las.
if variant.ToolsetName != "browser" {
continue
}
if failed {
toolResults = append(toolResults, browserToolResult(variant.ID, textContent(notExecuted), true))
continue
}
var input map[string]any
var content []anthropic.ToolResultBlockParamContentUnion
err := json.Unmarshal(variant.Input, &input)
if err == nil {
content, err = handleBrowserAction(variant.Name, input)
}
if err != nil {
failed = true
content = textContent("Error: " + err.Error())
}
toolResults = append(toolResults, browserToolResult(variant.ID, content, err != nil))
}
}
return toolResults
}
```
```java Java
/** The exact text the toolset contract prescribes for member calls skipped after a failure. */
static final String HALT_TEXT = "Not executed: an earlier action in this turn failed.";
/** Every result answering a browser toolset member echoes toolset_name. */
ToolResultBlockParam.Builder browserResult(ToolUseBlock toolUse) {
return ToolResultBlockParam.builder()
.toolUseId(toolUse.id())
.toolsetName("browser");
}
/**
* Run the browser actions in Claude's response in order and build one
* tool_result per tool_use block. After the first failure, skip the rest:
* Claude planned them assuming the earlier actions succeeded.
*/
List processToolCalls(Message response) {
List toolResults = new ArrayList<>();
boolean failed = false;
for (ContentBlock block : response.content()) {
// Este exemplo declara apenas o conjunto de ferramentas do navegador; roteie outras ferramentas aqui se você as adicionar.
if (!block.isToolUse() || !block.asToolUse().toolsetName().equals(Optional.of("browser"))) {
continue;
}
ToolUseBlock toolUse = block.asToolUse();
ToolResultBlockParam result;
if (failed) {
result = browserResult(toolUse).content(HALT_TEXT).isError(true).build();
} else {
try {
Map input =
(Map) toolUse._input().asObject().get();
ToolResultBlockParam.Content output = handleBrowserAction(toolUse.name(), input);
// Um executor real também adiciona um bloco browser_state aos resultados de navegação e
// de gerenciamento de abas; veja "Rastrear abas com browser_state" nesta página.
result = browserResult(toolUse).content(output).build();
} catch (RuntimeException e) {
failed = true;
result = browserResult(toolUse).content("Error: " + e.getMessage()).isError(true).build();
}
}
toolResults.add(ContentBlockParam.ofToolResult(result));
}
return toolResults;
}
```
```php PHP
const HALT_TEXT = 'Not executed: an earlier action in this turn failed.';
function processToolCalls(Message $response): array
{
$toolResults = [];
$failed = false;
foreach ($response->content as $block) {
// Este exemplo declara apenas o conjunto de ferramentas do navegador; roteie outras ferramentas aqui se você as adicionar.
if (!($block instanceof \Anthropic\Messages\ToolUseBlock) || $block->toolsetName !== 'browser') {
continue;
}
$result = ['type' => 'tool_result', 'tool_use_id' => $block->id, 'toolset_name' => 'browser'];
if ($failed) {
// Um lote para na primeira falha; as ações restantes são respondidas sem serem executadas
$toolResults[] = [...$result, 'content' => HALT_TEXT, 'is_error' => true];
continue;
}
try {
// Um executor real também retorna um bloco browser_state em resultados de navegação e gerenciamento de abas
$toolResults[] = [...$result, 'content' => handleBrowserAction($block->name, $block->input)];
} catch (\Throwable $e) {
$failed = true;
$toolResults[] = [...$result, 'content' => 'Error: ' . $e->getMessage(), 'is_error' => true];
}
}
return $toolResults;
}
```
```ruby Ruby
NOT_EXECUTED = "Not executed: an earlier action in this turn failed."
# Execute as ações do navegador na resposta do Claude em ordem e crie um
# tool_result por bloco tool_use. Após a primeira falha, pule o restante:
# o Claude as planejou assumindo que as ações anteriores tiveram sucesso.
def process_tool_calls(response)
tool_results = []
failed = false
response.content.each do |block|
# Este exemplo declara apenas o conjunto de ferramentas do navegador; roteie outras ferramentas aqui
# se você as adicionar.
next unless block.type == :tool_use && block.toolset_name == "browser"
result = { type: "tool_result", tool_use_id: block.id, toolset_name: "browser" }
if failed
result.update(content: NOT_EXECUTED, is_error: true)
else
begin
# Uma String, ou blocos de conteúdo para uma captura de tela. 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)
rescue => e
result.update(content: "Error: #{e.message}", is_error: true)
failed = true
end
end
tool_results << result
end
tool_results
end
```
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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/parallel-tool-use); 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:
```json
{
"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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#tab-context-on-other-results)). 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/parallel-tool-use#disable-parallel-tool-use)). O restante do contrato descrito em [Ações em lote para a ferramenta de uso do computador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#batch-actions) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#member-tools) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#tab-management-results)), e o resultado de qualquer outro membro pode adicionar um bloco `browser_state` ao seu texto ou imagem ([Contexto da aba em outros resultados](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#tab-context-on-other-results)). Onde os breakpoints de cache dentro de um lote entram em vigor é descrito na linha `cache_control` dos [Parâmetros da ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#tool-parameters) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#member-tools) usam `Target` para um parâmetro que aceita qualquer um dos dois formatos.
| Formato | `target.type` | Campos | Aceito por |
| ------------------ | -------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CoordinateTarget` | `"coordinate"` | `x`, `y` (inteiros, pixels da viewport) | `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click`, `hover`, `left_click_drag` (`from` e `target`), `left_mouse_down`, `left_mouse_up`, `mouse_move`, `scroll` |
| `RefTarget` | `"ref"` | `ref` (uma referência de elemento como `"ref_2"`) | `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click`, `hover`, `scroll_to`, `form_input`, `file_upload` |
**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](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#evaluate-image-size) do seu modelo, ou o limite por imagem mais rigoroso que se aplica quando uma requisição contém [mais de 20 imagens](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#request-limits), é 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)).
**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:
```text wrap
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.
Para reduzir esses riscos, tome precauções como as seguintes:
1. Execute o navegador e seu executor em um contêiner ou máquina virtual dedicada com privilégios mínimos, um perfil novo que não contenha credenciais e sem acesso a sistemas de arquivos sensíveis ou redes internas; isole da mesma forma qualquer ferramenta que você execute junto com ele.
2. Restrinja os hosts que o navegador pode acessar a uma "allowlist" (lista de permissões) de domínios aplicada na camada de rede e verificada novamente no seu handler de `navigate` após redirecionamentos, e bloqueie faixas de loopback, link-local e privadas, a menos que a tarefa precise delas.
3. Trate tudo o que uma página fornece como entrada não confiável, incluindo os títulos e URLs das abas, e o `url`, `path` e `error` de cada download, que você informa em um bloco [`browser_state`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state), e construa as leituras de página a partir do que a página renderiza (a árvore de acessibilidade ou o texto visível), não do código-fonte bruto do DOM, para que texto oculto não chegue a Claude.
4. No seu handler de `navigate`, aceite as palavras-chave de histórico `"back"`, `"forward"` e `"reload"`, trate uma URL sem esquema como `https://`, depois analise a URL e recuse qualquer esquema diferente de `http` ou `https` (`javascript:`, `file:`, `data:`, `chrome:` e assim por diante) com um [resultado de erro](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor). Verifique o esquema com um parser de URL em vez de um prefixo de string; a API não filtra as URLs que Claude abre, portanto não pode rejeitar uma por você.
5. Mantenha `javascript_exec` e `file_upload` desabilitados, a menos que você precise deles, e leia [Habilitar membros opcionais](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools) antes de ativar qualquer um deles.
6. Faça com que um humano confirme ações com consequências e qualquer coisa que exija consentimento afirmativo (compras, modificação de contas, envio de mensagens e aceitação de termos), e faça essa verificação no seu executor antes de cada chamada, porque um único turno pode conter várias.
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](https://platform.claude.com/docs/pt-BR/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks) 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](https://support.claude.com/en/). 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#targets-and-coordinates). Quatro membros (`javascript_exec`, `file_upload`, `read_console` e `read_network`) são desabilitados por padrão e só aparecem quando você [os habilita](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools). 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`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/handle-tool-calls#handling-results-from-client-tools) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#tab-management-results)). 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#batch-actions) 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
| Membro | Entrada | Descrição |
| ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `navigate` | `url`, `tab_id?` | Carrega uma URL `http` ou `https`, ou percorre o histórico com `"back"`, `"forward"` ou `"reload"`. Trate uma URL sem esquema como `https://` e recuse qualquer outro esquema com um resultado de erro. Retorne uma breve confirmação, mais um bloco `browser_state` quando a URL ou o título da aba tiver mudado. |
| `screenshot` | `tab_id?` | Captura a viewport e retorna um bloco `image`. |
| `zoom` | `region`, `tab_id?` | Retorna uma `image` recortada e ampliada de `region`, fornecida como `[x0, y0, x1, y1]` em pixels da viewport, para inspecionar de perto textos ou controles pequenos. |
### Ponteiro
| Membro | Entrada | Descrição |
| ----------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `left_click` | `target: Target`, `modifiers?`, `tab_id?` | Clica com o botão esquerdo em uma coordenada ou em um elemento referenciado. `modifiers` é uma combinação de teclas mantida pressionada durante o clique, por exemplo, `"shift"` ou `"ctrl+shift"`. |
| `right_click` | `target: Target`, `modifiers?`, `tab_id?` | Clica com o botão direito em uma coordenada ou elemento. |
| `middle_click` | `target: Target`, `modifiers?`, `tab_id?` | Clica com o botão do meio em uma coordenada ou elemento. |
| `double_click` | `target: Target`, `modifiers?`, `tab_id?` | Clica duas vezes com o botão esquerdo em uma coordenada ou elemento. |
| `triple_click` | `target: Target`, `modifiers?`, `tab_id?` | Clica três vezes com o botão esquerdo em uma coordenada ou elemento, o que normalmente seleciona uma linha ou parágrafo. |
| `hover` | `target: Target`, `tab_id?` | Move o ponteiro sobre uma coordenada ou elemento sem clicar. |
| `left_click_drag` | `from: CoordinateTarget`, `target: CoordinateTarget`, `tab_id?` | Pressiona em `from`, arrasta até `target` e solta. |
| `left_mouse_down` | `target: CoordinateTarget`, `tab_id?` | Pressiona e mantém o botão esquerdo em uma coordenada; combine com `left_mouse_up` para um arrasto personalizado. |
| `left_mouse_up` | `target: CoordinateTarget`, `tab_id?` | Solta o botão esquerdo em uma coordenada. |
| `mouse_move` | `target: CoordinateTarget`, `tab_id?` | Move o ponteiro para uma coordenada. |
| `scroll` | `target: CoordinateTarget`, `scroll_direction`, `scroll_amount?`, `tab_id?` | Rola em uma posição da viewport. `scroll_direction` é `"up"`, `"down"`, `"left"` ou `"right"`; `scroll_amount` é medido em entalhes da roda de rolagem, de 1 a 10, padrão 3. |
| `scroll_to` | `target: RefTarget`, `tab_id?` | Rola um elemento referenciado até que fique visível. |
### Teclado e temporização
| Membro | Entrada | Descrição |
| ---------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `text`, `tab_id?` | Digita uma string literal no foco atual. |
| `key` | `text`, `repeat?`, `tab_id?` | Pressiona uma tecla ou combinação. `text` é uma única tecla (`"Enter"`), uma combinação unida com `+` (`"ctrl+a"`) ou uma sequência separada por espaços (`"Backspace Backspace"`); `repeat` vai de 1 a 100, padrão 1. |
| `hold_key` | `text`, `duration`, `tab_id?` | Mantém uma tecla ou combinação pressionada por `duration` segundos, de 0 a 30. |
| `wait` | `duration`, `tab_id?` | Pausa por `duration` segundos, de 0 a 30. |
### Leitura de página
| Membro | Entrada | Descrição |
| --------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `read_page` | `filter?`, `depth?`, `ref?`, `tab_id?` | Retorna a árvore de acessibilidade da página como texto, com cada elemento marcado com uma referência como `[ref_2]`. Com `filter` omitido, retorna todos os elementos visíveis; com `"interactive"`, apenas os elementos interativos visíveis; com `"all"`, também os elementos fora da viewport. `depth` limita a profundidade da árvore (mínimo 1, padrão 15) e `ref` restringe a leitura à subárvore daquele elemento. Limite a saída a 50.000 caracteres e informe isso no texto; Claude então restringe com um `depth` menor ou uma `ref`. |
| `find` | `query`, `tab_id?` | Procura elementos que correspondam a uma descrição em linguagem natural, como `"search field"` ou `"add to cart button"`, e retorna até 20 correspondências no mesmo formato marcado de `read_page`. |
| `get_page_text` | `tab_id?` | Retorna o texto visível da página como texto simples, priorizando o conteúdo principal do artigo; adequado para artigos, documentação e outras páginas com muito texto. |
### Formulários e arquivos
| Membro | Entrada | Descrição |
| --------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `form_input` | `target: RefTarget`, `value`, `tab_id?` | Define diretamente o valor de um elemento de formulário. `value` é uma `string`, `number` ou `boolean`; use um `boolean` para caixas de seleção e o valor ou o texto visível de uma opção para selects. |
| `file_upload` (desabilitado por padrão) | `target: RefTarget`, `paths?`, `document_ids?`, `tab_id?` | Define os arquivos em um elemento de entrada de arquivo a partir de `paths` no sistema de arquivos do executor, de `document_ids` que sua aplicação preparou, ou de ambos; pelo menos um é obrigatório. Consulte [Enviar arquivos](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#upload-files). |
### Diagnóstico e scripts
| Membro | Entrada | Descrição |
| ------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read_console` (desabilitado por padrão) | `tab_id?` | Retorna as entradas do console da aba (linhas de log, aviso e erro) acumuladas desde a última leitura, uma linha por entrada. Consulte [Ler a atividade do console e da rede](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#read-console-and-network-activity). |
| `read_network` (desabilitado por padrão) | `tab_id?` | Retorna as requisições de rede da aba (método, URL, status, tipo MIME, tempo) desde a última leitura, uma linha por entrada. |
| `javascript_exec` (desabilitado por padrão) | `text`, `tab_id?` | Executa `text` como JavaScript no contexto da página e retorna o valor da última expressão como texto. Consulte [Habilitar membros opcionais](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools). |
### Gerenciamento de abas
| Membro | Entrada | Descrição |
| ------------ | ---------------------- | ----------------------------------- |
| `new_tab` | (nenhuma) | Abre uma aba e a torna a aba ativa. |
| `list_tabs` | (nenhuma) | Informa o inventário de abas. |
| `switch_tab` | `tab_id` (obrigatório) | Torna `tab_id` a aba ativa. |
| `close_tab` | `tab_id` (obrigatório) | Fecha `tab_id`. |
Em caso de sucesso, cada um deles retorna exatamente um bloco `browser_state` e nenhum texto ou imagem; consulte [Resultados de gerenciamento de abas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#tab-management-results).
## 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets), 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:
| Campo | Padrão | Significado |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | `true`, exceto `false` para os quatro [membros opcionais](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools) | Se o membro é oferecido a Claude. |
| `defer_loading` | `false` | Se a definição do toolset é adiada para a busca de ferramentas. Deve resultar no mesmo valor em todos os membros habilitados. Com os quatro membros opcionais mantidos desabilitados, adiar o toolset significa defini-lo nos outros 27; consulte [Conjuntos de ferramentas de cliente](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets). |
### 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:
```json
{
"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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor).
### 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool), 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.
```json
{
"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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#security-considerations), 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ê.
```json
{
"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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#report-downloads). 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#report-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`.
Os títulos e URLs das abas vêm da página e são renderizados em texto que Claude lê, portanto são uma superfície de "prompt injection" (injeção de prompt). A API renderiza as URLs das abas literalmente, então sanitize as URLs fornecidas pela página antes de preencher `tabs`. Ela escapa aspas duplas e barras invertidas nos títulos ao renderizá-los, então não escape os títulos previamente (um título escapado previamente chega a Claude com escape duplo); truncar ou descartar títulos suspeitos ainda vale a pena. Os campos `url`, `path` e `error` de uma entrada de download também são renderizados em texto que Claude lê, então trate-os também como não confiáveis; a API os coloca entre aspas e os escapa da mesma forma que faz com os títulos. Os limites de tamanho e de caracteres que a API impõe são um mínimo, não uma defesa.
### 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`.
| Membro | Texto que Claude vê |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `switch_tab` | `Switched to tab {tab_id}`, obtido do `input.tab_id` da chamada |
| `close_tab` | `Closed tab {tab_id}`, obtido do `input.tab_id` da chamada |
| `new_tab` | `Created new tab with tab_id: {tab_id}, URL: {url}. It is now the current tab.`, obtido da entrada marcada com `active: true` |
| `list_tabs` | `Available tabs:` seguido de uma linha por aba, ou `No tabs available` quando `tabs` está vazio |
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:
```text wrap
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`:
```json
{
"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`:
```text wrap
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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#report-downloads). 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:
```json
{
"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:
| `type` | Campos | Quando enviar |
| -------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `download_started` | `download_id`, `url` | No resultado da chamada durante a qual o download começou. `url` é a URL final a partir da qual o arquivo é servido, após os redirecionamentos. |
| `download_completed` | `download_id`, `url`, `path?`, `size_bytes?` | No resultado de qualquer chamada posterior que esteja em execução quando o download terminar. Inclua `path` apenas quando outra ferramenta no mesmo ambiente (por exemplo, a [ferramenta bash](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/bash-tool) ou `file_upload`) puder ler o arquivo ali; caso contrário, `download_id` é o único identificador do download. |
| `download_failed` | `download_id`, `url`, `error?` | Quando o download falha ou é cancelado, com o motivo em `error` se o navegador fornecer um. |
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`:
```json
{
"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:
```text wrap
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:
```json
{
"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."
}
```
```json
{
"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."
}
```
```json
{
"type": "tool_result",
"tool_use_id": "toolu_013h2Q55HcNwVyapSpy2s5ZG",
"toolset_name": "browser",
"is_error": true,
"content": "Error: javascript_exec is not enabled in this environment."
}
```
Quando o `left_click` em `ref_3` de [Ações em lote](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#batch-actions) falha com o erro de referência obsoleta mostrado anteriormente, as chamadas `type` e `key` posteriores recebem, cada uma, este resultado:
```json
{
"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.
| Requisição | Por que falha e o que fazer |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Uma opção ou combinação que a entrada do toolset não aceita, por exemplo, um `name`, `strict: true`, `input_examples`, `defer_loading` na própria entrada, uma chave de `configs` que não é um nome de membro, um campo diferente de `enabled` ou `defer_loading` no valor de `configs` de um membro ([Configure o toolset](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#configure-the-toolset)), membros habilitados cujos valores de `defer_loading` diferem ([Configure o toolset](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#configure-the-toolset)), um `configs` que não deixa nenhum membro habilitado, um chamador de execução de código em `allowed_callers`, o cabeçalho beta legado `fine-grained-tool-streaming-2025-05-14` na requisição, um `tool_choice` do tipo `tool` nomeando `browser` ou um membro, ou uma segunda entrada de toolset de browser ou outra ferramenta chamada `browser` | Esses itens não são suportados em toolsets de cliente. Consulte [Toolsets de cliente](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets) para cada regra e sua alternativa. |
| Um `tool_result` respondendo a uma chamada de membro sem `"toolset_name": "browser"` ou com um valor diferente, ou `toolset_name` em um resultado cuja chamada não foi uma chamada de membro | Repita `toolset_name` exatamente nos resultados de membros, e somente neles. |
| Um `tool_use` de membro de um turno anterior sem `tool_result` correspondente | Responda a todas as chamadas de membros, incluindo as que você não executou após uma falha. |
| Um bloco de conteúdo diferente de `text`, `image` ou `browser_state` em um resultado de membro | Resultados de membros aceitam apenas esses três tipos de bloco. |
| Um bloco `browser_state` que viola uma regra em [Rastreie abas com `browser_state`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state), por exemplo, um em um resultado com `is_error: true` ou em um resultado que não responde a uma chamada de membro do browser, mais de um em um resultado, um `tabs` não vazio sem exatamente uma entrada `active: true`, um `tab_id` duplicado, um array `state_changes` vazio, um `tab_opened` cujo `tab_id` não está em `tabs`, duas mudanças de estado para um mesmo `download_id` ou um campo de mudança de estado que seu `type` não declara ([Informe downloads](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#report-downloads)), ou um campo acima de seus limites | Corrija o bloco. "Nada a informar" é expresso omitindo o bloco ou o campo `state_changes`, nunca por um valor vazio. |
| Um resultado bem-sucedido de `new_tab`, `switch_tab`, `close_tab` ou `list_tabs` cujo `content` não é exatamente um bloco `browser_state`, ou um resultado de `new_tab` sem exatamente um `tab_opened` correspondente à aba ativa | A API renderiza esses resultados a partir do bloco e precisa dele exatamente nesse formato; consulte [Resultados de gerenciamento de abas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#tab-management-results). |
| Uma `image` em um resultado acima dos [limites de tamanho de imagem](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#evaluate-image-size) do seu modelo, ou acima do limite por imagem mais rigoroso que se aplica quando a requisição contém [mais de 20 imagens](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#request-limits), contando capturas de tela e imagens de `zoom` em resultados anteriores | A API não reduz a escala das imagens do toolset. Redimensione as capturas de tela antes de retorná-las ([Dimensione capturas de tela para caber nos limites de imagem](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)). |
| Um `model` que não suporta `browser_toolset_20260801` | Consulte [Compatibilidade](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool#compatibility) para ver os modelos suportados. |
## Limitações
* **Disponibilidade de plataforma:** O uso de navegador está disponível na Claude API e no [Google Cloud](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-vertex-ai).
* **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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#client-toolsets)).
* **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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#understand-computer-use-limitations) da ferramenta de uso de computador), e suas orientações em [Otimize o desempenho do modelo com prompts](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#optimize-model-performance-with-prompting), [Gerencie o histórico de capturas de tela](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#manage-screenshot-history) e [Siga as melhores práticas de implementação](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool#follow-implementation-best-practices) (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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview#pricing). 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.670 no Claude Sonnet 5 e cerca de 6.610 nos outros modelos suportados), o que abrange as definições das ferramentas membro 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 de uma requisição é informada no `usage` da resposta, e você pode estimá-la antecipadamente com o [endpoint de contagem de tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/token-counting).
**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](https://platform.claude.com/docs/pt-BR/build-with-claude/vision#evaluate-image-size))
* Resultados de ferramentas em texto retornados ao Claude, como árvores de acessibilidade, texto da página e entradas de console ou de rede
Se você também usar a ferramenta de uso do computador, a ferramenta bash, a ferramenta de editor de texto ou suas próprias ferramentas junto com o uso do navegador, essas ferramentas têm seus próprios custos de tokens, conforme documentado em suas respectivas páginas.
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](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention) para ver os períodos de retenção e a elegibilidade entre os recursos.
## Próximos passos
Comece a partir do driver de um parceiro ou escreva o seu próprio em Python ou TypeScript. O SDK executa o loop e as verificações que você configurar.
Dê a Claude o controle de um desktop completo quando a tarefa sair do navegador; suas orientações de implementação também se aplicam a executores de navegador.
Formate blocos `tool_result`, retorne imagens e erros e continue a conversa.
Navegue pelos toolsets de cliente e por todas as outras ferramentas fornecidas pela Anthropic, com suas versões e parâmetros.