Uso de Cloud Browser con agentes de IA

• Renderizado de JavaScript e interacciones reales de usuario (clic, desplazamiento, rellenado de formularios)
• Sesiones persistentes (cookies/almacenamiento) mediante perfiles
• Enrutamiento por proxy y una configuración de navegador repetible

Nota: esta página describe un patrón técnico de integración. No modifica las reglas de los sitios web de destino ni garantiza el acceso.

​

Patrón de integración general

1. planifican qué hacer a continuación
2. llaman a las herramientas/funciones que tú expones (tool calling)
3. leen los resultados estructurados y continúan

1. se conectan a una sesión en la nube (token + perfil opcional)
2. ejecutan acciones en el navegador (navegar, hacer clic, extraer, capturar pantalla)
3. devuelven resultados estructurados al agente

​

Arquitectura recomendada

• tu token de Gologin permanece en el servidor
• puedes aplicar límites de frecuencia, reintentos, registros y comprobaciones de seguridad
• puedes reutilizar perfiles y proxies de forma coherente

​

Requisitos previos

​

1) Token de API (en el servidor)

Trata el token como un secreto. No lo expongas en código del lado del cliente.

​

2) (Recomendado) Perfiles y proxies mediante la API REST

• API de perfiles: https://gologin.com/docs/api-reference/profile
• API de proxies: https://gologin.com/docs/api-reference/proxy

Importante: si un perfil tiene un proxy mal configurado o inaccesible, la sesión del navegador en la nube no se iniciará y devolverá un error de tiempo de espera del proxy. Comprueba que tu proxy sea accesible antes de conectarte, o establece el modo de proxy en none para hacer pruebas.

​

Dos URL: conoce la diferencia

​

Conexión a una sesión en la nube

https://cloudbrowser.gologin.com/connect?token=${token}&profile=${profileId}

• token: tu token de API de Gologin
• profile: ID del perfil (opcional)
  • Usa profileId cuando quieras sesiones persistentes y una configuración controlada
  • Si omites profile, es posible que se cree un perfil nuevo para la sesión

​

Herramientas CLI predefinidas frente a herramientas personalizadas

​

Opción A: usar las herramientas CLI de Gologin (recomendada en la mayoría de los casos)

• Agent Browser CLI: CLI listo para usar con open, snapshot, click, type, fill, screenshot, close y más de 30 comandos adicionales. Incluye un daemon persistente, interacción basada en referencias y una salida compacta diseñada para los bucles de los agentes.
• Web Access CLI: CLI unificado que combina scraping (Web Unlocker) e interacción con el navegador en una sola herramienta.
• AI Skills: skills listas para usar con Claude Code que se encargan de todo automáticamente.

​

Opción B: crear herramientas personalizadas con Puppeteer/Playwright

• open_url(url)
• click(selector)
• type(selector, text)
• wait_for(selector | timeout)
• extract_text(selector | page)
• screenshot()
• close_session()

​

Fundamental: gestión de sesiones entre llamadas a herramientas

// session.js — shared browser/page instance
let _browser = null;
let _page = null;

const TOKEN = process.env.GOLOGIN_TOKEN;
const PROFILE_ID = process.env.GOLOGIN_PROFILE_ID;

async function getSession() {
  if (_browser && _browser.isConnected()) {
    return { browser: _browser, page: _page };
  }

  const cloudBrowserUrl = `https://cloudbrowser.gologin.com/connect?token=${TOKEN}&profile=${PROFILE_ID}`;
  _browser = await puppeteer.connect({
    browserWSEndpoint: cloudBrowserUrl,
    defaultViewport: null,
  });

  const pages = await _browser.pages();
  _page = pages[0] || await _browser.newPage();

  return { browser: _browser, page: _page };
}

async function closeSession() {
  if (_browser) {
    await _browser.close();
    _browser = null;
    _page = null;
  }
}

module.exports = { getSession, closeSession };

// tools.js
const { getSession } = require('./session');

async function open_url(url) {
  const { page } = await getSession();
  await page.goto(url, { waitUntil: 'domcontentloaded' });
  return { url: page.url(), title: await page.title() };
}

async function extract_text(selector) {
  const { page } = await getSession();
  const el = await page.$(selector);
  if (!el) return { found: false };
  return { found: true, text: await el.evaluate(e => e.innerText) };
}

​

¿Qué deben devolver las herramientas al agente?

• la URL actual
• texto extraído / JSON
• si se encontró un elemento
• una referencia a la captura de pantalla (si la almacenas)
• el tipo de error (tiempo de espera agotado, error de navegación, etc.)

​

Notas operativas

• Seguridad: mantén el token en el servidor; nunca lo incluyas en aplicaciones cliente.
• Gestión de sesiones: cierra las sesiones cuando termines para no alcanzar los límites de concurrencia. Llama a closeSession() cuando finalice el flujo de trabajo del agente.
• Fiabilidad: añade reintentos con espera progresiva (backoff) para fallos transitorios (tiempos de espera agotados, errores de navegación).
• Observabilidad: para depurar, puedes abrir Live View cuando esté disponible. Ejemplo de formato de URL: https://cloudbrowser.gologin.com/browsers/{profileId}/{sessionId-or-view-token}/

​

Limitaciones

• Los resultados dependen del sitio web de destino y de tu configuración.
• Los sitios web pueden bloquear la automatización; Cloud Browser es un entorno de ejecución, no una garantía.
• Conectarse al mismo perfil desde varias sesiones simultáneas puede provocar conflictos: usa una sola conexión por perfil a la vez.
• Se aplican cuotas y límites de frecuencia: https://gologin.com/docs/api-reference/limitations/rate-limits