Używanie Cloud Browser z agentami AI

• renderowania JavaScript i prawdziwych interakcji użytkownika (klikanie, 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

1. planują kolejny krok
2. wywołują udostępnione przez Ciebie narzędzia/funkcje (tool calling)
3. odczytują ustrukturyzowane wyniki i kontynuują pracę

1. łączą się z sesją w chmurze (token + opcjonalny profil)
2. wykonują akcje w przeglądarce (nawigacja, klikanie, pobieranie danych, zrzut ekranu)
3. zwracają agentowi ustrukturyzowane wyniki

​

Zalecana architektura

• 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 używać profili i serwerów proxy

​

Wymagania wstępne

​

1) Token API (po stronie serwera)

Traktuj token jak sekret. Nie udostępniaj go w kodzie po stronie klienta.

​

2) (Zalecane) Profile i proxy przez 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 błędnie skonfigurowane lub niedostępne proxy, sesja Cloud Browser nie uruchomi się i zakończy się błędem przekroczenia czasu proxy. Przed połączeniem sprawdź, czy proxy jest osiągalne, lub na czas testów ustaw tryb proxy na none.

​

Dwa adresy URL — poznaj różnicę

​

Łączenie z sesją w chmurze

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

• token — Twój token API Gologin
• profile — identyfikator profilu (opcjonalny)
  • Użyj profileId, gdy potrzebujesz trwałych sesji i kontrolowanej konfiguracji
  • Jeśli profile zostanie pominięty, dla sesji może zostać utworzony nowy profil

​

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

​

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 dane wyjściowe zaprojektowane z myślą o pętlach agentów.
• Web Access CLI — zunifikowane narzędzie CLI łączące scraping (Web Unlocker) i interakcję z przeglądarką w jednym.
• AI Skills — gotowe do użycia umiejętności dla Claude Code, które automatycznie obsługują wszystko.

​

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

• 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

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

​

Co powinny zwracać narzędzia agentowi?

• bieżący adres URL
• pobrany tekst / JSON
• informację, czy element został znaleziony
• odnośnik do zrzutu ekranu (jeśli go zapisujesz)
• typ błędu (przekroczenie czasu, błąd nawigacji itp.)

​

Uwagi operacyjne

• Bezpieczeństwo: przechowuj token po stronie serwera; nigdy nie umieszczaj go w aplikacjach klienckich.
• Zarządzanie sesjami: zamykaj sesje po zakończeniu pracy, aby nie osiągnąć limitów równoczesnych sesji. Wywołaj closeSession(), gdy scenariusz agenta się zakończy.
• Niezawodność: dodaj ponawianie prób z narastającym opóźnieniem (backoff) dla przejściowych błędów (przekroczenia czasu, błędy nawigacji).
• Obserwowalność: podczas 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 internetowe mogą blokować automatyzację; Cloud Browser jest środowiskiem uruchomieniowym, a nie gwarancją dostępu.
• Łączenie się z tym samym profilem z wielu równoczesnych 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