Herramienta de uso del navegador

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 visible).

La herramienta es un conjunto de herramientas de cliente 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. Tu aplicación ejecuta cada llamada con su propia automatización del navegador; nada se ejecuta del lado de Anthropic. Actualmente, la herramienta no está disponible en Claude Managed Agents.

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, 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 y la herramienta de búsqueda web son más ligeras. Son herramientas de servidor que la API ejecuta por ti, sin ningún 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 antes de implementarla.

Inicio rápido

La herramienta de uso del navegador está disponible en la Claude API y en Google Cloud: agrega una entrada de tipo browser_toolset_20260801, sin name, al arreglo tools de una solicitud a la Messages API.

client = anthropic.Anthropic()

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

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":

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

Tu "executor" (ejecutor), 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:

{
  "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.

1. 1

   Proporciona a Claude la herramienta de uso del navegador y un prompt de usuario

   • 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."
2. 2

   Claude responde con llamadas a herramientas miembro

   • Claude devuelve uno o más bloques tool_use en un solo turno del asistente; varios en un mismo turno forman una 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.
3. 3

   Ejecuta las llamadas en orden y devuelve los resultados

   • 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 recibir respuesta 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 a cada bloque posterior del turno.
4. 4

   Claude continúa hasta completar la tarea

   • 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 nuevas 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, controladores de miembros simulados que 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.

# 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}")

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, convirtiendo un error del controlador en un resultado de error. El bucle de muestreo que la llama es el que se muestra en Comprende el bucle de agente, con el conjunto de herramientas del navegador en tools.

NOT_EXECUTED = "Not executed: an earlier action in this turn failed."


def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
    """
    Run the browser actions in Claude's response in order and answer each
    one. After the first failure the rest are skipped, because Claude planned
    them assuming the earlier actions succeeded.
    """
    tool_results: list[ToolResultBlockParam] = []
    failed = False
    for block in response.content:
        # 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

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 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 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 "batch action" (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; 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:

{
  "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 solo 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). 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 Devuelve errores desde tu ejecutor.

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 un resultado 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). El resto del contrato descrito en Acciones por lotes para la herramienta de uso de computadora 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 cambio, el contenido del resultado sigue lo indicado en Herramientas miembro 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), 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). 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 de la herramienta de uso de computadora.

Objetivos y coordenadas

Las herramientas miembro que actúan sobre una ubicación reciben 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 escriben Target para un parámetro que acepta cualquiera de las dos formas.

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 una captura de pantalla o imagen de zoom que supere los límites de tamaño de imagen 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. Redimensiona antes de devolverlas y escala las coordenadas de Claude de vuelta por el inverso de tu factor antes de despacharlas (Ajusta el tamaño de las capturas de pantalla a los límites de imagen).

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:

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 entre cada una y 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 de forma sustancial. 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 navegue, porque eso invalida silenciosamente referencias que Claude todavía conserva.

Claude usa ambos estilos de objetivo 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 coordenada; tu ejecutor determina en qué marco cae una coordenada.
• Acota las lecturas y lee el árbol antes de tomar una captura de pantalla. En páginas grandes, read_page con filter: "interactive" o el ref de un contenedor devuelve un subárbol enfocado, y una lectura del árbol de una página típica suele costar 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.

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 Mitiga jailbreaks e inyecciones de prompts 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 identifican 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 ciclo), así que si deseas excluirte y desactivarla, contacta con soporte. Las precauciones anteriores siguen siendo importantes incluso con estos clasificadores en funcionamiento.

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 son exactamente los parámetros que se enumeran 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. Cuatro miembros (javascript_exec, file_upload, read_console y read_network) están deshabilitados de forma predeterminada y solo aparecen cuando los habilitas. 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 respecto a tu viewport) y aplica las convenciones en tu ejecutor.

Solo screenshot y zoom requieren un bloque image 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). 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 muestra dónde adjuntarla en un lote. Un tool_result de miembro solo puede contener bloques de contenido text, image y browser_state.

Navegación y captura

Puntero

Teclado y temporización

Lectura de páginas

Formularios y archivos

Diagnóstico y scripting

Gestión de pestañas

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.

Configura 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, 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:

Habilita o deshabilita herramientas miembro

Enumera en configs solo los miembros que quieres cambiar; cada miembro que omitas conserva su valor predeterminado. Por ejemplo, un ejecutor que implementa lecturas de consola pero no control de bajo nivel del puntero ni de mantener teclas presionadas activa read_console y retira tres miembros:

{
  "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 debe seguir respondiendo a esa llamada con un resultado de error.

Combina 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, 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 (píxeles del viewport aquí, píxeles de la captura de pantalla del escritorio allá), y las llamadas de Claude a miembros que comparten nombre, como screenshot o key, se distinguen por toolset_name.

Habilita 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 del navegador pueden proporcionar esos registros y 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.

Sube archivos

file_upload establece directamente los archivos de un elemento <input type="file">, 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 recibe 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 no puede hacerlo. Tu aplicación define qué significan los identificadores; acota su resolución de la misma forma en que acotas paths, a los archivos preparados para esta tarea.

{
  "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 dirija 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 y permitido 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 subible.

Ejecuta 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 instrucción return. El código se ejecuta con todos los privilegios de la página, incluidas sus cookies, su almacenamiento y las solicitudes del mismo origen. Habilita el miembro solo en sesiones que no contengan credenciales, mantén vigente la lista de dominios permitidos de Consideraciones de seguridad, trata el valor devuelto como entrada no confiable y registra el código que emite Claude.

Lee 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 funciona 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 las solicitudes, 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 por 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.

{
  "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; siempre que 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. También incluye los eventos de descarga. 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 expresar "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 muestran ese texto.

Tú asignas los valores de tab_id. Cualquier cadena estable sirve, 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 listada 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 saltos de línea) ni separadores Unicode de línea o de párrafo.
• Un bloque puede listar 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.

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.

Supón un resultado de list_tabs cuyo bloque lista 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:

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 ordinario 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:

{
  "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. 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 una llamada aparte a list_tabs:

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

Executed on 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.

Hay tres casos en los que 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, y el contexto de pestañas aparece en el siguiente resultado que lleve tanto texto como un bloque browser_state. Si quieres que Claude vea un cambio de pestaña en ese mismo resultado, incluye un bloque de texto breve junto a la imagen.

  La excepción es un resultado cuyo bloque informa un evento de descarga. 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 la página lo abrió en una nueva pestaña 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:

{
  "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 "batch" (lote), adjunta el bloque al resultado de la llamada durante la cual ocurrió el cambio. Además, dale a cada resultado exitoso de gestión de pestañas su propio bloque, aunque 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:

La API convierte cada entrada en una línea de texto para Claude, en el orden en que aparecen las entradas:

• Ubicación: las líneas van después del texto del resultado, separadas por una línea en blanco, y antes de cualquier pie Tab Context.
• Resultados que las llevan: todos los tipos de resultados de miembros, incluidos los de zoom y los de gestión de pestañas. Un resultado sin bloque text las recibe como un bloque de texto propio.
• Contenido: cada línea indica el download_id y la url, además de 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.
• Escapado: 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 previamente estos valores.

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:

{
  "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:

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 lo que 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; informa un evento de descarga ocurrido durante una llamada fallida en el siguiente resultado exitoso.
• state_changes no es un inventario de 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.
• 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, a menudo lleva credenciales firmadas en la cadena de consulta. Elimina los parámetros de consulta que no quieras en el contexto de Claude, y sanéala 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 ordinario: 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:

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

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

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

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

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 está mal formado, la API devuelve un invalid_request_error antes de que Claude se ejecute. En la siguiente tabla, la columna izquierda indica lo que enviaste.

Limitaciones

• Disponibilidad por plataforma: el uso del navegador está disponible en la API de Claude y en Google Cloud.
• 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).
• 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 de la herramienta de uso de computadora). Sus recomendaciones también se aplican a los ejecutores de navegador, en concreto las de estas secciones:
  • Optimiza el rendimiento del modelo con prompts
  • Gestiona el historial de capturas de pantalla
  • Sigue las mejores prácticas de implementación (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. 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,610 en Claude Fable 5, Claude Mythos 5, Claude Opus 5 y Claude Opus 4.8, y aproximadamente 6,670 en Claude Sonnet 5), lo que cubre las definiciones de las herramientas miembro y la indicación del sistema del uso de herramientas. Habilitar los cuatro miembros opcionales agrega aproximadamente 880 tokens, y deshabilitar miembros con configs reduce el recuento. El recuento exacto para una solicitud se informa en el usage de la respuesta, y puedes estimarlo con anticipación con el endpoint de conteo de tokens.

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)
• Resultados de herramientas de texto devueltos a Claude, como árboles de accesibilidad, texto de la página y entradas de consola o de red

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. Por eso, siguen la política de retención estándar, o tu acuerdo de ZDR si tienes uno. La herramienta de uso del navegador es elegible para ZDR; consulta API y retención de datos para ver los períodos de retención y la elegibilidad de cada funcionalidad.

Próximos pasos

Compatibility