Tutorial de Browser Use: abre páginas, haz clic en botones y extrae datos con un agente de IA

Después de ejecutar uvx browser-use install, el verdadero punto de bloqueo suele ser la task. Si escribes “abre el sitio y mira”, el agente no sabe qué debe completar. Puede intentar una y otra vez, adivinar o terminar demasiado pronto.

Browser Use es una biblioteca open source de Python que permite a la IA controlar un navegador Chromium para automatizar tareas web. Puede ejecutarse en local o en un entorno self-hosted, sin depender de Browser Use Cloud. Si ya entiendes el concepto de Browser Agent, este tutorial va desde la instalación hasta la primera tarea exitosa, con configuración segura, lectura de resultados y depuración.

Qué es Browser Use: una definición corta

Browser Use es una Python library for AI browser automation. Permite que un LLM Agent opere un navegador como una persona: navegar, hacer clic, escribir, desplazarse, extraer datos y tomar capturas.

Su enfoque es local o self-hosted, no dependiente de Browser Use Cloud. La biblioteca open source y el Cloud Agent tienen APIs distintas. Esta guía usa la ruta open source; capacidades del Cloud SDK como structured output, human-in-the-loop o live preview quedan fuera del alcance.

Si todavía te preguntas “qué es un Browser Agent”, empieza por el artículo conceptual cuando esté publicado. Si ya conoces el concepto, esta guía responde a la pregunta práctica: ¿cómo lo pongo a funcionar ahora?

Instalación y preparación: de uv a la clave API

Al 2026-06-30, el README oficial y el quickstart describen esta ruta:

1. Requisito de versión de Python

Browser Use requiere Python 3.11 o superior. El ejemplo del quickstart oficial crea un venv con Python 3.12, pero puedes elegir según tu entorno.

2. Instalar uv (recomendado)

uv es un gestor de paquetes moderno para Python, desarrollado por Astral. Si aún no lo tienes:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Inicializar el proyecto e instalar browser-use

# Crear el directorio del proyecto
mkdir my-browser-use
cd my-browser-use

# Inicializar el proyecto
uv init

# Instalar browser-use con dependencias core
uv add "browser-use[core]"

# Sincronizar dependencias
uv sync

Si no usas uv, también puedes usar pip:

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

pip install "browser-use[core]"

4. Instalar el entorno de ejecución Chromium

Browser Use depende de Playwright por debajo, así que primero instala Chromium:

uvx browser-use install

Este comando descarga y configura Chromium para que el agente pueda iniciar una instancia del navegador.

5. Configurar la clave API

Browser Use necesita conectarse a un LLM para entender tareas y tomar decisiones. El quickstart oficial recomienda ChatBrowserUse, un modelo diseñado para tareas de navegador.

Crea un archivo .env en la raíz del proyecto:

# .env
BROWSER_USE_API_KEY=your_api_key_here

Si usas OpenAI, Anthropic, Google Gemini u Ollama local, configura la clave correspondiente:

OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GOOGLE_API_KEY=your_google_key

Escribir el primer script: plantilla mínima

El script mínimo solo necesita tres partes: importar módulos, crear el Agent y ejecutar la tarea.

from browser_use import Agent, Browser, ChatBrowserUse
import asyncio

async def main():
    # Crear una instancia del navegador (visible durante la depuración)
    browser = Browser(headless=False)

    # Crear la instancia LLM
    llm = ChatBrowserUse()

    # Crear el Agent
    agent = Agent(
        task="Abre quotes.toscrape.com, desplázate una pantalla hacia abajo, haz clic en el botón 'Next' y extrae todas las quotes y autores de la segunda página",
        llm=llm,
        browser=browser
    )

    # Ejecutar la tarea con límite de pasos
    history = await agent.run(max_steps=20)

    # Cerrar el navegador
    await browser.close()

if __name__ == "__main__":
    asyncio.run(main())

Este script hace varias cosas:

1. Browser(headless=False): muestra la ventana del navegador para facilitar la depuración. Después puedes cambiarlo a headless=True.
2. ChatBrowserUse(): usa el modelo oficial para navegador. También puedes cambiar a ChatOpenAI(model="gpt-4o") u otro modelo.
3. task debe ser concreta: no escribas “abre el sitio y mira”. Escribe “navega a X URL, desplázate, haz clic en el botón Y, extrae el contenido Z”. Las tareas vagas provocan bucles o cierres tempranos.
4. max_steps=20: limita el agente a 20 acciones como máximo. Para una primera tarea, 10-20 pasos ayudan a depurar sin dejarlo atrapado en una acción.

Ejecuta el script:

uv run python main.py

No dejes que el agente corra sin fin: max_steps es la línea de seguridad

max_steps limita cuántos pasos puede ejecutar el agente. El valor oficial por defecto es 100, pero para la primera tarea conviene bajarlo a 10-20.

Por qué importa:

• El agente puede encontrarse con un clic fallido, una página lenta, un popup o un elemento oculto y repetir la misma acción.
• Sin límite, puede consumir tiempo y tokens sin avanzar.
• La meta de la primera tarea es comprobar que el circuito funciona, no completar un workflow complejo a la perfección. Un límite menor muestra antes el primer problema.

Configuración recomendada:

# Primera tarea: 10-20 pasos
await agent.run(max_steps=20)

# Tarea compleja: ajustar cuando haga falta, pero evitar superar 50 al principio
await agent.run(max_steps=50)

Configuración segura para empezar

No empieces con tu cuenta principal iniciada ni permitas que el agente navegue libremente por cualquier sitio. Una configuración inicial segura incluye:

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

1. Modo de depuración headless=False

browser = Browser(headless=False)

Así ves la ventana del navegador y puedes saber si el agente hace clic mal, si la página se queda bloqueada o si la tarea está mal descrita. Después de depurar, cambia a headless=True.

2. Limitar la navegación con allowed_domains

browser = Browser(
    headless=False,
    allowed_domains=["quotes.toscrape.com"]
)

allowed_domains impide que el agente navegue a otros dominios. Si la tarea solo necesita un sitio, conserva este límite.

Browser Use admite wildcards de subdominio como allowed_domains=["*.example.com"], pero no wildcards de TLD. allowed_domains=["example.*"] no se reconocerá. Para un sitio fijo, lo más estable es escribir el dominio completo:

allowed_domains=["quotes.toscrape.com", "github.com"]

3. Usar un perfil aislado, no tu Chrome principal

browser = Browser(
    headless=False,
    user_data_dir="./browser_profile"
)

El agente crea un perfil separado del navegador. No accede a cookies, sesiones ni datos sensibles de tu Chrome principal. Este primer tutorial usa solo páginas públicas.

4. No usar disable_security

El parámetro disable_security desactiva políticas de seguridad del navegador. La documentación oficial lo marca como no recomendado. Si lo ves en otro tutorial, sáltalo.

Leer resultados: no basta con que el navegador se mueva

agent.run() devuelve un AgentHistoryList. Puedes usar varios métodos helper para inspeccionar resultado y proceso:

history = await agent.run(max_steps=20)

# Resultado final
result = history.final_result()
print("Resultado final:", result)

# Contenido extraído
extracted = history.extracted_content()
print("Contenido extraído:", extracted)

# Lista de errores
errors = history.errors()
print("Errores:", errors)

# Si hubo errores
if history.has_errors():
    print("La tarea encontró errores")

# Lista de URL visitadas
urls = history.urls()
print("URL visitadas:", urls)

# Rutas de capturas de pantalla
screenshots = history.screenshot_paths()
print("Capturas:", screenshots)

# Nombres de acciones ejecutadas
actions = history.action_names()
print("Acciones:", actions)

# Total de pasos
steps = history.number_of_steps()
print("Pasos:", steps)

Un error común al empezar es mirar la ventana del navegador y asumir que la tarea funcionó. Si final_result() está vacío, quizá el agente terminó pronto o no entendió la tarea. Si errors() tiene contenido, lee esos errores antes de cambiar el prompt.

Primera tarea: abrir, hacer clic, extraer

Usa quotes.toscrape.com como primer escenario. Es un sitio público creado para practicar scraping, no requiere login y tiene una estructura simple.

Tarea 1: abrir y desplazarse

agent = Agent(
    task="Abre quotes.toscrape.com y desplázate una pantalla hacia abajo",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=10)
print("URL visitadas:", history.urls())

Tarea 2: hacer clic en un botón

agent = Agent(
    task="Abre quotes.toscrape.com y haz clic en el botón 'Next' al final de la página",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=10)
print("Éxito:", history.is_successful())

Tarea 3: extraer contenido

agent = Agent(
    task="Abre quotes.toscrape.com y extrae todos los textos de quotes y sus autores de la primera página",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=15)
extracted = history.extracted_content()
print("Contenido extraído:", extracted)

Tarea 4: combinar pasos

agent = Agent(
    task="Abre quotes.toscrape.com, haz clic en el botón 'Next' y extrae todos los textos de quotes y sus autores de la segunda página",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=20)
print("Resultado final:", history.final_result())
print("Errores:", history.errors())

Dónde mirar cuando falla

Cuando el agente devuelve un resultado vacío, muestra un error o se queda atascado, sigue esta lista:

1. Falla el clic

• Revisa si history.errors() contiene “click failed” o “element not found”
• Agrega un fallback de teclado a la tarea: “si falla el clic, usa Tab para enfocar el botón y luego presiona Enter”
• Revisa history.screenshot_paths() para ver si el elemento estaba visible

2. La extracción está vacía

• Revisa history.urls() para confirmar que la página se abrió
• Revisa history.screenshot_paths() para ver el estado de la página
• Confirma que la tarea sea clara: “extrae todos los textos de quotes y sus autores”, no “mira el contenido”

3. La página se queda bloqueada

• Revisa si allowed_domains bloqueó una navegación
• Revisa la conexión y el tiempo de carga
• Baja max_steps o agrega comportamiento de timeout: “si la página no carga en 10 segundos, vuelve al inicio”

4. El resultado queda incompleto

• Revisa si max_steps detuvo la ejecución demasiado pronto
• Revisa history.number_of_steps() para ver cuántos pasos se usaron
• Ajusta la descripción y divide la tarea en subtareas

5. Falla toda la tarea

• Verifica que la clave API en .env sea correcta
• Confirma que el modelo sea compatible: ChatBrowserUse, OpenAI, Anthropic, Google Gemini u Ollama local
• Revisa si la tarea es demasiado abstracta: cambia “abre el sitio y mira” por acciones concretas

Beta Agent vs API estable: dos entradas

Al 2026-06-30, el README oficial describe dos rutas de importación del Agent:

API estable

from browser_use import Agent, Browser

Esta es la entrada estable. Si ya usabas Browser Use, puedes seguir con esta ruta.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

API beta (0.13)

from browser_use.beta import Agent, BrowserProfile, ChatBrowserUse

Este es el beta agent 0.13, respaldado por Rust core y browser harness. El README oficial dice que los usuarios existentes pueden seguir con la API estable y los nuevos pueden probar beta.

Si no sabes cuál usar, revisa el README oficial actual. Esta guía usa ejemplos estables; la API beta puede variar.

Open source vs Cloud: dónde está el límite

Esta guía usa la biblioteca open source de Browser Use en local.

Browser Use Cloud es un servicio alojado con otra API:

• El Cloud SDK actualmente usa API v3
• Cloud ofrece structured output, human-in-the-loop, live preview, persistent profiles y otras funciones de producción
• El SDK Python/TypeScript de Cloud no es compatible con la API de la biblioteca open source

Cuándo considerar Cloud:

• Despliegue en producción o runtime alojado
• Necesidades avanzadas como stealth, CAPTCHA y proxies, que esta guía no cubre
• Varias cuentas, perfiles persistentes y colaboración en equipo

Esta guía se queda en la entrada local. El uso de Cloud y sus precios quedan para otro artículo.

Siguientes pasos

Este tutorial cubre la entrada local a Browser Use: instalación, claves API, script mínimo, abrir una página, hacer clic en un botón, extraer información y depurar fallos.

Buenos siguientes pasos:

• Publicado: guía práctica de automatización de navegador con OpenClaw, Computer-Use Agent: deja que la IA controle tu computadora, guía de plugins MCP
• Temas posteriores: Playwright MCP con Claude, Codex y Cursor; ingeniería con Stagehand; elección de herramientas Browser Use; sesiones y autenticación; infraestructura cloud; cumplimiento y seguridad
• Documentación oficial: quickstart, prompting guide, browser config

Primero haz funcionar una tarea en quotes.toscrape.com o en una página pública de GitHub. Después considera sesiones iniciadas y Cloud.