Saltar para o conteúdo principal
O Gologin Cloud Browser pode ser usado como um ambiente de execução remoto de navegador 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
Não quer escrever as ferramentas do zero? Use o Agent Browser CLI ou as AI Skills para obter recursos de agente prontos para uso, 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

Os agentes de IA normalmente não “se conectam a um navegador” diretamente. Em vez disso, eles:
  1. planejam o que fazer a seguir
  2. chamam as ferramentas/funções que você disponibiliza (tool calling)
  3. leem os resultados estruturados e continuam
Com o Gologin Cloud Browser, 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, capturar tela)
  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 captura de tela) ao agente Por que usar esse padrão:
  • seu token do Gologin permanece no servidor
  • você pode aplicar limites de taxa, novas tentativas, registros de log e verificações de segurança
  • você pode reutilizar perfis e proxies de forma consistente

Pré-requisitos

1) Token de API (no servidor)

Crie seu token no app do Gologin: API & MCP → API → Novo Token.
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:
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 tempo limite do proxy. Verifique se o seu 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: Apenas 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:
  • 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

Ferramentas de CLI prontas vs. ferramentas personalizadas

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

Opção A: usar as ferramentas de CLI do Gologin (recomendado na maioria dos casos)

  • Agent Browser CLI: CLI pronta para uso 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, pensada 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

Se você precisa de controle total, implemente um pequeno conjunto de wrappers em torno do Playwright/Puppeteer e exponha-os como ferramentas. Um conjunto mínimo normalmente é 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.

Crítico: 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, armazenamento local e o estado da página entre as etapas. Padrão recomendado: mantenha uma sessão singleton no seu servidor de ferramentas.
Cada ferramenta então chama getSession() para obter a instância compartilhada:

O que as ferramentas devem retornar ao agente?

Retorne resultados pequenos e estruturados para que o agente possa continuar com segurança, por exemplo:
  • URL atual
  • texto extraído / JSON
  • se um elemento foi encontrado
  • referência da captura de tela (se você a armazenar)
  • tipo de erro (tempo limite, erro de navegação etc.)

Observações operacionais

  • Segurança: mantenha o token no servidor; nunca o incorpore em aplicativos do lado do cliente.
  • Gerenciamento de sessões: 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 com backoff para falhas transitórias (tempos limite, 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.
  • Os sites podem bloquear automação; o Cloud Browser é um ambiente de execução, não uma garantia.
  • Conectar-se ao mesmo perfil a partir de várias sessões simultâneas pode causar conflitos. Use uma conexão por perfil de cada vez.
  • Aplicam-se cotas e limites de taxa: https://gologin.com/docs/api-reference/limitations/rate-limits