agent-browser CLI 入門：スナップショット、ref、セッション

agent-browser でページを開き、操作用のスナップショットを取り、ref を指定して操作し、結果を確認します。ページが変化した場合、次の操作前に取り直します。番号だけでは対象のボタンを特定できません。

DOM が頻繁に変わるページで ref が通用するか、利用者が質問しました。別の利用者は失敗を観察し、再現できるか確認するよう提案しました。この練習で両方を確認します。 r/ClaudeAI · r/AI_Agents

CLI とセッションの関係

CLI はバックグラウンドのプロセスに命令を送り、起動中のブラウザを使い続けます。同じ作業の各コマンドで同じ --session を指定します。スナップショットは現在のタブを示し、セッションは命令が共有するブラウザ状態を指定します。

セッション · Tabbit と agent-browser の比較 · ブラウザエージェント · ブラウザ自動化

練習ページを開く

CLI とブラウザを準備し、公式のインストール手順を確認してください。練習用 HTML はローカルで配信するか、公開ページを開きます。タイトルとボタン名を読んでください。出力の ref=e2 はコマンドでは @e2 と指定します。

公式インストール · スナップショット · 練習ページを開く

練習を実行する

HTML はアカウント不要です。空のフォルダーに fixture.html を保存し、別の端末でサーバーを起動します。タイトルを確認するか、公開ページを使う場合は URL を置き換えます。

python3 -m http.server 4173 --bind 127.0.0.1

agent-browser --session refs-demo-a open http://127.0.0.1:4173/fixture.html
agent-browser --session refs-demo-a snapshot -i

判断に必要な部分を読む

対象を選ぶときは snapshot -i から始めます。説明やエラーに依存する場合は、全体を読むかステータスを直接確認します。フィルターに表示されなくても、ページには文言が残っている場合があります。同じボタンがある場合は領域を確認してから範囲を絞ります。

古い ref の失敗を再現する

パネルを差し替えるボタンを押します。URL は同じですが、元のボタンは消えます。0.41.2 では古い @e3 が終了コード 1 を返し、元のボタンが見つからないと表示しました。別の読み取りは Panel B ready のままでした。

agent-browser --session refs-demo-a click @e2
agent-browser --session refs-demo-a get text '#status'
agent-browser --session refs-demo-a click @e3

Panel B ready
✗ Could not locate element with role=button name=Use original action

撮り直して結果を確認する

新しいスナップショットでは Use revised action が @e5 になりました。クリック後に Panel B selected を確認しました。0.26.0 では撮り直した後に @e3 が別のボタンに割り当てられました。毎回ロールと名前を読んでください。

agent-browser --session refs-demo-a snapshot -i
agent-browser --session refs-demo-a click @e5
agent-browser --session refs-demo-a get text '#status'

根拠を分ける

最初の結果はパネルの変更を示します。エラーは元の名前が見つからなかったことを示し、最後の読み取りは新しいボタンの結果を示します。画面の状態とスナップショットを一緒に残してください。

保持できる参照

公式文書では、同じ文書に残る DOM 要素は ref を維持できると説明しています。置換時は、条件を満たせば同じロールと名前で一意の要素を探します。この練習では元の名前を削除するため失敗します。同名が複数なら、領域の文脈を含めて再確認します。

別の作業に別のセッションを使う

refs-demo-a や refs-demo-b のように命名します。第二のセッションは別の一時プロファイルで同じ URL を開き、Panel A ready を表示しました。第一のセッションは Panel B selected のままです。外部ブラウザが同じ場合、セッション名だけでは別のアカウント状態になるとは限りません。

agent-browser --session refs-demo-b open http://127.0.0.1:4173/fixture.html
agent-browser --session refs-demo-b get text '#status'
agent-browser --session refs-demo-a get text '#status'

自動化エージェント · エージェントの安全性 · 既存ブラウザの接続

実験に使ったブラウザ

二回とも macOS 上の実際の Tabbit Browser Dev を別々の一時プロファイルで起動しました。製品実験は agent-browser、記事の検証は別途 Tabbit CLI を使用しました。セットアップは公式ガイドを参照してください。

分離する単位を選ぶ

タブはページを選び、セッションは命令間の状態を維持し、プロファイルはローカル起動時のデータの保存先を決めます。一つのセッション内で設定を固定し、次のテストには別の一時プロファイルを使います。起動設定の変更はブラウザを再起動させることがあります。

セッションを閉じてエラーを調べる

結果を読み取ってから自分のセッションだけを名前で閉じます。必要なら session list で確認します。新しい ref でも失敗したら URL、タブ、ロール、名前、表示状態を調べます。必要な画面状態を待ってから操作します。

agent-browser --session refs-demo-a close
agent-browser --session refs-demo-b close
agent-browser session list

初回タスクの確認項目 · ブラウザのデバッグ

Secholar.L

Tabbit グロース&コンテンツ担当

Secholar.L は AI ブラウザとエージェントワークフローについて、実際の調査と検証可能な一次情報に基づく実践的なガイドを執筆しています。