---
title: Herramienta de uso del navegador
url: https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool
description: Permite que Claude navegue, lea e interactúe con páginas web en tu propio entorno de navegador con la herramienta de uso del 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
---
**Empieza con los conjuntos de herramientas del SDK:** Los SDK de Python y TypeScript tienen una clase de conjunto de herramientas de navegador, en beta. Empieza desde [la integración de un socio](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-sdk#partner-integrations), o consulta [Uso del navegador y de la computadora con los conjuntos de herramientas del SDK](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-sdk). Usa esta página como referencia de la herramienta, o cuando gestiones tú mismo las llamadas a herramientas.
La herramienta de uso del navegador permite que Claude navegue, lea e interactúe con páginas web en un navegador que ejecuta tu aplicación. Claude trabaja con la página tanto a través de su estructura (el "accessibility tree" (árbol de accesibilidad), los elementos, los formularios y las pestañas) como a través de capturas de pantalla y coordenadas del "viewport" (área de visualización).
La herramienta es un ["client toolset" (conjunto de herramientas de cliente)](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference#client-toolsets) definido por Anthropic: una entrada `browser_toolset_20260801` en `tools` le da a Claude 27 herramientas miembro de forma predeterminada, como `navigate`, `read_page`, `left_click` y `screenshot`, además de cuatro más cuando [las habilitas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools). Tu aplicación ejecuta cada llamada con su propia automatización del navegador; nada se ejecuta del lado de Anthropic. La herramienta no está disponible actualmente en [Claude Managed Agents](https://platform.claude.com/docs/es/managed-agents/tools).
Elige el uso del navegador cuando la tarea se mantiene dentro de páginas web e implica actuar sobre ellas, o cuando las páginas construyen su contenido con JavaScript. Cuando una tarea necesita un escritorio completo, usa la [herramienta de uso de computadora](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool), que funciona únicamente mediante capturas de pantalla y coordenadas. Para leer páginas a las que puedes dirigir a Claude, o para encontrar fuentes en la web, la [herramienta de obtención web](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-fetch-tool) y la [herramienta de búsqueda web](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-search-tool) son más ligeras. Son [herramientas de servidor](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools) que la API ejecuta por ti, sin un navegador que operar.
Con el uso del navegador, Claude lee y actúa sobre páginas web en vivo, por lo que todo lo que proporciona una página es entrada no confiable y las acciones que realiza Claude pueden tener efectos reales. Consulta [Consideraciones de seguridad](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#security-considerations) antes de implementar.
## Inicio rápido
La herramienta de uso del navegador está disponible en la Claude API y en [Google Cloud](https://platform.claude.com/docs/es/build-with-claude/claude-on-vertex-ai): agrega una entrada de tipo `browser_toolset_20260801`, sin `name`, al arreglo `tools` de una solicitud a la [Messages API](https://platform.claude.com/docs/es/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
```
La primera respuesta de Claude termina con `stop_reason: "tool_use"` y contiene uno o más bloques `tool_use` de miembros, cada uno de los cuales nombra una herramienta miembro en `name` y lleva `"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
}
```
Tu "executor" (ejecutor), es decir, la parte de tu aplicación que controla el navegador y produce los resultados de las herramientas, ejecuta `navigate` y luego `read_page`. Tu aplicación devuelve un `tool_result` por bloque en su siguiente solicitud, repitiendo `toolset_name` en cada uno. El resultado de `navigate` informa la pestaña que cargó en un bloque `browser_state`; el resultado de `read_page` es texto en el que cada elemento lleva una referencia:
```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 ahora tiene referencias sobre las que puede actuar, por lo que en su siguiente turno puede hacer clic en `ref_2` para abrir la página de introducción, sin necesidad de localizar primero el enlace en una captura de pantalla.
## Cómo funciona el uso del navegador
El uso del navegador se ejecuta como un "agent loop" (bucle de agente) en tu aplicación: Claude devuelve llamadas a herramientas miembro, tu ejecutor las ejecuta en el navegador y tú devuelves los resultados hasta que Claude responde con texto.
* Agrega la entrada `browser_toolset_20260801` y, opcionalmente, otras herramientas a tu solicitud de API.
* Incluye un prompt de usuario que requiera trabajar con páginas web, por ejemplo, "Abre example.com/docs y dime cómo empezar."
* Claude devuelve uno o más bloques `tool_use` en un solo turno del asistente; varios en un mismo turno forman una "batch action" (acción por lotes), por ejemplo, `left_click`, luego `type` y luego `key`.
* El `name` de cada bloque es el nombre del miembro, cada uno lleva `"toolset_name": "browser"` e `input` contiene solo los parámetros de ese miembro, sin campo `action`. El `stop_reason` de la respuesta es `tool_use`.
* Itera sobre cada bloque `tool_use` en `response.content` (no supongas que hay exactamente uno) y ejecútalos secuencialmente, en el orden en que aparecen, porque las llamadas posteriores suelen depender de las anteriores.
* Devuelve un `tool_result` por bloque en un nuevo mensaje `user`, emparejado por `tool_use_id`, y repite `"toolset_name": "browser"` en cada uno. Cada llamada debe responderse o la siguiente solicitud será rechazada.
* Si una llamada falla, devuelve `is_error: true` con una descripción en texto para ese bloque y luego aplica la regla de detención de [Acciones por lotes](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#batch-actions) a cada bloque posterior del turno.
* Claude lee los resultados (texto de la página, árboles de accesibilidad, capturas de pantalla, estado de las pestañas) y, si necesita más, devuelve más llamadas a miembros, lo que te lleva de vuelta al paso 3.
* De lo contrario, devuelve una respuesta de texto al usuario.
Aquí tienes un esqueleto del paso de llamadas a herramientas de ese bucle, en dos partes. Primero, unos controladores de miembros de prueba sustituyen a tu automatización del navegador. Cinco miembros (`navigate`, `read_page`, `left_click`, `type` y `screenshot`) devuelven el texto, o en el caso de `screenshot` el bloque de imagen, que se convierte en el contenido del resultado, y el despachador genera un error para cualquier miembro que no implemente.
```python Python
# Datos de imagen de marcador de posición; un ejecutor real captura el viewport y devuelve los 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):
# Un objetivo es una referencia de elemento de read_page o find, o una coordenada del 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 con un bloque de imagen en lugar de texto: devuelve la lista de contenido del 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()
# Maneja otras acciones según sea necesario
raise ValueError(f"Unknown or unimplemented member: {name}")
```
```typescript TypeScript
// Datos de imagen de marcador de posición; un ejecutor real captura el 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 con un bloque de imagen en lugar 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 es una referencia de elemento de read_page o una coordenada del 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();
}
// Maneja otras acciones según sea necesario
throw new Error(`Unknown or unimplemented member: ${action}`);
}
```
```csharp C#
// Datos de imagen de marcador de posición; un ejecutor real captura el viewport y devuelve los 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 es {"type": "ref", "ref": "ref_1"} o {"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 con un bloque de imagen en lugar de texto: devuelve la lista de contenido del 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(),
// Maneja otras acciones según sea necesario
_ => throw new NotSupportedException($"Unknown or unimplemented member: {action}"),
};
```
```go Go
// placeholderPNG sustituye a una captura real: un ejecutor devuelve el
// viewport como datos PNG codificados en base64.
const placeholderPNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
// textContent envuelve texto como contenido 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 devuelve un bloque de imagen en lugar 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 es una referencia de elemento de read_page o una coordenada del 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
// Maneja otras acciones según sea necesario
default:
return nil, fmt.Errorf("unknown or unimplemented member: %s", action)
}
// Se alcanza cuando a la entrada de un miembro le falta un campo o un campo tiene el tipo incorrecto
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 es {"type": "ref", "ref": "ref_1"} o {"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());
// Maneja otras acciones según sea necesario
default -> throw new UnsupportedOperationException("Unknown or unimplemented member: " + action);
};
return ToolResultBlockParam.Content.ofString(output);
}
```
```php PHP
// Sustituto de bytes PNG reales; un ejecutor real captura el 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
{
// Un objetivo es una referencia de elemento de read_page o find, o una coordenada de píxel del 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 con un bloque de imagen en lugar de texto, así que devuelve la lista de contenido del 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(),
// Maneja otras acciones según sea necesario
default => throw new \RuntimeException("Unknown or unimplemented member: {$name}"),
};
}
```
```ruby Ruby
# Datos de imagen de ejemplo; un ejecutor real captura el 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 es una referencia a un elemento (de read_page o find) o una coordenada
click(input[:target])
when "type"
type_text(input[:text])
when "screenshot"
capture_screenshot
# Maneja otras acciones según sea necesario
else
raise ArgumentError, "Unknown or unimplemented member: #{name}"
end
end
```
La segunda parte ejecuta un lote en orden, despacha cada bloque a esos controladores, repite `toolset_name` en cada resultado y aplica la regla de detención de [Acciones por lotes](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#batch-actions), convirtiendo un error del controlador en un resultado de error. El bucle de muestreo que la llama es el que se muestra en [Comprender el bucle de agente](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool#understanding-the-agentic-loop), con el conjunto de herramientas del navegador en `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:
# Solo se declara el conjunto de herramientas del navegador; enruta otras herramientas aquí si las agregas
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:
# Una cadena o una lista de bloques de contenido; un ejecutor real también agrega un
# bloque browser_state a los resultados de navegación y gestión de pestañas
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 ejemplo declara solo el conjunto de herramientas del navegador; enruta otras herramientas
// aquí si las agregas.
continue;
}
if (failed) {
// Un lote se detiene en su primer fallo; responde las acciones posteriores como no ejecutadas
toolResults.push(browserResult(block.id, HALT_TEXT, true));
continue;
}
try {
// Una cadena o una lista de bloques de imagen; un ejecutor real también agrega un
// bloque browser_state a los resultados de navegación y gestión de pestañas
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 ejemplo declara solo el conjunto de herramientas del navegador; enruta otras herramientas
// aquí si las agregas.
continue;
}
if (failed)
{
// Un lote se detiene en su primer fallo; responde las acciones posteriores sin ejecutarlas
toolResults.Add(
new ToolResultBlockParam(toolUse.ID)
{
Content = HaltText,
IsError = true,
ToolsetName = "browser",
}
);
continue;
}
try
{
// Una cadena o una lista de bloques de contenido; un ejecutor real también agrega un
// bloque browser_state a los resultados de navegación y gestión de pestañas
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 construye el resultado de una acción del navegador. A diferencia de un
// resultado de herramienta ordinario, debe repetir el nombre del toolset. Un ejecutor real también
// agrega un bloque browser_state a los resultados de navegación y gestión de pestañas.
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 ejecuta en orden las acciones del navegador en la respuesta de Claude y
// construye un tool_result por cada bloque tool_use. Tras el primer fallo omite
// el resto: Claude las planificó asumiendo que las acciones anteriores tuvieron éxito.
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 ejemplo declara solo el toolset del navegador; enruta aquí otras herramientas si las agregas.
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 ejemplo declara solo el conjunto de herramientas del navegador; enruta otras herramientas aquí si las agregas.
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);
// Un ejecutor real también agrega un bloque browser_state a los resultados de navegación y
// de gestión de pestañas; consulta "Rastrear pestañas con browser_state" en esta 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 ejemplo declara solo el conjunto de herramientas del navegador; enruta otras herramientas aquí si las agregas.
if (!($block instanceof \Anthropic\Messages\ToolUseBlock) || $block->toolsetName !== 'browser') {
continue;
}
$result = ['type' => 'tool_result', 'tool_use_id' => $block->id, 'toolset_name' => 'browser'];
if ($failed) {
// Un lote se detiene en su primer fallo; las acciones restantes se responden sin ejecutarse
$toolResults[] = [...$result, 'content' => HALT_TEXT, 'is_error' => true];
continue;
}
try {
// Un ejecutor real también devuelve un bloque browser_state en resultados de navegación y gestión de pestañas
$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."
# Ejecuta en orden las acciones del navegador de la respuesta de Claude y crea un
# tool_result por cada bloque tool_use. Tras el primer fallo, omite el resto:
# Claude las planificó asumiendo que las acciones anteriores tuvieron éxito.
def process_tool_calls(response)
tool_results = []
failed = false
response.content.each do |block|
# Este ejemplo declara solo el conjunto de herramientas del navegador; enruta aquí otras
# herramientas si las agregas.
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
# Un String, o bloques de contenido para una captura de pantalla. Un ejecutor real también
# agrega un bloque browser_state a los resultados de navegación y gestión de pestañas.
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
```
Despacha cada bloque según el par (`toolset_name`, `name`) en lugar de solo según `name`, porque una herramienta personalizada en la misma solicitud puede compartir el nombre de un miembro; [Conjuntos de herramientas de cliente](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference#client-toolsets) describe las partes de este contrato que comparten ambos conjuntos de herramientas. Si Claude nombra un miembro que tu ejecutor no implementa, o uno que deshabilitaste, responde a ese bloque con un [resultado de error](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor) en lugar de descartarlo.
Cuando haces streaming de la respuesta, el `input` de cada miembro llega como un único `input_json_delta` completo en lugar de en fragmentos, así que espera a que termine el turno antes de ejecutar el lote.
### Acciones por lotes
Un turno con varias llamadas a miembros es una acción por lotes: ejecuta las llamadas en el orden en que aparecen, detente en el primer fallo y responde a cada llamada posterior con `is_error: true` y el texto exacto `Not executed: an earlier action in this turn failed.` Un lote usa la misma forma de respuesta que el [uso de herramientas en paralelo](https://platform.claude.com/docs/es/agents-and-tools/tool-use/parallel-tool-use); la diferencia es que ejecutas los bloques en orden en lugar de simultáneamente. Aquí Claude hace clic en el cuadro de búsqueda que encontró antes, escribe una consulta y presiona Enter en un solo 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" }
}
]
}
```
Tu aplicación devuelve tres bloques `tool_result` en un mensaje `user`, cada uno con `toolset_name` y un breve acuse de recibo en texto como `Clicked element ref_3.` Presionar Enter carga una página de resultados, por lo que el resultado de `key` también lleva un bloque `browser_state` con la URL actualizada de la pestaña ([Contexto de pestañas en otros resultados](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#tab-context-on-other-results)). Si, en cambio, el clic hubiera fallado, su resultado llevaría tu texto de error y los otros dos resultados llevarían el texto de detención, como se muestra en [Devolver errores desde tu ejecutor](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor).
No necesitas devolver una captura de pantalla después de cada llamada. Claude normalmente termina un lote con una llamada de observación (`screenshot`, `read_page` o `get_page_text`), y tu aplicación también puede adjuntar su propia observación, como una captura de pantalla nueva o un árbol de accesibilidad, como un bloque de contenido adicional en el último resultado del lote para ahorrar un viaje de ida y vuelta. Como el resultado de una llamada de gestión de pestañas debe ser exactamente un bloque `browser_state`, adjúntala al último resultado que no sea una llamada de gestión de pestañas.
Si tu ejecutor solo puede ejecutar una llamada por viaje de ida y vuelta, establece `disable_parallel_tool_use` en `true` en `tool_choice` y Claude devolverá como máximo una llamada a miembro por turno, a costa de más viajes de ida y vuelta ([Deshabilitar el uso de herramientas en paralelo](https://platform.claude.com/docs/es/agents-and-tools/tool-use/parallel-tool-use#disable-parallel-tool-use)). El resto del contrato descrito en [Acciones por lotes para la herramienta de uso de computadora](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool#batch-actions) se aplica igualmente, incluido un `tool_result` por cada `tool_use` en el siguiente mensaje `user`, salvo dos cosas: el texto de detención y lo que contiene el `content` de un resultado exitoso. En su lugar, el contenido del resultado sigue lo indicado en [Herramientas miembro](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#member-tools) en esta página: un resultado de `new_tab`, `switch_tab`, `close_tab` o `list_tabs` es exactamente un bloque `browser_state` sin texto ni imagen ([Resultados de gestión de pestañas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#tab-management-results)), y el resultado de cualquier otro miembro puede agregar un bloque `browser_state` a su texto o imagen ([Contexto de pestañas en otros resultados](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#tab-context-on-other-results)). Dónde surten efecto los puntos de interrupción de caché dentro de un lote se describe en la fila `cache_control` de los [Parámetros de la herramienta](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool#tool-parameters) de la herramienta de uso de computadora.
### Objetivos y coordenadas
Las herramientas miembro que actúan sobre una ubicación toman un objeto `target`, que es una coordenada en píxeles del viewport o una referencia a un elemento que devolvió `read_page` o `find`. Las tablas de [Herramientas miembro](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#member-tools) escriben `Target` para un parámetro que acepta cualquiera de las dos formas.
| Forma | `target.type` | Campos | Aceptado por |
| ------------------ | -------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CoordinateTarget` | `"coordinate"` | `x`, `y` (enteros, píxeles del viewport) | `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click`, `hover`, `left_click_drag` (`from` y `target`), `left_mouse_down`, `left_mouse_up`, `mouse_move`, `scroll` |
| `RefTarget` | `"ref"` | `ref` (una referencia de elemento como `"ref_2"`) | `left_click`, `right_click`, `middle_click`, `double_click`, `triple_click`, `hover`, `scroll_to`, `form_input`, `file_upload` |
**Las coordenadas son píxeles del viewport**, el espacio de píxeles de un `screenshot` del viewport completo con el origen en la esquina superior izquierda de la página renderizada; no hay escritorio ni marco de ventana alrededor. El conjunto de herramientas no declara dimensiones de pantalla y Claude infiere el tamaño del viewport a partir de las capturas de pantalla que devuelves, así que mantenlas con un tamaño uniforme. Un `zoom` no cambia el marco, por lo que su `region` y cualquier coordenada que Claude emita después de ver la imagen ampliada siguen siendo píxeles del viewport completo.
**Las capturas de pantalla deben ajustarse a los límites de imagen.** La API no reduce la escala de las imágenes del conjunto de herramientas: se rechaza cualquier captura de pantalla o imagen de zoom que supere los [límites de tamaño de imagen](https://platform.claude.com/docs/es/build-with-claude/vision#evaluate-image-size) de tu modelo, o el límite por imagen más estricto que se aplica cuando una solicitud contiene [más de 20 imágenes](https://platform.claude.com/docs/es/build-with-claude/vision#request-limits). Redimensiona antes de devolverlas y vuelve a escalar las coordenadas de Claude por el inverso de tu factor antes de despacharlas ([Dimensiona las capturas de pantalla para ajustarse a los límites de imagen](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)).
**Las referencias de elementos provienen de `read_page` y `find`.** Cada elemento en su salida lleva una etiqueta como `[ref_2]`, como en el resultado del Inicio 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 devuelve una referencia como un objetivo `{"type": "ref", "ref": "ref_2"}` en una llamada posterior de clic, `hover`, `scroll_to`, `form_input` o `file_upload`, o como el parámetro `ref` en `read_page` para leer un subárbol. Tu ejecutor asigna las referencias, mantiene la correspondencia de cada una con el nodo subyacente (un ID de nodo de accesibilidad, un selector almacenado o equivalente) y actúa sobre ese nodo cuando una referencia regresa.
Las referencias están limitadas a la pestaña que las produjo y siguen siendo válidas hasta que esa pestaña navega o su DOM cambia sustancialmente. La API no puede detectar una referencia obsoleta o desconocida, así que cuando Claude pase una referencia que tu ejecutor ya no reconoce, devuelve un resultado de error como `Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references.` Claude entonces vuelve a leer la página. No renumeres las referencias que ya entregaste para una pestaña hasta que esta navegue, porque eso invalida silenciosamente referencias que Claude aún conserva.
Claude usa ambos estilos de selección de objetivos y alterna entre ellos según lo que expone la página; tu prompt y lo que devuelve tu ejecutor orientan la elección:
* **Prefiere referencias cuando la página tiene un árbol de accesibilidad utilizable.** Una referencia sobrevive a los cambios de diseño y reflujos que hacen frágiles las coordenadas en píxeles, y permite que Claude actúe sobre controles difíciles de alcanzar con un puntero.
* **Recurre a coordenadas para el contenido que el árbol no describe.** Las interfaces renderizadas en canvas, las superficies de video incrustado o de escritorio remoto, las listas muy virtualizadas y los elementos dentro de iframes de origen cruzado a menudo no tienen un nodo útil, por lo que Claude trabaja a partir de `screenshot` y `zoom` y hace clic por coordenadas; tu ejecutor determina en qué marco cae una coordenada.
* **Limita el alcance de las lecturas y lee el árbol antes de tomar una captura de pantalla.** En páginas grandes, `read_page` con `filter: "interactive"` o con el `ref` de un contenedor devuelve un subárbol enfocado, y una lectura del árbol de una página típica a menudo cuesta menos tokens de entrada que una captura de pantalla, a la vez que le da a Claude referencias sobre las que puede actuar de inmediato. Las capturas de pantalla siguen siendo la observación adecuada cuando importan el diseño visual, las imágenes o el estado de renderizado.
## Consideraciones de seguridad
El uso del navegador conlleva riesgos que las funciones estándar de la API no tienen, porque Claude lee y actúa sobre contenido de la web abierta, donde cualquier página puede contener texto escrito para manipularlo.
Para reducir estos riesgos, toma precauciones como las siguientes:
1. Ejecuta el navegador y tu ejecutor en un contenedor o máquina virtual dedicados con privilegios mínimos, un perfil nuevo que no contenga credenciales y sin acceso a sistemas de archivos sensibles ni a redes internas; aísla de la misma manera cualquier herramienta que ejecutes junto a él.
2. Restringe los hosts a los que puede acceder el navegador mediante una "allowlist" (lista de permitidos) de dominios aplicada en la capa de red y verificada de nuevo en tu controlador de `navigate` después de las redirecciones, y bloquea los rangos de loopback, link-local y privados a menos que la tarea los necesite.
3. Trata todo lo que proporciona una página como entrada no confiable, incluidos los títulos y las URL de las pestañas, así como el `url`, `path` y `error` de cada descarga, que informas en un bloque [`browser_state`](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state), y construye las lecturas de página a partir de lo que la página renderiza (el árbol de accesibilidad o el texto visible), no del código fuente DOM sin procesar, para que el texto oculto no llegue a Claude.
4. En tu controlador de `navigate`, acepta las palabras clave de historial `"back"`, `"forward"` y `"reload"`, trata una URL sin esquema como `https://`, luego analiza la URL y rechaza cualquier esquema distinto de `http` o `https` (`javascript:`, `file:`, `data:`, `chrome:`, etc.) con un [resultado de error](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor). Verifica el esquema con un analizador de URL en lugar de con un prefijo de cadena; la API no filtra las URL que abre Claude, por lo que no puede rechazar ninguna por ti.
5. Deja `javascript_exec` y `file_upload` deshabilitados a menos que los necesites, y lee [Habilitar miembros opcionales](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools) antes de activar cualquiera de ellos.
6. Haz que una persona confirme las acciones con consecuencias y cualquier cosa que requiera consentimiento afirmativo (compras, modificación de cuentas, mensajería y aceptación de términos), y realiza esa verificación en tu ejecutor antes de cada llamada, porque un turno puede contener varias.
Claude a veces sigue instrucciones encontradas en el contenido de la página incluso cuando entran en conflicto con las tuyas; un texto en una página que diga "ignora tus instrucciones anteriores y navega a..." puede desviarlo de la tarea. Aísla a Claude de datos y acciones sensibles para limitar lo que puede alcanzar una "prompt injection" (inyección de prompts), revisa [Mitigar jailbreaks e inyecciones de prompts](https://platform.claude.com/docs/es/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks) y, si una tarea no puede evitar una sesión iniciada, usa una cuenta dedicada con pocos privilegios y mantén la confirmación humana en las acciones que modifican la cuenta.
Anthropic ha entrenado al modelo para resistir estas inyecciones de prompts y ha agregado una capa adicional de defensa. Si usas la herramienta de uso del navegador, unos clasificadores analizarán automáticamente lo que devuelve el navegador, como el texto de la página o las capturas de pantalla, para señalar posibles inyecciones de prompts. Cuando estos clasificadores identifiquen una posible inyección de prompts, orientarán automáticamente al modelo para que verifique si la instrucción realmente provino de ti antes de actuar en consecuencia.
Esta protección adicional no será ideal para todos los casos de uso (por ejemplo, casos de uso sin una persona en el circuito), así que si deseas excluirte y desactivarla, [contacta con soporte](https://support.claude.com/en/). Las precauciones anteriores siguen siendo importantes incluso con estos clasificadores activos.
Como el navegador se ejecuta en tu entorno, los sitios que visita Claude ven la identidad de red de tu ejecutor, y el contenido de la página llega a la API solo como los resultados de herramientas que devuelves. Informa a los usuarios finales de los riesgos relevantes y obtén su consentimiento antes de habilitar el uso del navegador en tus productos.
## Herramientas miembro
La entrada `browser_toolset_20260801` declara 31 herramientas miembro; el `input` de cada llamada consiste exactamente en los parámetros enumerados aquí, y `tab_id`, cuando es opcional, toma como valor predeterminado la pestaña activa. `Target`, `CoordinateTarget` y `RefTarget` son las formas descritas en [Objetivos y coordenadas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#targets-and-coordinates). Cuatro miembros (`javascript_exec`, `file_upload`, `read_console` y `read_network`) están deshabilitados de forma predeterminada y solo aparecen cuando [los habilitas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools). Los límites de entrada y las convenciones de salida indicados en la fila de cada miembro se le comunican a Claude, pero la API no los aplica, así que valida las entradas (incluidas las coordenadas con respecto a tu viewport) y aplica las convenciones en tu ejecutor.
Solo `screenshot` y `zoom` requieren un [bloque `image`](https://platform.claude.com/docs/es/agents-and-tools/tool-use/handle-tool-calls#handling-results-from-client-tools) en su resultado, y los cuatro miembros de gestión de pestañas (`new_tab`, `list_tabs`, `switch_tab` y `close_tab`) devuelven exactamente un bloque `browser_state` (consulta [Resultados de gestión de pestañas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#tab-management-results)). Todos los demás miembros devuelven un bloque `text`: ya sea un breve acuse de recibo como `Clicked element ref_2.` o la salida del miembro. Cualquier resultado que no sea de gestión de pestañas también puede llevar un bloque `image`, normalmente una captura de pantalla tomada después de la acción, para que Claude vea el resultado sin una llamada `screenshot` separada; [Acciones por lotes](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#batch-actions) muestra dónde adjuntar una en un lote. Un `tool_result` de miembro solo puede contener bloques de contenido `text`, `image` y `browser_state`.
### Navegación y captura
| Miembro | Entrada | Descripción |
| ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `navigate` | `url`, `tab_id?` | Carga una URL `http` o `https`, o muévete por el historial con `"back"`, `"forward"` o `"reload"`. Trata una URL sin esquema como `https://` y rechaza cualquier otro esquema con un resultado de error. Devuelve un breve acuse de recibo, más un bloque `browser_state` cuando cambió la URL o el título de la pestaña. |
| `screenshot` | `tab_id?` | Captura el viewport y devuelve un bloque `image`. |
| `zoom` | `region`, `tab_id?` | Devuelve una `image` recortada y ampliada de `region`, expresada como `[x0, y0, x1, y1]` en píxeles del viewport, para inspeccionar de cerca texto o controles pequeños. |
### Puntero
| Miembro | Entrada | Descripción |
| ----------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `left_click` | `target: Target`, `modifiers?`, `tab_id?` | Haz clic izquierdo en una coordenada o en un elemento referenciado. `modifiers` es una combinación de teclas que se mantiene presionada durante el clic, por ejemplo, `"shift"` o `"ctrl+shift"`. |
| `right_click` | `target: Target`, `modifiers?`, `tab_id?` | Haz clic derecho en una coordenada o elemento. |
| `middle_click` | `target: Target`, `modifiers?`, `tab_id?` | Haz clic con el botón central en una coordenada o elemento. |
| `double_click` | `target: Target`, `modifiers?`, `tab_id?` | Haz doble clic izquierdo en una coordenada o elemento. |
| `triple_click` | `target: Target`, `modifiers?`, `tab_id?` | Haz triple clic izquierdo en una coordenada o elemento, lo que normalmente selecciona una línea o un párrafo. |
| `hover` | `target: Target`, `tab_id?` | Mueve el puntero sobre una coordenada o elemento sin hacer clic. |
| `left_click_drag` | `from: CoordinateTarget`, `target: CoordinateTarget`, `tab_id?` | Presiona en `from`, arrastra hasta `target` y suelta. |
| `left_mouse_down` | `target: CoordinateTarget`, `tab_id?` | Presiona y mantén el botón izquierdo en una coordenada; combínalo con `left_mouse_up` para un arrastre personalizado. |
| `left_mouse_up` | `target: CoordinateTarget`, `tab_id?` | Suelta el botón izquierdo en una coordenada. |
| `mouse_move` | `target: CoordinateTarget`, `tab_id?` | Mueve el puntero a una coordenada. |
| `scroll` | `target: CoordinateTarget`, `scroll_direction`, `scroll_amount?`, `tab_id?` | Desplázate en una posición del viewport. `scroll_direction` es `"up"`, `"down"`, `"left"` o `"right"`; `scroll_amount` se expresa en muescas de la rueda de desplazamiento, de 1 a 10, con valor predeterminado 3. |
| `scroll_to` | `target: RefTarget`, `tab_id?` | Desplaza un elemento referenciado hasta que quede visible. |
### Teclado y temporización
| Miembro | Entrada | Descripción |
| ---------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `text`, `tab_id?` | Escribe una cadena literal en el foco actual. |
| `key` | `text`, `repeat?`, `tab_id?` | Presiona una tecla o combinación. `text` es una sola tecla (`"Enter"`), una combinación unida con `+` (`"ctrl+a"`) o una secuencia separada por espacios (`"Backspace Backspace"`); `repeat` va de 1 a 100, con valor predeterminado 1. |
| `hold_key` | `text`, `duration`, `tab_id?` | Mantén presionada una tecla o combinación durante `duration` segundos, de 0 a 30. |
| `wait` | `duration`, `tab_id?` | Haz una pausa de `duration` segundos, de 0 a 30. |
### Lectura de páginas
| Miembro | Entrada | Descripción |
| --------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read_page` | `filter?`, `depth?`, `ref?`, `tab_id?` | Devuelve el árbol de accesibilidad de la página como texto, con cada elemento etiquetado con una referencia como `[ref_2]`. Si se omite `filter`, devuelve todos los elementos visibles; con `"interactive"`, solo los elementos interactivos visibles; con `"all"`, también los elementos fuera del viewport. `depth` limita la profundidad del árbol (mínimo 1, valor predeterminado 15) y `ref` limita la lectura al subárbol de ese elemento. Limita la salida a 50,000 caracteres e indícalo en el texto; Claude entonces acota con un `depth` menor o un `ref`. |
| `find` | `query`, `tab_id?` | Busca elementos que coincidan con una descripción en lenguaje natural como `"search field"` o `"add to cart button"`, y devuelve hasta 20 coincidencias en el mismo formato etiquetado que `read_page`. |
| `get_page_text` | `tab_id?` | Devuelve el texto visible de la página como texto sin formato, priorizando el contenido principal del artículo; adecuado para artículos, documentación y otras páginas con mucho texto. |
### Formularios y archivos
| Miembro | Entrada | Descripción |
| ----------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `form_input` | `target: RefTarget`, `value`, `tab_id?` | Establece directamente el valor de un elemento de formulario. `value` es un `string`, `number` o `boolean`; usa un `boolean` para las casillas de verificación y el valor o el texto visible de una opción para los selectores. |
| `file_upload` (deshabilitado de forma predeterminada) | `target: RefTarget`, `paths?`, `document_ids?`, `tab_id?` | Establece los archivos en un elemento de entrada de archivos a partir de `paths` en el sistema de archivos del ejecutor, de `document_ids` que tu aplicación haya preparado, o de ambos; se requiere al menos uno. Consulta [Subir archivos](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#upload-files). |
### Diagnóstico y scripting
| Miembro | Entrada | Descripción |
| --------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read_console` (deshabilitado de forma predeterminada) | `tab_id?` | Devuelve las entradas de consola de la pestaña (líneas de registro, advertencia y error) acumuladas desde la última lectura, una línea por entrada. Consulta [Leer la actividad de consola y de red](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#read-console-and-network-activity). |
| `read_network` (deshabilitado de forma predeterminada) | `tab_id?` | Devuelve las solicitudes de red de la pestaña (método, URL, estado, tipo MIME, tiempos) desde la última lectura, una línea por entrada. |
| `javascript_exec` (deshabilitado de forma predeterminada) | `text`, `tab_id?` | Ejecuta `text` como JavaScript en el contexto de la página y devuelve el valor de la última expresión como texto. Consulta [Habilitar miembros opcionales](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools). |
### Gestión de pestañas
| Miembro | Entrada | Descripción |
| ------------ | ---------------------- | ---------------------------------------------------- |
| `new_tab` | (ninguna) | Abre una pestaña y conviértela en la pestaña activa. |
| `list_tabs` | (ninguna) | Informa el inventario de pestañas. |
| `switch_tab` | `tab_id` (obligatorio) | Convierte `tab_id` en la pestaña activa. |
| `close_tab` | `tab_id` (obligatorio) | Cierra `tab_id`. |
Si tienen éxito, cada uno de estos devuelve exactamente un bloque `browser_state` y ningún texto ni imagen; consulta [Resultados de gestión de pestañas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#tab-management-results).
## Configurar el conjunto de herramientas
Además de `type`, la entrada del conjunto de herramientas acepta `configs`, `cache_control` y `allowed_callers`; las reglas que estos campos comparten con el conjunto de herramientas de uso de computadora se enumeran en [Conjuntos de herramientas de cliente](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference#client-toolsets), y esta sección cubre los valores predeterminados específicos del navegador. `configs` es un objeto cuyas claves son nombres de miembros, y el valor de cada miembro acepta dos campos:
| Campo | Valor predeterminado | Significado |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled` | `true`, excepto `false` para los cuatro [miembros opcionales](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools) | Si el miembro se ofrece a Claude. |
| `defer_loading` | `false` | Si la definición del conjunto de herramientas se difiere para la búsqueda de herramientas. Debe resolverse al mismo valor en todos los miembros habilitados. Con los cuatro miembros opcionales deshabilitados, diferir el conjunto de herramientas significa establecerlo en los otros 27; consulta [Conjuntos de herramientas de cliente](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference#client-toolsets). |
### Habilitar o deshabilitar herramientas miembro
Enumera en `configs` solo los miembros que quieras cambiar; cada miembro que omitas conserva su valor predeterminado. Por ejemplo, un ejecutor que implementa lecturas de consola pero no el control de bajo nivel del puntero ni el de mantener teclas presionadas activa `read_console` y retiene tres miembros:
```json
{
"type": "browser_toolset_20260801",
"configs": {
"read_console": { "enabled": true },
"left_mouse_down": { "enabled": false },
"left_mouse_up": { "enabled": false },
"hold_key": { "enabled": false }
}
}
```
Un miembro deshabilitado desaparece de la definición que ve Claude; eso no garantiza que Claude nunca lo nombre, así que tu ejecutor aún debe responder a esa llamada con un [resultado de error](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor).
### Combinar con otras herramientas
Declara la herramienta de uso del navegador junto con tus propias herramientas y otras herramientas proporcionadas por Anthropic en el mismo arreglo `tools`. Una herramienta personalizada puede compartir el nombre de un miembro (tu propio `navigate`, por ejemplo), porque `toolset_name` distingue las llamadas de Claude, pero ninguna otra entrada puede llamarse `browser`, y una solicitud solo puede contener una entrada de conjunto de herramientas del navegador.
También puedes declararla junto con la [herramienta de uso de computadora](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool), ya sea el conjunto de herramientas o una versión anterior de la herramienta de uso de computadora. Ambas funcionan de forma independiente, cada una en su propio marco de coordenadas (aquí, píxeles del viewport; allí, píxeles de capturas de pantalla del escritorio), y las llamadas de Claude a miembros que comparten nombre, como `screenshot` o `key`, se distinguen por `toolset_name`.
## Habilitar miembros opcionales
Cuatro herramientas miembro están deshabilitadas de forma predeterminada: `javascript_exec` y `file_upload` porque amplían lo que una página manipulada podría hacer que Claude haga, y `read_console` y `read_network` porque no todas las pilas de automatización de navegadores pueden proporcionar esos registros y porque amplían el contenido controlado por la página que llega a Claude. Habilita cada uno con `configs` (por ejemplo, `"configs": {"file_upload": {"enabled": true}}`) solo cuando tu ejecutor lo implemente y la tarea lo necesite.
### Subir archivos
`file_upload` establece directamente los archivos en un elemento ``, lo cual es más confiable que controlar un selector de archivos nativo. Su `target` es solo una referencia, porque la llamada necesita la identidad del elemento, y acepta `paths`, `document_ids` o ambos:
* `paths` son rutas de archivo en el sistema de archivos del ejecutor, para implementaciones en las que el ejecutor puede leer directamente los archivos de tu aplicación (la misma condición bajo la cual completas el `path` de una descarga).
* `document_ids` son identificadores de archivos que tu aplicación ha preparado para el navegador, para implementaciones en las que el ejecutor no puede hacerlo. Tu aplicación define qué significan los identificadores; limita su resolución de la misma forma en que limitas `paths`, a los archivos preparados para esta tarea.
```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 escribe estas rutas mientras lee páginas no confiables, por lo que una implementación sin restricciones permitiría que una página maliciosa dirigiera la subida de cualquier archivo que el ejecutor pueda leer a un sitio que la página controla. Habilita el miembro solo cuando tu ejecutor resuelva cada ruta (siguiendo enlaces simbólicos y segmentos `..`) y no acepte nada fuera de un directorio de subida dedicado e incluido en la lista de permitidos que contenga solo archivos destinados a la tarea. No reutilices para esto el directorio de descargas del navegador; si lo haces, cualquier archivo que una página haga descargar al navegador se vuelve susceptible de subirse.
### Ejecutar JavaScript en la página
`javascript_exec` ejecuta la expresión que escribe Claude en el contexto de la página y devuelve el valor de la última expresión como texto; Claude escribe una expresión, no una sentencia `return`. El código se ejecuta con todos los privilegios de la página, incluidas sus cookies, su almacenamiento y sus solicitudes del mismo origen. Habilita el miembro solo en sesiones que no contengan credenciales, mantén vigente la lista de permitidos de dominios de [Consideraciones de seguridad](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#security-considerations), trata el valor devuelto como entrada no confiable y registra el código que emite Claude.
### Leer la actividad de consola y de red
`read_console` devuelve las entradas de consola de la pestaña y `read_network` devuelve sus solicitudes de red, cada uno como texto con una línea por entrada acumulada desde la lectura anterior de esa pestaña. Una línea de consola contiene una entrada de registro, advertencia o error; una línea de red contiene el método, la URL, el estado, el tipo MIME y los tiempos. Las entradas existen solo desde el momento en que tu automatización del navegador se conectó a la pestaña, por lo que un resultado vacío no significa que una pestaña que ya estaba abierta no tuviera tráfico.
Estos miembros permiten que Claude diagnostique una página que se comporta mal (una solicitud fallida detrás de un indicador de carga, un error de script detrás de un botón que no responde) sin capturas de pantalla repetidas. Las entradas de consola y de red están controladas por la página y a menudo contienen secretos, como tokens en las URL de solicitud, así que oculta los valores similares a credenciales que no quieras en el contexto de Claude y trunca las entradas muy largas antes de devolverlas.
## Rastrea pestañas con `browser_state`
Claude identifica las pestañas mediante `tab_id`. Tu aplicación es la fuente de verdad sobre qué pestañas existen, y tú informas ese estado en un bloque de contenido `browser_state` que Claude nunca ve directamente: la API genera a partir de él el texto que Claude lee.
```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` es el inventario completo de pestañas abiertas después de la llamada, no un delta. Puede estar vacío; cuando no lo está, exactamente una entrada lleva `"active": true`.
* `state_changes` (no se muestra aquí) informa los efectos secundarios de la llamada. Incluye una entrada `tab_opened` por cada pestaña que la llamada abrió y que sigue abierta cuando termina, cuyo `tab_id` también debe aparecer en `tabs`, y los [eventos de descarga](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#report-downloads). Omite el campo cuando no haya nada que informar; un arreglo vacío se rechaza.
* Envía el bloque solo en resultados que respondan a una llamada a un miembro del navegador, como máximo una vez por `tool_result`, y nunca en un resultado con `is_error: true`. Para indicar que "no hay estado de pestañas que informar", omite el bloque.
* La API convierte `tabs`, y cualquier entrada de descarga en `state_changes`, en texto para Claude. Las dos secciones siguientes y [Informa las descargas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#report-downloads) muestran ese texto.
**Tú asignas los valores de `tab_id`.** Sirve cualquier cadena estable, como el identificador de página de tu biblioteca de automatización o tu propio contador. La única condición es que no reutilices un `tab_id` mientras una pestaña con ese identificador siga figurando como abierta en un resultado anterior. La API aplica estos límites al bloque:
* Cada `tab_id`, `title` y `url` puede tener como máximo 4,096 caracteres. `tab_id` no puede estar vacío, y ninguno puede contener caracteres de control (incluidos los saltos de línea) ni separadores Unicode de línea o de párrafo.
* Un bloque puede enumerar como máximo 100 pestañas y 200 cambios de estado.
* Los mismos límites se aplican al `tab_id` que Claude pasa a `switch_tab` y `close_tab`, porque la API lo incluye en el texto del resultado. Por eso, responde a una llamada cuyo `tab_id` los infrinja con un resultado de error en lugar de un bloque `browser_state`.
Los títulos y las URL de las pestañas provienen de la página y se convierten en texto que Claude lee, por lo que son una superficie de "prompt injection" (inyección de prompts). La API muestra las URL de las pestañas textualmente, así que sanea las URL proporcionadas por la página antes de rellenar `tabs`. La API escapa las comillas dobles y las barras invertidas de los títulos al mostrarlos, así que no escapes los títulos de antemano (un título escapado previamente llega a Claude doblemente escapado). Aun así, vale la pena truncar o descartar los títulos sospechosos. Los campos `url`, `path` y `error` de una entrada de descarga también se convierten en texto que Claude lee, así que trátalos también como no confiables; la API los entrecomilla y los escapa igual que los títulos. Los límites de longitud y de caracteres que aplica la API son un mínimo, no una defensa.
### Resultados de gestión de pestañas
Para `new_tab`, `switch_tab`, `close_tab` y `list_tabs`, el `content` de un resultado exitoso es exactamente un bloque `browser_state`, sin texto ni imagen, y la API escribe el texto que ve Claude. El bloque de un resultado de `new_tab` también debe llevar exactamente un cambio de estado `tab_opened` cuyo `tab_id` coincida con la entrada marcada con `active: true`.
| Miembro | Texto que ve Claude |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `switch_tab` | `Switched to tab {tab_id}`, tomado del `input.tab_id` de la llamada |
| `close_tab` | `Closed tab {tab_id}`, tomado del `input.tab_id` de la llamada |
| `new_tab` | `Created new tab with tab_id: {tab_id}, URL: {url}. It is now the current tab.`, tomado de la entrada marcada con `active: true` |
| `list_tabs` | `Available tabs:` seguido de una línea por pestaña, o `No tabs available` cuando `tabs` está vacío |
Supón un resultado de `list_tabs` cuyo bloque enumera dos pestañas, con la primera activa. Se muestra de la siguiente manera: cada línea lleva una sangría de dos espacios y solo la pestaña activa lleva `(current)` al final:
```text wrap
Available tabs:
• tab_id tab-1: "Documentation" (https://example.com/docs) (current)
• tab_id tab-2: "Pricing" (https://example.com/pricing)
```
Un resultado de error para uno de estos miembros es lo contrario: texto de error normal en `content`, `is_error: true` y ningún bloque `browser_state`.
Por ejemplo, cuando Claude llama a `new_tab` (su `input` está vacío), tu ejecutor abre la pestaña, la activa y devuelve el inventario con una 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 ve `Created new tab with tab_id: tab-3, URL: about:blank. It is now the current tab.` Informa la URL con la que se abrió la pestaña, como aquí, y no una a la que redirija después; los resultados posteriores informan la URL que tenga la pestaña en ese momento.
### Contexto de pestañas en otros resultados
En todos los demás miembros, el bloque es opcional. Envíalo cuando haya cambiado el conjunto de pestañas abiertas, la pestaña activa o el título o la URL de una pestaña, o cuando haya `state_changes` que informar, e incluye siempre el inventario completo de `tabs`. Cuando un resultado lleva tanto texto como un bloque `browser_state`, la API añade un pie `Tab Context` al texto de ese resultado, separado de tu texto por una línea en blanco. Así, Claude recibe el nuevo estado sin necesidad de una llamada aparte 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` indica la pestaña en la que se ejecutó la llamada: su entrada `tab_id` cuando está presente y, en caso contrario, la pestaña activa. Las líneas de pestañas del pie no llevan el marcador `(current)`. No añadas este texto tú mismo; envía el bloque estructurado y deja que la API lo genere. El pie se deduplica: un estado de pestañas idéntico no se vuelve a mostrar en resultados posteriores, así que rellenar el bloque con frecuencia no tiene ningún costo.
En tres casos no se muestra ningún pie, aunque el bloque esté presente:
* Cualquier resultado de `zoom`.
* Un resultado sin bloque `text` (por ejemplo, un resultado de `screenshot` que solo contiene una imagen). No se muestra ni se recuerda nada para ese resultado; el contexto de pestañas aparece en el siguiente resultado que lleve tanto texto como un bloque `browser_state`. Por eso, incluye un bloque de texto breve junto a la imagen cuando quieras que Claude vea un cambio de pestaña en ese mismo resultado. La excepción es un resultado cuyo bloque informa un [evento de descarga](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#report-downloads). La API añade las líneas de descarga como un bloque de texto, y el pie las sigue como lo haría en cualquier resultado con texto.
* Un resultado cuya lista `tabs` está vacía en una llamada que no llevaba `tab_id`, porque no hay ninguna pestaña que nombrar.
Por ejemplo, supón que Claude hizo clic antes en esta sesión en el enlace "Pricing" (`ref_5`) y que la página lo abrió en una pestaña nueva que Claude no pidió. Sin un informe, Claude tendría que llamar a `list_tabs` para descubrirla. Devuelve la confirmación del clic junto con un bloque cuyo `state_changes` nombre la pestaña abierta, y marca como activa la pestaña que tu ejecutor haya dejado activa:
```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 ve `Clicked element ref_5.` seguido del pie Tab Context mostrado antes. Una pestaña abierta durante una llamada que falló no recibe ninguna entrada `tab_opened`, porque los resultados de error no llevan `browser_state`; en su lugar, aparece en el inventario `tabs` del siguiente resultado exitoso. En un lote, adjunta el bloque al resultado de la llamada durante la cual ocurrió el cambio. Además, da a cada resultado exitoso de gestión de pestañas su propio bloque, incluso cuando un resultado anterior del mismo turno haya informado el mismo estado.
### Informa las descargas
Cuando un clic o una navegación inicia la descarga de un archivo, infórmala en `state_changes` en el resultado de la llamada durante la cual ocurrió. Para correlacionarla entre resultados, usa un `download_id` que tú asignas. Las descargas se ejecutan de forma asíncrona y pueden abarcar varios resultados, por lo que hay tres tipos de eventos:
| `type` | Campos | Cuándo enviarlo |
| -------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `download_started` | `download_id`, `url` | En el resultado de la llamada durante la cual comenzó la descarga. `url` es la URL final desde la que se sirve el archivo, después de las redirecciones. |
| `download_completed` | `download_id`, `url`, `path?`, `size_bytes?` | En el resultado de la llamada posterior que se esté ejecutando cuando termine la descarga. Incluye `path` solo cuando otra herramienta del mismo entorno (por ejemplo, la [herramienta bash](https://platform.claude.com/docs/es/agents-and-tools/tool-use/bash-tool) o `file_upload`) pueda leer el archivo en esa ubicación; de lo contrario, `download_id` es el único identificador de la descarga. |
| `download_failed` | `download_id`, `url`, `error?` | Cuando la descarga falla o se cancela, con el motivo en `error` si el navegador lo proporciona. |
La API convierte cada entrada en una línea de texto para Claude, en el orden en que aparecen las entradas. Añade las líneas después del texto del resultado, separadas por una línea en blanco, y antes de cualquier pie Tab Context. Todos los tipos de resultados de miembros llevan estas líneas, incluidos los resultados de `zoom` y de gestión de pestañas. Un resultado sin bloque `text` las recibe como un bloque de texto propio. Cada línea indica el `download_id` y la `url`. También incluye `path` y `size_bytes` (para `download_completed`) o `error` (para `download_failed`) cuando los envías. No necesitas describir la descarga en tu propio texto. La API encierra `url`, `path` y `error` entre comillas dobles y escapa las comillas dobles y las barras invertidas que contengan, así que no escapes estos valores de antemano.
Por ejemplo, un clic en "Download price list (CSV)" (`ref_8`) en la pestaña Pricing inicia una descarga. Por eso, el resultado del clic lleva una entrada `download_started` con el `download_id` `"dl-1"` y la URL del archivo. La descarga termina mientras se ejecuta una llamada posterior a `screenshot`. El `content` de ese resultado contiene la imagen, un bloque de texto como `Screenshot captured.` y este bloque `browser_state`, que informa la finalización con el mismo `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 ve `Screenshot captured.` seguido de una línea en blanco y una línea 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.
```
Los informes de descarga siguen estas reglas:
* Como máximo una entrada por `download_id` en un mismo bloque. Por eso, una descarga que comienza y termina durante la misma llamada informa solo `download_completed`.
* Nunca envíes `state_changes` en un resultado con `is_error: true`. Si ocurrió un evento de descarga durante una llamada fallida, infórmalo en el siguiente resultado exitoso.
* `state_changes` no es un inventario de las descargas en curso; informa cada evento una sola vez.
* Cada entrada lleva solo los campos que declara su `type`. `size_bytes` es un entero no negativo y `download_id` no puede estar vacío. Además, `download_id`, `url`, `path` y `error` tienen cada uno como máximo 4,096 caracteres, sin caracteres de control ni separadores Unicode de línea o de párrafo. La `url` proviene del servidor remoto y, después de las redirecciones, suele llevar credenciales firmadas en la cadena de consulta. Por eso, elimina los parámetros de consulta que no quieras en el contexto de Claude y sanea la URL antes de informarla o de usarla en una ruta del sistema de archivos.
## Gestiona los errores
Informa a Claude de una llamada fallida como un resultado de error normal: `is_error: true`, contenido de texto que explique qué salió mal, `toolset_name` repetido y ningún bloque `browser_state`.
### Devuelve errores desde tu ejecutor
Haz que el texto de error sea específico, porque Claude lo lee y se adapta. `Error: Navigation to https://example.com/status timed out after 30 seconds. The page may be unavailable.` le da a Claude algo con lo que actuar, mientras que un simple `Error: navigation failed` no lo hace. Otros casos comunes:
```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."
}
```
Cuando el `left_click` sobre `ref_3` de [Acciones por lotes](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#batch-actions) falla con el error de referencia obsoleta mostrado antes, cada una de las llamadas `type` y `key` posteriores recibe 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."
}
```
### Errores de solicitud
La API valida la entrada del conjunto de herramientas y cada bloque `tool_use` y `tool_result` de miembro en la conversación. Cuando alguno tiene un formato incorrecto, la API devuelve un `invalid_request_error` antes de que Claude se ejecute. En la siguiente tabla, la columna izquierda indica lo que enviaste.
| Solicitud | Por qué falla y qué hacer |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Una opción o combinación que la entrada del conjunto de herramientas no acepta. Por ejemplo: un `name`, `strict: true`, `input_examples` o `defer_loading` en la propia entrada; una clave de `configs` que no es un nombre de miembro; un campo distinto de `enabled` o `defer_loading` en el valor de `configs` de un miembro ([Configura el conjunto de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#configure-the-toolset)); miembros habilitados cuyos valores de `defer_loading` difieren ([Configura el conjunto de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#configure-the-toolset)); un `configs` que no deja ningún miembro habilitado; un llamador de ejecución de código en `allowed_callers`; el encabezado beta heredado `fine-grained-tool-streaming-2025-05-14` en la solicitud; un `tool_choice` de tipo `tool` que nombra `browser` o un miembro; o una segunda entrada de conjunto de herramientas de navegador u otra herramienta llamada `browser` | No se admiten en los conjuntos de herramientas de cliente. Consulta [Conjuntos de herramientas de cliente](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference#client-toolsets) para ver cada regla y su alternativa. |
| Un `tool_result` que responde a una llamada de miembro sin `"toolset_name": "browser"` o con un valor distinto, o un `toolset_name` en un resultado cuya llamada no era una llamada de miembro | Repite `toolset_name` exactamente en los resultados de miembros, y solo en ellos. |
| Un `tool_use` de miembro de un turno anterior sin un `tool_result` correspondiente | Responde a cada llamada de miembro, incluidas las que no ejecutaste tras un fallo. |
| Un bloque de contenido distinto de `text`, `image` o `browser_state` en un resultado de miembro | Los resultados de miembros solo aceptan esos tres tipos de bloque. |
| Un bloque `browser_state` que infringe una regla de [Rastrea pestañas con `browser_state`](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state). Por ejemplo: uno en un resultado con `is_error: true` o en un resultado que no responde a una llamada a un miembro del navegador; más de uno en un resultado; un `tabs` no vacío sin exactamente una entrada `active: true`; un `tab_id` duplicado; un arreglo `state_changes` vacío; un `tab_opened` cuyo `tab_id` no está en `tabs`; dos cambios de estado para un mismo `download_id` o un campo de cambio de estado que su `type` no declara ([Informa las descargas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#report-downloads)); o un campo que supera sus límites | Corrige el bloque. Para indicar "nada que informar", omite el bloque o el campo `state_changes`, nunca uses un valor vacío. |
| Un resultado exitoso de `new_tab`, `switch_tab`, `close_tab` o `list_tabs` cuyo `content` no es exactamente un bloque `browser_state`, o un resultado de `new_tab` sin exactamente un `tab_opened` que coincida con la pestaña activa | La API genera estos resultados a partir del bloque y lo necesita exactamente con esa forma; consulta [Resultados de gestión de pestañas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#tab-management-results). |
| Una `image` en un resultado que supera los [límites de tamaño de imagen](https://platform.claude.com/docs/es/build-with-claude/vision#evaluate-image-size) de tu modelo, o el límite por imagen más estricto que se aplica cuando la solicitud contiene [más de 20 imágenes](https://platform.claude.com/docs/es/build-with-claude/vision#request-limits), contando las capturas de pantalla y las imágenes de `zoom` de resultados anteriores | La API no reduce la escala de las imágenes del conjunto de herramientas. Redimensiona las capturas de pantalla antes de devolverlas ([Ajusta el tamaño de las capturas de pantalla a los límites de imagen](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)). |
| Un `model` que no admite `browser_toolset_20260801` | Consulta [Compatibilidad](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#compatibility) para ver los modelos compatibles. |
## Limitaciones
* **Disponibilidad por plataforma:** El uso del navegador está disponible en la Claude API y en [Google Cloud](https://platform.claude.com/docs/es/build-with-claude/claude-on-vertex-ai).
* **Solo streaming de entrada completa:** Cuando usas streaming, el `input` de cada miembro llega como un único `input_json_delta` completo ([Conjuntos de herramientas de cliente](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference#client-toolsets)).
* **Las referencias de elementos son de mejor esfuerzo:** Las páginas muy dinámicas (listas virtualizadas, interfaces renderizadas en canvas, páginas que se vuelven a renderizar al desplazarse) podrían no exponer referencias estables. En esos casos, Claude recurre a capturas de pantalla y clics por coordenadas.
* **`read_console` y `read_network` dependen de tu automatización del navegador:** Solo informan lo que esta puede capturar, y solo desde el momento en que se conectó a una pestaña.
* **Se aplican las limitaciones generales de los agentes:** La "latency" (latencia), la precisión de la visión y los riesgos de inyección de prompts se heredan del uso de computadora (consulta las [Limitaciones](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool#understand-computer-use-limitations) de la herramienta de uso de computadora). Sus recomendaciones también se aplican a los ejecutores de navegador: [Optimiza el rendimiento del modelo con prompts](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool#optimize-model-performance-with-prompting), [Gestiona el historial de capturas de pantalla](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool#manage-screenshot-history) y [Sigue las mejores prácticas de implementación](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool#follow-implementation-best-practices) (retrasos entre acciones, validación de acciones y registro).
## Precios y retención de datos
El uso del navegador sigue los [precios estándar del uso de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/overview#pricing). Al usar la herramienta de uso del navegador:
**Sobrecarga de la definición del conjunto de herramientas:** Declarar `browser_toolset_20260801` con sus miembros predeterminados agrega aproximadamente 6,600 tokens de entrada a una solicitud (aproximadamente 6,670 en Claude Sonnet 5 y aproximadamente 6,610 en los demás modelos compatibles), lo que cubre las definiciones de las herramientas miembro y la indicación del sistema de uso de herramientas. Habilitar los cuatro miembros opcionales agrega aproximadamente 880 tokens, y deshabilitar miembros con `configs` reduce el recuento. El recuento exacto de una solicitud se informa en el campo `usage` de la respuesta, y puedes estimarlo de antemano con el [endpoint de conteo de tokens](https://platform.claude.com/docs/es/build-with-claude/token-counting).
**Consumo adicional de tokens:**
* Imágenes de capturas de pantalla y de zoom devueltas en los resultados de herramientas, facturadas como entrada de imagen (consulta [Precios de visión](https://platform.claude.com/docs/es/build-with-claude/vision#evaluate-image-size))
* Resultados de herramientas de texto devueltos a Claude, como árboles de accesibilidad, texto de la página y entradas de consola o de red
Si también usas la herramienta de uso de computadora, la herramienta bash, la herramienta de editor de texto o tus propias herramientas junto con el uso del navegador, esas herramientas tienen sus propios costos de tokens, tal como se documenta en sus respectivas páginas.
La sesión del navegador, las descargas y los archivos subidos permanecen en tu entorno. Las capturas de pantalla, el texto de las páginas y el estado de las pestañas que devuelves forman parte del contenido de tu solicitud a la API y siguen la política de retención estándar, o tu acuerdo de ZDR si tienes uno. La herramienta de uso del navegador es apta para ZDR; consulta [API y retención de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention) para conocer los períodos de retención y la elegibilidad de cada función.
## Próximos pasos
Parte del controlador de un socio, o escribe el tuyo en Python o TypeScript. El SDK ejecuta el bucle y las comprobaciones que configures.
Dale a Claude el control de un escritorio completo cuando la tarea sale del navegador; su orientación de implementación también se aplica a los ejecutores de navegador.
Da formato a los bloques `tool_result`, devuelve imágenes y errores, y continúa la conversación.
Explora los conjuntos de herramientas de cliente y todas las demás herramientas proporcionadas por Anthropic, con sus versiones y parámetros.