Precio de lanzamiento (hasta el 25 de dic.), se mantiene mientras sigas suscrito: Go por $10/mes (antes $20), Plus con Opus 5.5 por solo $30/mes (antes $50)Suscribirme →

Browser-Use 1.0: guía de configuración y migración

Si construiste tu proyecto sobre browser-use 0.x, la versión 1.0 cambia tanto la arquitectura como los valores predeterminados. Las 24 acciones del navegador desaparecen y dejan paso a un único REPL persistente de Python; además, Browser() ahora significa un navegador en la nube. Esta guía repasa cómo fijar la versión 1.0.7, hacer la primera ejecución y migrar desde 0.x, basándose en las notas de la versión 1.0.7, MIGRATING.md y el artículo de ingeniería del 20 de noviembre.

Deja 1.0 funcionando en 5 minutos

Fija la versión desde el principio. La versión 1.0.0 llegó el 10 de noviembre de 2026 y, para el 20 de noviembre, la etiqueta estable era la 1.0.7; la 1.0.8rc1 seguía en pre lanzamiento (releases). El README lo deja claro: no uses nunca >=, porque las API pueden romperse entre versiones menores.

bash
uv add 'browser-use==1.0.7'
# or
pip install 'browser-use==1.0.7'

Los requisitos son concretos: Python 3.11 o una versión posterior, pero inferior a 4.0 (README, PyPI). Todas las dependencias están fijadas con ==. Eso favorece la reproducibilidad, aunque puede generar conflictos si tu aplicación necesita otra versión de pydantic, mcp o google-genai.

Autentícate una sola vez. Crea una clave en cloud.browser-use.com y expórtala o ejecuta el asistente de inicio de sesión:

bash
export BROWSER_USE_API_KEY=bu_...
# or
browser-use login

El inicio de sesión guarda las credenciales en ~/.config/browser-harness/auth.json y las comparten la CLI, el servidor MCP y browser-harness (MIGRATING.md). En contenedores, usa BROWSER_USE_AUTO_LOGIN=true. En máquinas con SSH o sin interfaz gráfica, la candidata 1.0.8 muestra un enlace y un código de aprobación que puedes validar desde otro dispositivo (notas de 1.0.8rc1).

La primera ejecución cabe en tres líneas:

python
from browser_use import Agent

result = Agent(
    "Find the number of stars of the browser-use repo"
).run_sync()

print(result.final_result())

Por defecto, esa ejecución genera costes: utiliza un navegador de Browser Use Cloud y el modelo predeterminado del gateway (README, rutas 1 y 3, valores predeterminados de MIGRATING.md). Si quieres hacer esta prueba sin gastar nada en la nube, añade ya Browser('chromium') y tu propio llm.

Qué sustituyó a las 24 acciones

En browser-use 0.x, el modelo recibía un menú: en cada paso elegía una acción a partir de una representación del DOM. La versión 1.0 elimina ese menú. Ahora dispone de una única herramienta principal, python: un REPL persistente con los asistentes de browser-harness y cdp() sin procesar preimportados, construido sobre Pydantic AI (artículo de ingeniería):

python
async def python(ctx: RunContext[Session], code: str) -> list[Any]:
    """Run Python in the persistent REPL
    (browser-harness helpers and raw cdp() pre-imported)."""

La limpieza eliminó 136.905 líneas y añadió 29.601 en 554 archivos; los archivos de Python pasaron de 178 a 43 (artículo de ingeniería).

La demostración más clara es la recuperación de una página bloqueada: el agente llamó a Page.stopLoading, bloqueó el script atascado, recargó la página, encontró su endpoint JSONP privado, descargó 730 fechas por lotes y reintentó únicamente los lotes fallidos. Todo ello devolvió 4.720 filas sin necesidad de una herramienta específica para ninguna de esas tareas (artículo de ingeniería).

El criterio que mantuvo el equipo es sencillo: solo hay que crear un asistente cuando el modelo no pueda reescribirlo después de leerlo una vez. La excepción son los CAPTCHA. En una pequeña prueba de staging, las instrucciones en texto obtuvieron 0/3 en hCaptcha, mientras que la herramienta específica solve_captcha logró 6/6, porque activa un interruptor del solucionador al que la página no puede acceder (artículo de ingeniería).

En costes y velocidad conviene leer la letra pequeña antes de quedarse con el titular. El artículo del 20 de noviembre informa de que los mismos tres modelos obtuvieron entre 14 y 33 puntos más, con un coste entre 2,7 y 5,2 veces menor, en 1.0 que en 0.x. El resultado procede de una ejecución de 200 tareas realizada el 8 de noviembre, de las que se puntuaron 180. El propio artículo advierte de que solo se hizo una ejecución por modelo y de que los valores predeterminados habían cambiado; por tanto, el rediseño de herramientas no puede atribuirse todo el mérito (artículo de ingeniería).

Las comparaciones más limpias son más específicas. La versión 1.0.4 obtuvo 76,1 frente a 76,0 en la 1.0.3, mientras el coste del modelo bajó de 0,434 a 0,208 dólares por tarea después de que la poda de capturas por lotes conservara la caché de prompts (notas de 1.0.4). En BU Bench v2, 1.0 ultrafast consiguió 62,5 puntos, costó 0,070 dólares y tardó 650 segundos, frente a los 56,3 puntos, 0,082 dólares y 743 segundos de Browser Use Pi. Los autores señalan que la diferencia deja de ser significativa al excluir los errores del proveedor. Presupuesta una ejecución más barata y rápida, no necesariamente más inteligente.

Los valores predeterminados que cambian tu factura y tu navegador sin avisar

Tabla elaborada a partir de MIGRATING.md y las notas de la versión 1.0.6. Refleja la 1.0.7 y el cambio de modelo predeterminado que se produjo a mitad de la serie 1.0 y que muchas guías antiguas no recogen.

Ajuste0.x1.0.7
llm=NoneExigía un modelobu-4.0 mediante el gateway de Browser Use
Precio de bu-4.0n/a1,80 $ / 1M de entrada, 9,00 $ / 1M de salida
Precio de bu-fastn/a0,12 $ / 1M de entrada, 0,60 $ / 1M de salida
Browser()Chromium localNavegador de Browser Use Cloud
Navegador localPredeterminadoHay que indicar explícitamente Browser('chromium')
Clave de APIUna por proveedorUna única BROWSER_USE_API_KEY
max_steps500100 (se reserva un paso para la entrega)
Tiempo de espera del agenteNo especificado1.700 segundos, sin contar el arranque ni el cierre
EvaluadorOpcionaljudge=True de forma predeterminada
Razonamiento / modon/areasoning='medium', mode='ultrafast' en bu-fast / bu-ultrafast
Precio por 1M de tokens de los modelos del gateway: bu-4.0 frente a bu-fast

Hay tres trampas especialmente importantes. La primera: el modelo predeterminado cambió a mitad de la serie 1.0. Las versiones hasta la 1.0.5 usaban bu-fast, pero la 1.0.6 cambió el valor predeterminado a bu-4.0, cuyo precio por token es 15 veces mayor. El propio proyecto calcula que la misma prueba corta cuesta 0,022 dólares con bu-4.0, frente a 0,0014 con bu-fast. Si quieres conservar el perfil de coste anterior, pasa llm='bu-fast' explícitamente. La segunda: un Browser() sin argumentos aprovisiona ahora un navegador en la nube por 0,06 dólares la hora de navegador, además del modelo y los cargos por búsqueda (README); esos navegadores no pueden acceder a localhost ni a IP privadas (MIGRATING.md). La tercera: un paso equivale a una petición al modelo y a una celda de Python, así que el límite inferior de 100 pasos también funciona como límite de gasto. Ahora max_steps < 1 o timeout <= 0 fallan antes de que se inicie el navegador (MIGRATING.md).

El evaluador es otro coste oculto. Después de cualquier ejecución con al menos un paso, tu propio modelo realiza una petición adicional de bajo esfuerzo sobre un registro de hasta 120.000 caracteres y, si la visión está activada, sobre las cuatro últimas imágenes distintas, incluida la página final. Todo se envía sin ocultar (MIGRATING.md). El resultado queda en result.judgement, con success, failure_reason, gotchas y las marcas de bot/CAPTCHA; su coste se suma a result.cost_usd. Puedes desactivarlo con judge=False o pasar judge_context con la respuesta esperada. Si las capturas no deben salir nunca de tu entorno, establece use_vision=False.

Mantente en local cuando sea imprescindible

Elige el navegador según la red a la que deba acceder, no por costumbre. El identificador del modelo del ejemplo siguiente es el proveedor ilustrativo que aparece en el fragmento del README sobre navegadores locales (README):

python
from browser_use import Agent, Browser, ChatOpenAI

agent = Agent(
    "Summarize the dashboard at http://localhost:3000",
    llm=ChatOpenAI("gpt-6-luna"),
    browser=Browser("chromium"),
)
print(agent.run_sync().final_result())

Usa Browser('chromium') para localhost, redes privadas, viewports personalizados o cualquier caso en el que las llamadas de métricas del dispositivo en la nube no vayan a cambiar el viewport real de la página. Usa Browser('chrome') para controlar tu Chrome ya abierto con las sesiones existentes. Browser('chrome', profile='Work') inicia una copia temporal con las sesiones, pero no escribe nada de vuelta en Sync; en Windows, cierra primero el Chrome original porque bloquea las cookies (MIGRATING.md). La nube sigue siendo la opción adecuada cuando necesitas sigilo gestionado, proxies, gestión de CAPTCHA o una configuración local nula (README); eso sí, calcula las horas de navegador por separado de los tokens.

Los modelos personalizados siguen funcionando, pero la ruta de configuración es importante (MIGRATING.md):

  • Alias del gateway: bu-4.0, bu-4.0-mini, bu-4.0-pro, bu-fast, bu-ultrafast, bu-smart
  • Proveedores: ChatOpenAI, ChatAnthropic, ChatGoogle o cadenas de Pydantic AI como groq:llama-3.3-70b-versatile
  • Azure mediante llm='azure:<deployment>' con AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY y OPENAI_API_VERSION

Los objetos de chat de LangChain usados como Agent(llm=...) ahora provocan un TypeError, y los nombres retirados del gateway, como bu-2-0, se rechazan antes de iniciar el navegador. Cada agente paralelo necesita su propio Browser(); si dos agentes comparten uno, se produce un RuntimeError. En cambio, un navegador con keep_alive=True puede reutilizarse de forma secuencial (MIGRATING.md).

Migra sin adivinar: deja que el error te indique el camino

La versión 1.0 falla rápido de forma deliberada. Las importaciones eliminadas generan un ImportError que indica el reemplazo, los argumentos no compatibles de Agent(...) generan un TypeError y cualquier cosa que 1.0 no pueda respetar falla antes de que arranque el navegador o se facture nada (MIGRATING.md). Hay un grupo más pequeño —use_vision=True, vision_detail_level, max_actions_per_step, flash_mode, max_failures, highlight_elements y otros ajustes similares— que se acepta, pero se ignora con una advertencia por cada opción. use_vision=False sí conserva su utilidad, porque evita que las capturas lleguen al modelo.

Después del arranque, el comportamiento cambia: normalmente run() devuelve un resultado de error en lugar de lanzar una excepción, con status='error' y los detalles en result.error. Solo la cancelación sigue propagándose. Actualiza tus comprobaciones:

python
# 0.x
history = await agent.run(max_steps=500)
ok = history.is_successful()

# 1.0
result = await agent.run(max_steps=100)
ok = result.is_done() and result.success is not False

is_done() ahora solo indica que la ejecución ha terminado; el éxito depende del veredicto finish(result, success) del modelo, e is_successful() devuelve None cuando el modelo no ha emitido ningún veredicto. Los antiguos asistentes del historial por paso (action_names(), model_actions(), extracted_content(), save_as_playwright_script() y el resto de API de historial eliminadas que aparecen en MIGRATING.md) ya no existen. En su lugar, consulta result.messages, result.status, result.partial, los archivos de agent.workspace y result.judgement.

Empieza con estos tres cambios: mueve max_steps de Agent(...) a agent.run(max_steps=...); sustituye los callbacks eliminados (on_step_start, pause, stop, multi_act, save_history) por logging.getLogger('browser_use') en INFO o por BROWSER_USE_LOGGING_LEVEL=warning; y vuelve a delimitar los secretos. Los secretos asociados a dominios ahora solo se escriben en páginas coincidentes, los nombres que terminan en bu_2fa_code se tratan como semillas TOTP, el antiguo marcador <secret>name</secret> genera un error y debe convertirse en type_secret('name'). Los valores aparecen ocultos como <secret:name> en celdas y resultados, pero esto es una redacción, no un sandbox: el código Python escrito por el modelo todavía puede leerlos (MIGRATING.md). Si necesitas tiempo, fija pip install 'browser-use<1' y haz la migración en una rama.

"browser use is more a python framework for building your own browsing agent" — u/Starks1293 en r/ClaudeCode

Ese enfoque encaja con la forma en que los usuarios lo describen en Reddit: un framework para construir agentes de navegación, mencionado a menudo para sitios protegidos por sistemas antibot y para flujos que necesitan control a nivel de código. La fiabilidad sigue dependiendo del modelo y del sitio. Un informe de producción cuenta cinco minutos y nueve pasos fallidos al rellenar un formulario básico.

Antes de producción: evaluador, secretos y una fiabilidad irregular

Para un uso avanzado, esto es lo que importa:

  • Resultados tipados mediante output_model_schema, disponibles en result.structured_output
  • Cargas en el workspace y workspace/downloads, con los archivos descargados en result.downloads
  • Controles de dominio (allowed_domains, prohibited_domains, block_ip_addresses), que protegen frente a un modelo alineado, pero no aíslan la red
  • web_search=True opcional, con el coste de cada búsqueda sumado a result.cost_usd
  • CLI/MCP mediante browser-use --cli-mcp, browser-use skill install y browser-use --doctor

Trata 1.0 como un framework que evoluciona deprisa: fija las versiones exactas, añade judge_context a las tareas largas, guarda el trabajo parcial con checkpoint('titles.json', titles, partial=True) y ejecuta las tareas no confiables en contenedores, porque los límites de dominio y la redacción de secretos no constituyen aislamiento (README).

¿Migrar ya, fijar una versión o seguir en 0.x?

SituaciónQué hacer
Proyecto nuevo de agente, la nube no es un problemaEmpieza con ==1.0.7, conserva bu-4.0 como valor predeterminado y mantén activado el evaluador
Trabajos por lotes sensibles al costePasa llm='bu-fast' y judge=False; mide antes de escalar
Localhost / intranet / viewport personalizadoUsa Browser('chromium') junto con tu propio modelo; nunca un Browser() sin argumentos
Proyecto 0.x existente en producciónFija browser-use<1 en la rama principal y migra en otra rama usando los errores de fallo rápido
Flujo con muchos CAPTCHAPresupuesta el solucionador específico; las instrucciones en texto por sí solas obtuvieron 0/3 en la prueba del equipo

Obtienes un agente capaz de bloquear un script atascado o llamar a una API privada que nunca envolviste en una herramienta, pero pierdes las barreras de seguridad de un menú fijo de acciones. Si ese intercambio encaja con tu sitio, migra. Si no, mantener browser-use<1 mientras evalúas sigue siendo la opción más segura para los sistemas existentes en producción.

Preguntas frecuentes

¿Qué hay de nuevo en browser-use 1.0?

Un único REPL persistente de Python, con asistentes de browser-harness y CDP sin procesar, sustituye el menú de 24 acciones de 0.x y elimina aproximadamente el 80 % de la biblioteca, cuyos archivos de Python pasan de 178 a 43. Los valores predeterminados cambian a Browser Use Cloud, un modelo del gateway y una única BROWSER_USE_API_KEY.

¿Se romperá mi código de 0.x?

Los puntos de entrada habituales (Agent, Browser, run(), final_result()) siguen existiendo, pero las importaciones y opciones eliminadas generan ImportError o TypeError antes de facturar nada. Además, max_steps se ha trasladado a run() y Browser() ahora significa un navegador en la nube. Fija browser-use<1 para continuar como hasta ahora o migra primero en una rama.

¿Puedo seguir usando mi propio modelo y un navegador local?

Sí. Pasa proveedores como ChatOpenAI, ChatAnthropic, ChatGoogle o una cadena de Pydantic AI, y usa Browser('chromium') para abrir un navegador local nuevo o Browser('chrome') para controlar tu Chrome abierto. Los navegadores en la nube no pueden acceder a localhost.

¿Qué versión de Python necesita browser-use 1.0?

Python 3.11 o una versión posterior, pero inferior a 4.0. Las dependencias fijadas exactamente pueden entrar en conflicto con otros paquetes, así que empieza instalándolo en un entorno virtual nuevo.

¿Cómo desactivo el evaluador de la ejecución?

Pasa judge=False para omitir la petición adicional de evaluación, o usa judge_context con tus criterios de aceptación para que el veredicto sea útil. Establece use_vision=False si no quieres que se envíen capturas al evaluador.