kernel-agent-browser

Kernel Cloud Browsers を使用した Agent-Browser

このスキルでは、クラウドブラウザーの自動化に agent-browser の組み込み Kernel プロバイダー（-p kernel）を使用する際のベストプラクティスを説明します。

このスキルを使用する場面

以下が必要な場合に、このスキルを使用してください。

• agent-browser -p kernel コマンドを使用してウェブサイトを自動化する
• 強力なボット対策が施されたサイトでボット検出に対処する
• プロファイルを使用して自動化の実行間でログインセッションを維持する
• クロスオリジンの決済フォームを含むiframe を操作する
• デバッグや手動操作のためにライブビュー URL を取得する
• 高度な Playwright スクリプト作成のために基盤となる Kernel セッション ID を特定する
• 新しいウェブサイト向けにサイト固有の自動化スキルを作成する

参考資料

• サイト固有のスキルの作成 - 特定のウェブサイト向けの自動化スキルを作成するためのガイド

前提条件

Kernel CLI のインストールと認証には、kernel-cli スキルを読み込んでください。

環境変数

最初に agent-browser -p kernel を呼び出す前に、これらの環境変数を設定してください。CLI は呼び出し間で状態を保持します。

変数	説明	デフォルト
KERNEL_API_KEY	必須。 認証用の Kernel API キー	(none)
KERNEL_HEADLESS	ブラウザーをヘッドレスモードで実行します（true/false）	true
KERNEL_STEALTH	ステルスブラウザーを起動します（true/false）	false
KERNEL_TIMEOUT_SECONDS	セッションのタイムアウト秒数	300
KERNEL_PROFILE_NAME	agent-browser 0.33.0 の -p kernel では現在使用できません。以下の CDP 回避策を使用してください	(none)

推奨設定

オプションは明示的に設定してください。agent-browser はプロバイダーセッションの作成時にその値を読み込みます。

export KERNEL_API_KEY="your-api-key"
export KERNEL_TIMEOUT_SECONDS=600     # 10-minute timeout for complex workflows
export KERNEL_HEADLESS=false          # Required when you need a live view
export KERNEL_STEALTH=true            # Opt in for bot-sensitive sites
# Do not set KERNEL_PROFILE_NAME with -p kernel; use the workaround below.

プロファイルの永続化

警告： agent-browser 0.33.0 の -p kernel では KERNEL_PROFILE_NAME は機能しません。Kernel が必要とするオブジェクトではなく、文字列として profile を送信するため、セッションの作成は HTTP 400 で失敗します。また、save_changes も設定されません。プロファイルは事前に作成する必要があります。

上流で修正されるまでは、Kernel CLI でブラウザーを作成し、CDP 経由で agent-browser を接続してください。-p kernel と --cdp を併用しないでください。

PROFILE_NAME=mysite  # Create once with: kernel profiles create --name mysite
kernel profiles get "$PROFILE_NAME" >/dev/null
BROWSER=$(kernel browsers create --profile-name "$PROFILE_NAME" --save-changes --timeout 600 -o json)
SESSION_ID=$(jq -er '.session_id' <<<"$BROWSER")
CDP_URL=$(jq -er '.cdp_ws_url' <<<"$BROWSER")
trap 'kernel browsers delete "$SESSION_ID" >/dev/null 2>&1 || true' EXIT

agent-browser --session mysite --cdp "$CDP_URL" open https://example.com
agent-browser --session mysite snapshot -i
# Run additional commands with --session mysite, then disconnect and end the Kernel session.
agent-browser --session mysite close
kernel browsers delete "$SESSION_ID"
trap - EXIT

CDP_URL を表示したり共有したりしないでください。ブラウザーへのアクセス権が与えられてしまいます。CLI で作成したセッションを削除すると --save-changes が確定されるため、後続のセッションで認証済みプロファイルを再利用できます。

基本的な使い方

agent-browser -p kernel open <url>        # Navigate to page
agent-browser -p kernel snapshot -i       # Get interactive elements with refs
agent-browser -p kernel click @e1         # Click element by ref
agent-browser -p kernel fill @e2 "text"   # Fill input by ref
agent-browser -p kernel close             # Close the provider session

プロバイダー管理のセッションでは、各コマンドで -p kernel を使用してください。プロファイルと CDP の回避策を使用する場合は、同じ --session 名を再利用し、-p kernel を追加しないでください。

セマンティックセレクター（推奨）

ページが読み込まれるたびに変化する一時的な @e 参照の代わりに、find コマンドでセマンティックセレクターを使用すると、より安定して読みやすい自動化を実現できます。

# By ARIA role + accessible name (most stable)
agent-browser -p kernel find role button click --name "Log In"
agent-browser -p kernel find role textbox fill "[email protected]" --name "Email"

# By visible text content
agent-browser -p kernel find text "View Menus" click
agent-browser -p kernel find text "Submit Order" click

# By form label (great for inputs)
agent-browser -p kernel find label "Username" fill "myuser"
agent-browser -p kernel find label "Password" fill "secret123"

# By placeholder text
agent-browser -p kernel find placeholder "Search..." type "query"

# By data-testid (if the site uses them)
agent-browser -p kernel find testid "submit-btn" click

# By position (when needed)
agent-browser -p kernel find first "li.item" click
agent-browser -p kernel find nth 2 ".card" hover

セレクターの使い分け

セレクターの種類	最適な用途	安定性
find role --name	ボタン、リンク、ナビゲーション	⭐⭐⭐ 最も安定
find label	ラベル付きのフォーム入力	⭐⭐⭐ 最も安定
find text	クリック可能なテキスト要素	⭐⭐ 安定
find testid	テスト属性があるサイト	⭐⭐⭐ 最も安定
find placeholder	検索ボックス、入力欄	⭐⭐ 安定
@e refs	不明なサイト、素早い反復作業	⭐ 一時的

推奨： 本番環境での自動化には find を使用してください。探索や素早いプロトタイピングには @e refs を使用し、その後セマンティックセレクターに置き換えてください。

カーネルセッションとライブビューを見つける

agent-browser の CDP エンドポイントをアクティブな Kernel セッションに対応付けます。クエリ文字列を除いた URL を比較してください。同じセッションでも、CLI と agent-browser では有効期間の短い異なる jwt クエリ値が保持される場合があります。エンドポイントのスキーム、ホスト、パスは変わりません。複数のセッションが同じプロファイルを共有している場合、作成時刻から推測するよりもこの方法が確実です。このワークフローには jq が必要です。

CDP_URL="$(agent-browser -p kernel get cdp-url)"
CDP_ENDPOINT="${CDP_URL%%\?*}"
SESSION_ID="$(
  kernel browsers list --status active --limit 100 -o json |
    jq -r --arg endpoint "$CDP_ENDPOINT" \
      '.[] | select((.cdp_ws_url | split("?")[0]) == $endpoint) | .session_id' |
    head -n 1
)"
test -n "$SESSION_ID"

kernel browsers view "$SESSION_ID"

CDP URL はブラウザーへのアクセス権を付与するため、表示したり共有したりしないでください。ライブビュー URL は、対象のユーザーとのみ共有してください。ヘッドレスセッションにはライブビューがありません。--session <name> を使用する場合は、get cdp-url を含むすべての agent-browser コマンドに指定してください。

ボット検出への対処

ステルスとプロキシのルーティング

現在の agent-browser リリースでは、ステルスはオプトインです。セッションの最初のコマンドを実行する前に KERNEL_STEALTH=true を設定してください。後から変更しても、実行中のブラウザーの設定は変わりません。

ステルスブラウザーでは、Kernel のデフォルトのステルスプロキシを使用できます。そのプロキシが特定のサイトでネットワークやレピュテーションに関する障害を引き起こし、直接のメトロエグレスを許容できる場合は、ステルスを無効にせずに実行中のセッションを変更してください。

kernel browsers update "$SESSION_ID" --disable-default-proxy
# Retry the navigation and compare behavior.

# Re-enable the default stealth proxy while continuing the same session.
kernel browsers update "$SESSION_ID" --disable-default-proxy=false

直接のエグレスではパブリック IP が変わり、ボット対策が弱まる可能性があります。テストでデフォルトプロキシが問題だと判明しない限り、デフォルトプロキシを使用してください。Kernel プロキシを設定するには --proxy-id <proxy-id> を使用します。削除するには --clear-proxy を使用してください。

手動ログインへのフォールバック

自動ログインに失敗した場合：

1. 上記の CDP 対応付けワークフローを使って SESSION_ID を解決します。
2. kernel browsers view "$SESSION_ID" を実行し、URL は対象のユーザーとのみ共有します。
3. ユーザーにログインを完了してもらい、同じ agent-browser セッションで続行します。
4. ログインを永続化するには、上記の CLI で作成したプロファイル／CDP ワークフローを使用します。agent-browser を閉じてから Kernel セッションを削除し、--save-changes を確定させます。

扱いにくい要素への JavaScript フォールバック

一部の要素（特にボット対策が施されたサイト上の要素）は、標準コマンドに応答しません。

# Click by CSS selector
agent-browser -p kernel eval "document.querySelector('.submit-btn').click()"

# Fill by selector (with event dispatch)
agent-browser -p kernel eval "
  const el = document.querySelector('#email');
  el.value = '[email protected]';
  el.dispatchEvent(new Event('input', {bubbles: true}));
  el.dispatchEvent(new Event('change', {bubbles: true}));
"

# Click by test ID
agent-browser -p kernel eval "document.querySelector('[data-testid=\"submit\"]').click()"

ボット対策用フォームフィールド

一部の決済処理業者（例：Point and Pay）は、おとりのフォームフィールドを使用します。特定のパターンに一致するフィールドのみ入力してください。

agent-browser -p kernel eval "
  const realInputs = Array.from(document.querySelectorAll('input'))
    .filter(el => el.name && el.name.startsWith('xeiinput'));
  // Fill only these inputs
"

iframe の処理

同一オリジンの iframe

コンテキストを切り替えるには、frame コマンドを使用します。

agent-browser -p kernel frame "#iframe-id"   # Switch to iframe
agent-browser -p kernel snapshot -i          # Snapshot within iframe
agent-browser -p kernel click @e1            # Interact within iframe
agent-browser -p kernel frame main           # Return to main frame

クロスオリジンの iframe

まず agent-browser frame を試してください。現在のリリースでは、多くのクロスオリジンフレームを含め、iframe のコンテキストに切り替えられます。プロセス外または決済用の iframe で引き続き失敗する場合は、SESSION_ID を解決し、Kernel の Playwright executor を使用してください。

kernel browsers playwright execute "$SESSION_ID" '
  const frame = page.frameLocator("#payment-iframe");
  await frame.locator("#card-number").fill("4111111111111111");
  await frame.locator("#submit").click();
'

フレーム内の操作後は、agent-browser -p kernel frame main でメインドキュメントに戻ります。

待機戦略

スマート待機は、高速で信頼性の高い自動化に不可欠です。 固定タイムアウトではなく条件ベースの待機を使うと、信頼性を高めながら実行時間を50％以上短縮できます。

スマート待機（推奨）

# Wait for page load states
agent-browser -p kernel wait --load domcontentloaded  # DOM ready
agent-browser -p kernel wait --load networkidle       # Network settled

# Wait for specific URL pattern (great for redirects after login)
agent-browser -p kernel wait --url "**/dashboard"
agent-browser -p kernel wait --url "**/order-confirmation"

# Wait for text to appear (great for dynamic content)
agent-browser -p kernel wait --text "Password"        # Field appeared
agent-browser -p kernel wait --text "Order confirmed" # Success message

# Wait for JavaScript condition
agent-browser -p kernel wait --fn "window.appReady === true"
agent-browser -p kernel wait --fn "document.querySelector('.spinner') === null"

# Wait for element by CSS selector
agent-browser -p kernel wait "#login-form"
agent-browser -p kernel wait ".results-loaded"

固定待機（最後の手段）

# Only when no condition is available
agent-browser -p kernel wait 2000

要素参照のベストプラクティス

要素参照（@e1、@e2 など）は一時的なもので、次のタイミングで変わります。

• ページ遷移後
• DOM が大幅に更新された後
• ブラウザーセッション間

操作の前には必ず新しいスナップショットを取得してください。

agent-browser -p kernel snapshot -i
# Now use the refs from this snapshot
agent-browser -p kernel click @e5

スナップショットのフィルタリング

# Filter for specific elements
agent-browser -p kernel snapshot -i | grep -i "button\|submit"

# Scope to a specific area
agent-browser -p kernel snapshot -s "#main-content" -i

ログインのパターン

1ページのフォーム（最適化済み）

ユーザー名とパスワードが同じページにある場合：

agent-browser -p kernel open https://example.com/login
agent-browser -p kernel wait --load domcontentloaded

# Use semantic selectors for stability
agent-browser -p kernel find label "Email" fill "[email protected]"
agent-browser -p kernel find label "Password" fill "secret123"
agent-browser -p kernel find role button click --name "Sign In"

# Wait for actual redirect, not arbitrary timeout
agent-browser -p kernel wait --url "**/dashboard"

2段階フォーム（最適化済み）

最初の画面でユーザー名を入力し、2つ目の画面でパスワードを入力する場合：

agent-browser -p kernel open https://example.com/login
agent-browser -p kernel wait --load domcontentloaded

# Step 1: Username
agent-browser -p kernel find label "Username" fill "myuser"
agent-browser -p kernel press Enter

# Wait for password field to appear (not a fixed sleep!)
agent-browser -p kernel wait --text "Password"

# Step 2: Password
agent-browser -p kernel find label "Password" fill "secret123"
agent-browser -p kernel press Enter

# Wait for successful redirect
agent-browser -p kernel wait --url "**/home"

モーダルでのログイン

モーダルオーバーレイにログインフォームが表示される場合：

# Click login link to open modal
agent-browser -p kernel find text "Log In" click
agent-browser -p kernel wait --text "Password"  # Wait for modal

# Fill modal fields
agent-browser -p kernel find label "Email" fill "[email protected]"
agent-browser -p kernel find label "Password" fill "password123"
agent-browser -p kernel find role button click --name "Sign In"
agent-browser -p kernel wait --url "**/dashboard"

フォールバック：扱いにくいモーダルへの JavaScript

一部のモーダルでは、アクセシブルなラベルが公開されません。

agent-browser -p kernel eval "document.querySelector('.login-link').click()"
agent-browser -p kernel wait 1000

agent-browser -p kernel eval "
  document.getElementById('username').value = '[email protected]';
  document.getElementById('username').dispatchEvent(new Event('input', {bubbles: true}));
  document.getElementById('password').value = 'password123';
  document.getElementById('password').dispatchEvent(new Event('input', {bubbles: true}));
  document.querySelector('button[type=submit]').click();
"
agent-browser -p kernel wait --url "**/dashboard"

新しいタブの処理

リンクによっては、新しいタブで開きます。

# Click link that opens new tab
agent-browser -p kernel click @e38
agent-browser -p kernel tab 1           # Switch to new tab (0-indexed)
agent-browser -p kernel wait 2000
agent-browser -p kernel snapshot -i     # Interact with new tab

スクリーンショットとデバッグ

# Take screenshot
agent-browser -p kernel screenshot ~/Downloads/page.png

# Full page screenshot
agent-browser -p kernel screenshot ~/Downloads/full.png --full

# View console messages
agent-browser -p kernel console

# View page errors
agent-browser -p kernel errors

# Get current URL
agent-browser -p kernel get url

セッション管理

クリーンアップ

開いたときと同じ名前の agent-browser セッションを閉じます。これによりプロファイルの変更が保存され、Kernel ブラウザーが削除されます。

agent-browser -p kernel close
# Named session: agent-browser -p kernel --session site1 close

agent-browser を使用できない場合、または close に失敗した場合は、残存したセッションを明示的に削除します。

kernel browsers delete "$SESSION_ID"

無関係な agent-browser セッションが実行中の可能性がある場合は、close --all を使用しないでください。

複数のセッション

名前付きセッションで、ブラウザーセッションを並行して実行します。

agent-browser -p kernel --session site1 open https://site1.com
agent-browser -p kernel --session site2 open https://site2.com
agent-browser -p kernel session list

よくある注意点

1. ナビゲーション後は参照先が変わります：リンクのクリック、フォームの送信、または DOM の大幅な更新後に、再度スナップショットを取得してください。
2. 結果を待ちます：非同期アクションの後は、URL、テキスト、読み込み状態、または JavaScript の条件を使用してください。
3. プロバイダーの設定は起動時に適用されます：KERNEL_HEADLESS、KERNEL_STEALTH、またはタイムアウトを変更する前に、現在のセッションを終了してください。
4. プロファイルの永続化には CDP の回避策が必要です：KERNEL_PROFILE_NAME は現在正常に動作しません。--save-changes を確定するには、agent-browser を終了してから、CLI が作成した Kernel セッションを削除してください。
5. ステルス機能だけでは対応できないサイトもあります：プロキシ経由のルーティングを比較するか、手動でログインするか、難しいフレームでは Playwright を直接使用してください。

クイックリファレンス

# Start a standard provider session (for persistence, use the CDP workflow above)
export KERNEL_TIMEOUT_SECONDS=600
agent-browser -p kernel open https://example.com

# Basic interaction with semantic selectors (recommended)
agent-browser -p kernel wait --load domcontentloaded
agent-browser -p kernel find label "Email" fill "[email protected]"
agent-browser -p kernel find label "Password" fill "secret"
agent-browser -p kernel find role button click --name "Submit"
agent-browser -p kernel wait --url "**/success"

# Alternative: snapshot + refs (for exploration)
agent-browser -p kernel snapshot -i
agent-browser -p kernel fill @eN "text"
agent-browser -p kernel click @eM

# Resolve the underlying session before manual intervention
CDP_URL="$(agent-browser -p kernel get cdp-url)"
CDP_ENDPOINT="${CDP_URL%%\?*}"
SESSION_ID="$(kernel browsers list --status active --limit 100 -o json |
  jq -r --arg endpoint "$CDP_ENDPOINT" \
    '.[] | select((.cdp_ws_url | split("?")[0]) == $endpoint) | .session_id' |
  head -n 1)"
test -n "$SESSION_ID"
kernel browsers view "$SESSION_ID"

# Cleanup (delete by ID only if close fails)
agent-browser -p kernel close

セレクター早見表

# Buttons and links
agent-browser -p kernel find role button click --name "Submit"
agent-browser -p kernel find role link click --name "Next"
agent-browser -p kernel find text "Click here" click

# Form inputs
agent-browser -p kernel find label "Email" fill "[email protected]"
agent-browser -p kernel find placeholder "Search" type "query"
agent-browser -p kernel find testid "username-input" fill "myuser"

# Smart waits
agent-browser -p kernel wait --load domcontentloaded
agent-browser -p kernel wait --text "Success"
agent-browser -p kernel wait --url "**/dashboard"
agent-browser -p kernel wait --fn "window.loaded === true"