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

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.

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.

El nuevo sistema de drivers modulares permite a Stagehand trabajar sin problemas con Puppeteer o cualquier driver construido sobre CDP. Esto significa que puedes agregar Stagehand a proyectos Puppeteer existentes sin reescribir tu infraestructura. La arquitectura es AI-nativa desde la base: v3 cachea automáticamente elementos descubiertos y acciones que puedes reutilizar sin costo adicional de inferencia LLM.

Stagehand es completamente open source bajo la licencia MIT, haciéndolo seguro para uso comercial. La expansión multi-lenguaje es significativa: más allá del SDK original de TypeScript, Stagehand está disponible en Python, Go, Java, Ruby y Rust. El SDK de Python tiene paridad completa de features con v3.

v3 soporta todos los proveedores de modelos principales vía el Vercel AI SDK -- Anthropic Claude, OpenAI GPT-5.6 y Google Gemini. Claude sobresale en razonamiento de alto nivel y toma de decisiones dinámicas, mientras que modelos más pequeños y económicos como GPT-5.6 Luna son más adecuados para ejecutar acciones de navegador específicas y dirigidas.

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)
npm install @browserbasehq/stagehand

# Install Stagehand (Python)
pip install stagehand-py

Un script local mínimo que demuestra los cuatro primitivos.

// local-dev.ts -- Stagehand local Chromium dev loop
import Stagehand from "@browserbasehq/stagehand";
import { z } from "zod";

const stagehand = new Stagehand({
  env: "LOCAL",            // Run local Chromium, no cloud
  modelName: "claude-sonnet-5",
  modelClientOptions: {
    apiKey: process.env.ANTHROPIC_API_KEY
  }
});

await stagehand.init();
const page = stagehand.page;

// Navigate with standard CDP -- fast, deterministic
await page.goto("https://news.ycombinator.com");

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

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

// extract() -- pull structured data
const data = await page.extract({
  instruction: "Extract the article title and all comments",
  schema: z.object({
    title: z.string(),
    comments: z.array(z.string())
  })
});
console.log("Extracted:", data);

// agent() -- autonomous multi-step workflow
await page.agent(
  "Go back to the homepage, find the highest-scored post, " +
  "click into it, and extract the submission URL"
);

await stagehand.close();

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

# local_dev.py -- Stagehand local dev loop (Python)
import asyncio
from stagehand import Stagehand, StagehandConfig

async def main():
    config = StagehandConfig(
        env="LOCAL",
        model_name="claude-sonnet-5",
        model_client_options={
            "api_key": os.environ["ANTHROPIC_API_KEY"]
        }
    )
    stagehand = Stagehand(config)
    await stagehand.init()
    page = stagehand.page

    await page.goto("https://example.com")
    await page.act("Click the 'More information' link")

    result = await page.extract(
        instruction="Extract the page title and first paragraph",
        schema={"title": "string", "body": "string"}
    )
    print(result)

    await stagehand.close()

asyncio.run(main())

Ejecuta tus scripts locales con ANTHROPIC_API_KEY=sk-... npx ts-node local-dev.ts. El navegador se lanza visiblemente por defecto en modo LOCAL, para que puedas ver la AI interactuar con la página en tiempo real. Configura headless: true en la config para suprimir la ventana del navegador en entornos CI.

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 requiere cambiar una línea de configuración -- configura env: "BROWSERBASE" -- y proveer tu API key y project ID. Desde abril de 2026, el Model Gateway de Browserbase permite usar Stagehand con cualquier LLM soportado usando solo tu API key de Browserbase -- Browserbase maneja el ruteo de modelos, los reintentos y la facturación, por lo que las keys de proveedores separadas son opcionales.

// production.ts -- Stagehand with Browserbase
import Stagehand from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "BROWSERBASE",      // Switch from LOCAL to cloud
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  modelName: "claude-sonnet-5",
  modelClientOptions: {
    apiKey: process.env.ANTHROPIC_API_KEY
  }
});

await stagehand.init();
// Everything else stays exactly the same
const page = stagehand.page;
await page.goto("https://target-site.com");
await page.act("Accept the cookie banner");
const data = await page.extract({
  instruction: "Extract all product prices and names",
  schema: z.object({
    products: z.array(z.object({
      name: z.string(),
      price: z.string()
    }))
  })
});
await stagehand.close();

Características de Producción de Browserbase

Resumen de Precios

Browserbase ofrece un tier gratuito con 1 hora de navegador y 3 navegadores concurrentes. Developer a $20/mes incluye 100 horas y 25 navegadores concurrentes ($0.12/hr excedente). Startup a $99/mes provee 500 horas, 5 GB de proxies y 100 navegadores concurrentes ($0.10/hr excedente, retención de 30 días). Ambos incluyen llamadas de Search API y Fetch API (luego $7/1K requests de search y $1/1K de fetch). El plan Scale tiene precio personalizado para 250+ navegadores concurrentes y agrega 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 se integra como la herramienta de navegador dentro de un workflow de Claude Agent SDK, 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 Agent SDK + Stagehand
import Anthropic from "@anthropic-ai/sdk";
import Stagehand from "@browserbasehq/stagehand";

// Initialize Stagehand as the browser tool
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  modelName: "claude-sonnet-5",
  modelClientOptions: {
    apiKey: process.env.ANTHROPIC_API_KEY
  }
});
await stagehand.init();

// 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_schema: {
        type: "object",
        description: "Optional: schema for data extraction"
      }
    },
    required: ["url", "action"]
  }
};

// The agent loop: Claude reasons, Stagehand executes
const client = new Anthropic();
const response = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 4096,
  tools: [browserTool],
  messages: [{
    role: "user",
    content: "Research the pricing for Vercel, Netlify, " +
             "and Cloudflare Pages. 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 = stagehand.page;
    await page.goto(block.input.url);
    await page.act(block.input.action);
    if (block.input.extract_schema) {
      const data = await page.extract({
        instruction: "Extract the requested data",
        schema: block.input.extract_schema
      });
      // Feed results back to Claude for reasoning
    }
  }
}
await stagehand.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 las capacidades de 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, extraer datos y tomar capturas de pantalla.

// .mcp.json -- Browserbase MCP server (Streamable HTTP)
{
  "mcpServers": {
    "browserbase": {
      "type": "streamable-http",
      "url": "https://mcp.browserbase.com",
      "headers": {
        "Authorization": "Bearer ${BROWSERBASE_API_KEY}",
        "X-BB-Project-Id": "${BROWSERBASE_PROJECT_ID}"
      }
    }
  }
}

// Alternative: local STDIO mode
{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["-y", "@browserbasehq/mcp-server-browserbase"],
      "env": {
        "BROWSERBASE_API_KEY": "${BROWSERBASE_API_KEY}",
        "BROWSERBASE_PROJECT_ID": "${BROWSERBASE_PROJECT_ID}"
      }
    }
  }
}

Una vez configurado, tu cliente AI obtiene acceso a herramientas de navegador: navegar a URLs, interactuar con elementos de página vía lenguaje natural, extraer contenido estructurado, tomar capturas y gestionar múltiples sesiones concurrentes.

También hay una opción de servidor MCP completamente local que ejecuta Stagehand con una instancia local de Chromium, sin requerir cuenta de Browserbase. Ideal para desarrollo, testing y entornos restringidos.npx @browserbasehq/mcp-server-browserbase --local and configure it in your MCP settings with the LOCAL environment flag.

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. Todo habilitado por defecto.

Para configuraciones self-hosted: usa puppeteer-extra-plugin-stealth con el driver Puppeteer de Stagehand, 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.

Migración desde Puppeteer

Stagehand v3 fue diseñado para adopción incremental. Como soporta el driver Puppeteer nativamente, puedes introducir Stagehand 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 alongside Puppeteer
import Stagehand from "@browserbasehq/stagehand";

const stagehand = new Stagehand({
  env: "LOCAL",
  modelName: "claude-sonnet-5",
  modelClientOptions: {
    apiKey: process.env.ANTHROPIC_API_KEY
  }
});
await stagehand.init();
const page = stagehand.page;

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

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

// Mix and match: use Puppeteer for fast, known actions
await page.evaluate(() => window.scrollTo(0, 0));

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

await stagehand.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 page.act('click the [descripción]'), page.type(selector, text) se convierte en page.act('type [texto] into the [descripción]'), page.$(selector) se convierte en page.extract({ instruction, schema }) y page.$$(selector) se convierte en page.observe('list all [tipo de elemento]').

Context Builder y Ejecución Auto-Reparable

Stagehand v3.2 (abril 2026) introduce el Context Builder, una capa de pre-procesamiento que reduce el consumo de tokens LLM hasta un 60% por acción. En vez de enviar todo el DOM de la página al modelo para cada llamada act() o extract(), el Context Builder realiza análisis heurístico local para identificar el subárbol DOM relevante, elimina elementos no visibles, colapsa estructuras repetitivas y comprime datos de atributos. El payload de contexto resultante es típicamente 3-5x más pequeño que el DOM completo, reduciendo tanto latencia como costo por operación.

La Ejecución Auto-Reparable maneja cambios de DOM que ocurren entre observación y acción. Cuando Stagehand identifica un elemento vía el LLM pero el DOM muta antes de que el comando CDP se ejecute (por lazy loading, animaciones o re-renders de React), el sistema auto-reparable re-escanea automáticamente el subárbol afectado, re-identifica el elemento objetivo y reintenta la acción sin requerir un round-trip completo al LLM. Esto reduce las fallas a mitad de acción en aproximadamente 40% en SPAs dinámicas.

Ambas características aprovechan el diseño agnóstico de driver de la reescritura v3. Context Builder y Auto-Reparación funcionan de forma idéntica ya sea que uses el driver CDP integrado, el driver Puppeteer o una implementación de driver personalizada. Esto asegura comportamiento consistente entre desarrollo local y entornos de producción de Browserbase.