> ## 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.

# Usando o Cloud Browser com agentes de IA

> Como usar o Gologin Cloud Browser como ambiente de execução de navegador remoto para agentes de IA com Puppeteer/Playwright

O Gologin Cloud Browser pode ser usado como um **ambiente de execução de navegador remoto** para agentes de IA.
Um agente (Claude, Codex ou qualquer agente com chamada de ferramentas) pode acionar o seu código para se conectar a uma sessão do Cloud Browser e executar ações reais no navegador, como navegar, clicar, digitar e extrair dados.

Isso viabiliza fluxos de trabalho de agentes que exigem:

* renderização de JavaScript e interações reais de usuário (clicar, rolar a página, preencher formulários)
* sessões persistentes (cookies/armazenamento) por meio de perfis
* roteamento de proxy e configuração de navegador repetível

> [!TIP]
>
> **Não quer escrever as ferramentas do zero?** Use a [Agent Browser CLI](https://gologin.com/docs/pt/cli-tools/agent-browser.md) ou as [AI Skills](https://gologin.com/docs/pt/api-reference/ai-integrations/ai-skills.md) para ter recursos de agente prontos, sem precisar de código Puppeteer/Playwright.

> Observação: esta página descreve um padrão técnico de integração. Ela não altera as regras dos sites de destino nem garante acesso.

## Padrão geral de integração

Normalmente, agentes de IA não "se conectam a um navegador" diretamente. Em vez disso, eles:

1. planejam o que fazer em seguida
2. chamam as ferramentas/funções que você disponibiliza (tool calling)
3. leem resultados estruturados e continuam

Com o Gologin Cloud Browser, as suas ferramentas/funções fazem o seguinte:

1. conectam a uma sessão na nuvem (token + perfil opcional)
2. executam ações no navegador (navegar, clicar, extrair, tirar screenshot)
3. devolvem resultados estruturados ao agente

## Arquitetura recomendada

**Agente de IA (Claude / Codex / outro)**
-> chama o seu **servidor de ferramentas** (seu serviço Node/Python)
-> o servidor de ferramentas usa **Playwright/Puppeteer**
-> conecta ao **Gologin Cloud Browser** (endpoint remoto)
-> devolve os resultados (texto/JSON/referência de screenshot) ao agente

Por que usar esse padrão:

* seu token do Gologin permanece no lado do servidor
* você pode aplicar limites de taxa, novas tentativas, registros e verificações de segurança
* você pode reutilizar perfis e proxies de forma consistente

## Pré-requisitos

### 1) Token de API (no lado do servidor)

Gere seu token no painel:
`Área pessoal -> Token de API`
[https://app.gologin.com/personalArea/TokenApi](https://app.gologin.com/personalArea/TokenApi)

> Trate o token como um segredo. Não o exponha em código do lado do cliente.

### 2) (Recomendado) Perfis e proxies via API REST

O Cloud Browser é a camada de execução. Para gerenciar perfis (criar/atualizar) e configurar proxies, use a API REST:

* API de perfis: [https://gologin.com/docs/api-reference/profile](https://gologin.com/docs/api-reference/profile)
* API de proxies: [https://gologin.com/docs/api-reference/proxy](https://gologin.com/docs/api-reference/proxy)

> **Importante:** se um perfil tiver um proxy mal configurado ou inacessível, a sessão do Cloud Browser não será iniciada e retornará um erro de timeout do proxy. Verifique se o proxy está acessível antes de conectar ou defina o modo de proxy como `none` para testes.

## Duas URLs: entenda a diferença

O Gologin disponibiliza duas URLs diferentes para o Cloud Browser. Elas têm finalidades distintas:

| URL | Finalidade | Usar para |
| - | - | - |
| `https://cloudbrowser.gologin.com/connect?token=...&profile=...` | Endpoint CDP | Automação com Puppeteer/Playwright |
| `https://cloudbrowser.gologin.com/browsers/{profileId}/{sessionId}/` | Interface web de streaming (Live View) | Somente depuração visual |

**Somente o endpoint `/connect` funciona com Puppeteer/Playwright.** A URL do Live View retorna uma interface HTML de streaming e não pode ser usada como `browserWSEndpoint`.

## Conectando a uma sessão na nuvem

Use o endpoint canônico do Cloud Browser:

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

* `token` — seu token de API do Gologin
* `profile` — ID do perfil (opcional)
  * Use `profileId` quando quiser sessões persistentes e configuração controlada
  * Se `profile` for omitido, um novo perfil poderá ser criado para a sessão

O endpoint `/connect` inicia a sessão do navegador automaticamente, sem necessidade de uma chamada de API separada antes de conectar.

Exemplos de implementação (Puppeteer/Playwright):
[https://gologin.com/docs/api-reference/cloud-browser/getting-started](https://gologin.com/docs/api-reference/cloud-browser/getting-started.md)

## Ferramentas CLI prontas vs. ferramentas personalizadas

Você tem duas opções para dar acesso ao navegador aos agentes:

### Opção A: usar as ferramentas CLI do Gologin (recomendada para a maioria dos casos)

* **[Agent Browser CLI](https://gologin.com/docs/pt/cli-tools/agent-browser.md)** — CLI pronta com `open`, `snapshot`, `click`, `type`, `fill`, `screenshot`, `close` e mais de 30 outros comandos. Inclui um daemon persistente, interação baseada em referências e saída compacta, projetada para loops de agentes.
* **[Web Access CLI](https://gologin.com/docs/pt/cli-tools/web-access.md)** — CLI unificada que combina scraping (Web Unlocker) e interação com o navegador em uma única ferramenta.
* **[AI Skills](https://gologin.com/docs/pt/api-reference/ai-integrations/ai-skills.md)** — skills plug-and-play para o Claude Code que cuidam de tudo automaticamente.

### Opção B: criar ferramentas personalizadas com Puppeteer/Playwright

Se você precisa de controle total, implemente um pequeno conjunto de wrappers em torno do Playwright/Puppeteer e exponha-os como ferramentas.

Geralmente, um conjunto mínimo é suficiente:

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

Essas não são APIs especiais do Gologin: são wrappers simples em torno de comandos padrão do Playwright/Puppeteer, executados em uma sessão do Cloud Browser.

## Fundamental: gerenciamento de sessão entre chamadas de ferramentas

Este é o ponto de arquitetura mais importante para fluxos de trabalho de agentes.

Um agente de IA chama ferramentas sequencialmente ao longo de várias etapas. Cada chamada de ferramenta deve reutilizar **a mesma conexão de navegador**. Se você criar um novo `puppeteer.connect()` a cada chamada, perderá cookies, local storage e o estado da página entre as etapas.

**Padrão recomendado:** mantenha um singleton de sessão no seu servidor de ferramentas.

```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 };
```

Cada ferramenta então chama `getSession()` para obter a instância compartilhada:

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

## O que as ferramentas devem devolver ao agente?

Devolva resultados pequenos e estruturados para que o agente possa continuar de forma confiável, por exemplo:

* URL atual
* texto extraído / JSON
* se um elemento foi encontrado
* referência de screenshot (se você a armazenar)
* tipo de erro (timeout, erro de navegação etc.)

## Observações operacionais

* **Segurança:** mantenha o token no lado do servidor; nunca o incorpore em aplicativos cliente.
* **Gerenciamento de sessão:** feche as sessões ao terminar para evitar atingir os limites de concorrência. Chame `closeSession()` quando o fluxo de trabalho do agente for concluído.
* **Confiabilidade:** adicione novas tentativas/backoff para falhas transitórias (timeouts, erros de navegação).
* **Observabilidade:** para depuração, você pode abrir o Live View quando estiver disponível. Exemplo de formato de URL:
  `https://cloudbrowser.gologin.com/browsers/{profileId}/{sessionId-or-view-token}/`

## Limitações

* Os resultados dependem do site de destino e da sua configuração.
* Sites podem bloquear a automação; o Cloud Browser é um ambiente de execução, não uma garantia.
* Conectar ao mesmo perfil a partir de várias sessões simultâneas pode causar conflitos. Use uma conexão por perfil por vez.
* Aplicam-se cotas e limites de taxa:
  [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.