Browser-Use Automation スキル

Browser-Use を使用したブラウザーオートメーションの専門家です。Browser-Use は、永続的で複数セッション対応のブラウザーオートメーション向けに設計された強力な CLI ツールです。ユーザーが複雑なブラウザーワークフローの自動化、セッション管理、または長期実行オートメーションタスクの実行をお願いする場合は、以下の詳細な指示に従ってください。

コア原則

1. 永続的なセッション -- 複数のオートメーション実行全体でブラウザーの状態を維持します。
2. 複数セッション対応 -- 複数の独立したブラウザーセッションを並列で実行します。
3. 柔軟なブラウザーモード -- Chromium（ヘッドレス）、Real（ヘッド付き）、Remote ブラウザーインスタンスに対応します。
4. Cookie 管理 -- 認証の永続化のために Cookie をエクスポート、インポート、管理します。
5. JavaScript 実行 -- ページコンテキストでカスタム JavaScript を実行して高度なオートメーションを実現します。

インストール

# npm でインストール
npm install -g browser-use

# または npx で使用
npx browser-use --version

# Python でインストール
pip install browser-use

# インストールを確認
browser-use --help

ブラウザーモード

Chromium モード（デフォルトヘッドレス）

# Chromium をヘッドレスモードで起動
browser-use start --mode chromium --headless

# カスタムユーザーデータディレクトリ指定
browser-use start --mode chromium --user-data-dir ./browser-data

# カスタムビューポート指定
browser-use start --mode chromium --viewport 1920x1080

Real ブラウザーモード（ヘッド付き）

# 表示される Chrome ブラウザーを起動
browser-use start --mode real --browser chrome

# Firefox を起動
browser-use start --mode real --browser firefox

# 特定のプロフィール指定
browser-use start --mode real --browser chrome --profile "Profile 1"

リモートブラウザーモード

# リモート Chrome DevTools Protocol に接続
browser-use start --mode remote --cdp-url ws://localhost:9222

# Selenium Grid に接続
browser-use start --mode remote --selenium-url http://localhost:4444/wd/hub

セッション管理

セッションの作成と管理

# 名前付きセッションを作成
browser-use session create --name "user-session-1" --persist

# すべてのセッションをリストアップ
browser-use session list

# 既存セッションに接続
browser-use session attach --name "user-session-1"

# セッションを削除
browser-use session delete --name "user-session-1"

# セッション状態をエクスポート
browser-use session export --name "user-session-1" --output ./session-state.json

# セッション状態をインポート
browser-use session import --input ./session-state.json --name "restored-session"

セッションリスト出力:

{
  "sessions": [
    {
      "name": "user-session-1",
      "id": "abc123",
      "created": "2024-02-12T10:00:00Z",
      "lastActive": "2024-02-12T10:30:00Z",
      "persistent": true,
      "tabs": 3
    },
    {
      "name": "test-session-2",
      "id": "def456",
      "created": "2024-02-12T11:00:00Z",
      "lastActive": "2024-02-12T11:15:00Z",
      "persistent": false,
      "tabs": 1
    }
  ]
}

複数セッション並列実行

# 複数セッションを並列で実行
browser-use parallel --sessions "session-1,session-2,session-3" \
  --command "navigate --url https://example.com"

# セッションごとに異なるコマンドを実行
browser-use parallel \
  --session session-1 --command "navigate --url https://site1.com" \
  --session session-2 --command "navigate --url https://site2.com" \
  --session session-3 --command "navigate --url https://site3.com"

Cookie 管理

Cookie のエクスポートとインポート

# セッションから Cookie をエクスポート
browser-use cookies export --session "user-session-1" --output cookies.json

# 特定ドメインの Cookie をエクスポート
browser-use cookies export --session "user-session-1" --domain "example.com" --output example-cookies.json

# Cookie をセッションにインポート
browser-use cookies import --session "user-session-1" --input cookies.json

# 特定ドメインの Cookie をインポート
browser-use cookies import --session "user-session-1" --input auth-cookies.json --domain "app.example.com"

# すべての Cookie をクリア
browser-use cookies clear --session "user-session-1"

# 特定ドメインの Cookie をクリア
browser-use cookies clear --session "user-session-1" --domain "example.com"

Cookie エクスポート形式:

{
  "cookies": [
    {
      "name": "session_token",
      "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "domain": ".example.com",
      "path": "/",
      "expires": 1707753600,
      "httpOnly": true,
      "secure": true,
      "sameSite": "Lax"
    },
    {
      "name": "user_preferences",
      "value": "theme=dark&lang=en",
      "domain": "app.example.com",
      "path": "/",
      "expires": 1739289600,
      "httpOnly": false,
      "secure": true,
      "sameSite": "Strict"
    }
  ]
}

Cookie ベースの認証永続化

#!/bin/bash
# auth-persist.sh - 1 回ログインして、セッションを再利用

SESSION_NAME="authenticated-user"

# セッションが存在するかチェック
if browser-use session list | grep -q "$SESSION_NAME"; then
  echo "Using existing authenticated session"
  browser-use session attach --name "$SESSION_NAME"
else
  echo "Creating new authenticated session"
  browser-use session create --name "$SESSION_NAME" --persist

  # ログインを実行
  browser-use navigate --url "https://app.example.com/login"
  browser-use type --selector "#email" --text "user@example.com"
  browser-use type --selector "#password" --text "$PASSWORD"
  browser-use click --selector "button[type='submit']"
  browser-use wait --selector ".dashboard" --timeout 10000

  # バックアップ用に Cookie をエクスポート
  browser-use cookies export --session "$SESSION_NAME" --output auth-cookies.json
  echo "Session authenticated and cookies saved"
fi

# 認証済みセッションを使用
browser-use navigate --url "https://app.example.com/dashboard"

JavaScript 実行

ページコンテキストで JavaScript を実行

# シンプルな JavaScript を実行
browser-use execute --script "return document.title"

# 引数付きで実行
browser-use execute --script "return arguments[0] + arguments[1]" --args "[5, 10]"

# 結果を保存して実行
browser-use execute --script "return document.querySelectorAll('.item').length" --output item-count.json

# ファイルからスクリプトを実行
browser-use execute --script-file ./custom-script.js

スクリプトファイルの例（custom-script.js）:

// ページからすべての商品データを抽出
const products = Array.from(document.querySelectorAll('.product-card')).map(card => {
  return {
    name: card.querySelector('.product-name')?.textContent.trim(),
    price: card.querySelector('.product-price')?.textContent.trim(),
    image: card.querySelector('.product-image')?.src,
    rating: card.querySelector('.rating')?.getAttribute('data-rating'),
    available: !card.querySelector('.out-of-stock')
  };
});

return { products, total: products.length };

# スクリプトを実行
browser-use execute --script-file ./extract-products.js --output products.json

高度な JavaScript パターン

# カスタム条件で動的コンテンツを待機
browser-use execute --script "
  return new Promise(resolve => {
    const check = () => {
      if (document.querySelectorAll('.loaded-item').length >= 10) {
        resolve(true);
      } else {
        setTimeout(check, 100);
      }
    };
    check();
  });
"

# ページ要素を操作
browser-use execute --script "
  document.querySelectorAll('.annoying-popup').forEach(el => el.remove());
  document.body.style.backgroundColor = '#f0f0f0';
  return 'Page modified';
"

# イベントをトリガー
browser-use execute --script "
  const event = new Event('custom-event');
  document.dispatchEvent(event);
  return 'Event triggered';
"

ナビゲーションとページ操作

高度なナビゲーション

# カスタムヘッダー付きでナビゲート
browser-use navigate --url "https://api.example.com" \
  --headers '{"Authorization": "Bearer token123", "X-Custom": "value"}'

# POST データ付きでナビゲート
browser-use navigate --url "https://example.com/search" \
  --method POST \
  --data '{"query": "automation", "filters": ["category:tools"]}'

# リファラー付きでナビゲート
browser-use navigate --url "https://example.com/protected" \
  --referer "https://example.com/home"

# 特定イベント待機でナビゲート
browser-use navigate --url "https://example.com" \
  --wait-for-event "load"

ページ操作コマンド

# 要素までスクロール
browser-use scroll --selector ".footer" --behavior smooth

# ピクセル数でスクロール
browser-use scroll --delta "0,500"

# トップ/ボトムにスクロール
browser-use scroll --position top
browser-use scroll --position bottom

# 要素の上にマウスを移動
browser-use hover --selector ".dropdown-trigger"

# 要素にフォーカス
browser-use focus --selector "input#search"

# ドロップダウンオプションを選択
browser-use select --selector "select#country" --value "US"

# ファイルをアップロード
browser-use upload --selector "input[type='file']" --file ./document.pdf

# ファイルをダウンロード
browser-use download --url "https://example.com/file.pdf" --output ./downloaded.pdf

タブ管理

複数タブ操作

# 新規タブを開く
browser-use tab new --url "https://example.com"

# すべてのタブをリストアップ
browser-use tab list

# インデックスでタブを切り替え
browser-use tab switch --index 0

# URL パターンでタブを切り替え
browser-use tab switch --url-pattern "example.com"

# タブを閉じる
browser-use tab close --index 1

# 現在のタブ以外を閉じる
browser-use tab close --others

# タブを複製
browser-use tab duplicate --index 0

タブリスト出力:

{
  "tabs": [
    {
      "index": 0,
      "url": "https://example.com",
      "title": "Example Domain",
      "active": true
    },
    {
      "index": 1,
      "url": "https://google.com",
      "title": "Google",
      "active": false
    }
  ],
  "total": 2
}

ネットワークモニタリングとインターセプション

ネットワークリクエストをモニタリング

# ネットワークモニタリングを開始
browser-use network start --filter "*.json"

# ナビゲートしてリクエストをキャプチャ
browser-use navigate --url "https://api.example.com"

# ネットワークログを取得
browser-use network log --output network-requests.json

# モニタリングを停止
browser-use network stop

ネットワークログ形式:

{
  "requests": [
    {
      "url": "https://api.example.com/users",
      "method": "GET",
      "status": 200,
      "responseTime": 234,
      "size": 1024,
      "timestamp": "2024-02-12T10:30:00Z"
    }
  ]
}

リクエストインターセプション

# リクエストをインターセプトして修正
browser-use intercept --pattern "*/api/*" \
  --modify-headers '{"X-Custom-Header": "value"}' \
  --modify-response-status 200

# 特定のリクエストをブロック
browser-use intercept --pattern "*.jpg" --block

# API レスポンスをモック
browser-use intercept --pattern "*/api/users" \
  --mock-response ./mock-users.json

TypeScript/JavaScript インテグレーション

import { BrowserUse } from 'browser-use';

interface BrowserUseConfig {
  mode: 'chromium' | 'real' | 'remote';
  headless?: boolean;
  viewport?: { width: number; height: number };
  userDataDir?: string;
}

class BrowserAutomation {
  private browser: BrowserUse;
  private sessionName: string;

  constructor(sessionName: string, config: BrowserUseConfig = { mode: 'chromium' }) {
    this.sessionName = sessionName;
    this.browser = new BrowserUse(config);
  }

  async start(): Promise<void> {
    await this.browser.session.create({
      name: this.sessionName,
      persist: true,
    });
  }

  async navigate(url: string, options?: { waitUntil?: string }): Promise<void> {
    await this.browser.navigate({ url, ...options });
  }

  async executeScript<T>(script: string | Function, args: any[] = []): Promise<T> {
    const scriptStr = typeof script === 'function' ? script.toString() : script;
    const result = await this.browser.execute({
      script: scriptStr,
      args,
    });
    return result.value as T;
  }

  async saveAuthCookies(filepath: string): Promise<void> {
    await this.browser.cookies.export({
      session: this.sessionName,
      output: filepath,
    });
  }

  async loadAuthCookies(filepath: string): Promise<void> {
    await this.browser.cookies.import({
      session: this.sessionName,
      input: filepath,
    });
  }

  async cleanup(): Promise<void> {
    await this.browser.session.delete({ name: this.sessionName });
  }
}

// 使用例
async function automateWorkflow() {
  const automation = new BrowserAutomation('my-workflow-session');

  try {
    await automation.start();

    // 保存済みの認証 Cookie があるかチェック
    const cookiesExist = await fs.promises.access('./auth-cookies.json')
      .then(() => true)
      .catch(() => false);

    if (cookiesExist) {
      // 認証済みセッションを復元
      await automation.loadAuthCookies('./auth-cookies.json');
      await automation.navigate('https://app.example.com/dashboard');
    } else {
      // 新規ログインを実行
      await automation.navigate('https://app.example.com/login');
      // ... ログインステップ ...
      await automation.saveAuthCookies('./auth-cookies.json');
    }

    // カスタム JavaScript を実行
    const itemCount = await automation.executeScript<number>(() => {
      return document.querySelectorAll('.item').length;
    });

    console.log(`Found ${itemCount} items on page`);

  } finally {
    await automation.cleanup();
  }
}

Python インテグレーション

import json
from browser_use import BrowserUse

class BrowserAutomation:
    def __init__(self, session_name: str, mode: str = "chromium", headless: bool = True):
        self.session_name = session_name
        self.browser = BrowserUse(mode=mode, headless=headless)

    def start(self):
        self.browser.session.create(name=self.session_name, persist=True)

    def navigate(self, url: str, wait_until: str = "load"):
        self.browser.navigate(url=url, wait_until=wait_until)

    def execute_script(self, script: str, *args):
        return self.browser.execute(script=script, args=list(args))

    def save_cookies(self, filepath: str):
        self.browser.cookies.export(session=self.session_name, output=filepath)

    def load_cookies(self, filepath: str):
        self.browser.cookies.import_(session=self.session_name, input=filepath)

    def cleanup(self):
        self.browser.session.delete(name=self.session_name)

# 使用例
def main():
    automation = BrowserAutomation("my-session")

    try:
        automation.start()

        # セッション復元を試行
        try:
            automation.load_cookies("auth-cookies.json")
            automation.navigate("https://app.example.com/dashboard")
            print("Restored authenticated session")
        except FileNotFoundError:
            # 新規ログイン
            automation.navigate("https://app.example.com/login")
            # ... ログイン実行 ...
            automation.save_cookies("auth-cookies.json")
            print("New session authenticated")

        # JavaScript でデータを抽出
        data = automation.execute_script("""
            return Array.from(document.querySelectorAll('.data-item')).map(el => ({
                id: el.dataset.id,
                text: el.textContent.trim()
            }));
        """)

        print(f"Extracted {len(data)} items")

    finally:
        automation.cleanup()

if __name__ == "__main__":
    main()

高度なパターン

長期実行モニタリング

#!/bin/bash
# monitor-site.sh - 継続的なサイトモニタリング

SESSION="monitor-session"
INTERVAL=300  # 5分

browser-use session create --name "$SESSION" --persist
browser-use navigate --url "https://status.example.com"

while true; do
  # モニタリングスクリプトを実行
  STATUS=$(browser-use execute --script "
    const statusEl = document.querySelector('.status-indicator');
    return {
      status: statusEl.textContent,
      color: getComputedStyle(statusEl).backgroundColor,
      timestamp: new Date().toISOString()
    };
  ")

  echo "$(date): $STATUS" >> monitor.log

  # 障害をチェック
  if echo "$STATUS" | grep -q "down"; then
    browser-use snapshot --output "failure-$(date +%s).png"
    # アラートを送信
    curl -X POST https://alerts.example.com/notify -d "$STATUS"
  fi

  sleep $INTERVAL
  browser-use execute --script "location.reload()"
done

並列セッション処理

async function processMultipleAccounts(accounts: Array<{ email: string; password: string }>) {
  const sessions = await Promise.all(
    accounts.map(async (account, index) => {
      const sessionName = `account-${index}`;
      const browser = new BrowserAutomation(sessionName);

      await browser.start();
      await browser.navigate('https://app.example.com/login');

      // 各アカウントでログイン
      await browser.executeScript((email: string, password: string) => {
        (document.querySelector('#email') as HTMLInputElement).value = email;
        (document.querySelector('#password') as HTMLInputElement).value = password;
        (document.querySelector('button[type="submit"]') as HTMLButtonElement).click();
      }, account.email, account.password);

      // ダッシュボード待機
      await new Promise(resolve => setTimeout(resolve, 3000));

      // セッション保存
      await browser.saveAuthCookies(`./cookies-${index}.json`);

      return browser;
    })
  );

  return sessions;
}

ベストプラクティス

1. 永続的なセッションを使用 -- 認証状態が必要なワークフローに用います。
2. 定期的に Cookie をエクスポート -- セッション障害からの復旧に備えます。
3. セッションを説明的に命名 -- セッション一覧表示時に目的を特定しやすくします。
4. 完了後にセッションをクリーンアップ -- リソースリークを防ぎます。
5. JavaScript 実行を活用 -- CLI コマンドでは処理できない複雑なデータ抽出に用います。
6. ネットワークリクエストをモニタリング -- API インタラクションを確認して問題をトラブルシューティングします。
7. リトライロジックを実装 -- 長期実行オートメーションで一時的な障害に対応します。
8. 複数セッション並列処理を活用 -- 複数アカウントやサイトを同時に処理します。
9. セッション状態を検証 -- クリティカルな操作前に認証が永続しているか確認します。
10. セッション要件をドキュメント化 -- 各オートメーションワークフローの要件を文書化します。

回避すべきアンチパターン

1. セッションをクリーンアップしない -- リソースの枯渇につながります。
2. 認証情報をハードコード -- 環境変数またはセキュアボルトを使用します。
3. セッション期限満了を無視 -- Cookie リフレッシュまたは再認証を実装します。
4. 遅延過多への依存 -- 固定時間スリープの代わりにイベントベースの待機を使用します。
5. 並列タスク用に単一セッション使用 -- レースコンディションと状態競合が発生します。
6. Cookie をバックアップしない -- セッション損失時に再認証が必要になります。
7. ネットワークエラーを無視 -- 適切なエラーハンドリングとリトライを実装します。
8. セッションコンテキストを混合 -- セッションを独立させて状態漏洩を防ぎます。
9. JavaScript 結果を検証しない -- 常に戻り値を期待される構造で確認します。
10. 並列セッションを多数実行 -- システムリソースとレート制限を尊重します。

デバッグとトラブルシューティング

デバッグモードを有効化

# 詳細ロギング
browser-use --debug navigate --url "https://example.com"

# コンソール出力を保存
browser-use --console-output ./console.log navigate --url "https://example.com"

# エラー時にスクリーンショット
browser-use --screenshot-on-error ./errors/ navigate --url "https://example.com"

# DevTools を表示
browser-use start --mode real --devtools

セッション復旧

# セッションヘルスをチェック
browser-use session health --name "my-session"

# 破損したセッションを復旧
browser-use session recover --name "my-session" --backup ./session-backup.json

# スタックしたセッションを強制削除
browser-use session delete --name "my-session" --force

CI/CD インテグレーション

# .github/workflows/browser-automation.yml
name: Browser Automation Tests

on: [push, pull_request]

jobs:
  automation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install browser-use
        run: npm install -g browser-use

      - name: Run automation tests
        env:
          APP_PASSWORD: ${{ secrets.APP_PASSWORD }}
        run: |
          browser-use session create --name ci-session
          bash ./automation-script.sh
          browser-use session delete --name ci-session

      - name: Upload artifacts
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: failure-screenshots
          path: ./screenshots/

このスキルは、セッション管理と強力な永続的ブラウザーオートメーションを実現し、長期実行ワークフロー、認証が必要なアプリケーション、AI エージェントがオーケストレーションする必要のある複雑な複数ステップのオートメーションに理想的です。