Stagehand con la Browser API de Bright Data: automatización de navegadores

En este artículo, aprenderás:

Qué es Stagehand y qué ofrece para la automatización de navegadores.
Los beneficios de usar Stagehand junto con sesiones de navegador sigiloso en la nube proporcionadas por la Browser API de Bright Data.
Una guía paso a paso para configurar la Browser API en Stagehand.

¡Comencemos!

¿Qué es Stagehand?

Stagehand es un framework de automatización de navegadores de código abierto desarrollado por Browserbase. Combina IA en lenguaje natural con código determinista. Resuelve el compromiso entre herramientas frágiles basadas en selectores (como Playwright) y agentes de IA impredecibles, permitiéndote elegir cuándo usar cada enfoque.

Funciona traduciendo instrucciones en acciones del navegador y salidas estructuradas, usando un LLM subyacente más una capa de ejecución controlada. Stagehand también soporta el desarrollo de agentes de IA basados en navegador.

Crecimiento de estrellas en GitHub de Stagehand a lo largo del tiempo

También incluye capacidades que le permiten funcionar como una herramienta de scraping web con IA. Stagehand cuenta con el respaldo de una gran comunidad de desarrolladores, con más de 22.9k estrellas en GitHub y más de 1 millón de descargas semanales en npm.

Características de Stagehand

Las principales características que ofrece Stagehand son:

Ejecución de act(): Realiza acciones en el navegador como clics, desplazamiento y relleno de formularios usando instrucciones en lenguaje natural.
Datos estructurados con extract(): Extrae contenido de páginas en esquemas validados con Zod para un uso posterior confiable.
Conciencia de página con observe(): Detecta elementos accionables en una página antes de ejecutar operaciones, mejorando la seguridad y precisión.
Flujos de trabajo autónomos con agent(): Ejecuta tareas de navegador de múltiples pasos de extremo a extremo con supervisión mínima.
Automatización autocurativa: Se adapta a los cambios de interfaz, reduciendo fallos frágiles basados en selectores.
Caché de acciones: Evita llamadas redundantes al LLM almacenando acciones en caché, garantizando una ejecución altamente predecible y económica en múltiples ejecuciones.
Flexibilidad de LLM: Funciona con múltiples proveedores manteniendo la ejecución determinista y depurable.
Primitivas componibles: Combina act, extract, observe y agent para construir pipelines de automatización personalizados.
Herramientas orientadas al desarrollador: Diseñadas para mantenibilidad, reproducibilidad e integración en sistemas de IA modernos.

Más información en la documentación oficial.

Por qué combinar Stagehand con la Browser API de Bright Data

Las herramientas de automatización de navegadores como Stagehand se enfrentan a los mismos problemas fundamentales:

Los sitios web bloquean activamente el tráfico automatizado mediante sistemas de detección de bots, CAPTCHAs, fingerprinting y verificaciones de reputación de IP. Esto hace que las automatizaciones sean frágiles, ya que un script puede funcionar en pruebas pero fallar de forma impredecible en producción.
Ejecutar muchas instancias de navegador localmente o en infraestructura autogestionada consume muchos recursos. Los navegadores son intensivos en recursos, requiriendo una CPU y memoria considerables. Esto hace que ejecutar muchas instancias simultáneamente sea costoso y difícil de escalar de forma confiable.
Gestionar proxies y la distribución geográfica añade sobrecarga operativa. Con el tiempo, esta complejidad se vuelve difícil de mantener para cargas de trabajo de scraping de nivel productivo o de agentes de IA.

La Browser API de Bright Data aborda estos problemas trasladando la ejecución local del navegador a una infraestructura en la nube completamente gestionada, diseñada para escala y sigilo.

En lugar de gestionar navegadores localmente, puedes conectarte a través de un único endpoint CDP. Obtienes acceso a navegadores remotos preconfigurados con rotación de Proxy integrada, resolución de CAPTCHA y evasión avanzada de fingerprinting.

Lo que distingue a Bright Data es su arquitectura de nivel empresarial, respaldada por una red de proxies de más de 400 millones de IPs residenciales. Esto permite un alto anonimato, geolocalización global y concurrencia infinita, logrando una tasa de éxito del 99.95% y un tiempo de actividad garantizado por SLA del 99.99%.

Cómo integrar Stagehand con la Browser API

En este capítulo, verás cómo usar Stagehand para automatizar instancias de navegador remotas. En detalle, te conectarás a sesiones de navegador en la nube sigilosas, anti-detección e infinitamente escalables a través de la Browser API de Bright Data.

Sigue las instrucciones a continuación.

Requisitos previos

Para seguir esta sección del tutorial, asegúrate de tener:

Node.js 20+ instalado localmente (se recomienda Node.js 22+).
Una clave de API de un proveedor de IA compatible con Stagehand (aquí usaremos una clave de API de OpenAI).
Una cuenta de Bright Data.
Conocimientos básicos de la API de Stagehand y sus capacidades de automatización de navegador impulsadas por IA.

Paso #1: Inicializar el proyecto Stagehand

Configura un nuevo proyecto Stagehand siguiendo la guía de inicio rápido. Alternativamente, ejecuta el siguiente comando:

npx create-browser-app bright-data-stagehand-example

El comando npx create-browser-app crea un nuevo proyecto Stagehand en el directorio bright-data-stagehand-example.

Después de ejecutarlo, deberías obtener:

A continuación, entra en el directorio del proyecto:

cd bright-data-stagehand-example

La estructura de tu proyecto debería verse así:

bright-data-stagehand-example/
├── .cursorrules
├── .env.example
├── claude.md
├── index.ts
├── package.json
├── README.md
└── tsconfig.json

Tómate unos minutos para explorar los archivos generados y familiarizarte con la estructura del proyecto. Céntrate en index.ts, que representa el archivo principal de Stagehand.

Ahora, limpia el archivo index.ts dejando solo:

import { Stagehand } from "@browserbasehq/stagehand";

Pronto verás cómo conectar Stagehand a la Browser API de Bright Data. ¡Muy bien!

Paso #2: Configurar la lectura de variables de entorno

Tu proyecto de automatización en la nube con Stagehand dependerá de algunos secretos (por ejemplo, clave de API del proveedor de IA, credenciales de la Browser API de Bright Data, etc.). En lugar de codificarlos directamente en el código, la mejor práctica es cargarlos desde variables de entorno.

Por defecto, Stagehand no carga automáticamente los archivos .env. Para habilitarlo, comienza instalando el paquete dotenv:

npm install dotenv

A continuación, en index.ts, añade lo siguiente:

import dotenv from "dotenv";

dotenv.config({
  path: ".env",
});

Ahora necesitas definir un archivo .env. Puedes crearlo copiando el archivo .env.example generado cuando ejecutaste npx create-browser-app. De lo contrario, añade manualmente un archivo .env a tu proyecto Stagehand:

bright-data-stagehand-example/
├── .cursorrules
├── .env           # <---------
├── .env.example
├── claude.md
├── index.ts
├── package.json
├── README.md
└── tsconfig.json

Rellena el archivo .env con tu clave de API del proveedor de IA (en este caso, OpenAI):

OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"

Reemplaza el marcador <YOUR_OPENAI_API_KEY> con tu clave de API de OpenAI real.

Stagehand leerá automáticamente la variable de entorno OPENAI_API_KEY en tiempo de ejecución, por lo que no se necesita configuración adicional. ¡Excelente!

Paso #3: Comenzar con la Browser API de Bright Data

Es momento de obtener la URL de conexión remota basada en CDP para la Browser API de Bright Data.

Si aún no lo has hecho, crea una cuenta de Bright Data. Si ya la tienes, inicia sesión y accede al panel de control:

A continuación, navega a la opción “Web Access > Web Access API” en el menú izquierdo:

Si ya ves una entrada de Browser API en la tabla “My APIs” (como se muestra a continuación, a través de la API browser_api), estás listo para continuar:

De lo contrario, haz clic en el menú desplegable del botón “Create API” y selecciona “Browser API”:

Esto lanzará el asistente de configuración de la Browser API. Dale un nombre a tu Browser API (por ejemplo, browser_api) y configura la API según tus necesidades:

Cuando hayas terminado, haz clic en el botón “Add API”. Accede a la página de detalles de la Browser API:

Aquí encontrarás los detalles de conexión para integraciones basadas en CDP (la URL bajo “Puppeteer / Playwright”). La URL WebSocket de la Browser API sigue este formato:

wss://<BROWSER_API_USERNAME>:<BROWSER_API_USERNAME>@brd.superproxy.io:9222

Copia el nombre de usuario y la contraseña de la Browser API desde la página de la Browser API y añádelos a tu archivo .env:

BRIGHT_DATA_BROWSER_API_USERNAME="<BROWSER_API_USERNAME>"
BRIGHT_DATA_BROWSER_API_PASSWORD="<BROWSER_API_PASSWORD>"

Más adelante usarás estas variables en index.ts para construir la URL de conexión CDP remota.

Ahora tienes todos los componentes necesarios para la automatización de navegador en la nube con Stagehand a través de la Browser API de Bright Data. ¡Excelente!

Paso #4: Conectar a la Browser API de Bright Data en Stagehand

En index.ts, comienza leyendo las credenciales de la Browser API desde tus variables de entorno:

const BRIGHT_DATA_BROWSER_API_USERNAME = process.env.BRIGHT_DATA_BROWSER_API_USERNAME || "";
const BRIGHT_DATA_BROWSER_API_PASSWORD = process.env.BRIGHT_DATA_BROWSER_API_PASSWORD || "";

A continuación, inicializa Stagehand dentro de una función main() para conectarse a la Browser API de Bright Data a través de la URL WebSocket CDP:

async function main() {
  // configure Stagehand to connect remotely to Bright Data's Browser API
  // and use an OpenAI model
  const stagehand = new Stagehand({
    env: "LOCAL",
    localBrowserLaunchOptions: {
      cdpUrl: `wss://${BRIGHT_DATA_BROWSER_API_USERNAME}:${BRIGHT_DATA_BROWSER_API_PASSWORD}@brd.superproxy.io:9222`,
    },
    model: "openai/gpt-5.4-mini",
  });

  // launch Stagehand and get the browser page
  await stagehand.init();
  const page = stagehand.context.pages()[0];
 
  // browser automation logic...

  // close the Stagehand instance and release the browser resources
  await stagehand.close();
}

main().catch(console.error);

El fragmento anterior configura Stagehand con la URL WSS autenticada de la Browser API construida usando las credenciales leídas desde las variables de entorno. Luego lanza una sesión de navegador remota y expone un objeto de página para la automatización. Tras ejecutar tu lógica de automatización, cierra la sesión y libera todos los recursos del navegador remoto.

En el ejemplo anterior, configuramos OpenAI GPT-5.4 Mini. Ten en cuenta que cualquier otro modelo de OpenAI (o una configuración de proveedor de IA compatible) también funcionará.

La parte clave está en el constructor de Stagehand. La configuración puede parecer algo confusa al principio porque, para conectarse a un navegador remoto, aún necesitas establecer env en "LOCAL". Luego, dentro de localBrowserLaunchOptions, debes proporcionar la URL WSS de la Browser API de Bright Data a través del campo cdpUrl.

Así que aunque env esté establecido en "LOCAL", Stagehand en realidad se conecta a las instancias de navegador en la nube anti-detección remotas de Bright Data.

Ahora puedes probar la integración con un ejemplo sencillo para confirmar que todo funciona correctamente.

Paso #5: Verificar la integración de la Browser API de Bright Data

Para comprobar que la integración con la Browser API funciona, prueba la siguiente lógica de automatización:

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

// take the screenshot of the page
await page.screenshot({
  path: "screenshot.png",
  type: "png",
  fullPage: false,
});

Esto indica al navegador remoto (expuesto a través de la Browser API de Bright Data) que abra example.com y capture una captura de pantalla.

Ponlo todo junto:

// index.ts 

import { Stagehand } from "@browserbasehq/stagehand";
import dotenv from "dotenv";

// load the environment variables from the .env file
dotenv.config({
  path: ".env",
});

// read the Bright Data Browser API credentials
const BRIGHT_DATA_BROWSER_API_USERNAME = process.env.BRIGHT_DATA_BROWSER_API_USERNAME || "";
const BRIGHT_DATA_BROWSER_API_PASSWORD = process.env.BRIGHT_DATA_BROWSER_API_PASSWORD || "";

async function main() {
  // configure Stagehand to connect remotely to Bright Data's Browser API
  // and use an OpenAI model
  const stagehand = new Stagehand({
    env: "LOCAL",
    localBrowserLaunchOptions: {
      cdpUrl: `wss://${BRIGHT_DATA_BROWSER_API_USERNAME}:${BRIGHT_DATA_BROWSER_API_PASSWORD}@brd.superproxy.io:9222`,
    },
    model: "openai/gpt-5.4-mini",
  });

  // launch Stagehand and get the browser page
  await stagehand.init();
  const page = stagehand.context.pages()[0];

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

  // take the screenshot of the page
  await page.screenshot({
    path: "screenshot.png",
    type: "png",
    fullPage: false,
  });

  // close the Stagehand instance and release the browser resources
  await stagehand.close();
}

main().catch(console.error);

Ejecuta el script con:

npm run start

En la terminal, deberías ver registros similares a:

Importante: Los registros pueden mencionar “connecting to local browser.” Esto se debe a la configuración requerida env: "LOCAL". Sin embargo, la conexión real se realiza a la Browser API remota de Bright Data.

Una vez completada la ejecución, aparecerá un archivo screenshot.png en el directorio de tu proyecto:

bright-data-stagehand-example/
├── .cursorrules
├── .env           
├── .env.example
├── claude.md
├── index.ts
├── package.json
├── README.md
├── screenshot.png       # <---------
└── tsconfig.json

Abre screenshot.png y deberías ver la página example.com renderizada:

Esto confirma que Stagehand se conectó exitosamente al sitio objetivo y ejecutó la automatización del navegador como se esperaba.

Para verificar que se utilizó la Browser API de Bright Data, comprueba tu panel de control de Bright Data:

Nota el pico en el tráfico de la Browser API

Deberías ver un pico en el tráfico que indica uso activo desde la sesión de Browser API configurada a través de la conexión CDP remota. Esto confirma que toda la automatización de Stagehand se enruta correctamente a través de la Browser API de Bright Data. ¡Genial!

Paso #6: Implementar automatización real de navegador remoto impulsada por IA

Ahora, supón que deseas automatizar la lógica del navegador para recopilar datos de artículos de noticias de Yahoo Finance.

Cómo la página de inicio de Yahoo Finance carga nuevos artículos

Este es un buen ejemplo porque la página de inicio de Yahoo Finance usa desplazamiento infinito para cargar nuevos artículos de forma dinámica. También es un sitio conocido por sus estrictas protecciones anti-bot y anti-scraping.

Gracias a las capacidades de sigilo y evasión anti-bot proporcionadas por la Browser API, puedes acceder a Yahoo Finance a través de Stagehand sin ser bloqueado.

Como deseas que los datos extraídos sigan una estructura específica, comienza definiendo un tipo de datos de salida con Zod:

import { z } from "zod";

// ...

// structured output schema
const YahooFinanceNewsSchema = z.object({
  news: z.array(
    z.object({
      title: z
        .string()
        .describe("The visible headline text of the news article"),

      articleUrl: z
        .string()
        .describe("The full article URL"),

      imageUrl: z
        .string()
        .describe("The full image URL"),

      source: z
        .string()
        .optional()
        .describe("The publisher name, such as Reuters or Yahoo Finance"),

      timestamp: z
        .string()
        .optional()
        .describe("The visible publication time, such as '4h ago'"),

      marketMoves: z
        .array(
          z.object({
            ticker: z
              .string()
              .describe("The stock ticker symbol, such as NVDA or ^GSPC"),

            changePercent: z
              .string()
              .optional()
              .describe(
                "The visible market percentage change, such as '+2.4%' or '-0.69%'"
              ),
          })
        )
        .optional()
        .describe(
          "List of stock tickers mentioned in the article footer with their change percentages"
        ),
    })
  ),
});

Esto define la estructura de salida esperada para los datos extraídos. En particular, coincide con la información disponible en las tarjetas de noticias de Yahoo Finance:

Nota la información disponible en las tarjetas de noticias de Yahoo Finance

Si inicializas tu aplicación Stagehand a través de npx create-browser-app, no necesitas instalar zod manualmente. Ya está incluido en las dependencias del proyecto. De lo contrario, instálalo con:

npm install zod

Ahora puedes automatizar el flujo de navegación y extracción con:

// automate the news article loading
await stagehand.act(
  `Scroll down multiple times and wait for articles to load in the "More News" section. Repeat until at least 20 news articles are loaded.`,
  {
    timeout: 90000, // 90-second timeout
  }
);

// scrape the news information
const data = await stagehand.extract(
  `Scrape all visible news articles`,
  YahooFinanceNewsSchema,
  {
    "timeout": 120000, // 120-second timeout
  }
);

Esto replica el comportamiento de un usuario real desplazándose por la página para cargar más artículos, pero dirigido por instrucciones de IA. Luego usa extracción estructurada impulsada por IA para convertir el contenido de la página en el esquema definido.

Observa cómo el script de automatización se basa en dos APIs de Stagehand impulsadas por IA:

.act(): Realiza acciones en la sesión del navegador (por ejemplo, desplazamiento, clics, navegación)
.extract(): Extrae datos estructurados de la página usando un esquema

¡Fantástico! El siguiente paso es exportar los datos extraídos.

Paso #7: Exportar los datos extraídos

En este punto, los datos extraídos ya están almacenados en el objeto data devuelto por stagehand.extract(). El paso final es exportarlos a un archivo news.json para que puedan reutilizarse o procesarse posteriormente.

Consíguelo usando la API nativa fs/promises de Node.js:

import fs from "fs/promises";

// ...

// save extracted news to a JSON file
await fs.writeFile(
  "news.json",
  JSON.stringify(data.news, null, 2),
  "utf-8"
);

Esto escribe un archivo news.json que contiene los datos de noticias estructurados en un formato limpio y legible.

¡Misión cumplida! El flujo de trabajo de scraping con Stagehand que emplea la Browser API como agente de IA en el navegador está ahora completamente implementado.

Paso #8: Unirlo todo

Tu script final index.ts para automatizar el scraping de Yahoo Finance con Stagehand tendrá este aspecto:

import { Stagehand } from "@browserbasehq/stagehand";
import dotenv from "dotenv";
import { z } from "zod";
import fs from "fs/promises";

// load the environment variables from the .env file
dotenv.config({
  path: ".env",
});

// read the Bright Data Browser API credentials
const BRIGHT_DATA_BROWSER_API_USERNAME = process.env.BRIGHT_DATA_BROWSER_API_USERNAME || "";
const BRIGHT_DATA_BROWSER_API_PASSWORD = process.env.BRIGHT_DATA_BROWSER_API_PASSWORD || "";

// structured output schema
const YahooFinanceNewsSchema = z.object({
  news: z.array(
    z.object({
      title: z
        .string()
        .describe("The visible headline text of the news article"),

      articleUrl: z
        .string()
        .describe(
          "The full article URL."
        ),

      imageUrl: z
        .string()
        .describe(
          "The full image URL."
        ),

      source: z
        .string()
        .optional()
        .describe("The publisher name, such as Reuters or Yahoo Finance"),

      timestamp: z
        .string()
        .optional()
        .describe("The visible publication time, such as '4h ago'"),

      marketMoves: z
        .array(
          z.object({
            ticker: z
              .string()
              .describe("The stock ticker symbol, such as NVDA or ^GSPC"),

            changePercent: z
              .string()
              .optional()
              .describe(
                "The visible market percentage change, such as '+2.4%' or '-0.69%'"
              ),
          })
        )
        .optional()
        .describe(
          "List of stock tickers mentioned in the article footer with their market change percentages"
        ),
    })
  ),
});

async function main() {
  // configure Stagehand to connect remotely to Bright Data's Browser API
  // and use an OpenAI model
  const stagehand = new Stagehand({
    env: "LOCAL",
    localBrowserLaunchOptions: {
      cdpUrl: `wss://${BRIGHT_DATA_BROWSER_API_USERNAME}:${BRIGHT_DATA_BROWSER_API_PASSWORD}@brd.superproxy.io:9222`,
    },
    model: "openai/gpt-5.4-mini",
    keepAlive: true,
    verbose: 1,
  });

  // launch Stagehand and get the browser page
  await stagehand.init();
  const page = stagehand.context.pages()[0];

  // go to Yahoo Finance
  await page.goto("https://finance.yahoo.com/");

  // automate the news article loading
  await stagehand.act(
    `Scroll down multiple times and wait for articles to load in the "More News" section. Repeat until at least 20 news articles are loaded.`,
    {
      timeout: 90000, // 90-second timeout
    }
  );

  // scrape the news information
  const data = await stagehand.extract(
    `Scrape all visible news articles`,
    YahooFinanceNewsSchema,
    {
      "timeout": 120000, // 120-second timeout
    }
  );

  // save extracted news to a JSON file
  await fs.writeFile(
    "news.json",
    JSON.stringify(data.news, null, 2),
    "utf-8"
  );
  console.log("News exported to news.json");

  // close the Stagehand instance and release the browser resources
  await stagehand.close();
}

main().catch(console.error);

El archivo .env almacenará:

OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"
BRIGHT_DATA_BROWSER_API_USERNAME="<BROWSER_API_USERNAME>"
BRIGHT_DATA_BROWSER_API_PASSWORD="<BROWSER_API_PASSWORD>"

Lanza el script con:

npm run start

Una vez que el script termine de ejecutarse, aparecerá un archivo news.json en tu carpeta de proyecto. Si lo abres, deberías ver datos estructurados como este:

Nota los datos de noticias estructurados extraídos en el archivo \

Observa cómo el archivo contiene los mismos artículos que aparecen en la página de inicio de Yahoo Finance después de desplazarse varias veces, pero ahora en un formato limpio y estructurado.

Esto demuestra cómo la Browser API puede acceder a contenido dinámico y extraer datos a escala, incluso desde un sitio con protecciones anti-bot.

¡Et voilà! Este fue solo un ejemplo, pero puedes usar Stagehand para automatizar flujos de trabajo de la Browser API de Bright Data en muchos otros escenarios y casos de uso.

Conclusión

En este artículo, aprendiste qué es Stagehand y cómo soporta la automatización de navegadores. En concreto, viste cómo usarlo con la Browser API de Bright Data para ejecutar sesiones de navegador en la nube altamente escalables e indetectables.

El resultado es una configuración de automatización de navegador que puede escalar a cargas de trabajo de nivel empresarial. Con la misma integración, también puedes implementar operaciones de IA de navegador agéntico respaldadas por infraestructura en la nube a gran escala.

¡Crea una nueva cuenta de Bright Data y explora nuestras soluciones de scraping de datos web y automatización de navegadores listas para IA!

Contactar ventas Prueba gratuita