Toda demo de agentes de IA choca contra la misma pared: el navegador. Playwright fue construido para testing, no para agentes — los dumps crudos del DOM queman tokens, los selectores se rompen con cada rediseño, y los iframes más el shadow DOM convierten scripts simples en pesadillas.
Stagehand, el SDK open-source de Browserbase con más de 24k estrellas en GitHub, resuelve exactamente eso. En esta guía te muestro qué es, cómo funciona su arquitectura en 4 pasos, y cómo correr tu primer agente en 5 minutos con comandos verificados contra el README real.
1. Qué Es Stagehand: Estrellas, Licencia y la Gran Idea
Stagehand es el SDK para agentes de navegador, mantenido por Browserbase. Te da la API estilo Playwright que ya conocés — goto, click, locator, screenshot — más tres primitivas en lenguaje natural (act, observe, extract) que siguen funcionando cuando los sitios cambian. Un protocolo, tres SDKs: TypeScript, Python y Go.
Repositorio
github.com/browserbase/stagehand
Estrellas
~24.1k en GitHub (sep 2026)
Licencia
MIT — totalmente open source
Paquete npm
@browserbasehq/stagehand (v4.0.1)
SDKs
TypeScript, Python, Go
Docs
docs.stagehand.dev
El pitch en una frase
Playwright fue construido para testing — Stagehand está construido para agentes. Control determinista donde lo querés, acciones de IA que se auto-reparan donde las necesitás, todo sobre un motor que vive al lado del navegador en vez de al otro lado de un round-trip lento.
¿Por qué es tendencia? Porque todo agente serio tarde o temprano necesita clickear, leer y completar sitios reales. Promptear un modelo genérico con HTML crudo quema tokens y se rompe cada semana. Stagehand recorta el árbol de accesibilidad a exactamente lo que el agente necesita, resuelve acciones con su propio motor CDP, y se recupera solo cuando la página cambia debajo tuyo.
2. Cómo Funciona: La Arquitectura en 4 Pasos
No necesitás entender cada interno para shippear con Stagehand, pero este modelo mental de 4 pasos explica por qué le gana a pasarle HTML a un LLM por tu cuenta.
Paso 1 — API determinista familiar
Estilo Playwright · motor CDP
goto, click, locator, screenshot — los métodos que vos y tus agentes ya conocen. Debajo, un motor CDP corre al lado del navegador, recorta la latencia de round-trip y maneja iframes fuera de proceso y shadow DOMs cerrados de forma nativa.
Paso 2 — Tres primitivas de IA
act · observe · extract
act() ejecuta una acción desde una instrucción en lenguaje claro, observe() te dice qué es accionable en la página, y extract() trae datos estructurados con un schema de zod. Lenguaje natural adentro, selectores confiables y datos tipados afuera.
Paso 3 — Contexto auto-reparable y eficiente en tokens
recorte de árbol a11y · auto-recuperación
El recorte híbrido del árbol de accesibilidad le da al modelo exactamente lo que necesita — ni más. Cuando un sitio se rediseña, Stagehand detecta el cambio y refresca cómo se resuelven las acciones en vez de tirar un error de selector muerto a las 3am.
Paso 4 — Corre en cualquier lado: local o cloud
Chromium local · Browserbase
Funciona en local out of the box con cualquier Chromium. Cuando estás listo para producción, el mismo código corre en navegadores cloud de Browserbase con replay de sesiones, resolución de captchas, identidad de agente y deploy sin infraestructura vía Functions.
El modelo mental que uso
Código determinista para el happy path, primitivas de IA para las partes desprolijas, y el loop completo de agent() solo cuando la tarea realmente necesita autonomía. La mayoría de los flujos que llevo a producción son 80% locators y 20% act/extract — esa proporción es todo el punto.
3. Quickstart: De Cero a un Agente Funcionando en 5 Minutos
Dos caminos verificados, ambos sacados directo del README oficial y los docs. El camino A genera una app lista con el CLI. El camino B suma Stagehand a un proyecto que ya tenés. En ambos necesitás una key de un proveedor de LLM, más la key de Browserbase solo si querés navegadores cloud.
A — Generar un proyecto de ejemplo (lo más rápido)
npx create-browser-app cd my-stagehand-app cp .env.example .env # Agregá tus API keys npm start # Corré el script de ejemplo
B — Instalar en tu app existente
npm install @browserbasehq/stagehand
Configurar entorno (.env)
OPENAI_API_KEY=your_api_key BROWSERBASE_API_KEY=your_api_key
Automatizar: el loop act / observe / extract (del README)
import { browserbase, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v4";
const browser = await browserbase.launch({
apiKey: process.env.BROWSERBASE_API_KEY,
});
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");
const { data: actions } = await stagehand.observe("find the latest PR");
await page.locator(actions[0].selector).click();
const { data } = await stagehand.extract(
"extract the author and title of the PR",
z.object({ author: z.string(), title: z.string() })
);Tip: dotenv corre por tu cuenta
Stagehand no carga archivos .env automáticamente. Si usás uno, instalá dotenv y llamá dotenv.config() en tu propio código primero. Y recordá: Chromium local no necesita nada más — salteá la key de Browserbase hasta que quieras sesiones cloud.
4. Casos de Uso Reales
Stagehand brilla donde un script determinista se pudriría en semanas. Estos son los cinco patrones que veo funcionando en producción, ordenados por cuánto rinden.
Evals de agentes de navegador
Ingeniería de confiabilidad
Stagehand trae su propia cultura de evals. Puntuá corridas de act/observe/extract frente a cambios de sitios y atrapá regresiones antes que tus usuarios — el hábito de mayor ROI de toda esta guía.
Scraping web estructurado
extract + zod
Traé registros tipados (precios, listados, metadata de PRs) con un schema en vez de regex sobre HTML. Cuando el layout cambia, el modelo se adapta mientras tus tipos downstream quedan congelados.
Completar formularios y flujos de QA
act + locators
Checkouts, signups, paneles de admin. Manejá el esqueleto estable con locators y dejá que act() absorba los pasos frágiles — los CAPTCHAs y muros de auth van al cloud de Browserbase.
Agentes de research y monitoreo
agent() + search/fetch
Scans nocturnos de competidores, digests de Hacker News, watchers de docs. La fachada de browserbase hasta expone Search y Fetch sin lanzar un navegador para las partes baratas del trabajo.
Tool use vía MCP
Model Context Protocol
Exponé Stagehand con su servidor MCP para que Claude o cualquier cliente MCP maneje un navegador real como herramienta. Tu agente gana manos, no solo palabras.
5. Cuándo NO Usar Stagehand
Sección honesta, porque cada llamada a un LLM tiene un precio. Stagehand es la herramienta equivocada más seguido de lo que parece — así trazo la línea después de shippear de ambos lados.
✅ Usá Stagehand
- • Flujos con IA sobre sitios que cambian de layout seguido
- • Extracción estructurada donde los selectores se pudren más rápido de lo que los mantenés
- • Equipos que necesitan TS, Python o Go contra un protocolo, local primero
- • Evals de agentes y flotas cloud con replay, captchas e identidad
❌ Saltealo
- • Páginas totalmente estáticas — un fetch plano más un parser es 100x más barato
- • Herramientas internas congeladas donde los selectores de Playwright nunca se rompen
- • Entornos air-gapped o sin key de modelo (cada act() necesita un LLM)
- • Presupuestos de latencia ultra-bajos donde un llamado al modelo por acción rompe el p99
Regla de oro
Determinista por defecto, IA donde paga. Si un locator sobrevive tres meses intacto, nunca necesitó un modelo. Si editaste el mismo selector dos veces este trimestre, ese paso pertenece a act().
Conclusión
Stagehand se gana sus 24k estrellas respetando una verdad simple: los agentes viven en el navegador, y el navegador es terreno hostil. APIs familiares mantienen lo fácil barato, act/observe/extract absorben el caos, y el camino local-first más cloud hace que tu prototipo y tu flota de producción sean el mismo codebase.
Cloná el repo, corré npx create-browser-app, y automatizá un flujo molesto esta semana — un login, un scrape, un form. Medí los tokens, quedate con los evals, y en días vas a saber si tu roadmap lo necesita.
Stagehand en 30 segundos
Primitivas
- • act — hacé esto
- • observe — qué puedo hacer
- • extract — datos tipados
Corrélo
- • npx create-browser-app
- • npm i @browserbasehq/stagehand
- • local o Browserbase
Recordá
- • MIT, 24k+ estrellas
- • TS · Python · Go
- • determinista primero
