Herramienta de uso del navegador

La "browser use tool" (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. Trabaja con la página tanto a través de su estructura (el árbol de accesibilidad, los elementos, los formularios y las pestañas) como a través de píxeles (capturas de pantalla y coordenadas del viewport), mientras que la herramienta de uso de computadora trabaja con un escritorio completo únicamente mediante capturas de pantalla y coordenadas. Es un conjunto de herramientas de cliente definido por Anthropic: una entrada browser_toolset_20260801 en tu array tools le da a Claude 27 herramientas miembro de forma predeterminada, como navigate, read_page, left_click y screenshot, más cuatro adicionales (javascript_exec, file_upload, read_console y read_network) cuando las habilitas. Tu aplicación ejecuta cada llamada contra su propia automatización de navegador; nada se ejecuta del lado de Anthropic. Actualmente no está disponible en Claude Managed Agents. Esta página dice "tu aplicación" para referirse al bucle de agente que llama a la Messages API y "tu ejecutor" para la parte de este que controla el navegador y produce los resultados de las herramientas.

Elige el uso del navegador en lugar del uso de computadora cuando la tarea se mantiene dentro de páginas web: Claude puede leer la estructura de una página, actuar sobre un elemento por referencia además de por coordenada, establecer valores de formularios directamente y trabajar entre pestañas, y no necesitas ejecutar un escritorio. Si Claude solo necesita leer páginas a las que puedes dirigirlo, o encontrar fuentes en la web, la herramienta web fetch y la herramienta web search son aún más ligeras, porque son herramientas de servidor que la API ejecuta por ti sin ningún navegador que operar. Elige en cambio el uso del navegador cuando las páginas construyen su contenido con JavaScript o cuando la tarea implica actuar sobre la página en lugar de solo leerla.

Con el uso del navegador, Claude lee y actúa sobre páginas web en vivo, por lo que todo lo que una página proporciona es entrada no confiable y las acciones que Claude realiza pueden tener efectos reales. Consulta Consideraciones de seguridad antes de desplegar.



Inicio rápido

La herramienta de uso del navegador está disponible en la Claude API sin encabezado beta: agrega una entrada de tipo browser_toolset_20260801, sin name, al array 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 miembro, cada uno nombrando una herramienta miembro en name y llevando "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 ejecutor ejecuta navigate, luego read_page, y 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 primeros pasos, 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): Claude devuelve llamadas a herramientas miembro, tu ejecutor las ejecuta contra el navegador y tú devuelves los resultados hasta que Claude responde con texto.

Aquí hay un esqueleto del paso de llamadas a herramientas de ese bucle en dos partes. Primero, unos manejadores de miembros simulados sustituyen a tu automatización de 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 lanza 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 manejadores, repite toolset_name en cada resultado y aplica la regla de detención de Acciones por lotes, convirtiendo un error del manejador en un resultado de error. El bucle de muestreo que lo 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 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 ambos conjuntos de herramientas comparten. 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 fragmentos, así que espera a que el turno termine 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 concurrentemente. 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 mensaje user, cada uno con toolset_name y una breve confirmación 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ña 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 reciente 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. Dado que un resultado de gestión de pestañas debe ser exactamente un bloque browser_state, adjúntalo 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 mantiene, incluido un tool_result por cada tool_use en el siguiente mensaje user, excepto por dos cosas: el texto de detención y lo que contiene el content de un resultado exitoso. El contenido del resultado sigue en cambio lo indicado en Herramientas miembro de 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ña 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 read_page o find devolvió. 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 de 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 de un tamaño consistente. 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: 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 una vez que una solicitud contiene más de 20 imágenes, es rechazada. Redimensiona antes de devolverla, y escala las coordenadas de Claude de vuelta por el inverso de tu factor antes de despacharlas (Dimensiona las capturas de pantalla para ajustarse 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 el mapeo de cada una al 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 pasa 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 objetivo y alterna entre ellos según lo que la página expone; tu prompt y lo que tu ejecutor devuelve orientan la elección:

• Prefiere referencias donde la página tenga un árbol de accesibilidad utilizable. Una referencia sobrevive a 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 contenido que el árbol no describe. Las interfaces renderizadas en canvas, las superficies de video incrustado o de escritorio remoto, las listas fuertemente 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 resuelve en qué marco cae una coordenada.
• Delimita las lecturas, y lee el árbol antes de capturar la 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 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 correcta 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 una inyección de prompts puede alcanzar, revisa Mitiga jailbreaks e inyecciones de prompts, y si una tarea no puede evitar una sesión con inicio de sesión, usa una cuenta dedicada de bajos privilegios y mantén la confirmación humana en las acciones que modifican la cuenta.

Dado que el navegador se ejecuta en tu entorno, los sitios que Claude visita 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 es exactamente los parámetros listados aquí, y tab_id, donde es opcional, toma por defecto 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 aparecen solo 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, no los aplica la API, así que valida las entradas (incluidas las coordenadas contra 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 una breve confirmación 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 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



Puntero



Teclado y tiempos



Lectura de página



Formularios y archivos



Diagnóstico y scripting



Gestión de pestañas

En caso de é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 listan en Conjuntos de herramientas de cliente, y esta sección cubre los valores predeterminados específicos del navegador. configs es un objeto indexado por nombre de miembro, y el valor de cada miembro acepta dos campos:



Habilita o deshabilita herramientas miembro

Lista en configs solo los miembros que quieres cambiar; cada miembro que omitas mantiene su valor predeterminado. Por ejemplo, un ejecutor que implementa lecturas de consola pero no control de puntero de bajo nivel 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 Claude ve; eso no garantiza que Claude nunca lo nombre, así que tu ejecutor igualmente responde a tal 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 array 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. Las dos funcionan de forma independiente, cada una en su propio marco de coordenadas (píxeles del viewport aquí, píxeles de 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 de navegador pueden proporcionar esos logs y amplían el contenido controlado por la página que llega a Claude. Habilita cada una con configs (por ejemplo, "configs": {"file_upload": {"enabled": true}}) solo cuando tu ejecutor la implemente y la tarea la necesite.



Sube archivos

file_upload establece directamente los archivos en un elemento <input type="file">, lo que 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 archivos en el sistema de archivos del ejecutor, para despliegues donde 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 despliegues donde no puede. Tu aplicación define qué significan los identificadores; delimita su resolución de la misma forma que delimitas paths, a 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 en lista de permitidos que contenga solo archivos destinados a la tarea. No reutilices el directorio de descargas del navegador para esto; si lo haces, cada archivo que una página haga que el navegador descargue se vuelve subible.



Ejecuta JavaScript en la página

javascript_exec ejecuta la expresión que Claude escribe 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, almacenamiento y 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 Claude emite.



Lee la actividad de consola y red

read_console devuelve las entradas de consola de la pestaña y read_network devuelve sus solicitudes de red, cada una como texto con una línea por entrada acumulada desde la lectura anterior de esa pestaña. Una línea de consola lleva una entrada de log, advertencia o error; una línea de red lleva 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 de 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 tuvo 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 red están controladas por la página y a menudo contienen secretos como tokens en las URLs de las solicitudes, así que redacta los valores con aspecto de 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 se refiere a las pestañas por tab_id, tu aplicación es la fuente de verdad sobre qué pestañas existen, y tú reportas ese estado en un bloque de contenido browser_state que Claude nunca ve directamente: la API genera el texto que Claude lee a partir de él.

{
  "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í) reporta los efectos secundarios de la llamada: 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 eventos de descarga. Omite el campo cuando no haya nada que reportar; un arreglo vacío se rechaza.
• Envía el bloque solo en resultados que respondan a una llamada de un miembro del navegador, como máximo una vez por tool_result, y nunca en un resultado con is_error: true. Expresas "no hay estado de pestañas que reportar" omitiendo el bloque.
• La API convierte tabs en texto para Claude como describen las dos secciones siguientes; las entradas de descarga en state_changes se validan pero no se convierten en texto.

Tú asignas los valores de tab_id. Cualquier cadena estable funciona, como el identificador de página de tu biblioteca de automatización o tu propio contador, siempre 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 debe estar vacío, y ninguno puede contener caracteres de control (incluidos saltos de línea) ni separadores de línea o de párrafo Unicode.
• 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, así que 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 Claude ve. 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 active: true.

Un resultado de list_tabs cuyo bloque lista dos pestañas con la primera activa se muestra de la siguiente manera, con cada línea sangrada dos espacios y (current) añadido solo a la pestaña activa:

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 inverso: 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. Reporta la URL en la que se abrió la pestaña, como aquí, no una a la que redirija después; los resultados posteriores reportan la URL actual de 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 reportar, 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, de modo que Claude recibe el nuevo estado sin una llamada separada 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 nombra la pestaña en la que se ejecutó la llamada, que es su entrada tab_id cuando está presente y, en caso contrario, la pestaña activa, y 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, por lo que un estado de pestañas idéntico no se vuelve a mostrar en resultados posteriores y poblar el bloque generosamente no cuesta nada.

Tres casos no muestran ningún pie incluso cuando el bloque está presente:

• Cualquier resultado de zoom.
• Un resultado sin bloque text (un resultado de screenshot solo con imagen, por ejemplo). 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, así que incluye un bloque de texto breve junto a la imagen cuando quieras que Claude vea un cambio de pestaña en ese mismo resultado.
• 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, cuando Claude hizo clic en el enlace "Pricing" (ref_5) anteriormente en esta sesión, la página lo abrió en una pestaña nueva que Claude no pidió, y sin un reporte Claude tendría que llamar a list_tabs para descubrirla. Devuelve la confirmación del clic más un bloque cuyo state_changes nombre la pestaña abierta, marcando 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 lote, adjunta el bloque al resultado de la llamada durante la cual ocurrió el cambio, y dale a cada resultado exitoso de gestión de pestañas su propio bloque incluso cuando un resultado anterior en el mismo turno haya reportado el mismo estado.



Reporta descargas

Cuando un clic o una navegación inicia la descarga de un archivo, repórtala en state_changes en el resultado de la llamada durante la cual ocurrió, correlacionada entre resultados mediante 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 valida estas entradas pero no las convierte en texto que Claude vea, así que cuando Claude necesite actuar sobre el archivo, menciona también el nombre del archivo o el path en el bloque text del mismo resultado.

Por ejemplo, un clic en "Download price list (CSV)" (ref_8) en la pestaña Pricing inicia una descarga, así que el resultado del clic lleva una entrada download_started con download_id "dl-1" y la URL del archivo. La descarga termina mientras se ejecuta una llamada posterior a screenshot, así que el content de ese resultado contiene la imagen, un bloque de texto como Screenshot captured. Download complete: /home/user/downloads/price-list.csv (48,213 bytes)., y este bloque browser_state que reporta la finalización bajo 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
    }
  ]
}

Los reportes de descarga siguen estas reglas:

• Como máximo una entrada por download_id en un solo bloque, así que una descarga que comienza y termina durante la misma llamada reporta solo download_completed.
• Nunca envíes state_changes en un resultado con is_error: true; reporta un evento de descarga que ocurrió durante una llamada fallida en el siguiente resultado exitoso.
• state_changes no es un inventario de descargas en curso; reporta cada evento una sola vez.
• Cada entrada lleva solo los campos que declara su type. size_bytes es un entero no negativo, download_id no está vacío, y download_id, url, path y error tienen cada uno como máximo 4,096 caracteres sin caracteres de control ni separadores de línea o de párrafo Unicode. La url proviene del servidor remoto y a menudo lleva credenciales firmadas en la cadena de consulta después de las redirecciones, así que elimina los parámetros de consulta que no quieras en el contexto de Claude y sanéala antes de reportarla o usarla en una ruta del sistema de archivos.



Maneja errores

Reporta una llamada fallida a Claude como un resultado de error ordinario: is_error: true, contenido de texto que diga 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 sobre lo que actuar, mientras que un simple Error: navigation failed no. Otros casos comunes:



Errores de solicitud

La API valida la entrada del toolset y cada bloque tool_use y tool_result de miembro en la conversación. Cuando uno está mal formado, la API devuelve un invalid_request_error antes de que Claude se ejecute. En la siguiente tabla, la columna izquierda nombra lo que enviaste.



Limitaciones

• Disponibilidad de plataforma: El uso del navegador está disponible solo en la Claude API.
• Solo streaming de entrada completa: Cuando usas streaming, el input de cada miembro llega como un único input_json_delta completo (Toolsets 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, y allí Claude recurre a capturas de pantalla y clics por coordenadas.
• read_console y read_network dependen de tu automatización del navegador: Reportan solo lo que esta puede capturar, y solo desde el momento en que se adjuntó a una pestaña.
• Se aplican las limitaciones generales de los agentes: La 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), y su orientación en Optimiza el rendimiento del modelo con prompts, Gestiona el historial de capturas de pantalla y Sigue las mejores prácticas de implementación (retrasos entre acciones, validación de acciones y registro) también se aplica a los ejecutores de navegador.



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 de uso de herramientas. Habilitar los cuatro miembros opcionales agrega aproximadamente 880 tokens, y deshabilitar miembros con configs reduce el conteo. El conteo 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 en 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 y siguen la política de retención estándar, o tu acuerdo ZDR si tienes uno. La herramienta de uso del navegador es elegible para ZDR; consulta API y retención de datos para conocer los períodos de retención y la elegibilidad en las distintas funciones.



Próximos pasos