> ## Documentation Index
> Fetch the complete documentation index at: https://gologin.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Puppeteer/Playwrightを使って、Gologin Cloud BrowserをAIエージェント向けのリモートブラウザ実行環境として利用する方法

Gologin Cloud Browserは、AIエージェント向けの**リモートブラウザ実行環境**として利用できます。
エージェント(Claude、Codex、その他のツール呼び出し対応エージェント)は、お客様のコードを介してCloud Browserセッションに接続し、ページ移動、クリック、入力、データ抽出といった実際のブラウザ操作を行えます。

これにより、次のようなエージェントのワークフローが可能になります。

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

> [!TIP]
>
> **ツールを一から作りたくない場合は、** [Agent Browser CLI](https://gologin.com/docs/ja/cli-tools/agent-browser.md)または[AI Skills](https://gologin.com/docs/ja/api-reference/ai-integrations/ai-skills.md)をご利用ください。すぐに使えるエージェント機能が揃っており、Puppeteer/Playwrightのコードは不要です。

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

## 連携パターンの概要

AIエージェントは通常、ブラウザに直接「接続」することはありません。代わりに、次の流れで動作します。

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

Gologin Cloud Browserを使う場合、お客様のツール/関数が行う処理は次のとおりです。

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

## 推奨アーキテクチャ

**AIエージェント(Claude / Codex / その他)**
-> お客様の**ツールサーバー**(Node/Pythonサービス)を呼び出す
-> ツールサーバーが**Playwright/Puppeteer**を使用する
-> **Gologin Cloud Browser**(リモートエンドポイント)に接続する
-> 結果(テキスト/JSON/スクリーンショットの参照)をエージェントに返す

このパターンを使う理由:

* Gologinトークンをサーバー側に保持できる
* レート制限、リトライ、ログ記録、安全性チェックを適用できる
* プロファイルとプロキシを一貫して再利用できる

## 前提条件

### 1) APIトークン(サーバー側)

ダッシュボードでトークンを生成します。
`個人エリア -> APIトークン`
[https://app.gologin.com/personalArea/TokenApi](https://app.gologin.com/personalArea/TokenApi)

> トークンは機密情報として扱ってください。クライアント側のコードで公開しないでください。

### 2) (推奨)REST APIによるプロファイルとプロキシの管理

Cloud Browserは実行/ランタイム層です。プロファイルの管理(作成/更新)やプロキシの設定には、REST APIを使用します。

* Profiles API: [https://gologin.com/docs/api-reference/profile](https://gologin.com/docs/api-reference/profile)
* Proxy API: [https://gologin.com/docs/api-reference/proxy](https://gologin.com/docs/api-reference/proxy)

> **重要:** プロファイルのプロキシが誤って設定されている、または到達できない場合、クラウドブラウザのセッションはプロキシのタイムアウトエラーで起動に失敗します。接続する前にプロキシに到達できることを確認するか、テスト時はプロキシモードを`none`に設定してください。

## 2種類のURLの違い

Gologinでは、Cloud Browser向けに2種類のURLを提供しています。用途が異なります。

| URL | 用途 | 使いどころ |
| - | - | - |
| `https://cloudbrowser.gologin.com/connect?token=...&profile=...` | CDPエンドポイント | Puppeteer/Playwrightによる自動化 |
| `https://cloudbrowser.gologin.com/browsers/{profileId}/{sessionId}/` | ストリーミングWeb UI(Live View) | ビジュアルなデバッグ専用 |

**Puppeteer/Playwrightで使えるのは`/connect`エンドポイントのみです。** Live ViewのURLはHTMLのストリーミング画面を返すため、`browserWSEndpoint`として使用できません。

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

標準のCloud Browserエンドポイントを使用します。

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

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

`/connect`エンドポイントはブラウザセッションを自動的に開始します。接続前に別途APIを呼び出す必要はありません。

実装例(Puppeteer/Playwright):
[https://gologin.com/docs/api-reference/cloud-browser/getting-started](https://gologin.com/docs/api-reference/cloud-browser/getting-started.md)

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

エージェントにブラウザへのアクセスを与える方法は2つあります。

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

* **[Agent Browser CLI](https://gologin.com/docs/ja/cli-tools/agent-browser.md)** — `open`、`snapshot`、`click`、`type`、`fill`、`screenshot`、`close`に加え、さらに30以上のコマンドを備えた既製のCLIです。永続デーモン、参照(ref)ベースの操作、エージェントのループ向けに設計されたコンパクトな出力を備えています。
* **[Web Access CLI](https://gologin.com/docs/ja/cli-tools/web-access.md)** — スクレイピング(Web Unlocker)とブラウザ操作を1つにまとめた統合CLIです。
* **[AI Skills](https://gologin.com/docs/ja/api-reference/ai-integrations/ai-skills.md)** — 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()`

これらはGologin独自のAPIではなく、標準のPlaywright/Puppeteerのコマンドを薄くラップしたもので、Cloud Browserセッションに対して実行されます。

## 重要: ツール呼び出し間のセッション管理

エージェントのワークフローにおいて、これは最も重要な設計上のポイントです。

AIエージェントは、複数のステップにわたって順番にツールを呼び出します。各ツール呼び出しでは、**同じブラウザ接続**を再利用する必要があります。ツールを呼び出すたびに新しく`puppeteer.connect()`を実行すると、ステップ間でCookie、ローカルストレージ、ページの状態が失われます。

**推奨パターン:** ツールサーバー上でセッションのシングルトンを保持します。

```js theme={null}
// 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 };
```

各ツールは`getSession()`を呼び出して、共有インスタンスを取得します。

```js theme={null}
// 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](https://gologin.com/docs/api-reference/limitations/rate-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.