- 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
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:- planują, co zrobić dalej
- wywołują udostępnione przez Ciebie narzędzia/funkcje (tool calling)
- odczytują ustrukturyzowane wyniki i kontynuują
- łączą się z sesją w chmurze (token + opcjonalny profil)
- wykonują akcje w przeglądarce (nawigacja, kliknięcie, pobieranie danych, zrzut ekranu)
- 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:- Profiles API: https://gologin.com/docs/api-reference/profile
- Proxy API: https://gologin.com/docs/api-reference/proxy
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 Gologinprofile— ID profilu (opcjonalne)- Użyj
profileId, gdy chcesz mieć trwałe sesje i kontrolowaną konfigurację - Jeśli
profilezostanie pominięty, dla sesji może zostać utworzony nowy profil
- Użyj
/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,closei 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()
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 nowepuppeteer.connect(), utracisz cookies, local storage i stan strony między krokami.
Zalecany wzorzec: utrzymuj singleton sesji na serwerze narzędzi.
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