Cloud Browser mit KI-Agenten verwenden

• JavaScript-Rendering und echte Nutzerinteraktionen (Klicken, Scrollen, Formulare ausfüllen)
• persistente Sitzungen (Cookies/Storage) über Profile
• Proxy-Routing und wiederholbare Browserkonfiguration

Hinweis: Diese Seite beschreibt ein technisches Integrationsmuster. Sie ändert weder die Regeln der Zielwebsites noch garantiert sie den Zugriff.

​

Integrationsmuster im Überblick

1. planen sie den nächsten Schritt
2. rufen sie Tools/Funktionen auf, die Sie bereitstellen (Tool-Calling)
3. lesen sie strukturierte Ergebnisse und machen weiter

1. Verbindung mit einer Cloud-Sitzung herstellen (Token + optionales Profil)
2. Browseraktionen ausführen (navigieren, klicken, extrahieren, Screenshot)
3. strukturierte Ergebnisse an den Agenten zurückgeben

​

Empfohlene Architektur

• Ihr Gologin-Token bleibt serverseitig
• Sie können Rate Limits, Wiederholungen, Logging und Sicherheitsprüfungen einsetzen
• Sie können Profile und Proxys konsistent wiederverwenden

​

Voraussetzungen

​

1) API-Token (serverseitig)

Behandeln Sie den Token als Geheimnis. Geben Sie ihn nicht in clientseitigem Code preis.

​

2) (Empfohlen) Profile und Proxys über die REST API

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

Wichtig: Wenn ein Profil einen falsch konfigurierten oder nicht erreichbaren Proxy hat, kann die Cloud Browser-Sitzung nicht gestartet werden und es tritt ein Proxy-Timeout-Fehler auf. Prüfen Sie vor dem Verbinden, ob Ihr Proxy erreichbar ist, oder setzen Sie den Proxy-Modus zu Testzwecken auf none.

​

Zwei URLs – der Unterschied

​

Verbindung mit einer Cloud-Sitzung herstellen

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

• token – Ihr Gologin API-Token
• profile – Profil-ID (optional)
  • Verwenden Sie profileId, wenn Sie persistente Sitzungen und eine kontrollierte Konfiguration wünschen
  • Wenn profile weggelassen wird, kann für die Sitzung ein neues Profil erstellt werden

​

Vorgefertigte CLI-Tools oder eigene Tools

​

Option A: Gologin CLI-Tools verwenden (für die meisten Fälle empfohlen)

• Agent Browser CLI – fertiges CLI mit open, snapshot, click, type, fill, screenshot, close und über 30 weiteren Befehlen. Enthält einen persistenten Daemon, referenzbasierte Interaktion und eine kompakte Ausgabe, die für Agent-Schleifen ausgelegt ist.
• Web Access CLI – einheitliches CLI, das Scraping (Web Unlocker) und Browserinteraktion in einem Tool vereint.
• AI Skills – Plug-and-play-Skills für Claude Code, die alles automatisch erledigen.

​

Option B: Eigene Tools mit Puppeteer/Playwright erstellen

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

​

Wichtig: Sitzungsverwaltung über Tool-Aufrufe hinweg

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

​

Was sollten Tools an den Agenten zurückgeben?

• aktuelle URL
• extrahierter Text / JSON
• ob ein Element gefunden wurde
• Screenshot-Referenz (falls Sie ihn speichern)
• Fehlertyp (Timeout, Navigationsfehler usw.)

​

Hinweise zum Betrieb

• Sicherheit: Halten Sie den Token serverseitig; binden Sie ihn niemals in Client-Apps ein.
• Sitzungsverwaltung: Schließen Sie Sitzungen nach Gebrauch, um das Erreichen von Limits für gleichzeitige Sitzungen zu vermeiden. Rufen Sie closeSession() auf, wenn der Agent-Workflow abgeschlossen ist.
• Zuverlässigkeit: Fügen Sie Wiederholungen/Backoff für vorübergehende Fehler hinzu (Timeouts, Navigationsfehler).
• Beobachtbarkeit: Zum Debuggen können Sie Live View öffnen, sofern verfügbar. Beispiel für das URL-Format: https://cloudbrowser.gologin.com/browsers/{profileId}/{sessionId-or-view-token}/

​

Einschränkungen

• Die Ergebnisse hängen von der Zielwebsite und Ihrer Konfiguration ab.
• Websites können Automatisierung blockieren; Cloud Browser ist eine Runtime und keine Garantie.
• Wenn mehrere Sitzungen gleichzeitig mit demselben Profil verbunden sind, kann es zu Konflikten kommen – verwenden Sie pro Profil jeweils nur eine Verbindung.
• Es gelten Kontingente und Rate Limits: https://gologin.com/docs/api-reference/limitations/rate-limits