Использование Cloud Browser с ИИ-агентами

• отрисовка JavaScript и действия реального пользователя (клик, прокрутка, заполнение форм)
• постоянные сессии (cookies и хранилище) с помощью профилей
• маршрутизация через прокси и воспроизводимая конфигурация браузера

Примечание: на этой странице описан технический шаблон интеграции. Он не меняет правила целевых сайтов и не гарантирует доступ к ним.

​

Общая схема интеграции

1. планируют следующий шаг
2. вызывают инструменты и функции, которые вы им предоставили (tool calling)
3. читают структурированные результаты и продолжают работу

1. подключаются к облачной сессии (токен и, при необходимости, профиль)
2. выполняют действия в браузере (переход, клик, извлечение данных, снимок экрана)
3. возвращают агенту структурированные результаты

​

Рекомендуемая архитектура

• токен Gologin остаётся на стороне сервера
• можно применять ограничения частоты запросов, повторные попытки, логирование и проверки безопасности
• профили и прокси можно использовать единообразно

​

Предварительные требования

​

1) API-токен (на стороне сервера)

Относитесь к токену как к секрету. Не используйте его в клиентском коде.

​

2) (Рекомендуется) Профили и прокси через REST API

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

Важно: если у профиля неверно настроен или недоступен прокси, сессия облачного браузера не запустится и завершится ошибкой тайм-аута прокси. Перед подключением убедитесь, что прокси доступен, либо для тестирования установите режим прокси none.

​

Два URL — в чём разница

​

Подключение к облачной сессии

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

• token — ваш API-токен Gologin
• profile — ID профиля (необязательно)
  • Используйте profileId, если нужны постоянные сессии и управляемая конфигурация
  • Если profile не указан, для сессии может быть создан новый профиль

​

Готовые CLI-инструменты и собственные инструменты

​

Вариант A: использовать CLI-инструменты Gologin (рекомендуется в большинстве случаев)

• Agent Browser CLI — готовый CLI с командами open, snapshot, click, type, fill, screenshot, close и более чем 30 другими. Включает постоянный демон, взаимодействие через ссылки на элементы (ref) и компактный вывод, рассчитанный на циклы работы агента.
• Web Access CLI — единый CLI, объединяющий скрапинг (Web Unlocker) и работу с браузером в одном инструменте.
• AI Skills — готовые навыки для Claude Code, которые всё делают автоматически.

​

Вариант B: создать собственные инструменты на Puppeteer/Playwright

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

​

Важно: управление сессией между вызовами инструментов

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

​

Что инструменты должны возвращать агенту

• текущий URL
• извлечённый текст / JSON
• найден ли элемент
• ссылку на снимок экрана (если вы его сохраняете)
• тип ошибки (тайм-аут, ошибка навигации и т. д.)

​

Эксплуатационные замечания

• Безопасность: храните токен на стороне сервера, никогда не встраивайте его в клиентские приложения.
• Управление сессиями: закрывайте сессии после завершения работы, чтобы не упереться в лимит одновременных сессий. Вызывайте closeSession(), когда сценарий агента завершён.
• Надёжность: добавьте повторные попытки с задержкой (backoff) для временных сбоев (тайм-ауты, ошибки навигации).
• Наблюдаемость: для отладки можно открыть Live View, если он доступен. Пример формата URL: https://cloudbrowser.gologin.com/browsers/{profileId}/{sessionId-or-view-token}/

​

Ограничения

• Результаты зависят от целевого сайта и вашей конфигурации.
• Сайты могут блокировать автоматизацию; Cloud Browser — это среда выполнения, а не гарантия доступа.
• Подключение к одному профилю из нескольких одновременных сессий может вызывать конфликты — используйте одно подключение на профиль одновременно.
• Действуют квоты и ограничения частоты запросов: https://gologin.com/docs/api-reference/limitations/rate-limits