> ## Documentation Index
> Fetch the complete documentation index at: https://gologin.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Как использовать Gologin Cloud Browser как удалённую среду выполнения браузера для ИИ-агентов с Puppeteer/Playwright

Gologin Cloud Browser можно использовать как **удалённую среду выполнения браузера** для ИИ-агентов.
Агент (Claude, Codex или любой другой агент с вызовом инструментов) может запускать ваш код, который подключается к сессии Cloud Browser и выполняет реальные действия в браузере: переходы по страницам, клики, ввод текста и извлечение данных.

Это позволяет строить сценарии для агентов, которым нужны:

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

> [!TIP]
>
> **Не хотите писать инструменты с нуля?** Используйте [Agent Browser CLI](https://gologin.com/docs/ru/cli-tools/agent-browser.md) или [AI Skills](https://gologin.com/docs/ru/api-reference/ai-integrations/ai-skills.md) — это готовые возможности для агентов, код на Puppeteer/Playwright не нужен.

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

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

ИИ-агенты, как правило, не «подключаются к браузеру» напрямую. Вместо этого они:

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

При работе с Gologin Cloud Browser ваши инструменты и функции:

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

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

**ИИ-агент (Claude / Codex / другой)**
-> вызывает ваш **сервер инструментов** (сервис на Node/Python)
-> сервер инструментов использует **Playwright/Puppeteer**
-> подключается к **Gologin Cloud Browser** (удалённая конечная точка)
-> возвращает агенту результаты (текст/JSON/ссылку на снимок экрана)

Преимущества такой схемы:

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

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

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

Сгенерируйте токен в личном кабинете:
`Личный кабинет -> API-токен`
[https://app.gologin.com/personalArea/TokenApi](https://app.gologin.com/personalArea/TokenApi)

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

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

Cloud Browser — это слой выполнения. Чтобы управлять профилями (создавать и обновлять) и настраивать прокси, используйте REST API:

* Profiles API: [https://gologin.com/docs/api-reference/profile](https://gologin.com/docs/api-reference/profile)
* Proxy API: [https://gologin.com/docs/api-reference/proxy](https://gologin.com/docs/api-reference/proxy)

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

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

Gologin предоставляет два разных URL для Cloud Browser. Они служат разным целям:

| URL | Назначение | Для чего использовать |
| - | - | - |
| `https://cloudbrowser.gologin.com/connect?token=...&profile=...` | CDP-эндпоинт | Автоматизация через Puppeteer/Playwright |
| `https://cloudbrowser.gologin.com/browsers/{profileId}/{sessionId}/` | Веб-интерфейс трансляции (Live View) | Только визуальная отладка |

**Для Puppeteer/Playwright подходит только эндпоинт `/connect`.** URL Live View возвращает HTML-интерфейс трансляции и не может использоваться как `browserWSEndpoint`.

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

Используйте основной эндпоинт Cloud Browser:

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

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

Эндпоинт `/connect` запускает сессию браузера автоматически — отдельный вызов API перед подключением не нужен.

Примеры реализации (Puppeteer/Playwright):
[https://gologin.com/docs/api-reference/cloud-browser/getting-started](https://gologin.com/docs/api-reference/cloud-browser/getting-started.md)

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

Есть два способа дать агентам доступ к браузеру:

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

* **[Agent Browser CLI](https://gologin.com/docs/ru/cli-tools/agent-browser.md)** — готовый CLI с командами `open`, `snapshot`, `click`, `type`, `fill`, `screenshot`, `close` и более чем 30 другими. Включает постоянный демон, взаимодействие через ссылки на элементы (ref) и компактный вывод, рассчитанный на циклы работы агента.
* **[Web Access CLI](https://gologin.com/docs/ru/cli-tools/web-access.md)** — единый CLI, объединяющий скрапинг (Web Unlocker) и работу с браузером в одном инструменте.
* **[AI Skills](https://gologin.com/docs/ru/api-reference/ai-integrations/ai-skills.md)** — готовые навыки для Claude Code, которые всё делают автоматически.

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

Если вам нужен полный контроль, реализуйте небольшой набор обёрток вокруг Playwright/Puppeteer и предоставьте их как инструменты.

Обычно хватает минимального набора:

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

Это не специальные API Gologin, а тонкие обёртки над стандартными командами Playwright/Puppeteer, которые выполняются в сессии Cloud Browser.

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

Это самый важный архитектурный момент для сценариев с агентами.

ИИ-агент вызывает инструменты последовательно, на нескольких шагах. Каждый вызов должен использовать **одно и то же подключение к браузеру**: если на каждый вызов создавать новый `puppeteer.connect()`, между шагами будут теряться cookies, локальное хранилище и состояние страницы.

**Рекомендуемый подход:** храните единственный экземпляр сессии (singleton) на сервере инструментов.

```js theme={null}
// 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 };
```

Каждый инструмент затем вызывает `getSession()`, чтобы получить общий экземпляр:

```js theme={null}
// 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](https://gologin.com/docs/api-reference/limitations/rate-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.