AIエージェントでCloud Browserを使う

• JavaScriptのレンダリングと、実際のユーザー操作(クリック、スクロール、フォーム入力)
• プロファイルによる永続的なセッション(Cookie/ストレージ)
• プロキシ経由の接続と、再現性のあるブラウザ設定

注意: このページでは、技術的な連携パターンを説明しています。対象サイトのルールを変更するものではなく、アクセスを保証するものでもありません。

​

連携パターンの概要

1. 次に何をするかを計画する
2. お客様が公開したツール/関数を呼び出す(ツール呼び出し)
3. 構造化された結果を読み取り、処理を続ける

1. クラウドセッションに接続する(トークン+任意のプロファイル)
2. ブラウザ操作を実行する(ページ移動、クリック、データ抽出、スクリーンショット)
3. 構造化された結果をエージェントに返す

​

推奨アーキテクチャ

• 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に設定してください。

​

2種類のURLの違い

​

クラウドセッションへの接続

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

• token — Gologin APIトークン
• profile — プロファイルID(任意)
  • 永続的なセッションや管理された設定が必要な場合は、profileIdを指定します
  • profileを省略すると、セッション用に新しいプロファイルが作成される場合があります

​

既製のCLIツールとカスタムツール

​

オプションA: GologinのCLIツールを使う(ほとんどの場合に推奨)

• Agent Browser CLI — open、snapshot、click、type、fill、screenshot、closeに加え、さらに30以上のコマンドを備えた既製のCLIです。永続デーモン、参照(ref)ベースの操作、エージェントのループ向けに設計されたコンパクトな出力を備えています。
• Web Access CLI — スクレイピング(Web Unlocker)とブラウザ操作を1つにまとめた統合CLIです。
• 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) };
}

​

ツールがエージェントに返すべき内容

• 現在のURL
• 抽出したテキスト/JSON
• 要素が見つかったかどうか
• スクリーンショットの参照(保存している場合)
• エラーの種類(タイムアウト、ナビゲーションエラーなど)

​

運用上の注意

• セキュリティ: トークンはサーバー側に保持し、クライアントアプリには決して埋め込まないでください。
• セッション管理: 同時接続数の上限に達しないよう、使い終わったセッションは閉じてください。エージェントのワークフローが完了したらcloseSession()を呼び出します。
• 信頼性: 一時的な障害(タイムアウト、ナビゲーションエラー)に備えて、リトライやバックオフを追加してください。
• 可観測性: デバッグ時には、利用可能であればLive Viewを開けます。URLの形式の例: https://cloudbrowser.gologin.com/browsers/{profileId}/{sessionId-or-view-token}/

​

制限事項

• 結果は対象サイトやお客様の設定によって異なります。
• サイトによっては自動化がブロックされる場合があります。Cloud Browserはあくまで実行環境であり、アクセスを保証するものではありません。
• 同じプロファイルに複数のセッションから同時に接続すると、競合が発生する場合があります。1つのプロファイルにつき、同時に使う接続は1つにしてください。
• クォータとレート制限が適用されます: https://gologin.com/docs/api-reference/limitations/rate-limits