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.
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:
export BROWSER_USE_API_KEY=bu_...
# or
browser-use loginEl 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:
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):
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.
| Ajuste | 0.x | 1.0.7 |
|---|---|---|
llm=None | Exigía un modelo | bu-4.0 mediante el gateway de Browser Use |
Precio de bu-4.0 | n/a | 1,80 $ / 1M de entrada, 9,00 $ / 1M de salida |
Precio de bu-fast | n/a | 0,12 $ / 1M de entrada, 0,60 $ / 1M de salida |
Browser() | Chromium local | Navegador de Browser Use Cloud |
| Navegador local | Predeterminado | Hay que indicar explícitamente Browser('chromium') |
| Clave de API | Una por proveedor | Una única BROWSER_USE_API_KEY |
max_steps | 500 | 100 (se reserva un paso para la entrega) |
| Tiempo de espera del agente | No especificado | 1.700 segundos, sin contar el arranque ni el cierre |
| Evaluador | Opcional | judge=True de forma predeterminada |
| Razonamiento / modo | n/a | reasoning='medium', mode='ultrafast' en bu-fast / bu-ultrafast |
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):
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,ChatGoogleo cadenas de Pydantic AI comogroq:llama-3.3-70b-versatile - Azure mediante
llm='azure:<deployment>'conAZURE_OPENAI_ENDPOINT,AZURE_OPENAI_API_KEYyOPENAI_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:
# 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 Falseis_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 enresult.structured_output - Cargas en el workspace y
workspace/downloads, con los archivos descargados enresult.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=Trueopcional, con el coste de cada búsqueda sumado aresult.cost_usd- CLI/MCP mediante
browser-use --cli-mcp,browser-use skill installybrowser-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ón | Qué hacer |
|---|---|
| Proyecto nuevo de agente, la nube no es un problema | Empieza con ==1.0.7, conserva bu-4.0 como valor predeterminado y mantén activado el evaluador |
| Trabajos por lotes sensibles al coste | Pasa llm='bu-fast' y judge=False; mide antes de escalar |
| Localhost / intranet / viewport personalizado | Usa Browser('chromium') junto con tu propio modelo; nunca un Browser() sin argumentos |
| Proyecto 0.x existente en producción | Fija browser-use<1 en la rama principal y migra en otra rama usando los errores de fallo rápido |
| Flujo con muchos CAPTCHA | Presupuesta 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.