Utiliser Cloud Browser avec des agents IA

• le rendu JavaScript et de véritables interactions utilisateur (clic, défilement, remplissage de formulaires)
• des sessions persistantes (cookies/stockage) grâce aux profils
• le routage par proxy et une configuration de navigateur reproductible

Remarque : cette page décrit un modèle d’intégration technique. Elle ne modifie pas les règles des sites web cibles et ne garantit pas l’accès à ces sites.

​

Modèle d’intégration général

1. planifient la prochaine action
2. appellent les outils/fonctions que vous exposez (tool calling)
3. lisent les résultats structurés et poursuivent

1. se connectent à une session cloud (token + profil facultatif)
2. exécutent des actions dans le navigateur (navigation, clic, extraction, capture d’écran)
3. renvoient des résultats structurés à l’agent

​

Architecture recommandée

• votre token Gologin reste côté serveur
• vous pouvez appliquer des limites de débit, des nouvelles tentatives, de la journalisation et des contrôles de sécurité
• vous pouvez réutiliser les profils et les proxys de manière cohérente

​

Prérequis

​

1) Token d’API (côté serveur)

Traitez le token comme un secret. Ne l’exposez pas dans du code côté client.

​

2) (Recommandé) Profils et proxys via l’API REST

• API Profils : https://gologin.com/docs/api-reference/profile
• API Proxy : https://gologin.com/docs/api-reference/proxy

Important : si un profil a un proxy mal configuré ou inaccessible, la session de navigateur cloud ne démarrera pas et renverra une erreur de délai d’attente du proxy. Vérifiez que votre proxy est accessible avant de vous connecter, ou définissez le mode proxy sur none pour les tests.

​

Deux URL : comprendre la différence

​

Se connecter à une session cloud

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

• token : votre token d’API Gologin
• profile : ID du profil (facultatif)
  • Utilisez profileId si vous souhaitez des sessions persistantes et une configuration maîtrisée
  • Si profile est omis, un nouveau profil peut être créé pour la session

​

Outils CLI prêts à l’emploi ou outils personnalisés

​

Option A : utiliser les outils CLI de Gologin (recommandé dans la plupart des cas)

• Agent Browser CLI : une CLI prête à l’emploi avec open, snapshot, click, type, fill, screenshot, close et plus de 30 autres commandes. Elle inclut un démon persistant, des interactions basées sur des références et une sortie compacte conçue pour les boucles d’agents.
• Web Access CLI : une CLI unifiée qui combine le scraping (Web Unlocker) et l’interaction avec le navigateur dans un seul outil.
• AI Skills : des skills prêts à brancher pour Claude Code, qui gèrent tout automatiquement.

​

Option B : créer des outils personnalisés avec Puppeteer/Playwright

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

​

Point essentiel : la gestion de session entre les appels d’outils

// 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) };
}

​

Que doivent renvoyer les outils à l’agent ?

• l’URL actuelle
• le texte extrait / du JSON
• l’indication qu’un élément a été trouvé ou non
• une référence de capture d’écran (si vous la stockez)
• le type d’erreur (délai d’attente dépassé, erreur de navigation, etc.)

​

Remarques opérationnelles

• Sécurité : gardez le token côté serveur ; ne l’intégrez jamais dans des applications clientes.
• Gestion des sessions : fermez les sessions lorsque vous avez terminé pour éviter d’atteindre les limites de concurrence. Appelez closeSession() à la fin du workflow de l’agent.
• Fiabilité : ajoutez des nouvelles tentatives avec temporisation progressive (backoff) pour les échecs temporaires (délais d’attente dépassés, erreurs de navigation).
• Observabilité : pour le débogage, vous pouvez ouvrir Live View lorsqu’il est disponible. Exemple de format d’URL : https://cloudbrowser.gologin.com/browsers/{profileId}/{sessionId-or-view-token}/

​

Limitations

• Les résultats dépendent du site web cible et de votre configuration.
• Les sites web peuvent bloquer l’automatisation ; Cloud Browser est un environnement d’exécution, pas une garantie.
• Se connecter au même profil depuis plusieurs sessions simultanées peut provoquer des conflits : utilisez une seule connexion par profil à la fois.
• Des quotas et des limites de débit s’appliquent : https://gologin.com/docs/api-reference/limitations/rate-limits