- JavaScriptのレンダリングや、実際のユーザー操作(クリック、スクロール、フォーム入力)
- プロファイルによる永続的なセッション(Cookie/ストレージ)
- プロキシ経由の通信と、再現性のあるブラウザ設定
注: このページでは、技術的な連携パターンについて説明しています。対象ウェブサイトのルールを変更するものではなく、アクセスを保証するものでもありません。
連携パターンの概要
AIエージェントは通常、ブラウザに「直接接続」するわけではありません。代わりに、次の流れで動作します。- 次に行うことを計画する
- お客様が公開したツール/関数を呼び出す(ツール呼び出し)
- 構造化された結果を読み取り、処理を続ける
- クラウドセッションに接続する(トークン+任意のプロファイル)
- ブラウザ操作を実行する(ページ遷移、クリック、抽出、スクリーンショット)
- 構造化された結果をエージェントに返す
推奨アーキテクチャ
AIエージェント(Claude / Codex / その他) -> お客様のツールサーバー(Node/Pythonサービス)を呼び出す -> ツールサーバーがPlaywright/Puppeteerを使用する -> Gologin Cloud Browser(リモートエンドポイント)に接続する -> 結果(テキスト/JSON/スクリーンショットの参照)をエージェントに返す このパターンを採用する理由:- Gologinのトークンをサーバー側だけで管理できる
- レート制限、リトライ、ログ記録、安全性チェックを適用できる
- プロファイルとプロキシを一貫して再利用できる
前提条件
1) APIトークン(サーバー側)
Gologinアプリでトークンを作成します: API & MCP → API → 新しいトークン。トークンは機密情報として扱ってください。クライアント側のコードで公開しないでください。
2)(推奨)REST APIによるプロファイルとプロキシの管理
Cloud Browserは実行(ランタイム)層です。プロファイルの管理(作成/更新)やプロキシの設定には、REST APIを使用します。- Profiles API: https://gologin.com/docs/api-reference/profile
- Proxy API: https://gologin.com/docs/api-reference/proxy
重要: プロファイルのプロキシ設定に誤りがある場合や、プロキシに到達できない場合、クラウドブラウザのセッションはプロキシのタイムアウトエラーで起動に失敗します。接続する前にプロキシに到達できることを確認するか、テスト時はプロキシモードを none に設定してください。
2種類のURLの違い
Gologinは、Cloud Browser用に2種類のURLを提供しています。それぞれ用途が異なります。
Puppeteer/Playwrightで使えるのは
/connect エンドポイントだけです。 ライブビューのURLはHTMLのストリーミングインターフェースを返すため、browserWSEndpoint として使用することはできません。
クラウドセッションへの接続
Cloud Browserの標準エンドポイントを使用します。token— GologinのAPIトークンprofile— プロファイルID(任意)- 永続的なセッションや制御された設定が必要な場合は、
profileIdを指定します profileを省略すると、セッション用に新しいプロファイルが作成されることがあります
- 永続的なセッションや制御された設定が必要な場合は、
/connect エンドポイントはブラウザセッションを自動的に開始します。接続前に別途APIを呼び出す必要はありません。
実装例(Puppeteer/Playwright):
https://gologin.com/docs/api-reference/cloud-browser/getting-started
既製のCLIツールとカスタムツールの比較
エージェントにブラウザへのアクセス手段を与える方法は2つあります。オプション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でカスタムツールを作成する
完全な制御が必要な場合は、Playwright/Puppeteerを包む小さなラッパーをいくつか実装し、ツールとして公開します。 通常は、次の最小構成で十分です。open_url(url)click(selector)type(selector, text)wait_for(selector | timeout)extract_text(selector | page)screenshot()close_session()
重要: ツール呼び出し間のセッション管理
これは、エージェントのワークフローにおいて最も重要な設計上の課題です。 AIエージェントは、複数のステップにわたって順番にツールを呼び出します。各ツール呼び出しでは同じブラウザ接続を再利用する必要があります。ツールを呼び出すたびに新しくpuppeteer.connect() を実行すると、ステップ間でCookie、ローカルストレージ、ページの状態が失われます。
推奨パターン: ツールサーバー上でセッションのシングルトンを保持します。
getSession() を呼び出して、共有インスタンスを取得します。
ツールがエージェントに返すべき内容
エージェントが確実に処理を続けられるよう、小さく構造化された結果を返してください。例:- 現在のURL
- 抽出したテキスト/JSON
- 要素が見つかったかどうか
- スクリーンショットの参照(保存している場合)
- エラーの種類(タイムアウト、ナビゲーションエラーなど)
運用上の注意点
- セキュリティ: トークンはサーバー側で管理し、クライアントアプリには決して埋め込まないでください。
- セッション管理: 同時接続数の上限に達しないよう、使い終わったセッションは閉じてください。エージェントのワークフローが完了したら
closeSession()を呼び出します。 - 信頼性: 一時的な障害(タイムアウト、ナビゲーションエラー)に備えて、リトライやバックオフを追加してください。
- 可観測性: デバッグ時は、利用可能であればライブビューを開けます。URLの形式の例:
https://cloudbrowser.gologin.com/browsers/{profileId}/{sessionId-or-view-token}/
制限事項
- 結果は、対象ウェブサイトやお客様の設定によって異なります。
- ウェブサイトによっては自動化をブロックする場合があります。Cloud Browserは実行環境であり、アクセスを保証するものではありません。
- 同じプロファイルに複数のセッションから同時に接続すると、競合が発生する場合があります。1つのプロファイルにつき、同時に1つの接続のみを使用してください。
- クォータとレート制限が適用されます: https://gologin.com/docs/api-reference/limitations/rate-limits