在 AI Agent 中使用 Cloud Browser

• 需要 JavaScript 渲染和真实用户交互（点击、滚动、填写表单）
• 通过配置文件实现持久会话（Cookie/存储）
• 代理路由和可重复使用的浏览器配置

注意：本页介绍的是一种技术集成模式，不会改变目标网站的规则，也不保证一定能够访问。

​

集成模式概览

1. 规划下一步要做什么
2. 调用你提供的工具/函数（工具调用）
3. 读取结构化结果并继续执行

1. 连接到云端会话（令牌 + 可选的配置文件）
2. 执行浏览器操作（导航、点击、提取、截图）
3. 将结构化结果返回给 Agent

​

推荐架构

• 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 — 你的 Gologin API 令牌
• profile — 配置文件 ID（可选）
  • 需要持久会话和可控配置时，请使用 profileId
  • 如果省略 profile，可能会为该会话创建一个新的配置文件

​

预置 CLI 工具与自定义工具

​

方案 A：使用 Gologin CLI 工具（大多数情况下推荐）

• Agent Browser CLI — 现成的 CLI，包含 open、snapshot、click、type、fill、screenshot、close 以及 30 多个其他命令。内置常驻守护进程、基于引用的交互方式，以及专为 Agent 循环设计的精简输出。
• 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) };
}

​

工具应向 Agent 返回什么？

• 当前 URL
• 提取的文本 / JSON
• 是否找到了元素
• 截图引用（如果你保存了截图）
• 错误类型（超时、导航错误等）

​

运维说明

• 安全： 令牌只保存在服务器端，切勿嵌入客户端应用。
• 会话管理： 使用完毕后请关闭会话，以免触及并发限制。Agent 工作流完成时，请调用 closeSession()。
• 可靠性： 针对暂时性故障（超时、导航错误）添加重试/退避机制。
• 可观测性： 调试时，可以在可用时打开实时查看。URL 格式示例： https://cloudbrowser.gologin.com/browsers/{profileId}/{sessionId-or-view-token}/

​

限制

• 结果取决于目标网站和你的配置。
• 网站可能会阻止自动化操作；Cloud Browser 只是运行环境，不提供任何保证。
• 多个会话同时连接同一个配置文件可能会产生冲突，请确保每个配置文件同一时间只使用一个连接。
• 适用配额和速率限制： https://gologin.com/docs/api-reference/limitations/rate-limits