Automatización de navegador con Stagehand

La automatización de navegador con Stagehand tiene dos capas: Stagehand aporta primitivas para operar en una página, mientras que un lanzador elige el ejecutable de Chromium y sus argumentos de inicio. Stagehand v4 documenta act, extract y observe, y se conecta por Chrome DevTools Protocol (CDP) a un Chromium que ya está en ejecución. BotBrowser permite iniciar Chromium con un ejecutable elegido por el operador y el flag --bot-profile; Stagehand v4 puede conectarse por CDP a ese navegador. BotBrowser no proporciona un adaptador de Stagehand, no define la política del agente y no garantiza la clasificación de un sitio externo. La configuración de browser-use cubre otro framework, mientras que la guía directa de Playwright describe otra API de control.

Una conexión correcta no demuestra que se haya iniciado el proceso previsto. Una URL CDP identifica un endpoint, no la ruta del binario, el argumento del perfil, la ruta de red ni el estado de la página. Registra esas observaciones por separado y consulta la referencia de flags de BotBrowser para el argumento de perfil admitido; una llamada de Stagehand no configura el inicio del navegador.

TL;DR

• observe() descubre acciones candidatas, act() ejecuta una acción y extract() devuelve datos con la forma de un esquema.
• Stagehand v4 se conecta a Chromium por CDP; su documentación actual indica que no depende de Playwright ni de Puppeteer.
• El lanzador, no las primitivas de página de Stagehand, selecciona el ejecutable y pasa --bot-profile antes de iniciar el navegador.
• Una respuesta CDP demuestra que un endpoint respondió. No demuestra qué ejecutable o perfil se usó.
• Mantén el endpoint en loopback, comprueba el proceso por separado y detente si no coincide.

Contenido

• Responsabilidad de cada primitiva
• Lanzar y conectar son operaciones distintas
• Iniciar el navegador controlado antes de Stagehand
• Ejecutar las tres primitivas con un fixture
• Verificar el proceso y el destino CDP
• Tabla de fallos y recuperación
• Qué queda fuera de Stagehand
• Conclusión práctica

Responsabilidad de cada primitiva

Las tres primitivas con nombre de Stagehand resuelven tareas distintas. observe() descubre elementos accionables y devuelve acciones estructuradas; act() ejecuta una instrucción o una acción devuelta por observe(); extract() lee el contenido de la página con la forma solicitada. Las referencias oficiales de observe, act y extract describen sus entradas y resultados. Son operaciones de Stagehand, no opciones para elegir un ejecutable.

La distinción define lo que una traza puede afirmar. Un resultado de observe() indica que Stagehand encontró acciones candidatas según la página y la instrucción actuales, no que el usuario haya autorizado una. El resultado de act() registra un intento de interacción; la aplicación remota todavía puede rechazarlo o aplicar otro cambio. El resultado de extract() contiene los datos que encajan en el esquema solicitado, no una copia de la base de datos del servidor ni una verificación independiente de la página.

Primitiva	Trabajo en la página	Evidencia útil para conservar
observe()	Descubrir elementos candidatos para una instrucción delimitada	Origen, identificador de instrucción, cantidad de candidatos y acción seleccionada
act()	Ejecutar una instrucción o una acción seleccionada	Identificador de acción y resultado devuelto, sin llamarlo aceptación remota
extract()	Leer contenido con un esquema solicitado	Versión del esquema y los campos mínimos necesarios

Las tres operaciones se pueden componer, pero sus resultados no deberían convertirse en una sola marca success. Puede que la conexión al navegador funcione y la extracción falle; también puede haber una extracción correcta aunque un envío posterior siga pendiente. Guarda los estados por separado para que el operador pueda localizar la capa que requiere atención. Un elemento encontrado antes puede quedar obsoleto después de una navegación, un diálogo o un cambio de origen.

Stagehand también ofrece métodos de página familiares, como navegación y locators. Eso no convierte Stagehand v4 en Playwright: su introducción actual describe control del navegador por CDP y dice que no depende de Playwright ni de Puppeteer. Un proyecto que necesite el ciclo de vida BrowserType.launch() de Playwright debe usar la guía de configuración de Playwright y su propio código de inicio. Un proyecto que necesite las primitivas de Stagehand debe seguir el contrato de conexión al navegador de Stagehand.

Lanzar y conectar son operaciones distintas

El lanzamiento crea el proceso del sistema operativo. El lanzador proporciona la ruta del ejecutable, el argumento del perfil, el directorio de datos de usuario, el endpoint de depuración y las opciones de red que recibirá el proceso. Una conexión CDP posterior se une a un navegador que ya se está ejecutando. La referencia de configuración de navegador de Stagehand documenta localBrowser.launch() para un proceso local y localBrowser.connect() para un Chromium existente. El ejemplo de conexión usa una URL CDP y entrega el navegador devuelto a Stagehand.create().

Para BotBrowser, el perfil se selecciona al iniciar el proceso con --bot-profile. No es una instrucción de Stagehand, un valor de page.evaluate() ni un ajuste que observe() pueda aplicar después del inicio. La documentación de Playwright de BotBrowser muestra dónde entran el ejecutable y el argumento de perfil en un lanzamiento de Playwright; el principio de responsabilidad es el mismo para cualquier lanzador: el proceso recibe sus opciones antes de que Stagehand se conecte. La guía de gestión de perfiles explica la selección y el manejo de los archivos.

Decisión	Ruta de lanzamiento	Ruta de conexión
¿Quién inicia Chromium?	La fábrica de navegador local de Stagehand o un lanzador externo	Un lanzador gestionado por el operador lo inicia primero
¿Dónde se elige el ejecutable?	En la configuración de inicio admitida por la versión fijada	En los argumentos del proceso antes de conectar Stagehand
¿Dónde se pasa --bot-profile?	Solo si la API de inicio admitida reenvía argumentos del navegador	En los argumentos del proceso antes de abrir el endpoint CDP
¿Qué recibe Stagehand?	Un navegador devuelto por su llamada de inicio local	Un navegador conectado a la URL CDP declarada
¿Qué se comprueba por separado?	El proceso real y sus argumentos	La identidad del proceso, el endpoint y el argumento del perfil

La conexión resulta útil si el entorno ya tiene un proceso Chromium controlado o si otro supervisor administra su creación. También introduce una dependencia estricta: Stagehand no se conecta hasta que el endpoint escucha. El lanzamiento puede ser más simple cuando las opciones locales de la versión fijada cubren todos los requisitos. No supongas que el helper local acepta cualquier ejecutable o argumento de perfil solo porque inicia Chrome; consulta los tipos de esa versión.

Iniciar el navegador controlado antes de Stagehand

Un lanzamiento gestionado por el operador hace visible la configuración. El siguiente ejemplo de shell usa variables de sustitución; no es un registro de ejecución ni prueba que un binario concreto de BotBrowser haya aceptado esos valores. Configura las variables desde el despliegue, asigna un puerto loopback libre para cada ejecución y pasa el mismo STAGEHAND_CDP_PORT al lanzador y al cliente:

"$BOTBROWSER_EXEC_PATH" \
  --user-data-dir="$STAGEHAND_USER_DATA_DIR" \
  --remote-debugging-port="$STAGEHAND_CDP_PORT" \
  --bot-profile="$BOT_PROFILE_PATH"

--bot-profile selecciona el archivo de perfil de BotBrowser. --user-data-dir es un directorio de almacenamiento de Chromium distinto, no reemplaza el perfil cifrado de BotBrowser. Usa un directorio dedicado y nuevo cuando la versión del navegador lo requiera para depuración remota; no reutilices los datos de cliente para una ejecución de prueba. El endpoint CDP permite un control privilegiado del navegador: limítalo a loopback, no lo expongas a redes compartidas y cierra el proceso al terminar. La documentación de depuración remota de Chrome describe esa interfaz y sus límites de seguridad.

Cuando el proceso esté disponible, la forma de conexión documentada por Stagehand es breve:

import { localBrowser, Stagehand } from '@browserbasehq/stagehand';
import { z } from 'zod';

const cdpPort = process.env.STAGEHAND_CDP_PORT;
if (!cdpPort || !/^\d+$/.test(cdpPort)) {
  throw new Error('The launcher must assign a numeric CDP port');
}

const browser = await localBrowser.connect({
  cdpUrl: `http://127.0.0.1:${cdpPort}`,
});
const stagehand = await Stagehand.create({ browser });

const { data: actions } = await stagehand.observe('Find the read-only build marker');
if (actions.length !== 1) {
  throw new Error(`Expected one build-marker action; found ${actions.length}`);
}

await stagehand.act(actions[0]);
const { data } = await stagehand.extract({
  instruction: 'Read the build marker from the current page',
  schema: z.object({ build: z.string() }),
});
console.log(data.build);

La conexión y las llamadas a primitivas siguen la documentación actual de Stagehand v4; el endpoint, el fixture y la instalación de paquetes dependen del entorno. Fija la versión de Stagehand y compara imports y campos de resultado con la referencia correspondiente. El ejemplo lee un fixture propio y no envía un formulario, no inicia sesión ni cambia un registro remoto. Es una forma de integración local, no evidencia de que el código se haya ejecutado aquí.

Asigna un endpoint a una ejecución, en vez de usar un puerto fijo que pueda pertenecer al navegador de otra persona. Si el puerto ya está ocupado, no te conectes en silencio: la dirección podría apuntar a otro Chromium. Haz que el lanzador asigne y registre el endpoint, y enlázalo a localhost. No expongas CDP en una interfaz pública; cualquier persona que pueda acceder puede obtener control del navegador.

Ejecutar las tres primitivas con un fixture

Un fixture propio hace observables las capas sin depender de un sitio público. Puede exponer un identificador de compilación fijo y un control inocuo. La primera instrucción de observe() debe nombrar ese control; la acción seleccionada solo revela el identificador y extract() devuelve el dato con un esquema pequeño. Evita fixtures con credenciales, compras, cambios de cuenta o borrados: eso convertiría una comprobación de integración en un flujo de autorización.

Conserva pocos valores esperados y observados. Por ejemplo, el fixture puede devolver build: "stagehand-fixture-7"; el recibo puede incluir esa cadena, la versión del fixture, el origen y el nombre del esquema. No hace falta guardar todo el DOM, una captura con contenido ajeno, cookies, almacenamiento local ni una traza completa del modelo. Un registro pequeño reduce la exposición accidental y facilita clasificar un fallo.

El fixture debe ser suficientemente estable para separar una conexión de un problema de página. Un marcador conocido puede verificar que la navegación llegó al origen local esperado. Un botón de solo lectura puede probar observe() y act() sin cambiar el estado del servidor. Un objeto JSON pequeño puede probar extract() y su esquema. Versiona juntos esos elementos: si cambia el atributo del marcador mientras Chromium permanece igual, el fallo pertenece al contrato del fixture, no al lanzador.

No uses el user-agent informado por el navegador como prueba de qué proceso o perfil se seleccionó. Un valor visible puede servir para su propia comprobación, pero no identifica el ejecutable que abrió la pestaña. A la inversa, la ruta del proceso no demuestra que el fixture se haya renderizado correctamente. El proceso del lanzador, el endpoint CDP y la respuesta del fixture contestan preguntas distintas y deben permanecer en campos separados.

El fixture también puede separar el estado de página de la disponibilidad de acciones. Si el marcador aparece después de aceptar un consentimiento, la instrucción de observe() no debe convertir esa decisión en un clic rutinario. Registra que la acción necesita aprobación o crea una ruta de solo lectura. Un contrato de prueba estable no justifica automatizar cambios de permisos o datos.

Verificar el proceso y el destino CDP

Tres comprobaciones establecen hechos distintos. Primero, inspecciona el proceso del lanzador y compara el ejecutable y sus argumentos redactados con los valores declarados. Segundo, solicita el endpoint CDP de loopback para confirmar que responde el servicio de depuración esperado. Tercero, navega al fixture propio y lee su marcador. Una fila aprobada no sustituye a las demás.

Comprobación	Observación esperada	Lo que no demuestra
Proceso del lanzador	El ejecutable coincide con la ruta BotBrowser declarada y aparece el flag de perfil requerido	Que el perfil cifrado se aceptó o produjo un valor de página previsto
Endpoint CDP	La URL local declarada devuelve metadatos del navegador	Que el endpoint pertenezca al proceso de la primera fila
Página fixture	Stagehand ve el origen esperado y el marcador de compilación	Que un servicio externo muestre lo mismo o tome la misma decisión

Un desajuste detiene el flujo. La misma comprobación se aplica cuando el lanzamiento lo posee un servidor MCP en lugar de un script, y las claves que llevan el ejecutable allí se tratan en configuración de Playwright MCP para un build Chromium propio. Si la ruta del proceso es distinta, no continúes solo porque el endpoint responde. Si la ruta coincide pero el endpoint identifica otro navegador, revisa la asignación del puerto y el propietario del proceso. Si ambos coinciden pero falta el marcador, inspecciona la ruta fixture y el ciclo de vida de la página, no cambies los valores del perfil. Este orden evita que un reintento de página oculte un error de lanzamiento.

Un recibo compacto puede guardar runId, versión fijada de Stagehand, nombre redactado del ejecutable, identificador no sensible del perfil, endpoint local, compilación fixture, primitiva usada y primer fallo. No registres contenidos del perfil cifrado, tokens, credenciales de proxy ni una ruta absoluta con identificadores de cliente. El recibo sirve cuando diferencia un valor configurado de uno observado.

Los metadatos del endpoint CDP no son un certificado de identidad del navegador. Si varios procesos pueden enlazar o reenviar el endpoint, relaciona la URL con el ID del proceso y revisa sus argumentos locales. Un túnel, un mapeo de puertos de contenedor, un proxy de desarrollo o un navegador antiguo pueden hacer que el cliente llegue a otro proceso. Usa un endpoint por ejecución y termina los procesos obsoletos antes de volver a usar un puerto.

El ciclo de vida también importa. Cierra la conexión de Stagehand tras la comprobación de solo lectura y cierra el proceso únicamente si esta ejecución lo creó y posee. La documentación de navegadores de Stagehand distingue los navegadores que lanzó de aquellos a los que se conectó. Un cliente conectado no debe asumir que puede terminar el proceso; un supervisor podría usarlo para otra tarea controlada.

Tabla de fallos y recuperación

Observación	Capa probable	Siguiente comprobación	Condición de parada
La conexión CDP es rechazada	Inicio del navegador o asignación del puerto	Confirma el estado del lanzador y el puerto asignado	No inicies otro navegador de forma implícita
CDP conecta, pero la ruta del proceso no coincide	Endpoint equivocado o proceso obsoleto	Relaciona el endpoint con el ID registrado	Cierra la ejecución antes de operar en la página
El proceso es correcto, pero falta el argumento de perfil	Configuración del lanzador	Revisa el constructor de argumentos antes de iniciar	No afirmes que se seleccionó el perfil
El flag está presente, pero el fixture no coincide	Perfil, fixture o aplicación	Compara por separado la compatibilidad del perfil y la versión fixture	No cambies valores de página para forzar coincidencia
observe() no devuelve candidatos	Estado de página o instrucción	Inspecciona el fixture y el control visible	No amplíes la instrucción a una acción distinta
act() devuelve resultado, pero el fixture no cambia	Resultado de acción o estado de aplicación	Lee de nuevo el marcador e inspecciona el resultado	No declares un cambio remoto sin evidencia
extract() falla la validación del esquema	Salida de página o contrato de esquema	Compara los datos visibles del fixture con el esquema	Mantén los datos mínimos; no debilites el esquema en silencio
El navegador se desconecta durante una acción	Ciclo de vida del proceso o resultado remoto	Comprueba el fixture o un estado idempotente antes de reintentar	Nunca repitas a ciegas una acción con efectos

La recuperación sigue la primera capa que falló. Una conexión rechazada no se arregla cambiando el esquema de extracción. Un endpoint válido conectado al proceso equivocado no se arregla ampliando la instrucción de página. La falta del argumento de perfil se corrige en la configuración del lanzador y requiere iniciar un proceso nuevo con otro identificador. Si una mutación remota pudo enviarse antes de la desconexión, consulta un estado idempotente o deriva el caso al operador responsable; no la repitas automáticamente.

La guía de browser-use describe puntos de aprobación para otro ciclo de agente. La introducción a detección de automatización trata señales generales. Ninguna sustituye la distinción propia de Stagehand entre el resultado de una primitiva, la conexión CDP y el ejecutable/perfil que se eligió antes de conectar.

Qué queda fuera de Stagehand

Stagehand proporciona APIs de automatización del navegador; la aplicación sigue siendo responsable de autorizar tareas, elegir cuentas, enrutar la red, proteger secretos, retener datos y pedir aprobación para acciones importantes. Un navegador conectado puede estar técnicamente listo mientras la tarea no es adecuada o su destino ha cambiado. La política debe vivir en la aplicación que invoca Stagehand, no en una instrucción que el agente pueda reescribir.

Mantén la selección de perfil en la configuración revisada del lanzador. El agente no debería enumerar archivos arbitrarios, imprimir su contenido ni elegir una cuenta según el texto de la página. El lanzador puede resolver un identificador aprobado y pasar la ruta al navegador. El recibo puede guardar una etiqueta no sensible y una versión de configuración, sin copiar el archivo cifrado ni su contenido.

La ruta de red es otro parámetro independiente. Un argumento de perfil no demuestra por qué ruta salió una solicitud, y un endpoint CDP no informa de una decisión de permiso a nivel de aplicación. Si el flujo necesita una ruta determinada, configúrala en la capa externa y valídala con los diagnósticos permitidos para ese flujo. No atribuyas a Stagehand una ruta, idioma o estado de cuenta salvo que el sistema circundante proporcione ese valor e identifique su origen.

La misma separación se aplica a la clasificación de terceros. Un act() correcto indica que una interacción del navegador devolvió un resultado; un extract() correcto indica que se devolvió la forma solicitada. Ninguno garantiza la aceptación de una sesión, una categoría de detector o el resultado comercial de una aplicación. BotBrowser ofrece una opción de navegador controlado, no un resultado prometido por un tercero.

Cuando el flujo alcance credenciales, consentimiento, pagos, borrados, cambios de permisos, publicaciones o envíos irreversibles, pausa en la capa de aplicación para que decida un operador. La pausa debería mostrar el origen de destino, la acción y los parámetros visibles que hacen falta para decidir, sin pasar secretos a la traza del modelo. Este límite pertenece a la política de la aplicación, no a observe(), act() ni extract().

Preguntas frecuentes

¿Stagehand v4 usa Playwright internamente?

La introducción actual de Stagehand v4 describe el control del navegador por CDP y afirma que no depende de Playwright ni de Puppeteer. Sus APIs de página pueden resultar familiares a quienes usan Playwright, pero eso no equivale al ciclo de lanzamiento de BrowserType.

¿Stagehand puede elegir un perfil BotBrowser después de conectarse?

No. El perfil se pasa al proceso al iniciarlo. Las primitivas de página actúan después de la conexión y no cambian retroactivamente los argumentos. Coloca --bot-profile aprobado en la configuración del lanzador antes de abrir el endpoint CDP.

¿Una conexión CDP correcta demuestra que se inició el navegador adecuado?

No. Demuestra que respondió un servicio en el endpoint. Relaciona ese endpoint con el ID de proceso y la ruta del ejecutable, revisa los argumentos redactados y, por separado, lee el fixture propio.

¿Esta integración garantiza el resultado de un detector o un sitio?

No. Las acciones de Stagehand y una configuración de navegador controlada no garantizan clasificación, aceptación ni un resultado comercial de terceros. Esos resultados no forman parte de una comprobación de lanzamiento.

Fuentes

• Introducción de Stagehand v4
• Stagehand act()
• Stagehand extract()
• Stagehand observe()
• Configuración de navegador de Stagehand
• Depuración remota de Chrome
• Chrome DevTools Protocol
• Configuración de Playwright de BotBrowser
• Flags de CLI de BotBrowser

Conclusión práctica

Mantén separadas las primitivas de Stagehand y la creación del proceso. Selecciona el ejecutable BotBrowser y el perfil en el lanzador, expón solo un endpoint CDP de loopback y conecta Stagehand a ese navegador ya iniciado. Verifica proceso, endpoint y fixture como observaciones distintas; detente ante cualquier discrepancia. Eso establece una comprobación de integración delimitada, no una afirmación sobre validez del perfil, autorización de tareas o decisiones de terceros.