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

Stagehand v4 es el SDK de Browserbase para construir agentes de navegador, lanzado en 2026 como una reescritura completa que mueve la ejecución core a una extensión nativa del navegador, prometiendo el doble de velocidad que Playwright y un ahorro del 80% en tokens. A diferencia de los navegadores headless tradicionales como Puppeteer o Playwright, diseñados para testing automatizado, Stagehand está construido específicamente para que agentes de IA interactúen con la web de manera semántica, usando comandos en lenguaje natural en lugar de selectores CSS frágiles. En su versión 4, el proyecto eliminó el orquestador agent() integrado para devolver el control al programador, duplicó el rendimiento y redujo drásticamente el coste de LLM por operación.

El cambio de arquitectura es profundo: en lugar de controlar el navegador desde un proceso externo mediante CDP (Chrome DevTools Protocol), Stagehand v4 ejecuta su lógica de gestión de estado, tracking de frames y despacho de comandos dentro de una extensión del propio navegador. Esto elimina la latencia de red entre el SDK y el browser, permite acceso asíncrono a páginas y contextos, y abre la puerta a un modelo de seguridad más robusto donde el enforcement corre en el mismo proceso del navegador.

¿Cómo funciona Stagehand v4?

Stagehand v4 opera sobre tres primitivas de lenguaje natural que forman su API core: act(), observe() y extract(). Cada una resuelve un problema distinto de la interacción agente-web.

act(accion) ejecuta una acción descrita en texto libre sobre la página. En lugar de escribir page.click('#submit-button') y cruzar los dedos para que el selector no haya cambiado, describes lo que quieres: \"haz clic en el botón de comprar\". Stagehand usa un modelo de lenguaje para interpretar la intención, localizar el elemento relevante en el DOM (o en el árbol de accesibilidad de Chrome), y ejecutar la acción. Si la página cambia mañana y el botón ahora tiene clase .purchase-btn en lugar de #submit-button, tu script sigue funcionando.

observe() inspecciona la página y devuelve una lista de elementos interactivos detectados, con metadatos sobre su tipo, posición y contexto. Es útil para depurar qué ve el agente antes de actuar, o para construir pipelines donde el agente primero "mira" y luego decide.

extract(esquema) extrae datos estructurados de la página validándolos contra un esquema que defines. Si necesitas precios, nombres de producto y disponibilidad de una tienda online, describes la estructura esperada y Stagehand devuelve JSON tipado, no HTML crudo que tengas que parsear con cheerio.

La versión 4 introduce cambios importantes en el ciclo de vida del SDK. En v3, creabas una instancia de Stagehand y esta lanzaba el navegador. En v4, el orden se invierte: primero lanzas o conectas el navegador, luego creas Stagehand pasándole esa instancia. Este cambio refleja la nueva arquitectura: Stagehand ya no "posee" el navegador, sino que se ejecuta "junto a él" como una extensión con la que el SDK se comunica.

Otro cambio significativo: agent() ha sido eliminado. En versiones anteriores, Stagehand incluía un orquestador autónomo que podía ejecutar secuencias de acciones sin intervención del programador. La versión 4 abandona esa idea. El flujo de control vuelve a ser responsabilidad del desarrollador; Stagehand proporciona las herramientas primitivas, pero tú decides cuándo actuar, cuándo observar y cuándo extraer. Es una apuesta explícita por la transparencia y el control sobre la magia opaca.

¿En qué se diferencia Stagehand v4 de Playwright y Puppeteer?

La comparación más honesta la hace el propio Browserbase en su documentación: "Playwright fue construido para testing; Stagehand fue construido para agentes". Esta distinción no es marketing, se traduce en decisiones técnicas concretas.

Playwright y Puppeteer brillan cuando conoces la estructura de la página y necesitas repetir la misma secuencia mil veces de forma determinista. Son herramientas de testing: rápidas, predecibles, pero frágiles ante el cambio. Cuando el CSS cambia, los tests rotos se acumulan en la bandeja de entrada del equipo de QA.

Stagehand apuesta por el caso opuesto: páginas que cambian constantemente, flujos donde la estructura no es conocida de antemano, o tareas donde el coste de mantener selectores actualizados supera el coste de usar un modelo de lenguaje. La pregunta de diseño no es "¿cuál es más rápido?" sino "¿dónde quieres gastar tus horas de ingeniería: en mantener selectores o en pagar tokens de LLM?"

Un dato concreto: Browserbase reporta que Stagehand v4 es aproximadamente 2 veces más rápido que Playwright en sus benchmarks internos, y un 80% más eficiente en tokens que versiones anteriores de Stagehand. Estas cifras vienen del propio fabricante, así que conviene tomarlas como claims de producto, no como verdad neutral independientemente verificada. Lo que sí es verificable sin confiar en Browserbase: la arquitectura de extensión nativa, la eliminación del método agent(), y la existencia de la API de tres primitivas documentada en código abierto.

¿Cuándo tiene sentido usar Stagehand v4?

Usa Stagehand v4 cuando estés construyendo agentes que necesiten navegar la web sin que alguien les haya escrito un mapa detallado de cada página. Web scraping de sitios estructurados pero no estáticos, automatización de flujos de login que cambian cada mes, extracción de datos de dashboards empresariales con DOMs impredecibles, o cualquier tarea donde "entender la página como la entendería un humano" valga más que "ejecutar la secuencia exacta que programaste hace seis meses".

No uses Stagehand v4 cuando necesites determinismo absoluto, velocidad de ejecución por encima de todo, o estés operando en un entorno donde el coste de tokens de LLM sea prohibitivo. Si tu caso de uso es "rellenar este formulario idéntico 10.000 veces al día", Playwright será más barato y más rápido. Si trabajas en regulación financiera donde cada acción debe ser auditada y reproducible al milímetro, la capa de interpretación de Stagehand añade complejidad que quizá no quieras.

La versión 4, al eliminar el orquestador agent(), también deja de ser la herramienta para quien buscaba "un bot que haga tareas complejas solo". Ahora necesitas construir tú el bucle de decisión, la memoria de estado, la lógica de reintentos. Stagehand te da las herramientas de bajo nivel afiladas; el agente completo lo montas tú, o usas otro framework (como CrewAI, LangGraph o tu propio código) que orqueste Stagehand como una de sus herramientas.

¿Qué cambia en la migración de v3 a v4?

Si vienes de Stagehand v3, hay tres breaking changes que romperán tu código existente.

Primero: el ciclo de vida del navegador. En v3 hacías const stagehand = new Stagehand({...}); await stagehand.init(); y Stagehand lanzaba el navegador por ti. En v4 primero lanzas el navegador con Playwright o Puppeteer, luego pasas esa instancia a Stagehand. El SDK ya no gestiona el proceso del navegador, solo se conecta a él.

Segundo: serverCache se renombra a cache, y el caché del cliente desaparece. La versión 4 centraliza todo el caché en el servidor (la extensión del navegador), eliminando la duplicación de estado entre cliente y servidor que existía en v3.

Tercero: agent() ya no existe. Si tu código usaba stagehand.agent({...}) para tareas autónomas multi-paso, necesitarás reescribir ese flujo usando las primitivas act/observe/extract dentro de tu propia lógica de orquestación. La documentación oficial de migración sugiere que este cambio fue intencional para dar más control al desarrollador sobre el comportamiento del agente.

Además, el acceso a páginas y contextos se vuelve asíncrono porque ahora viaja a través de la extensión del navegador en lugar de mantener referencias locales en el proceso del SDK.

¿Para quién está hecho Stagehand v4?

Stagehand v4 apunta a desarrolladores que construyen pipelines de datos, herramientas de automatización empresarial, o agentes de software que necesitan interactuar con la web moderna tal como es: cambiante, inconsistente, diseñada para humanos no para bots.

Si eres ingeniero de datos cansado de reparar selectores rotos cada vez que un equipo de frontend rediseña su dashboard, Stagehand ofrece una alternativa viable. Si eres desarrollador de agentes de IA buscando una capa de navegación que entienda semánticamente las páginas en lugar de hacer pattern matching ciego sobre el DOM, Stagehand es una opción seria junto a alternativas como Browser Use o Skyvern.

La curva de aprendizaje es suave si ya conoces Playwright: los métodos tradicionales (goto, click, type, screenshot) siguen disponibles y puedes mezclarlos con las primitivas de IA. Pero la promesa real de Stagehand no es "Playwright pero más fácil", es "Playwright pero que no se rompe cuando la web cambia". Esa resiliencia tiene un precio en tokens y latencia; la pregunta es si el precio es menor que el coste de mantenimiento de la alternativa.

¿Qué release de Stagehand está vigente ahora mismo?

El release más reciente y verificable hoy de Stagehand es v3.7.5, etiquetado como stagehand-server-v3/v3.7.5 en GitHub y publicado el 20 de agosto de 2026, junto con browse@0.9.6. Esa versión incorpora los siguientes cambios documentados en el diff comparado con browse@0.9.6:

• fix(v3): normalize CUA coordinates to actual viewport (#2767): antes, las coordenadas CUA (Chrome UA) no se normalizaban al viewport real, lo que podía desviar las acciones de clic o movimiento en páginas donde la posición del elemento depende del viewport actual. Este fix hace que las coordenadas que recibe la acción coincidan con lo que el navegador muestra.
• fix(v3): preserve provider for structured output (#2775): en operaciones de structured output, se conserva el provider configurado en vez de perderlo al redirigir la llamada; esto afecta a la estabilidad de extracciones estructuradas en producción.
• fix(server-v3): release useTouch parameter (#2711): el parámetro useTouch sale del release y ya no forma parte del contrato documentado.
• chore(release): retarget release automation from main to v3 (#2660) y chore(release) (#2384): infraestructura del release adaptada al flujo de la rama v3.

Atención con la confusión de versiones: no existe un Stagehand v4.0.2 lanzado en agosto de 2026. El tag que circula sin verificación devuelve 404 en GitHub; lo que sí tienes hoy es v3.7.5 como última etiqueta verificable. Esto importa porque el SDK sigue evolucionando en la rama v3; si partes de un artículo que citaba v4.0.2, hoy ese número no se sostiene.

Lo que sí es verificable sin confiar en la documentación de Browserbase: la versión última del release de Stagehand hoy, los cuatro cambios listados y la existencia del diff asociado en GitHub. Las cifras de rendimiento (2x, 80%) siguen siendo claims del fabricante y siguen sin ser un benchmark independiente replicable; esta sección no las mueve, solo añade el estado real del release.

Para consultar herramientas de IA para desarrolladores y contextualizar Stagehand entre el resto del ecosistema, revisa herramientas de IA para desarrolladores.

Comparativa de frameworks de automatización web: Stagehand v4 vs. otros

Elegir la herramienta adecuada para la automatización web depende de los requisitos específicos del proyecto, como la necesidad de resiliencia ante cambios en la interfaz de usuario, la velocidad de ejecución o la capacidad de integración con modelos de lenguaje. A continuación, se presenta una tabla comparativa que destaca las diferencias clave entre Stagehand v4 y otras soluciones populares, incluyendo Playwright y Puppeteer, así como alternativas centradas en IA como Browser Use y Skyvern.

Esta tabla subraya que, mientras Playwright y Puppeteer son excelentes para tareas de testing y scraping con estructuras predecibles, Stagehand v4, Browser Use y Skyvern están diseñados para escenarios donde la flexibilidad y la interpretación semántica son cruciales. Para explorar en profundidad las opciones de formación que te preparan para dominar estas y otras tecnologías, puedes consultar un comparador de bootcamps de programación.

Preguntas frecuentes

¿Stagehand v4 es gratuito? El SDK es open source bajo licencia MIT y puedes usarlo localmente sin coste. Sin embargo, para escala de producción con navegación remota, Browserbase ofrece infraestructura de navegadores cloud como servicio complementario, con precios basados en uso.

¿Stagehand v4 reemplaza a Playwright? No. Es complementario. Puedes usar Stagehand para las partes de tu flujo donde necesites resiliencia semántica, y caer a métodos Playwright tradicionales cuando necesites determinismo y velocidad. De hecho, Stagehand v4 requiere que tú lances el navegador con Playwright (o Puppeteer) antes de conectar Stagehand.

¿Qué modelos de lenguaje soporta Stagehand v4? Stagehand está diseñado para ser agnóstico de proveedor. Funciona con OpenAI, Anthropic, y cualquier proveedor compatible con la interfaz de chat completions. La elección del modelo afecta directamente al coste y a la precisión de las acciones.

¿Es Stagehand v4 adecuado para testing automatizado? No es su caso de uso principal. Si necesitas testing determinista con assertions precisas, Playwright sigue siendo la herramienta estándar. Stagehand brilla en automatización de agentes donde la flexibilidad importa más que la reproducibilidad exacta.

¿Cómo se compara con Browser Use o Skyvern? Las tres herramientas apuntan al mismo espacio: navegación web asistida por IA. Browser Use y Skyvern tienden a ofrecer orquestación de agente más completa "out of the box", mientras que Stagehand v4, tras eliminar agent(), se posiciona como una capa de navegación más primitiva que tú orquestas. La elección depende de cuánto control quieres sobre el flujo del agente.

¿Puedo usar Stagehand v4 con Python? Sí. Aunque el proyecto nació en TypeScript, existe un SDK oficial de Python (browserbase/stagehand-python) que expone las mismas primitivas act, extract y observe.

¿Stagehand v4 funciona con iframes y Shadow DOM? Sí, y es una de sus fortalezas documentadas. Soporta iframes anidados, iframes out-of-process, y Shadow DOM cerrado. Esto lo hace viable para automatizar aplicaciones web modernas complejas que usan estas tecnologías extensivamente.

¿Cuál es la relación entre Stagehand y Browserbase? Stagehand es desarrollado por Browserbase, una plataforma de infraestructura de navegadores para automatización. El SDK es open source y usable independientemente, pero Browserbase ofrece hosting de navegadores cloud, proxies integrados, y escalado como servicio complementario.