Qué es Stagehand v4: el SDK que reescribió los agentes de navegador desde cero

Stagehand es un SDK de código abierto de Browserbase que permite que un agente de IA maneje un navegador web con pasos en lenguaje natural, como "haz clic en el botón de iniciar sesión", mezclados con código normal. A diferencia de Playwright o Puppeteer, que nacieron para testing automatizado y necesitan selectores exactos, Stagehand se pensó para agentes: sus pasos con IA siguen funcionando cuando cambia el diseño de una página. Es una librería para desarrolladores y está disponible para TypeScript, Python y Go.

La versión mayor actual, la v4, salió el 10 de agosto de 2026. Movió casi todo el motor a una extensión que corre dentro del navegador, junto a la página. También le dio a Python y Go el mismo SDK que a TypeScript y eliminó el antiguo bucle agent(). A 29 de octubre de 2026, la versión estable más reciente en npm es la 4.3.0, publicada el 20 de octubre.

Cómo funciona Stagehand: act, observe y extract

Piensa en cómo le pedirías a un compañero que compre algo en internet. Le dirías "busca la taza azul y añádela al carrito". No le leerías la clase CSS del botón. Stagehand deja que tu código dé instrucciones de la misma forma.

Lo hace con tres métodos, y cada uno usa un modelo de lenguaje grande (LLM, por sus siglas en inglés):

• act() ejecuta una acción que describes con palabras. Stagehand lee el árbol de accesibilidad de la página (el esquema ordenado que usan los lectores de pantalla), le pregunta al modelo qué elemento encaja y hace clic o escribe ahí. Si mañana cambia la clase del botón, tu instrucción sigue igual.
• observe() te dice sobre qué puedes actuar ahora mismo. Devuelve elementos candidatos con sus selectores, así que puedes revisar qué ve el modelo antes de actuar, o guardar un selector y reutilizarlo sin otra llamada al modelo.
• extract() saca datos estructurados que encajan con un esquema que tú defines (Zod en TypeScript, Pydantic en Python). Recibes datos tipados en lugar de HTML crudo que tendrías que procesar.

No tienes que usar IA en cada paso. Stagehand también trae métodos de página conocidos como goto, click, locator y screenshot. El patrón habitual es sencillo: código normal donde la página es estable y una llamada al modelo solo donde la página exige criterio.

Así se ve en TypeScript:

import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
 
const browser = await localBrowser.launch();
const stagehand = await Stagehand.create({
  browser,
  model: { modelName: "openai/gpt-5.4-mini", apiKey: process.env.OPENAI_API_KEY },
});
 
const [page] = await browser.context.pages();
await page.goto("https://github.com/browserbase");
await stagehand.act("click on the stagehand repo");

En la v4, cada método de IA devuelve { data, metadata }. Tu resultado está en data. El metadata te dice si el paso salió de la caché y cuántos tokens gastó.

Qué cambió en Stagehand v4

El gran cambio es dónde corre Stagehand. Las versiones anteriores guardaban una copia del estado del navegador dentro de tu script. Cada comando viajaba por el Chrome DevTools Protocol (CDP), el canal que usan las herramientas para controlar Chrome a distancia. En tu portátil, esa copia se mantiene fiel. Cuando el navegador vive en la nube, la copia se desfasa, y un clic puede caer en una página que ya se cerró.

La v4 mueve la gestión de pestañas, el seguimiento de frames y el envío de comandos a una extensión que arranca y se apaga con el navegador. Tu código le pregunta al navegador qué es cierto en vez de fiarse de una copia vieja. Browserbase dice que eso también le permitió lanzar TypeScript, Python y Go a la vez: cada SDK es ahora un cliente ligero sobre el mismo núcleo.

Otros cambios que conviene conocer:

• La seguridad vive dentro del navegador. Puedes fijar una política de dominios, y la v4 bloquea una petición prohibida antes de que salga del navegador. Eso importa cuando un agente lee una página que intenta engañarlo para enviar tus datos a otro sitio.
• Las páginas difíciles se volvieron más fáciles. Los iframes anidados, los iframes que corren en otro proceso y el Shadow DOM cerrado se pueden manejar como contenido normal. La v4 también suma soporte real de portapapeles y WebMCP, así que las páginas que ofrecen herramientas a los agentes se pueden manejar a través de esas herramientas.
• agent() desapareció. Era un bucle integrado en el que el modelo elegía una acción por paso. La guía de migración de Browserbase ahora recomienda el "modo código": un asistente de programación escribe un script de Stagehand una vez y tú lo ejecutas. La otra opción es tu propio bucle de llamadas a herramientas, que le entrega al modelo los métodos de Stagehand como herramientas.

¿Y la velocidad? Browserbase promociona la v4 como 2 veces más rápida que Playwright y un 80% más eficiente en tokens. El gráfico de tokens de stagehand.dev muestra unos 7.400 tokens para Stagehand frente a 35.700 para Playwright. En su post de lanzamiento, Browserbase publicó una sola medición: un recorrido de 50 acciones por Wikipedia terminó en 14,2 segundos frente a 22,7 con Playwright. Eso es 1,59 veces, y la propia Browserbase lo llama una ejecución, no un benchmark. Toma ambas cifras como datos del fabricante hasta que midas tus propias páginas.

Stagehand frente a Playwright y Puppeteer

Browserbase lo resume en una línea: "Playwright se construyó para testing, Stagehand se construye para agentes". Esto es lo que significa en la práctica.

Un detalle que mucha gente pasa por alto: Stagehand v4 ya no funciona encima de Playwright. Lanza Chrome o se conecta a él por su cuenta y te da métodos de página que se parecen a los de Playwright. No necesitas tener Playwright instalado para usarlo.

Playwright y Puppeteer siguen ganando cuando conoces la página y necesitas los mismos pasos mil veces, rápidos e idénticos. Stagehand gana cuando la página cambia a menudo, o cuando mantener vivos los selectores cuesta más horas de ingeniería que pagar llamadas al modelo. La pregunta de fondo no es cuál es más rápido. Es dónde prefieres gastar: en mantener selectores o en tokens.

Cuándo tiene sentido Stagehand (y cuándo no)

Usa Stagehand cuando tu agente tenga que trabajar en páginas que nadie mapeó para él. Encajan bien el scraping de sitios que cambian de diseño, los flujos de login que se mueven cada mes y los dashboards con un HTML impredecible. Cualquier tarea donde "leer la página como lo haría una persona" valga más que "repetir los pasos exactos de hace seis meses" es candidata.

Evita Stagehand cuando necesites que cada ejecución sea idéntica, velocidad por encima de todo o cero gasto en modelos. Si el trabajo es "rellenar este mismo formulario 10.000 veces al día", Playwright a secas será más barato y más rápido. Si cada acción debe auditarse y reproducirse con exactitud, la interpretación del modelo añade una capa que quizá no quieras.

Como la v4 eliminó agent(), Stagehand tampoco es un bot de "dale un objetivo y olvídate". Tú escribes el bucle, la memoria y los reintentos, o dejas que un asistente de programación escriba el script por ti. Stagehand te da herramientas afiladas para cada paso. El agente que las rodea lo construyes tú.

Pasar de v3 a v4

Si tienes código en v3, cuenta con reescribir la parte de arranque, no con un buscar y reemplazar. Estos son los cambios con los que chocarás primero:

1. Primero se crea el navegador. new Stagehand() e init() ya no existen. Lanza o conecta un navegador con localBrowser.launch() o browserbase.launch(), y luego llama a Stagehand.create({ browser }). El navegador lo cierras tú con browser.close().
2. Las páginas cambiaron de sitio y ahora son asíncronas. Usa await browser.context.activePage() o await browser.context.pages() en lugar de stagehand.page.
3. Los métodos de IA pasaron a la instancia. page.act() pasa a ser stagehand.act(), cada llamada devuelve { data, metadata } y extract() ahora recibe la instrucción y el esquema como dos argumentos.
4. La caché cambió. serverCache ahora se llama cache y las opciones de caché local desaparecieron. La v4 guarda en caché los resultados de act(), observe() y extract() en los servidores de Browserbase, así que la caché necesita un navegador de Browserbase.
5. agent() no tiene reemplazo directo. Usa el modo código o tu propio bucle de herramientas, como se explica más arriba.

Si usabas los clientes de Python o Go de la v3, esos hablaban con una API alojada mediante objetos de sesión. En la v4, los tres lenguajes comparten la misma forma: un navegador que sale de una fábrica, una instancia de Stagehand encima y los mismos tres métodos. La guía de migración de v3 a v4 de Browserbase tiene la lista completa.

Qué versión de Stagehand es la actual

A 29 de octubre de 2026, npm marca @browserbasehq/stagehand 4.3.0 como la última versión, publicada el 20 de octubre de 2026. La 4.2.1 salió el 11 de octubre. El paquete de Python (pip install stagehand) también está en la 4.3.0, publicada en PyPI el mismo 20 de octubre. La línea v4 hasta ahora:

Qué cambió en la 4.2, según las definiciones de tipos que npm publica con cada versión:

• Exportar a PDF. La 4.2.0 añade page.pdf(), así que puedes guardar la página en la que estás como PDF sin cambiar de herramienta.
• Tiempo límite por llamada. Los métodos de locator aceptan un timeout opcional, para darle más tiempo a un paso lento sin frenar todos los demás.
• Eventos de herramientas WebMCP. page.onToolsAdded() y page.onToolsRemoved() avisan a tu código cuando un sitio publica o retira herramientas WebMCP. WebMCP es una forma de que una web ofrezca a los agentes acciones listas para usar, en vez de obligarlos a hacer clic por todas partes.
• Cualquier nombre de modelo con un prefijo conocido. Hasta la 4.2.0, modelName tenía que coincidir con una lista fija de nombres. En la 4.2.1 acepta cualquier id que empiece por openai/, anthropic/, google/, groq/ o cerebras/. Eso ayuda cuando un proveedor lanza un modelo nuevo. La pega: una errata ya no la detiene Stagehand, sino que falla después, con un error del proveedor.

Y de la 4.1.0, según el changelog del proyecto:

• Buscar y leer páginas sin navegador. El helper browserbase puede hacer una búsqueda web o traer una página como markdown en TypeScript, Python y Go, sin lanzar un navegador.
• Un cierre más claro. browser.close() siempre apaga el navegador, mientras que stagehand.close() lo deja abierto para que otra instancia de Stagehand se conecte después.
• WebMCP en más sitios. Stagehand puede encontrar y llamar herramientas WebMCP dentro de iframes que corren en otro proceso.
• Fallos más rápidos. Conectarse a una sesión de Browserbase sin la extensión, o con versiones de protocolo que no coinciden, falla al instante en lugar de más tarde.

La rama v3 sigue existiendo. npm la mantiene bajo la etiqueta v3-latest (3.7.3, publicada el 28 de agosto de 2026), y la etiqueta de servidor v3 más reciente en GitHub es stagehand-server-v3/v3.7.6, del mismo día.

Una cosa que puede confundirte: las versiones v4 no aparecen en la página de Releases de GitHub, así que consulta npm, PyPI o el changelog del repositorio. npm también muestra muchas compilaciones con "alpha" en el nombre. Son versiones de prueba. La etiqueta latest es la que te instala npm install.

Cuánto cuesta usar Stagehand

El SDK es gratis bajo licencia MIT y, por defecto, funciona con el Chrome de tu propia máquina. Tus costes reales vienen de dos sitios:

• Llamadas al modelo. Cada act(), observe() y extract() gasta tokens de un LLM. Puedes usar tu propia clave del proveedor o, en navegadores de Browserbase, el Model Gateway de Browserbase, que elige un modelo por ti y cobra los tokens al precio del proveedor.
• Navegadores en la nube (opcional). Browserbase te aloja los navegadores, con un plan gratuito para prototipos y planes mensuales de pago a partir de ahí. La caché en servidor y el Model Gateway solo funcionan en navegadores de Browserbase.

¿Quieres números reales en lugar de precios de lista? Instalamos la v4, medimos lo que gastaba cada método y la rompimos a propósito en Stagehand v4: qué pasa de verdad cuando lo corrés.

Para seguir leyendo

• Stagehand v4: qué pasa de verdad cuando lo corrés, nuestra prueba práctica de instalación, costes y fallos
• Nuestra selección de herramientas de IA probadas, ordenadas según el trabajo que necesitas hacer

Si ya usas APIs de IA y quieres un camino guiado para construir agentes como estos, mira cómo funciona AI Flex. Es a tu ritmo, con un tutor de IA y mentores, y puedes cancelar cuando quieras.