Przejdź do głównej treści
Gologin Cloud Browser może służyć jako zdalne środowisko uruchomieniowe przeglądarki dla agentów AI. Agent (Claude, Codex lub dowolny agent wywołujący narzędzia) może uruchomić Twój kod, który połączy się z sesją Cloud Browser i wykona prawdziwe akcje w przeglądarce, takie jak nawigacja, klikanie, wpisywanie tekstu i pobieranie danych. Dzięki temu możliwe są przepływy pracy agentów, które wymagają:
  • renderowania JavaScript i prawdziwych interakcji użytkownika (kliknięcie, przewijanie, wypełnianie formularzy)
  • trwałych sesji (cookies/storage) dzięki profilom
  • routingu przez proxy i powtarzalnej konfiguracji przeglądarki
Nie chcesz pisać narzędzi od zera? Skorzystaj z Agent Browser CLI lub AI Skills, aby uzyskać gotowe możliwości dla agentów — bez kodu Puppeteer/Playwright.
Uwaga: Ta strona opisuje techniczny wzorzec integracji. Nie zmienia zasad obowiązujących na docelowych stronach internetowych ani nie gwarantuje dostępu do nich.

Ogólny wzorzec integracji

Agenci AI zazwyczaj nie „łączą się z przeglądarką” bezpośrednio. Zamiast tego:
  1. planują, co zrobić dalej
  2. wywołują udostępnione przez Ciebie narzędzia/funkcje (tool calling)
  3. odczytują ustrukturyzowane wyniki i kontynuują
W przypadku Gologin Cloud Browser Twoje narzędzia/funkcje:
  1. łączą się z sesją w chmurze (token + opcjonalny profil)
  2. wykonują akcje w przeglądarce (nawigacja, kliknięcie, pobieranie danych, zrzut ekranu)
  3. zwracają ustrukturyzowane wyniki do agenta

Zalecana architektura

Agent AI (Claude / Codex / inny) -> wywołuje Twój serwer narzędzi (usługa w Node/Pythonie) -> serwer narzędzi używa Playwright/Puppeteer -> łączy się z Gologin Cloud Browser (zdalny endpoint) -> zwraca wyniki (tekst/JSON/odwołanie do zrzutu ekranu) do agenta Dlaczego ten wzorzec:
  • Twój token Gologin pozostaje po stronie serwera
  • możesz stosować limity zapytań, ponawianie prób, logowanie i kontrole bezpieczeństwa
  • możesz spójnie ponownie wykorzystywać profile i proxy

Wymagania wstępne

1) Token API (po stronie serwera)

Utwórz token w aplikacji Gologin: API & MCP → API → New Token.
Traktuj token jak sekret. Nie udostępniaj go w kodzie po stronie klienta.

2) (Zalecane) Profile i proxy przez REST API

Cloud Browser jest warstwą wykonawczą/uruchomieniową. Do zarządzania profilami (tworzenie/aktualizacja) i konfiguracji proxy użyj REST API:
Ważne: Jeśli profil ma źle skonfigurowane lub niedostępne proxy, sesja przeglądarki w chmurze nie uruchomi się i zakończy się błędem przekroczenia czasu proxy. Przed połączeniem upewnij się, że proxy jest osiągalne, lub na czas testów ustaw tryb proxy na none.

Dwa adresy URL — poznaj różnicę

Gologin udostępnia dwa różne adresy URL dla Cloud Browser. Służą do różnych celów: Z Puppeteer/Playwright działa tylko endpoint /connect. Adres Live View zwraca stronę HTML ze streamingiem i nie może być użyty jako browserWSEndpoint.

Łączenie z sesją w chmurze

Użyj kanonicznego endpointu Cloud Browser:
  • token — Twój token API Gologin
  • profile — ID profilu (opcjonalne)
    • Użyj profileId, gdy chcesz mieć trwałe sesje i kontrolowaną konfigurację
    • Jeśli profile zostanie pominięty, dla sesji może zostać utworzony nowy profil
Endpoint /connect uruchamia sesję przeglądarki automatycznie — przed połączeniem nie trzeba wykonywać osobnego wywołania API. Przykłady implementacji (Puppeteer/Playwright): https://gologin.com/docs/api-reference/cloud-browser/getting-started

Gotowe narzędzia CLI a własne narzędzia

Masz dwie opcje zapewnienia agentom dostępu do przeglądarki:

Opcja A: Użyj narzędzi CLI Gologin (zalecane w większości przypadków)

  • Agent Browser CLI — gotowe narzędzie CLI z poleceniami open, snapshot, click, type, fill, screenshot, close i ponad 30 innymi. Zawiera trwały daemon, interakcję opartą na referencjach oraz zwięzłe wyniki zaprojektowane z myślą o pętlach agentów.
  • Web Access CLI — jedno narzędzie CLI łączące scraping (Web Unlocker) i interakcję z przeglądarką.
  • AI Skills — gotowe do użycia umiejętności dla Claude Code, które wszystko obsługują automatycznie.

Opcja B: Zbuduj własne narzędzia z Puppeteer/Playwright

Jeśli potrzebujesz pełnej kontroli, zaimplementuj niewielki zestaw wrapperów wokół Playwright/Puppeteer i udostępnij je jako narzędzia. Zazwyczaj wystarczy minimalny zestaw:
  • open_url(url)
  • click(selector)
  • type(selector, text)
  • wait_for(selector | timeout)
  • extract_text(selector | page)
  • screenshot()
  • close_session()
To nie są specjalne API Gologin — to cienkie wrappery wokół standardowych poleceń Playwright/Puppeteer, wykonywanych w sesji Cloud Browser.

Kluczowe: zarządzanie sesją między wywołaniami narzędzi

To najważniejsza kwestia architektoniczna w przepływach pracy agentów. Agent AI wywołuje narzędzia sekwencyjnie w wielu krokach. Każde wywołanie narzędzia musi używać tego samego połączenia z przeglądarką — jeśli przy każdym wywołaniu utworzysz nowe puppeteer.connect(), utracisz cookies, local storage i stan strony między krokami. Zalecany wzorzec: utrzymuj singleton sesji na serwerze narzędzi.
Każde narzędzie wywołuje następnie getSession(), aby uzyskać współdzieloną instancję:

Co powinny zwracać narzędzia do agenta?

Zwracaj małe, ustrukturyzowane wyniki, aby agent mógł niezawodnie kontynuować pracę, na przykład:
  • bieżący adres URL
  • wyodrębniony tekst / JSON
  • informację, czy element został znaleziony
  • odwołanie do zrzutu ekranu (jeśli go zapisujesz)
  • typ błędu (przekroczenie czasu, błąd nawigacji itp.)

Uwagi operacyjne

  • Bezpieczeństwo: trzymaj token po stronie serwera; nigdy nie osadzaj go w aplikacjach klienckich.
  • Zarządzanie sesjami: zamykaj sesje po zakończeniu pracy, aby nie osiągnąć limitów współbieżności. Wywołaj closeSession(), gdy przepływ pracy agenta się zakończy.
  • Niezawodność: dodaj ponawianie prób i opóźnienia między nimi (backoff) dla błędów przejściowych (przekroczenia czasu, błędy nawigacji).
  • Obserwowalność: do debugowania możesz otworzyć Live View, gdy jest dostępny. Przykładowy format adresu URL: https://cloudbrowser.gologin.com/browsers/{profileId}/{sessionId-or-view-token}/

Ograniczenia

  • Wyniki zależą od docelowej strony internetowej i Twojej konfiguracji.
  • Strony mogą blokować automatyzację; Cloud Browser jest środowiskiem uruchomieniowym, a nie gwarancją.
  • Łączenie się z tym samym profilem z wielu jednoczesnych sesji może powodować konflikty — używaj jednego połączenia na profil w danym momencie.
  • Obowiązują limity i ograniczenia liczby zapytań: https://gologin.com/docs/api-reference/limitations/rate-limits