Stagehand v4 + Browserbase: Agentes de Navegador en Producción

La guía definitiva para construir agentes de navegador en producción con Stagehand v4 y Browserbase. Desde los cuatro primitivos (act, extract, observe, agent) y la reescritura con CDP directo hasta ciclos de desarrollo local con Chromium, despliegue en producción con Browserbase con replay de sesiones y resolución de captchas, integración con Claude Agent SDK, configuración de servidor MCP, estrategias anti-bot, benchmarks vs Puppeteer/Playwright y rutas de migración.

By Jose Nobile | 2026-04-20 | 18 min read

Por Qué la Automatización Basada en Selectores se Rompe a Escala

La automatización tradicional de navegadores con Puppeteer y Playwright depende de selectores CSS y expresiones XPath para localizar elementos. Esto funciona bien para páginas estáticas, pero las aplicaciones web modernas cambian su estructura DOM frecuentemente -- las pruebas A/B intercambian componentes, las actualizaciones de frameworks renombran clases CSS, el renderizado dinámico produce markup diferente por sesión y los límites de shadow DOM ocultan elementos de consultas externas. En 30 días en sitios de producción, los scripts de Playwright y Puppeteer requieren actualizar el 15-25% de sus selectores solo para mantener la funcionalidad básica.

La fragilidad se multiplica a escala. Un equipo manteniendo 500 tests E2E contra una SPA en rápida evolución pasará más tiempo arreglando selectores que escribiendo nueva automatización. La automatización potenciada por AI reemplaza selectores frágiles con instrucciones en lenguaje natural que se adaptan a cambios de layout. En vez de page.click('#submit-btn-v3'), escribes page.act('click the submit button'). La AI interpreta el DOM actual y encuentra el elemento correcto sin importar su clase CSS, atributo de datos o posición en el árbol.

Stagehand ocupa el punto medio pragmático entre la automatización completamente manual basada en selectores y las soluciones opacas de agente completo. Te da código determinístico donde lo quieres y flexibilidad potenciada por AI donde la página es impredecible, que es exactamente el balance que los workflows de producción requieren.

Los Cuatro Primitivos de Stagehand

ACT

act()

Realiza acciones de navegador desde una instrucción en inglés simple: click, llenar, navegar, scroll, hover, seleccionar. La AI interpreta la página actual y ejecuta la acción en el elemento correcto. Usa act() para interacciones únicas y determinísticas donde quieres control preciso.page.act('click the submit button') or page.act('fill the email field with [email protected]').

EXTRACT

extract()

Extrae datos estructurados de cualquier página usando validación de esquema con Zod. Describe lo que quieres y define la forma de salida -- Stagehand lee el DOM, identifica el contenido relevante y lo devuelve como un objeto tipado. Usa extract() para scraping de listados de productos, lectura de tablas o captura de estado de formularios.page.extract({ schema: z.object({ price: z.string(), title: z.string() }) }).

OBSERVE

observe()

Muestra qué es accionable en una página antes de comprometerte con una acción. Devuelve una lista de elementos interactivos con sus descripciones e interacciones posibles. Usa observe() para páginas dinámicas donde necesitas entender qué ofrece la página antes de decidir qué hacer.

AGENT

agent()

Ejecuta workflows multi-paso de forma autónoma cuando necesitas ejecución end-to-end. Dale al agente un objetivo de alto nivel y encadena llamadas a act, extract y observe internamente para lograr la tarea. Usa agent() para flujos complejos como procesos de checkout, wizards de formularios y navegación multi-página. Soporta modelos Claude y OpenAI.

Cuándo Usar Cada Primitivo

Usa act(), extract() y observe() cuando quieres control preciso paso a paso sobre las acciones del navegador -- son determinísticos y predecibles. Usa agent() cuando necesitas workflows multi-paso ejecutados de forma autónoma. La mayoría de los equipos de producción combinan ambos enfoques: agent() para exploración y descubrimiento, primitivos individuales para caminos críticos donde la confiabilidad importa más.

La Reescritura v3: CDP Directo, 44% Más Rápido, Licencia MIT

Stagehand v3, lanzado en octubre 2025, es una reescritura desde cero que elimina completamente la dependencia de Playwright. En vez de rutear comandos a través de la capa de protocolo de Playwright, v3 habla directamente con el navegador usando el Chrome DevTools Protocol (CDP). Esto elimina un salto de red completo por comando y minimiza el tiempo de ida y vuelta (RTT), resultando en una ejecución 44%+ más rápida en todos los escenarios.

Como Stagehand habla CDP directamente, no necesita Playwright ni Puppeteer como dependencia, así que puedes agregarlo junto a una stack de automatización existente (ver Puppeteer) sin reescribir tu infraestructura. La arquitectura es AI-nativa desde la base: las acciones descubiertas pueden cachearse para que los pasos repetidos salten la llamada al LLM (Browserbase recomienda sus navegadores alojados para el caché del lado del servidor y el Model Gateway).

Stagehand es completamente open source bajo la licencia MIT, haciéndolo seguro para uso comercial. La documentación de v4 lista SDKs para TypeScript, Python y Go.

Stagehand está ahora en v4 (docs en docs.stagehand.dev/v4; se recomienda Node.js 22.18+ o Python 3.11+). Mantiene los primitivos de AI act, extract y observe y agrega métodos page al estilo Playwright (goto, locator, screenshot). Los modelos se eligen con cadenas proveedor/modelo (el quickstart de v4 usa openai/gpt-5.6-sol; los modelos de Anthropic y Google funcionan igual), y en Browserbase el Model Gateway elige un modelo por ti cuando no configuras ninguno. Los ejemplos de código de abajo siguen el quickstart de v4.

Configuración del Ciclo de Desarrollo Local con Chromium

Empieza el desarrollo localmente antes de conectar a Browserbase para producción. La configuración local ejecuta una instancia real de Chromium en tu máquina con acceso CDP completo, dándote feedback instantáneo durante el desarrollo sin latencia de cloud ni costos.

# Install Stagehand (TypeScript; zod is pinned to the 4.4.x line per the v4 docs)
npm install @browserbasehq/stagehand "zod@~4.4.3"

# Install Stagehand (Python 3.11+)
pip install stagehand

Un script local mínimo que demuestra los tres primitivos de AI (observe, act, extract).

// local-dev.ts -- Stagehand v4 local dev loop (requires Chrome installed)
import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v4";

const browser = await localBrowser.launch();
try {
  const stagehand = await Stagehand.create({
    browser,
    // any provider/model string; the key is passed in explicitly
    model: {
      modelName: "anthropic/claude-sonnet-5-5",
      apiKey: process.env.ANTHROPIC_API_KEY,
    },
  });
  try {
    const [page] = await browser.context.pages();
    await page.goto("https://news.ycombinator.com");

    // observe() -- what can we do on this page?
    const actions = await stagehand.observe("What are the interactive elements on this page?");
    console.log("Available actions:", actions.data);

    // act() -- click using natural language
    await stagehand.act("Click on the first story link");

    // extract() -- pull structured data with a Zod schema
    const result = await stagehand.extract(
      "Extract the article title",
      z.object({ title: z.string() }),
    );
    console.log("Extracted:", result.data);
  } finally {
    await stagehand.close();
  }
} finally {
  await browser.close();
}

Para Python, la configuración equivalente es igual de directa.

# local_dev.py -- Stagehand v4 local dev loop (Python)
import asyncio
import os

from pydantic import BaseModel
from stagehand import Stagehand, local_browser


class Title(BaseModel):
    title: str


async def main() -> None:
    browser = await local_browser.launch()
    try:
        stagehand = await Stagehand.create(
            browser=browser,
            model="anthropic/claude-sonnet-5-5",
            model_api_key=os.environ["ANTHROPIC_API_KEY"],
        )
        try:
            page = (await browser.context.pages())[0]
            await page.goto("https://example.com")
            await stagehand.act("Click the 'More information' link")
            result = await stagehand.extract("Extract the page title", Title)
            print(result.data)
        finally:
            await stagehand.close()
    finally:
        await browser.close()

asyncio.run(main())

Ejecútalo con ANTHROPIC_API_KEY=sk-... pnpm dlx tsx local-dev.ts. Chrome debe estar instalado localmente porque Stagehand lo controla por el DevTools Protocol, y Stagehand no lee las API keys del entorno por sí solo -- tu script las lee y las pasa explícitamente, como arriba.

Conectando Browserbase para Producción

Browserbase provee la infraestructura de producción que convierte tus scripts Stagehand locales en agentes de navegador escalables y confiables. Cambiar de local a Browserbase significa cambiar la fuente del navegador -- localBrowser.launch() pasa a ser browserbase.launch({ apiKey }) -- y definir BROWSERBASE_API_KEY; no se necesita Chrome local. Si no configuras un modelo, el Model Gateway de Browserbase elige uno automáticamente, por lo que las keys de proveedores separadas son opcionales (los planes Developer y Startup pagan los modelos a precio de mercado a través del gateway).

// production.ts -- Stagehand v4 on Browserbase
import { browserbase, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v4";

// Cloud browser: no local Chrome needed, only BROWSERBASE_API_KEY
const browser = await browserbase.launch({
  apiKey: process.env.BROWSERBASE_API_KEY,
});
try {
  // model is optional on Browserbase: the Model Gateway picks one if omitted
  const stagehand = await Stagehand.create({ browser });
  try {
    // Everything else stays exactly the same
    const [page] = await browser.context.pages();
    await page.goto("https://target-site.com");
    await stagehand.act("Accept the cookie banner");
    const result = await stagehand.extract(
      "Extract all product prices and names",
      z.object({
        products: z.array(z.object({ name: z.string(), price: z.string() })),
      }),
    );
    console.log(result.data);
  } finally {
    await stagehand.close();
  }
} finally {
  await browser.close();
}

Características de Producción de Browserbase

DEBUG

Replay de Sesiones

Cada sesión de navegador se graba con snapshots completos del DOM, requests de red, logs de consola y capturas de pantalla. Cuando una automatización falla, reproduce la sesión exacta para ver qué vio el agente y dónde falló.

SOLVE

Resolución de CAPTCHA

La resolución de CAPTCHA está incluida en los planes de pago de Browserbase (no está disponible en el plan Free), así que los desafíos se manejan en tus sesiones sin suscripciones de CAPTCHA de terceros.

NET

Proxies Residenciales

Configura proxies residenciales para automatización geo-específica con pools de proxies rotativos para operaciones a gran escala. La rotación de IP integrada previene rate limiting.

SCALE

Sesiones Concurrentes

Ejecuta múltiples sesiones de navegador simultáneamente para scraping, testing y automatización en paralelo. Concurrencia por plan: 3 (Free), 25 (Developer), 100 (Startup), 250+ (Scale).

VIEW

Vista en Vivo

Integra sesiones de navegador en vivo en tus propias aplicaciones. Mira agentes navegar en tiempo real, útil para demos, automatización orientada al cliente y debugging.

CACHE

Cache de Acciones

Stagehand puede cachear las acciones descubiertas para que las visitas repetidas a la misma estructura de página salten la llamada al LLM, reduciendo latencia y costo. Browserbase recomienda sus navegadores alojados para obtener caché del lado del servidor.

Resumen de Precios

Precios de Browserbase (browserbase.com/pricing): el plan Free cuesta $0 con 1 hora de navegador, 3 navegadores concurrentes, sesiones de 15 minutos y 7 días de retención. Developer a $20/mes incluye 100 horas y 25 navegadores concurrentes ($0.12/hr excedente, 1 GB de proxies, resolución de CAPTCHA, 30 días de retención). Startup a $99/mes provee 500 horas, 5 GB de proxies y 100 navegadores concurrentes ($0.10/hr excedente). Las llamadas de Search y Fetch API están incluidas hasta una cuota y luego se facturan por 1K (search desde $5/1K por defecto; fetch $1/1K en Developer y $0.50/1K en Startup). El plan Scale tiene precio personalizado para 250+ navegadores concurrentes y agrega stealth avanzado, SSO, DPA y HIPAA (BAA).

Combinando Stagehand con Claude Agent SDK

El Claude Agent SDK provee la capa de orquestación para construir agentes AI de grado producción. Stagehand puede integrarse como la herramienta de navegador de un agente Claude (el ejemplo de abajo usa el ciclo de tool use de la Messages API), dándole a tu agente la capacidad de navegar la web, llenar formularios, extraer datos e interactuar con cualquier sitio web.

// agent-with-browser.ts -- Claude + Stagehand v4 as a browser tool
import Anthropic from "@anthropic-ai/sdk";
import { browserbase, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v4";

// Initialize Stagehand as the browser tool
const browser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY });
const stagehand = await Stagehand.create({ browser });

// Define a tool that the Claude agent can invoke
const browserTool = {
  name: "browse_web",
  description: "Navigate to a URL and interact with the page",
  input_schema: {
    type: "object",
    properties: {
      url: { type: "string", description: "URL to navigate to" },
      action: { type: "string", description: "Action to perform" },
      extract_instruction: {
        type: "string",
        description: "Optional: what text to extract afterwards"
      }
    },
    required: ["url", "action"]
  }
};

// The agent loop: Claude reasons, Stagehand executes
const client = new Anthropic();
const response = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 4096,
  tools: [browserTool],
  messages: [{
    role: "user",
    content: "Research the pricing for Vercel, Netlify, " +
             "and Cloudflare. Compare them in a table."
  }]
});

// Handle tool calls from Claude
for (const block of response.content) {
  if (block.type === "tool_use" && block.name === "browse_web") {
    const [page] = await browser.context.pages();
    await page.goto(block.input.url);
    await stagehand.act(block.input.action);
    if (block.input.extract_instruction) {
      const result = await stagehand.extract(
        block.input.extract_instruction,
        z.object({ text: z.string() })
      );
      // Feed result.data back to Claude as a tool_result for reasoning
    }
  }
}
await stagehand.close();
await browser.close();

Este patrón habilita casos de uso que ninguna herramienta puede lograr sola. Claude razona sobre qué información necesita, decide qué sitios visitar, formula instrucciones en lenguaje natural para Stagehand y sintetiza los datos extraídos en una respuesta coherente. Stagehand maneja la realidad desordenada de las páginas web mientras Claude maneja el razonamiento de alto nivel.

Para equipos que ya usan el Claude Agent SDK, Stagehand reemplaza la necesidad de implementaciones personalizadas de herramientas de navegador. En vez de mantener un wrapper de Puppeteer con gestión manual de selectores, obtienes interacción de navegador potenciada por AI que se adapta a cambios de página automáticamente.

Integración del Servidor MCP de Stagehand

El servidor MCP de Browserbase expone la automatización de navegador de Stagehand como herramientas MCP, permitiendo a cualquier cliente AI compatible con MCP (Claude Code, Claude Desktop, VS Code) navegar la web, interactuar con páginas y extraer datos. El servidor alojado en https://mcp.browserbase.com/mcp es la configuración más simple; el repo de GitHub browserbase/mcp-server-browserbase está archivado (solo lectura) y su README recomienda el servidor alojado.

// .mcp.json -- Browserbase hosted MCP server (Streamable HTTP)
{
  "mcpServers": {
    "browserbase": {
      "type": "http",
      "url": "https://mcp.browserbase.com/mcp"
    }
  }
}

// Alternative: local STDIO mode (npm package @browserbasehq/mcp)
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "...",
        "BROWSERBASE_PROJECT_ID": "...",
        "GEMINI_API_KEY": "..."
      }
    }
  }
}

Una vez configurado, tu cliente AI obtiene seis herramientas: start y end (crear o cerrar una sesión), navigate, act, observe y extract.

También hay una opción STDIO autoalojada: el paquete npm @browserbasehq/mcp corre en tu máquina con tu BROWSERBASE_API_KEY y BROWSERBASE_PROJECT_ID, más GEMINI_API_KEY para el modelo por defecto (o --modelApiKey para uno personalizado). Sigue usando los navegadores en la nube de Browserbase; no es un modo de Chromium local sin cuenta.

El enfoque MCP es particularmente poderoso para workflows de Claude Code. Pídele a Claude Code que "abra esta URL y extraiga la tabla de precios" -- rutea la solicitud a través del servidor MCP de Browserbase, Stagehand ejecuta la extracción y los resultados fluyen de vuelta a tu conversación.

Estrategias Anti-Bot y de Identidad

Los agentes de navegador en producción enfrentan detección agresiva de bots de Cloudflare, DataDome, PerimeterX y Akamai. Browserbase resuelve esto a través de alianzas directas con proveedores de protección contra bots -- los navegadores verificados son reconocidos como legítimos, logrando tasas de éxito más altas que los plugins de stealth.verified as legitimate through direct partnerships with leading bot protection providers. Verified browsers are recognized by the protection systems themselves, yielding higher success rates and fewer interruptions than stealth plugins.

El sistema de Identidad de Agente de Browserbase incluye rotación automática de fingerprint (canvas, WebGL, AudioContext, navigator), rotación de proxy residencial con geo-targeting, patrones de navegación tipo humano y gestión de fingerprint TLS. Cuáles aplican depende del plan (stealth básico en Developer y Startup, stealth avanzado y Verified Agents en Scale; ninguno en Free).

Para configuraciones self-hosted: usa puppeteer-extra-plugin-stealth con Puppeteer, rota user agents, agrega delays realistas entre acciones y evita señales específicas de headless. Para automatización de alto volumen, el enfoque de navegador verificado de Browserbase es significativamente más confiable.

Benchmarks de Costo y Confiabilidad

44% más rápido

Stagehand v3 vs v2 en todos los escenarios. La arquitectura CDP directa elimina el overhead del protocolo de Playwright, con las mayores ganancias en interacciones con iframes y shadow DOM.

Evals publicados

Los puntajes de benchmarks de agentes (WebVoyager y otros) dependen del modelo, el conjunto de tareas y la fecha, y las comparaciones entre proveedores cambian rápido. Consulta la página de evals en stagehand.dev para cifras actuales en vez de confiar en un solo número; los scripts Playwright escritos a mano siguen siendo los más confiables pero requieren horas de desarrollo por tarea.

Menos mantenimiento de selectores

Los pasos en lenguaje natural se resuelven de nuevo contra la página en vivo, así que una clase CSS renombrada o un layout reorganizado a menudo no los rompe como a un selector fijo. Espera mantener prompts y esquemas en vez de selectores.

El costo sigue a los tokens

Cada llamada act, extract u observe sin caché cuesta tokens de LLM al precio del modelo que elijas (en los planes de pago de Browserbase, los modelos se facturan a precio de mercado a través del Model Gateway). Las acciones en caché saltan el LLM por completo, así que el costo depende más de la diversidad de páginas que del volumen de acciones.

Browserbase desde $20/mes

El plan Developer incluye 100 horas de navegador, 25 navegadores concurrentes, 1 GB de proxies, resolución automática de CAPTCHA y replay de sesiones.

Tier gratuito disponible

1 hora de navegador gratis con 7 días de retención. Stagehand en sí es licencia MIT y gratuito. El único costo requerido es uso de API LLM.

Migración desde Puppeteer

Stagehand fue diseñado para adopción incremental. Como no necesita Playwright ni Puppeteer como dependencia, puedes introducirlo en un proyecto Puppeteer existente sin reemplazar toda tu stack de automatización.

// Step 1: Existing Puppeteer script
import puppeteer from "puppeteer";
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto("https://example.com");
// Fragile selector -- breaks when UI changes
await page.click("#login-form .submit-btn.primary");
await page.type("#email-input", "[email protected]");

// Step 2: Add Stagehand (v4) for the fragile steps
import { localBrowser, Stagehand } from "@browserbasehq/stagehand";
import { z } from "zod/v4";

const sbBrowser = await localBrowser.launch();
const stagehand = await Stagehand.create({
  browser: sbBrowser,
  model: {
    modelName: "anthropic/claude-sonnet-5-5",
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
});
const [sbPage] = await sbBrowser.context.pages();

await sbPage.goto("https://example.com");

// Replace brittle selectors with natural language
await stagehand.act("Fill the email field with [email protected]");
await stagehand.act("Click the submit button");

// Use Stagehand for dynamic or unpredictable elements
const summary = await stagehand.extract(
  "Extract the dashboard summary metrics",
  z.object({
    totalUsers: z.string(),
    revenue: z.string(),
    growth: z.string()
  })
);
console.log(summary.data);

await stagehand.close();
await sbBrowser.close();

La estrategia de migración es simple: mantén las acciones determinísticas como código, reemplaza los selectores frágiles con AI. Navegación de URL, configuración de cookies, configuración de viewport e intercepción de red se quedan como llamadas Puppeteer/CDP. Interacción con elementos, extracción de datos y llenado de formularios migran a primitivos de Stagehand.

Mapeos clave de API: page.click(selector) se convierte en stagehand.act('click the [descripción]'), page.type(selector, text) se convierte en stagehand.act('type [texto] into the [descripción]'), page.$(selector) se convierte en stagehand.extract(instruction, schema) y page.$$(selector) se convierte en stagehand.observe('list all [tipo de elemento]').

Pasos Auto-Reparables y Cache de Acciones

Los docs de v4 describen act, extract y observe como pasos en lenguaje natural y auto-reparables: cada llamada sin caché vuelve a leer la página en vivo, así que un botón movido o una clase renombrada no rompe el script como lo haría un selector fijo. Los métodos page al estilo Playwright, deterministas, siguen disponibles para los pasos que nunca cambian.

El caché lo complementa: una vez resuelta una acción, puede reproducirse sin otra llamada al LLM, y Browserbase recomienda sus navegadores alojados para el caché del lado del servidor. Usa el replay de sesiones de Browserbase para ver lo que vio el agente cuando un paso falla.

Nota: una versión anterior de esta guía describía un "Context Builder de v3.2" con porcentajes específicos de reducción de tokens y de fallas. Esas cifras no pudieron confirmarse en la documentación de Stagehand y se eliminaron.

Tecnologías Relacionadas