Stagehand + Scrapeless: Automatización de Navegación AI en un Navegador en la Nube

TL;DR:

• Stagehand es un marco de automatización de navegación basado en IA que combina instrucciones en inglés sencillo con código real de Playwright, exponiendo tres primitivas — act, extract y observe — sobre una sesión del Protocolo DevTools de Chrome.
• Dirige Stagehand al Scrapeless Scraping Browser configurando un campo: localBrowserLaunchOptions.cdpUrl al punto final WebSocket de Scrapeless. No hay ningún cambio en tu código de Stagehand.
• El navegador se ejecuta entonces en la nube, por lo que tu automatización obtiene sesiones gestionadas, fingerprinting y salida residencial en lugar de un Chromium local que debes lanzar, escalar y mantener desbloqueado.
• Tú traes tu propia clave de modelo. Stagehand llama a un modelo de lenguaje para act/extract/observe; el navegador y el modelo son preocupaciones separadas.
• Comienza gratis. Las nuevas cuentas de Scrapeless incluyen créditos gratuitos para el Scraping Browser — regístrate en app.scrapeless.com.

Stagehand, el marco de código abierto de Browserbase, se sitúa entre dos extremos: scripts de selectores frágiles que se rompen con cada cambio de marcado, y agentes de libre circulación que no puedes predecir. Te ofrece tres primitivas componibles — act para hacer algo, extract para obtener datos estructurados, y observe para encontrar elementos — cada una impulsada por una instrucción en lenguaje natural y cada una retornando a tu control. Lo que Stagehand todavía necesita es un navegador que dirigir. Ejecutar ese navegador localmente significa lanzar Chromium, escalarlo y mantenerlo sin ser bloqueado. Esta guía conecta Stagehand al Scrapeless Scraping Browser en su lugar, por lo que el marco permanece igual y el navegador se mueve a la nube. Cada comando y salida a continuación fue capturado de una ejecución en vivo.

Lo que esta integración te ofrece

Stagehand se conecta a un navegador a través del Protocolo DevTools de Chrome. El Scrapeless Scraping Browser expone exactamente eso: un entorno real de Chrome al cual puedes acceder a través de una URL de WebSocket. Conectar los dos significa:

• Sin navegador local que operar. No lanzas, parcheas ni escalas Chromium; la sesión se ejecuta en el servidor y tú te conectas a ella.
• Sesiones y salida gestionadas. El navegador en la nube maneja perfiles de dispositivos realistas y enrutamiento residencial, por lo que las páginas que lee Stagehand parecen las de un visitante real.
• La misma API de Stagehand. act, extract y observe se comportan de manera idéntica ya sea que el navegador sea local o remoto — solo la URL de conexión cambia.
• Una separación limpia de preocupaciones. Scrapeless ejecuta el navegador; tu modelo elegido ejecuta el razonamiento. Puedes reemplazar cualquiera sin tocar el otro.

Requisitos previos

• Node.js 20.19+ o 22.12+ y un gestor de paquetes (esta guía utiliza pnpm).
• Una clave de API de Scrapeless para el Scraping Browser — obtén una en el plan gratuito en app.scrapeless.com.
• Una clave de API de proveedor de modelo. Stagehand llama a un modelo de lenguaje para sus primitivas; cualquier proveedor compatible funciona.

Instalación

Agrega Stagehand y Zod, que tipa la salida estructurada de extract:

pnpm add @browserbasehq/stagehand zod

Conectar Stagehand al Scraping Browser

Toda la integración es un campo. localBrowserLaunchOptions.cdpUrl de Stagehand acepta un punto final CDP WebSocket; pasa la URL del Scrapeless Scraping Browser, con tu clave API como el parámetro de consulta token. El modelo se proporciona por separado como un llmClient.

import { Stagehand, AISdkClient, getAISDKLanguageModel } from "@browserbasehq/stagehand";
import { z } from "zod";

// Tu propio proveedor de modelo (OpenAI aquí; inserta cualquier clave de proveedor compatible).
const model = getAISDKLanguageModel("openai", "gpt-4o-mini", {
  apiKey: process.env.OPENAI_API_KEY,
});

const stagehand = new Stagehand({
  env: "LOCAL",
  llmClient: new AISdkClient({ model }),
  localBrowserLaunchOptions: {
    cdpUrl:
      `wss://browser.scrapeless.com/api/v2/browser` +
      `?token=${process.env.SCRAPELESS_API_KEY}` +
      `&session_ttl=180&proxy_country=US`,
  },
});

await stagehand.init();

Después de init(), Stagehand está dirigiendo una sesión de Chrome alojada por Scrapeless. El contexto de Playwright está disponible como stagehand.context, y las tres primitivas de IA viven en la instancia de stagehand.

Dirigir la Página

La navegación utiliza el contexto estándar de Playwright. Captura la página activa y ve a un objetivo:

const context = stagehand.context;
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://news.ycombinator.com", { waitUntil: "domcontentloaded" });

observar — encontrar un elemento en inglés sencillo

observar devuelve elementos candidatos con un selector resuelto, para que puedas inspeccionar qué acción se dirigiría antes de ejecutarla:

const candidates = await stagehand.observe("el enlace de inicio de sesión en la barra de navegación superior");
console.log(candidates[0]);

Una ejecución en vivo devolvió un único candidato resuelto:

// Capturado de una ejecución en vivo contra el navegador de raspeo Scrapeless.
{
  "description": "Enlace a la página de inicio de sesión en la barra de navegación superior",
  "method": "clic",
  "arguments": [],
  "selector": "xpath=/html[1]/body[1]/center[1]/table[1]/tbody[1]/tr[1]/td[1]/table[1]/tbody[1]/tr[1]/td[3]/span[1]/a[1]"
}

extraer — convertir una página en datos tipados

extraer toma una instrucción y un esquema de Zod, y devuelve datos que coinciden con el esquema. El esquema es el contrato; Stagehand lo llena desde la página:

const result = await stagehand.extract(
  "extraer los 3 títulos de historias principales y sus recuentos de puntos desde la página de inicio",
  z.object({
    stories: z.array(z.object({ title: z.string(), points: z.number() })).max(3),
  }),
);
console.log(result);

La ejecución en vivo devolvió filas tipadas directamente de la página de inicio:

// Capturado de una ejecución en vivo — títulos reales y recuentos de puntos de la página de inicio.
{
  "stories": [
    { "title": "Ejecutando Gemma 4 26B a 5 tokens/seg en un Xeon de 13 años sin GPU (neomindlabs.com)", "points": 82 },
    { "title": "Misterios de los Centros de Datos de Telegram (dev.moe)", "points": 163 },
    { "title": "Memoria de código abierto para agentes de codificación, sincronizada a través de SSH (github.com/vshulcz)", "points": 43 }
  ]
}

actuar — realizar una acción a partir de una instrucción

actuar ejecuta una acción en inglés sencillo contra la página. Aquí hace clic en un enlace de navegación, lo que mueve la sesión a una nueva URL:

console.log(page.url()); // https://news.ycombinator.com/
await stagehand.act("clic en el enlace 'nuevas' en la barra de navegación superior");
await page.waitForLoadState("domcontentloaded");
console.log(page.url()); // https://news.ycombinator.com/newest

La ejecución en vivo navegó de https://news.ycombinator.com/ a https://news.ycombinator.com/nuevas, confirmando que la instrucción se resolvió en un clic real.

Cerrar la Sesión

Libera el navegador en la nube cuando la ejecución termine:

await stagehand.close();

Por qué ejecutar el navegador en Scrapeless

Stagehand es deliberadamente poco opinativo sobre dónde vive el navegador — eso es lo que hace que el intercambio de cdpUrl sea tan limpio. Ejecutar Chromium por tu cuenta está bien para una demostración en un portátil, pero una carga de trabajo real significa concurrencia, higiene de sesión y mantenerse desbloqueado a través de muchas páginas. El Navegador de Raspeo Scrapeless es un entorno real de Chrome con perfiles de dispositivo y huella digitales realistas, y egresión residencial, alcanzados a través del mismo WebSocket CDP que Stagehand ya utiliza. Mantienes el modelo de programación de Stagehand y entregas las operaciones del navegador a un servicio gestionado. Las opciones de conexión — duración de la sesión, región y huella digital — están cubiertas en la documentación del Navegador de Raspeo, y para una integración de agente diferente impulsada por CDP consulta la guía de habilidades del navegador Hermes.

Obtén tu clave en el plan gratuito en app.scrapeless.com y los créditos del Navegador de Raspeo cubren las primeras ejecuciones.

Conclusión

Stagehand te brinda actuar, extraer y observar sobre un navegador que apuntas con una única URL. Establece localBrowserLaunchOptions.cdpUrl en el endpoint del Navegador de Raspeo Scrapeless, proporciona tu clave de modelo y el marco se ejecuta sin cambios en un navegador en la nube gestionado — con extraer devolviendo datos tipados por esquema y actuar moviendo la página desde inglés sencillo. La conexión es un campo; todo lo que construyas sobre eso permanece igual.
¿Listo para ejecutar tus scripts de Stagehand en un navegador en la nube? Comienza gratis desde el tablero de Scrapeless, consulta la página del producto Scraping Browser, o compara planes en precios de Scrapeless.

Preguntas Frecuentes

P: ¿Qué es Stagehand?
R: Stagehand es un marco de automatización de navegadores de código abierto de Browserbase que agrega tres primitivas en lenguaje natural — act, extract y observe — sobre una sesión del Protocolo de DevTools de Chrome, para que mezcles instrucciones en inglés simple con código determinista de Playwright.

P: ¿Cómo se conecta Stagehand al navegador de raspado Scrapeless?
R: Establece localBrowserLaunchOptions.cdpUrl en el constructor de Stagehand al endpoint WebSocket de Scrapeless wss://browser.scrapeless.com/api/v2/browser, con tu clave API como el parámetro de consulta token. Stagehand luego controla la sesión en la nube a través de CDP.

P: ¿Todavía necesito una clave de modelo de lenguaje?
R: Sí. Scrapeless proporciona el navegador; Stagehand llama a un modelo para act, extract y observe. Proporciona tu propia clave de proveedor a través de la configuración del modelo de Stagehand — el navegador y el modelo permanecen separados.

P: ¿Cambia mi código de Stagehand cuando me muevo al navegador en la nube?
R: No. Solo cambia la URL de conexión. act, extract, observe, y el contexto de Playwright se comportan igual tanto si el navegador es local como si es la sesión remota de Scrapeless.

P: ¿Cómo obtengo datos estructurados de una página?
R: Llama a extract con una instrucción y un esquema Zod. Stagehand devuelve un objeto que coincide con el esquema — por ejemplo, un array de { title, points } — para que obtengas datos tipados en lugar de HTML en bruto.

P: ¿Cómo configuro la región del navegador?
R: Agrega un parámetro de consulta proxy_country a la URL CDP de Scrapeless, para que la salida de la sesión coincida con el mercado que deseas ver.

P: ¿Puedo inspeccionar un elemento antes de actuar sobre él?
R: Sí. Llama a observe con una descripción; devuelve elementos candidatos con un selector resuelto y un método sugerido, que puedes revisar antes de ejecutar act.