kernel-browser-harness

Kernel Cloud Browsers での Browser-Harness の使用

このスキルでは、browser-harness（browser-use のオープンソース CDP ハーネス）を使用して Kernel クラウドブラウザーを操作する方法を説明します。browser-harness はすでに BU_CDP_WS 環境変数を介して任意の CDP エンドポイントに対応しています。このスキルでは、Kernel CLI からその URL を取得する方法、適切な kernel browsers create フラグの選び方、セッションが競合しないように Kernel セッション ID をハーネスのデーモン名として使用する方法を説明します。

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

次のような場合に、このスキルを使用してください。

• ユーザーのローカル Chrome の代わりに、browser-harness から Kernel ブラウザーを操作する
• kernel browsers create -o json から CDP URL を取得し、BU_CDP_WS に渡す
• 長時間のタスク（作成、操作、確認、さらに操作、終了）にわたって複数のハーネス呼び出しを行う
• ソケットが競合しないよう、複数の Kernel ブラウザーに対してハーネスセッションを並列実行する

前提条件

• Kernel CLI のインストールと認証については、kernel-cli スキルを読み込んでください。
• browser-harness が $PATH にない場合は、セットアッププロンプトに従ってインストールしてください。すでにインストールされている場合は、再インストールしたりセットアッププロンプトを実行したりしないでください。そのまま Kernel ブラウザーの作成に進みます。
• jq がない場合に限り、インストールしてください（CLI の -o json 出力からフィールドを取得するために使用します）。

環境変数

変数	説明	デフォルト
KERNEL_API_KEY	kernel login を実行していない場合は必須です。CLI がセッションを作成するために使用します。	（なし）
BU_CDP_WS	browser-harness が接続する CDP WebSocket URL です。最初の呼び出しでのみ設定してください。同じ BU_NAME での後続の呼び出しでは、デーモンが接続をキャッシュします。	（ローカル Chrome の検出）
BU_NAME	ハーネスのデーモンソケットに名前空間を設定します。Kernel セッション ID を使用してください（BU_NAME=$SESSION_ID）。セッションごとに衝突を防げるため、覚えておく必要のある命名規則もありません。	default

基本的な使い方

最短の手順では、Kernel ブラウザーをちょうど 1 つ作成し、その生の JSON レスポンスを非公開の一意な一時ファイルに保存して、すべての値をそのファイルから取得します。cdp_ws_url は認証情報として扱ってください。ログに記録したり、別のタスクにコピーしたりしないでください。

成功時、失敗時、中断時のいずれでも EXIT トラップで後処理が行われるよう、次のコマンドを 1 つの Bash スクリプトとして実行します。

set -euo pipefail

SESSION_FILE=$(mktemp "${TMPDIR:-/tmp}/kernel-browser-harness.XXXXXX.json")
SESSION_ID=
cleanup() {
  if [ -n "$SESSION_ID" ]; then
    BU_NAME="$SESSION_ID" browser-harness --reload >/dev/null 2>&1 || true
    kernel browsers delete "$SESSION_ID" || true
  fi
  rm -f "$SESSION_FILE"
}
trap cleanup EXIT

kernel browsers create --stealth --timeout 1800 -o json >"$SESSION_FILE"
SESSION_ID=$(jq -er '.session_id' "$SESSION_FILE")
CDP_WS=$(jq -er '.cdp_ws_url' "$SESSION_FILE")
echo "live view: $(jq -r '.browser_live_view_url // empty' "$SESSION_FILE")"

BU_NAME="$SESSION_ID" BU_CDP_WS="$CDP_WS" browser-harness <<'PY'
new_tab("https://news.ycombinator.com")
wait_for_load()
print(page_info())
PY

Kernel ブラウザーはデフォルトでヘッドフルで起動します。作成レスポンスには browser_live_view_url が含まれます。ユーザーがエージェントの作業を確認できるように URL を表示するか、--headless を渡してヘッドレスを選択してください（ライブビューは表示されず、画像も小さくなります）。

kernel browsers create フラグの選び方

ハーネスで使用するセッションを作成する際によく使われる選択肢です。

フラグ	用途
--stealth (-s)	ボット検出の回避。ほとんどの公開サイトで有効にします
--headless (-H)	デフォルトのヘッドフル設定を解除します。ライブビューも VNC も使用できません
--profile-name NAME	保存済みの Kernel プロファイルを再利用します（ログイン状態、Cookie、localStorage）
--proxy-id ID	Kernel が管理するプロキシ（レジデンシャル、地域別など）を経由します
--timeout N	アイドルタイムアウト（秒。デフォルトは 60、最大は 259200）。長時間のエージェント実行では大きくしてください
--start-url URL	セッションの起動時に URL を開きます
--save-changes	セッション終了時にプロファイルの変更を保存します

一覧については、kernel browsers create --help を参照してください。

ステルスのデフォルトプロキシの制御は、作成フラグではなく実行時の更新で行います。ステルスセッションを直接接続する必要がある場合は、最初のハーネス呼び出しより前に次を実行してください。

kernel browsers update "$SESSION_ID" --disable-default-proxy

--disable-default-proxy=false を指定すると、デフォルトのステルスプロキシを再び有効にできます。明示的に設定したプロキシを変更する場合は、代わりに --proxy-id または --clear-proxy を使用してください。

マルチステップでの使用

複数回のハーネス呼び出しにまたがるタスク（作成、操作、確認、追加操作、破棄）では、デーモンが CDP 接続を保持します。所有元のスクリプトで EXIT トラップが実行される前に、すべての呼び出しを行ってください。BU_CDP_WS が必要なのは、その BU_NAME に対する最初の呼び出しだけです。

BU_NAME=$SESSION_ID を規約とすれば、以降のハーネス呼び出しはすべて次のとおりです。

BU_NAME=$SESSION_ID browser-harness <<'PY'
print(js("document.title"))
PY

並列セッションも自動的に処理されます。各 Kernel ブラウザーには一意のセッション ID があるため、異なるセッションに対する 2 つの BU_NAME=$SESSION_ID 呼び出しがデーモンのソケット上で競合することはありません。

別々のシェルプロセスを避けられない場合は、親オーケストレーターがレスポンスファイルと最後のクリーンアップを管理するようにしてください。短命な作成サブプロセスのトラップによって、セッションが早々に削除されるのを防げます。変数が失われた場合は、保存された JSON から session_id と cdp_ws_url を再読み込みしてください。ファイルが見つからない場合は、kernel browsers list --limit 100 -o json | jq でアクティブなセッションを確認してください。追加のページを取得するには --offset を使用し、続行または削除する前に対象のセッションを正確に特定してください。

ハーネスセッションの前後でリプレイを記録する方法については、kernel-cli スキルの replays リファレンスを参照してください。

並列セッション

ワーカーごとに Kernel ブラウザーを 1 つ作成し、各ワーカーのレスポンスファイル、セッション ID、CDP URL、デーモン名をまとめて管理してください。ワーカー間でレスポンスファイルや BU_NAME を共有しないでください。作成が成功したら、すぐに各セッションを親プロセスのクリーンアップ対象に登録してください。

set -euo pipefail
declare -a SESSION_IDS=() SESSION_FILES=()

cleanup_parallel() {
  for sid in "${SESSION_IDS[@]}"; do
    BU_NAME="$sid" browser-harness --reload >/dev/null 2>&1 || true
    kernel browsers delete "$sid" || true
  done
  rm -f "${SESSION_FILES[@]}"
}
trap cleanup_parallel EXIT

mint() {
  local sid_var=$1 cdp_var=$2 file_var=$3 file sid cdp
  file=$(mktemp "${TMPDIR:-/tmp}/kernel-browser-harness.XXXXXX.json")
  SESSION_FILES+=("$file")
  kernel browsers create --stealth --timeout 1800 -o json >"$file"
  sid=$(jq -er '.session_id' "$file")
  SESSION_IDS+=("$sid")
  cdp=$(jq -er '.cdp_ws_url' "$file")
  printf -v "$sid_var" '%s' "$sid"
  printf -v "$cdp_var" '%s' "$cdp"
  printf -v "$file_var" '%s' "$file"
}

mint SESSION_A CDP_A FILE_A
mint SESSION_B CDP_B FILE_B

BU_NAME="$SESSION_A" BU_CDP_WS="$CDP_A" browser-harness <<'PY' &
new_tab("https://example.com"); wait_for_load(); print(page_info())
PY
PID_A=$!

BU_NAME="$SESSION_B" BU_CDP_WS="$CDP_B" browser-harness <<'PY' &
new_tab("https://example.org"); wait_for_load(); print(page_info())
PY
PID_B=$!

wait "$PID_A" "$PID_B"

このトラップは各ローカルデーモンを停止し、課金対象の各 Kernel セッションを削除して、両方のレスポンスファイルを削除します。クリーンアップに wait やアイドルタイムアウトを当てにしないでください。

よくある注意点

1. タスクの途中で BU_CDP_WS unreachable が発生する：Kernel セッションがアイドルタイムアウトに達した可能性があります。デフォルトは 60 秒です。作成時に --timeout 1800（またはタスクに適した値）を渡してください。

2. URL を混同しない：cdp_ws_url は不透明なシークレットとして扱い、書き換えずにそのまま BU_CDP_WS に渡してください。browser_live_view_url は人間の監視者専用です。

3. デーモンが新しいセッションを認識しない：新しい Kernel ブラウザーを作成しても、古い BU_NAME を再利用すると、デーモンは古い CDP URL に接続されたままになります。BU_NAME=$SESSION_ID を使えば、この問題を回避できます。それ以外の場合は、新しいエンドポイントにその名前を接続する前に BU_NAME=<name> browser-harness --reload を実行してください。

4. 不要な作成は時間と費用の無駄になる：通常、1 つのタスクで kernel browsers create を呼び出すのは 1 回だけです。-o json のレスポンスを保存して再利用し、以前のタスクの ID や CDP URL をハードコードしないでください。

5. 必ず両方のレイヤーを破棄する：BU_NAME="$SESSION_ID" browser-harness --reload で名前付きのローカルデーモンを停止し、続けて kernel browsers delete "$SESSION_ID" を実行して、保存した JSON ファイルを削除してください。--reload は Kernel ブラウザーを削除しません。Kernel セッションは削除されるかアイドルタイムアウトに達するまで課金されます。スクリプトでは、この 3 つの操作をすべて EXIT トラップに入れてください。

ヘルパーの使用方法（new_tab、page_info、js など）は browser-harness スキルが担当します。ブラウザーとリプレイのライフサイクルは kernel-cli スキルが担当します。このスキルでは、CLI とハーネスの連携に限定してください。