- 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
KI-Agenten „verbinden sich” in der Regel nicht direkt mit einem Browser. Stattdessen gehen sie so vor:- Sie planen den nächsten Schritt
- Sie rufen Tools/Funktionen auf, die Sie bereitstellen (Tool-Calling)
- Sie lesen strukturierte Ergebnisse und machen weiter
- Verbindung zu einer Cloud-Sitzung herstellen (Token + optional Profil)
- Browseraktionen ausführen (navigieren, klicken, extrahieren, Screenshot erstellen)
- Strukturierte Ergebnisse an den Agenten zurückgeben
Empfohlene Architektur
KI-Agent (Claude / Codex / andere) -> ruft Ihren Tool-Server auf (Ihr Node-/Python-Dienst) -> der Tool-Server nutzt Playwright/Puppeteer -> verbindet sich mit Gologin Cloud Browser (Remote-Endpunkt) -> gibt Ergebnisse (Text/JSON/Screenshot-Referenz) an den Agenten zurück Warum dieses Muster:- Ihr Gologin-Token bleibt serverseitig
- Sie können Rate Limits, Wiederholungen, Logging und Sicherheitsprüfungen anwenden
- Sie können Profile und Proxys einheitlich wiederverwenden
Voraussetzungen
1) API-Token (serverseitig)
Erstellen Sie Ihren Token in der Gologin-App: API & MCP → API → New Token.Behandeln Sie den Token wie ein Geheimnis. Geben Sie ihn nicht im clientseitigen Code preis.
2) (Empfohlen) Profile und Proxys über die REST API
Cloud Browser ist die Ausführungs- bzw. Laufzeitschicht. Um Profile zu verwalten (erstellen/aktualisieren) und Proxys zu konfigurieren, verwenden Sie die REST API:- Profiles API: https://gologin.com/docs/api-reference/profile
- Proxy API: https://gologin.com/docs/api-reference/proxy
Wichtig: Wenn bei einem Profil der Proxy falsch konfiguriert oder nicht erreichbar ist, kann die Cloud Browser-Sitzung nicht gestartet werden und es erscheint ein Proxy-Timeout-Fehler. Prüfen Sie vor dem Verbindungsaufbau, ob Ihr Proxy erreichbar ist, oder setzen Sie für Tests den Proxy-Modus auf none.
Zwei URLs – der Unterschied
Gologin stellt für Cloud Browser zwei verschiedene URLs bereit. Sie erfüllen unterschiedliche Zwecke:
Nur der
/connect-Endpunkt funktioniert mit Puppeteer/Playwright. Die URL von Live View liefert eine HTML-Streaming-Oberfläche und kann nicht als browserWSEndpoint verwendet werden.
Verbindung zu einer Cloud-Sitzung herstellen
Verwenden Sie den kanonischen Cloud Browser-Endpunkt:token– Ihr Gologin-API-Tokenprofile– Profil-ID (optional)- Verwenden Sie
profileId, wenn Sie persistente Sitzungen und eine kontrollierte Konfiguration wünschen - Wenn
profileweggelassen wird, kann für die Sitzung ein neues Profil erstellt werden
- Verwenden Sie
/connect-Endpunkt startet die Browsersitzung automatisch – vor dem Verbinden ist kein separater API-Aufruf nötig.
Implementierungsbeispiele (Puppeteer/Playwright):
https://gologin.com/docs/api-reference/cloud-browser/getting-started
Vorgefertigte CLI-Tools oder eigene Tools
Sie haben zwei Möglichkeiten, Agenten Browserzugriff zu geben:Option A: Gologin-CLI-Tools verwenden (für die meisten Fälle empfohlen)
- Agent Browser CLI – fertige CLI mit
open,snapshot,click,type,fill,screenshot,closeund über 30 weiteren Befehlen. Enthält einen persistenten Daemon, referenzbasierte Interaktion und eine kompakte Ausgabe, die für Agenten-Schleifen ausgelegt ist. - Web Access CLI – einheitliche CLI, die 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
Wenn Sie volle Kontrolle benötigen, implementieren Sie einige kleine Wrapper um Playwright/Puppeteer und stellen Sie diese als Tools bereit. In der Regel genügt ein minimaler Satz:open_url(url)click(selector)type(selector, text)wait_for(selector | timeout)extract_text(selector | page)screenshot()close_session()
Wichtig: Sitzungsverwaltung über mehrere Tool-Aufrufe hinweg
Dies ist der wichtigste architektonische Aspekt für Agenten-Workflows. Ein KI-Agent ruft Tools nacheinander über mehrere Schritte hinweg auf. Jeder Tool-Aufruf muss dieselbe Browserverbindung wiederverwenden – wenn Sie bei jedem Tool-Aufruf ein neuespuppeteer.connect() erstellen, gehen Cookies, Local Storage und der Seitenzustand zwischen den Schritten verloren.
Empfohlenes Muster: Verwalten Sie auf Ihrem Tool-Server eine Singleton-Sitzung.
getSession() auf, um die gemeinsame Instanz zu erhalten:
Was sollten Tools an den Agenten zurückgeben?
Geben Sie kleine, strukturierte Ergebnisse zurück, damit der Agent zuverlässig weiterarbeiten kann, zum Beispiel:- 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 Abschluss, um das Erreichen von Limits für gleichzeitige Sitzungen zu vermeiden. Rufen Sie
closeSession()auf, wenn der Agenten-Workflow beendet ist. - Zuverlässigkeit: Fügen Sie Wiederholungen mit 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 Laufzeitumgebung und keine Garantie.
- Die Verbindung zum selben Profil aus mehreren gleichzeitigen Sitzungen kann zu Konflikten führen – verwenden Sie pro Profil jeweils nur eine Verbindung.
- Es gelten Kontingente und Rate Limits: https://gologin.com/docs/api-reference/limitations/rate-limits