Paso Agente IA: automatizar portal - Insurance Boosters API

El paso browser.script ejecuta un guion de navegador con un agente de IA. A diferencia del Agente IA: investigar la web —que decide solo cómo completar una tarea—, aquí tú escribes los pasos y el agente los sigue en orden, interpretando cada instrucción sobre la página real. Úsalo para procesos repetitivos sobre un portal conocido: iniciar sesión, navegar a una sección, descargar un reporte, extraer datos.

Campos del paso

Campo	Requerido	Descripción
`actionKey`	Sí	Debe ser `browser.script`.
`code`	Sí	JavaScript que dirige al agente con el objeto `browser`.
`input`	No	Variables disponibles como `input.*` dentro del código. Acepta plantillas `{{...}}`.
`timeoutMs`	No	Límite de tiempo del paso.
`capture`	No	Copia campos del output a `context`.

El objeto `browser`

Dentro de code, el objeto browser abre un navegador en la nube y le da el control a tu guion:

const result = await browser.run(async (page) => {
  await page.goto(input.portalUrl);

  // Instrucciones en lenguaje natural: el agente de IA las interpreta
  // sobre la página real, sin selectores CSS. Una acción por llamada.
  await page.act("escribe %usuario% en el campo de usuario", {
    variables: { usuario: input.usuario },
  });
  await page.act("escribe %password% en el campo de contraseña", {
    variables: { password: input.password },
  });
  await page.act("haz clic en el botón 'Iniciar sesión'");

  await page.act("haz clic en la sección 'Cobranza' del menú");
  return await page.extract(
    "extrae el total de primas cobradas del mes (número) y la fecha de corte (AAAA-MM-DD)"
  );
});

output = { ...result.data, sessionId: result.sessionId };

browser.run(fn) crea la sesión, ejecuta tu función con la página y siempre cierra la sesión al terminar.
page.act(instruccion, opciones) ejecuta una acción descrita en lenguaje natural. Con opciones.variables, los valores sensibles (contraseñas, números de cuenta) se sustituyen como %nombre% sin pasar por el modelo de IA ni quedar en logs.
page.extract(instruccion) devuelve datos estructurados de la página.
page.observe(instruccion) devuelve las acciones disponibles sin ejecutarlas; puedes pasar una directamente a page.act.
page.goto(url) navega directo, sin IA.
browser.run resuelve a { data, sessionId }: data es lo que devuelve tu función y sessionId identifica la sesión para depuración.

Solo puede haber una sesión de navegador abierta a la vez por ejecución.

Mantén todo el recorrido relacionado dentro de una sola llamada a browser.run. Así conservas el estado de la sesión —incluidos login, cookies y pestañas— hasta terminar el guion.

Ejemplo completo: reporte de cobranza

{
  "actionKey": "browser.script",
  "name": "Descargar cobranza",
  "input": {
    "portalUrl": "https://portal.aseguradora.mx",
    "usuario": "{{context.portalUsuario}}",
    "password": "{{context.portalPassword}}",
    "periodo": "{{trigger.body.periodo}}"
  },
  "code": "const result = await browser.run(async (page) => { await page.goto(input.portalUrl); await page.act('escribe %usuario% en el campo de usuario', { variables: { usuario: input.usuario } }); await page.act('escribe %password% en el campo de contraseña', { variables: { password: input.password } }); await page.act(\"haz clic en el botón 'Iniciar sesión'\"); await page.act(\"haz clic en la sección 'Cobranza' del menú\"); await page.act(`haz clic en el botón de descarga del reporte del periodo ${input.periodo}`); return await page.extract('extrae el nombre del reporte descargado y el periodo (AAAA-MM)'); }); output = { ...result.data, sessionId: result.sessionId };"
}

No escribas credenciales directamente en code ni en la definición del paso. Pásalas por input con plantillas ({{context.*}} o {{trigger.body.*}}) y úsalas con variables dentro de act.

Buenas prácticas para `act`, `extract` y `observe`

Los guiones confiables siguen estas reglas. Un guion con instrucciones vagas o combinadas falla de formas difíciles de depurar.

Una acción por `act`

Cada llamada debe describir una sola acción atómica:

// Bien: acciones individuales y específicas
await page.act("haz clic en el botón 'Iniciar sesión'");
await page.act("escribe %usuario% en el campo de correo", {
  variables: { usuario: input.usuario },
});

// Mal: varias acciones combinadas
await page.act("llena el formulario de login y entra al panel de cobranza");

Describe el elemento por tipo y texto, no por color

// Bien
await page.act("haz clic en el botón 'Exportar' en la parte superior de la tabla");
await page.act("selecciona 'Enero 2026' en el menú desplegable de periodo");

// Mal
await page.act("haz clic en el botón azul");
await page.act("elige enero");

Usa el verbo correcto: haz clic para botones y enlaces, escribe para campos de texto, selecciona para menús desplegables, marca/desmarca para casillas.

Navega con `goto`, no con instrucciones

Si conoces la URL, page.goto(url) es más rápido y estable que pedirle al agente que navegue:

// Bien
await page.goto("https://portal.ejemplo.com/reportes/cobranza");

// Mal: gasta pasos del agente en algo determinista
await page.act("ve a la sección de reportes y luego a cobranza");

Datos sensibles siempre en `variables`

Los valores de variables se sustituyen localmente como %nombre%: no pasan por el modelo de IA ni quedan en logs. Nunca interpoles contraseñas directamente en el texto de la instrucción.

Pide campos concretos en `extract`

Nombra exactamente qué campos quieres y en qué formato:

// Bien
const datos = await page.extract(
  "extrae el número de póliza (texto), la prima total (número sin símbolo de moneda) y la fecha de corte (formato AAAA-MM-DD)"
);

// Mal
const datos = await page.extract("saca los datos del reporte");

Usa extract solo para leer y act solo para interactuar; no mezcles ambos en una instrucción.

Verifica antes de actuar con `observe`

En páginas que cambian de estado, observe devuelve las acciones disponibles sin ejecutarlas. Puedes inspeccionar el resultado y pasarlo directo a act, que lo reproduce sin volver a consultar al modelo:

const acciones = await page.observe("encuentra el botón 'Descargar reporte'");
if (acciones.length === 0) {
  throw new Error("El reporte no está disponible todavía");
}
await page.act(acciones[0]);

También puedes buscar varios candidatos en una sola consulta y elegir el correcto. Como description es texto generado, normalízalo antes de compararlo:

const descargas = await page.observe(
  "encuentra todos los botones de descarga de la tabla e identifica el periodo de cada reporte"
);

const periodo = String(input.periodo).toLowerCase();
const descarga = descargas.find((accion) =>
  accion.description.toLowerCase().includes(periodo)
);

if (!descarga) {
  throw new Error(`No hay un reporte disponible para ${input.periodo}`);
}

// Reproduce la acción observada sin otra inferencia.
await page.act(descarga);

Vuelve a llamar observe después de navegar, enviar un formulario o actualizar filtros. Las acciones observadas representan el estado de la página en ese momento y pueden dejar de ser válidas cuando cambia el contenido.

Trabaja con pestañas nuevas

Si un clic abre y enfoca otra pestaña, las siguientes llamadas a act, observe y extract trabajan sobre esa pestaña automáticamente:

await page.act("haz clic en el enlace 'Ver detalle', que abre una pestaña nueva");

const detalle = await page.extract(
  "extrae el número de póliza (texto) y el estatus actual (texto)"
);

El objeto de la página original no cambia cuando se abre otra pestaña. Si necesitas alternar entre ambas, conserva una referencia y cambia la pestaña activa de forma explícita:

const context = page.stagehand.browser.context;
const original = await context.activePage();

await page.act("haz clic en el enlace 'Ver detalle', que abre una pestaña nueva");
const detalle = await context.activePage();

if (detalle === original) {
  throw new Error("El detalle no abrió una pestaña nueva");
}

const datos = await page.extract(
  "extrae el número de póliza (texto) y el estatus actual (texto)"
);

await context.setActivePage(original);
await page.act("haz clic en el botón 'Continuar' del formulario");

Cada locator pertenece a la pestaña donde fue creado. No reutilices un locator de la pestaña original sobre la nueva. Si el sitio abre una pestaña en segundo plano sin enfocarla, cambia la pestaña activa antes de usar act, observe o extract.

Reduce tiempo y costo

Cada operación interpretada por IA añade latencia y consumo. Sigue este orden de preferencia:

Usa goto cuando ya conoces la URL.
Usa una sola llamada a observe para localizar varios candidatos visibles y luego pasa la acción elegida a act.
Agrupa en un solo extract todos los campos que necesitas del mismo estado de la página.
Usa act solo para interacciones y conserva una acción atómica por llamada.
Valida el resultado antes de continuar para detener pronto un guion incorrecto.

Por ejemplo, una extracción conjunta evita releer la misma página varias veces:

// Mejor: una lectura con todos los campos necesarios.
const reporte = await page.extract(
  "extrae el folio (texto), el periodo (AAAA-MM), el total (número sin símbolo de moneda) y si está conciliado (booleano)"
);

// Evita una llamada separada para folio, otra para periodo y otra para total.

En páginas estables puedes acortar esperas por operación. No uses límites agresivos en portales lentos o con contenido dinámico:

await page.goto(input.portalUrl, {
  waitUntil: "domcontentloaded",
  timeout: 15000,
});

await page.act("haz clic en el botón 'Consultar'", {
  timeout: 5000,
});

Para páginas grandes, limita el análisis a la sección relevante y excluye zonas repetitivas. Esto reduce el contenido que debe procesarse:

const formulario = page.page.locator("#consulta-poliza");

await page.act("haz clic en el botón 'Consultar'", {
  locator: formulario,
  ignoreLocators: [
    page.page.locator("nav"),
    page.page.locator(".cookie-banner"),
  ],
});

Usa este patrón solo cuando los selectores sean estables. Si el portal cambia con frecuencia, una instrucción descriptiva sin locator suele ser más mantenible.

Valida el resultado antes de devolverlo

const datos = await page.extract("extrae el total de primas (número)");
if (typeof datos.total !== "number") {
  throw new Error("No se encontró el total en la página");
}
output = { total: datos.total };

Un paso que falla con un error claro es más útil que un output incompleto que rompe los pasos siguientes.

¿Guion o agente autónomo?

Situación	Paso recomendado
Portal conocido, mismos pasos cada vez (login, reportes, RPA)	`browser.script` (esta página)
Investigar en fuentes públicas, sitios variados, tareas abiertas	`browser.use`
Solo transformar datos, sin navegador	`code.javascript`

browser.script es más rápido, más barato y más predecible cuando el camino es fijo. browser.use gana cuando el agente tiene que decidir por sí mismo dónde buscar.

Salida del paso

Lo que asignes a output se guarda como resultado del paso y queda disponible para los siguientes con {{steps.N.output.*}}, igual que en code.javascript.

Errores frecuentes

Situación	Qué hacer
El login falla	Verifica credenciales y si el portal pide CAPTCHA o un código MFA; estos flujos pueden requerir configuración adicional.
Una acción no encuentra el elemento	Describe el tipo, texto y ubicación del elemento (“el botón ‘Exportar’ en la parte superior derecha”) o navega con `page.goto` directo a la URL de la sección.
Una acción se ejecuta en la pestaña equivocada	Confirma cuál pestaña está activa y usa `context.setActivePage(...)` antes de continuar.
El guion tarda demasiado	Reemplaza navegación interpretada por `goto`, agrupa lecturas relacionadas en un `extract` y reutiliza acciones devueltas por `observe`.
El paso falla al abrir el navegador	Usa una sola llamada a `browser.run` por ejecución. Si el error persiste, contacta a soporte.

​Campos del paso

​El objeto browser

​Ejemplo completo: reporte de cobranza

​Buenas prácticas para act, extract y observe

​Una acción por act

​Describe el elemento por tipo y texto, no por color

​Navega con goto, no con instrucciones

​Datos sensibles siempre en variables

​Pide campos concretos en extract

​Verifica antes de actuar con observe

​Trabaja con pestañas nuevas

​Reduce tiempo y costo

​Valida el resultado antes de devolverlo

​¿Guion o agente autónomo?

​Salida del paso

​Errores frecuentes

​Relacionado

Campos del paso

El objeto `browser`

Ejemplo completo: reporte de cobranza

Buenas prácticas para `act`, `extract` y `observe`

Una acción por `act`

Describe el elemento por tipo y texto, no por color

Navega con `goto`, no con instrucciones

Datos sensibles siempre en `variables`

Pide campos concretos en `extract`

Verifica antes de actuar con `observe`

Trabaja con pestañas nuevas

Reduce tiempo y costo

Valida el resultado antes de devolverlo

¿Guion o agente autónomo?

Salida del paso

Errores frecuentes

Relacionado