Usando o Cloud Browser com agentes de IA

• 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

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

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

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

• 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)

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

• API de perfis: https://gologin.com/docs/api-reference/profile
• API de proxies: 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

​

Conectando a uma sessão na nuvem

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

​

Ferramentas CLI prontas vs. ferramentas personalizadas

​

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

• Agent Browser CLI — 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 — CLI unificada que combina scraping (Web Unlocker) e interação com o navegador em uma única ferramenta.
• AI Skills — skills plug-and-play para o Claude Code que cuidam de tudo automaticamente.

​

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

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

​

Fundamental: gerenciamento de sessão entre chamadas de ferramentas

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

​

O que as ferramentas devem devolver ao agente?

• 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