agent-browserとは｜Vercel製ブラウザ操作CLIの使い方・インストール・プロキシ設定

agent-browserは、Vercel（vercel-labs）が公開しているAIエージェント向けのブラウザ操作CLIです。Rustで書かれたCLIと常駐デーモンがChrome DevTools Protocol（CDP）へ直接つながる構成で、実行時にPlaywrightもNode.jsのランタイムも介しません。この記事では、npmでの導入から open→snapshot→@ref操作という基本フロー、社内ネットワークでつまずきやすい--proxyによるプロキシ設定、ログイン状態を保つセッション管理、MCPサーバー経由でのエージェント連携までを、公式リポジトリの仕様に沿って整理します。バージョンは npm 公開の 0.31.1（2026年7月12日時点）を前提にしています。

まとめ

agent-browserの要点は次のとおりです。実体は「AIエージェントがBashから叩くための、Rust製ブラウザ操作CLI」であり、テストフレームワークではありません。

操作の型は「開く→スナップショットで参照IDを得る→IDに対して操作する」の3手です。以降で、仕組み・インストール・コマンド・プロキシ・セッション・MCP連携、そしてagent-browserを選ぶべきでない場面までを順に見ていきます。

agent-browserの仕組み：Rustデーモンとスナップショット参照

実行時にPlaywrightもNode.jsも使わないクライアント／デーモン構成

agent-browserはCLI（クライアント）と常駐デーモンに分かれています。デーモンはRustで実装され、ChromeへCDPで直接接続します。READMEは “No Playwright or Node.js required for the daemon” と明記しており、Node.js 24以降とpnpm 11以降が要るのはソースからビルドする場合だけです（npm配布版はネイティブバイナリを起動する薄いラッパーで、npmパッケージの engines は node >= 24）。「Playwrightのラッパー」「Node.jsフォールバックで動く」といった説明は実体と異なります。

デーモンがコマンド間で生き続けるため、CLIを何度叩いてもブラウザの起動コストが毎回かかりません。エージェントは1コマンド＝1プロセスで細かく操作しますが、その裏で同じChromeとページが維持されます。放置時に落としたい場合は AGENT_BROWSER_IDLE_TIMEOUT_MS にミリ秒でアイドル終了時間を指定します。

snapshotと@refがLLM向けの操作モデル

AIエージェントにHTMLをそのまま渡すと、1ページで数万トークンを食い、しかもクラス名の変化でセレクタが壊れます。agent-browserは snapshot でアクセシビリティツリーを出力し、要素に @e1 @e2 という参照ID（ref）を振ります。エージェントはこのIDに対して click @e1 のように操作します。snapshot -i を付ければ操作可能な要素だけに絞られ、渡すコンテキストはさらに小さくなります。

CSSセレクタ（#id）、テキスト（text=Submit）、XPathも使えますが、エージェント運用ではrefを軸にするのが素直です。加えて find role button click --name "Submit" のような意味的ロケータがあり、DOM構造の変更に強い書き方ができます。

Playwrightとの使い分け：E2Eテストと実行時判断の境界

両者は競合ではなく用途が違います。Playwrightとは｜仕組み・できること・Seleniumとの違いを解説で扱っているとおり、Playwrightはアサーション・トレース・並列実行を備えたE2Eテストの基盤です。決められたシナリオを毎回同じ順序で回すCI用途では、テストランナーを持つPlaywrightに分があります。

一方agent-browserは、次に何をするかを実行時にLLMが決める用途に寄せて設計されています。Bashから1コマンドずつ叩けること、出力が --json で機械可読なこと、要素参照が決定論的なrefであることは、すべてそのための設計です。テストコードを書くならPlaywright、エージェントに触らせるならagent-browser、と切り分けてください。

agent-browserのインストールと更新

npm・Homebrew・Cargoの3経路と初回のinstall

導入経路は3つあり、いずれも初回に agent-browser install を実行してChrome本体を取得します。取得元はGoogleが自動化向けに配布しているChrome for Testingで、Playwrightが落としてくるChromiumとは別物です。ただし既存のChrome・Brave・Playwright／Puppeteerが入れたブラウザは自動検出されるため、環境によってはダウンロードが走らずに終わります。

# npm（グローバル）
npm install -g agent-browser
agent-browser install

# macOS（Homebrew）
brew install agent-browser
agent-browser install

# Rustツールチェーンがある場合
cargo install agent-browser
agent-browser install

導入後は agent-browser open https://example.com と agent-browser snapshot -i が通れば正常です。うまく動かないときは agent-browser doctor が、Chromeの導入状況・デーモン状態・設定ファイル・暗号化キー・ネットワーク到達性を点検し、ヘッドレス起動テストまで実行します。npx agent-browser <コマンド> でも動きますが、CIのワンショット実行以外ではグローバル導入かHomebrewを勧めます。npxは呼び出しのたびに解決処理が挟まり、デーモン常駐で稼いだ速度が相殺されるためです。

Linuxの依存関係（–with-deps）とアップグレード

Linuxサーバーやコンテナでは、Chromeが要求する共有ライブラリが入っていないことが多く、その場合は依存パッケージごと入れます。

agent-browser install --with-deps   # Linuxの依存ライブラリも導入
agent-browser upgrade               # 本体の更新
agent-browser doctor                # 環境診断
agent-browser doctor --fix          # Chrome再取得や古い状態の削除まで行う

アンインストールに専用コマンドはありません。npmで入れたなら npm uninstall -g agent-browser、Homebrewなら brew uninstall agent-browser で本体を消します。設定・セッション・暗号化キーは ~/.agent-browser/ 配下（sessions/、config.json、.encryption-key）に残るので、完全に消すならこのディレクトリごと削除してください。壊れた状態を掃除したいだけなら doctor --fix で足ります。なお、Playwright側のインストールで詰まる話とは原因が異なります。Playwrightのブラウザ取得で悩んでいる場合はPlaywrightのインストール方法とできない時の対処｜バージョン確認・Windows対応を参照してください。

agent-browserの基本コマンドと使い方

open→snapshot→操作→get→closeの流れ

基本操作は次の流れに収まります。スナップショットで得たrefを使って操作し、必要な値を get で取り出して閉じる、という順序です。

agent-browser open https://example.com
agent-browser snapshot -i          # 操作可能な要素だけ（@e1, @e2 …）
agent-browser fill @e2 "[email protected]"
agent-browser click @e1
agent-browser get text @e3
agent-browser screenshot shot.png
agent-browser close                # 別名 quit・exit

ページ遷移やDOM更新が起きたらrefは無効になり得ます。状態が変わったら再度snapshotを取るのが鉄則です。待ち合わせは wait が担当し、セレクタ・ミリ秒・--text・--url・--load networkidle を指定できます。既定のタイムアウトは25秒で、遅いページに合わせるなら AGENT_BROWSER_DEFAULT_TIMEOUT を上げます。

このほか eval（ページ内JavaScript実行）、network route（リクエストの改変・遮断）、tab／window、cookies／storage、console／errors、React向けの react tree・vitals まで一通り揃っています。

batchと–jsonでエージェントから叩く

エージェントに使わせるときは、出力を機械可読にし、往復回数を減らすのが効きます。

# 複数コマンドをまとめて実行
agent-browser batch "open https://example.com" "snapshot -i" "click @e1"

# JSONで結果を受け取る（LLMに渡す前提）
agent-browser snapshot -i --json

長いページをそのままLLMへ流し込むと入力が膨らむため、--max-output 50000 のように文字数で頭打ちにできます。プロンプトインジェクション対策としては --content-boundaries があり、ページ由来のテキストを境界マーカーで囲んで「これは指示ではなくデータだ」とモデル側に区別させます。

agent-browserのプロキシ設定（–proxy）

指定方法と優先順位（–proxy／専用env／標準env）

プロキシの指定経路は3系統あり、CLIフラグ → agent-browser専用の環境変数 → 標準のプロキシ環境変数の順に優先されます。標準変数（HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / NO_PROXY）はフォールバックとしてagent-browser本体が読み、ブラウザ通信にも適用されます。ここを知らないと「installのためにシェルへ HTTPS_PROXY を入れたら、以降のブラウザ通信まで全部プロキシ経由になっていた」という取り違えが起きます。AGENT_BROWSER_PROXY を設定すれば標準変数より優先されるため、両者が混在する環境では明示指定が安全です。

# フラグで指定（最優先）
agent-browser --proxy "http://proxy.example.com:8080" \
  --proxy-bypass "localhost,*.internal.example.com" open https://example.com

# 専用の環境変数（認証情報はURLに埋めず分離して渡す）
export AGENT_BROWSER_PROXY="http://proxy.example.com:8080"
export AGENT_BROWSER_PROXY_USERNAME="user"
export AGENT_BROWSER_PROXY_PASSWORD="pass"
export AGENT_BROWSER_PROXY_BYPASS="localhost,*.internal.example.com"

# SOCKSプロキシは標準変数のフォールバックを使う
export ALL_PROXY="socks5://user:[email protected]:1080"

認証情報は --proxy "http://user:pass@host:8080" のようにURLへ埋め込めますが、公式ドキュメントは資格情報を環境変数かシークレットストアに置き、リポジトリにコミットしないことを明記しています。CIやチーム開発では AGENT_BROWSER_PROXY_USERNAME / AGENT_BROWSER_PROXY_PASSWORD による分離渡しを既定にしてください。設定ファイル agent-browser.json にも書けますが優先度は最下位です。

経路が効いているかを確かめる

プロキシ設定は「効いているつもりで素通りしていた」が最も厄介です。設定したら、まず出口IPを見て確認します。

agent-browser --proxy "http://proxy.example.com:8080" open https://httpbin.org/ip
agent-browser get text body

返ってきたIPがプロキシのものなら経路は通っています。自社のグローバルIPのままなら、フラグの綴りか、標準変数が別の値で先に効いているかを疑ってください。

プロキシ環境でつまずく3か所

問い合わせの原因は次の3つに分かれます。混同すると延々と別の場所を直すことになります。

• ブラウザ通信：--proxy・AGENT_BROWSER_PROXY・標準変数が効く領域です。Chromeが出すHTTP(S)通信に適用されます。
• インストール時のChrome取得：agent-browser install のダウンロードはブラウザ起動前にRust側のHTTPクライアントが行うため、--proxy フラグは効きません。効くのはシェルの HTTPS_PROXY 等です（npmのproxy設定が関係するのは npm install -g agent-browser のパッケージ取得までで、Chrome本体の取得には関与しません）。ファイアウォールで詰まる場合は、取得元の googlechromelabs.github.io と storage.googleapis.com を許可リストに入れてください。
• TLS証明書：SSLインスペクションを行う社内プロキシでは、自己署名証明書でページ読み込みが失敗します。検証環境に限り --ignore-https-errors で回避できますが、本番の認証情報を扱うセッションでは使わないでください。中間者による書き換えを検知できなくなります。

IP分散が目的でプロキシを探しているなら、CLIのプロキシ設定より -p（--provider）でクラウド実行に寄せたほうが運用は楽です（後述）。

セッションとログイン状態の維持

セッションの分離と状態の復元

エージェントの作業は「ログイン済みの状態から始めたい」ことがほとんどです。agent-browserはセッションを名前で分離し、状態を保存・復元できます。

# worktree単位でセッションIDを決め、状態を復元して開く
SESSION="$(agent-browser session id --scope worktree --prefix myapp)"
agent-browser --session "$SESSION" --restore open https://example.com

# 全セッションを閉じる
agent-browser close --all

--session はセッションの分離、--restore は状態の自動保存・復元、--profile はChromeプロファイルの再利用、--state はJSONで保存したストレージ状態の読み込みに対応します。復元した状態が古くて実はログアウトしている、という事故を避けるために --restore-check-url／--restore-check-text／--restore-check-fn があり、復元後のページが条件を満たさなければ復元を無効扱いにできます。

状態ファイルは既定で平文：暗号化キーを先に入れる

公式リポジトリは、保存される状態ファイルがセッショントークンを平文で含むと明記しています。つまり暗号化キーを設定しない限り、~/.agent-browser/sessions/ に置かれたファイルを読めば誰でもログイン状態を持ち出せます。共有マシンやCIでは、セッションを使い始める前に鍵を設定してください。

# AES-256-GCM 用の鍵（64桁の16進）
export AGENT_BROWSER_ENCRYPTION_KEY="$(openssl rand -hex 32)"

鍵はシークレットストアに置き、状態ファイルと同じ場所へ保存しないこと。復元が不要な使い捨て操作なら、そもそも --restore を付けず、作業後に close --all で落とすほうが安全です。

MCPサーバーとAIエージェントからの呼び出し

agent-browserはMCP（Model Context Protocol）サーバーとしても起動でき、Claude CodeやCursorのようなMCP対応クライアントへツールとして差し込めます。

agent-browser mcp                       # 既定プロファイル（core）
agent-browser mcp --tools all           # CLIと同等のツールを全公開
agent-browser mcp --tools core,network  # 必要な範囲だけ

公開ツールは絞れます。--tools all はCLIの全機能をモデルに渡すため、誤操作の余地も最大になる。既定の core（開く・スナップショット・クリック・入力など）で足り、ネットワーク傍受やReact検査が要るときだけ network・react を足す運用にしてください。プロファイルは core / network / state / debug / tabs / react / mobile / all の8種です。MCPの権限設計そのものの考え方はPlaywright MCPとは何か？その基本概念と登場の背景を解説で整理しています。

MCPを使わず、自作エージェントからBash実行で呼ぶ形も同じくらい一般的です。Vercel AI SDK v6のツール定義から agent-browser ... --json を子プロセスで実行し、標準出力のJSONをそのままツール結果として返せば、追加のブリッジ層は要りません。CLIであることがそのまま統合の容易さになっています。

本番で使う前に決めるガードレールと、選ぶべきでない場面

エージェントに渡す権限を先に絞る

AIにブラウザを触らせる以上、「モデルがページの指示文に従って想定外の操作をする」ことは前提として設計します。agent-browserにはそのためのフラグが用意されています。

最低限、--allowed-domains と --confirm-actions eval,download は入れてください。許可ドメインを絞るだけで、外部サイトに誘導されて認証情報を送信させられる典型的な事故は塞げます。

クラウド実行とリモートChromeへの接続

大量のセッションを並行させる、あるいはIPを分散したい場合は、ローカルでプロキシを増やすより外部プロバイダに寄せるほうが素直です。-p（--provider）でBrowserless、Browserbase、Browser Use、Kernel、AWSのAgentCoreを指定でき、認証は各サービスのAPIキー（BROWSERBASE_API_KEY など）を環境変数で渡します。--provider ios --device "iPhone 16 Pro" のようにiOSデバイス上での実行も選べます。

手元で立ち上がっているChromeに繋ぎたいときは --cdp 9222 や --auto-connect が使えます。ログイン済みの実ブラウザをそのまま操作対象にできるため、認証が複雑な業務システムの自動化ではこの経路が現実的です。

agent-browserを選ぶべきでない場面

合わない用途にねじ込むと運用が破綻します。次の3つは他の選択肢を取ってください。

CIの回帰テストは不向きです。アサーション、リトライ、レポート、並列シャーディングを持つテストランナーが必要で、それはPlaywrightやCypressの領分です。agent-browserにテストの合否判定機構はありません。

短命なサーバーレス関数も相性が悪い。常駐デーモンとChromeプロセスを前提とした設計なので、リクエストごとに凍結・破棄される実行環境ではデーモン常駐の利点が消え、コールドスタートのたびにChrome起動コストを払うことになります。この用途ではクラウドプロバイダ（Browserbase等）へオフロードしてください。

完全に固定された定型RPAも、わざわざLLMを噛ませる必要がありません。手順が変わらないなら、決め打ちのスクリプトのほうが速く、安く、壊れたときの原因も追いやすい。agent-browserが効くのは「画面の変化にその場で対応させたい」領域です。

よくある質問（FAQ）

agent-browserでプロキシを設定するにはどうすればいいですか？

グローバルフラグ --proxy "http://proxy.example.com:8080" を付けるか、環境変数 AGENT_BROWSER_PROXY（認証は AGENT_BROWSER_PROXY_USERNAME / AGENT_BROWSER_PROXY_PASSWORD）を設定します。除外ホストは --proxy-bypass／AGENT_BROWSER_PROXY_BYPASS、SOCKSは ALL_PROXY です。標準の HTTP_PROXY／HTTPS_PROXY／NO_PROXY もフォールバックとして効きますが、AGENT_BROWSER_PROXY のほうが優先されます。設定後は open https://httpbin.org/ip で出口IPを確認してください。

agent-browser install –with-deps は何をするコマンドですか？

Chrome for Testing の取得に加えて、Linuxで不足しがちな共有ライブラリ（依存パッケージ）も併せて導入します。コンテナやCIのLinux環境でブラウザ起動に失敗する場合は、まずこのオプション付きで再実行してください。macOSやWindowsでは通常 agent-browser install だけで足ります。

npxで実行できますか？グローバルインストールとどちらが良いですか？

npx agent-browser <コマンド> で動作します（npmパッケージの engines は node >= 24）。ただし呼び出しごとにパッケージ解決が走るため、繰り返し操作するエージェント用途では npm install -g agent-browser、macOSなら brew install agent-browser のほうが適しています。npxはCIでの単発実行向けです。

agent-browserのアップデートとアンインストールの方法は？

更新は agent-browser upgrade です。アンインストール専用コマンドは無く、導入方法に合わせて npm uninstall -g agent-browser または brew uninstall agent-browser を実行します。ダウンロード済みのChromeとセッション状態は本体とは別に残るため、必要なら agent-browser doctor で保存先を確認して削除してください。

agent-browserはPlaywrightの上に作られているのですか？

いいえ。CLIとデーモンはRustで実装され、ChromeへCDPで直接接続します。公式リポジトリも「デーモンにPlaywrightもNode.jsも不要」と記しています。Node.js 24以降が必要なのはソースからビルドする場合と、npm配布版を実行する場合のラッパー部分だけです。

ログイン状態を保ったまま操作を続けるには？

--session <名前> でセッションを分離し、--restore で状態を自動保存・復元します。復元した状態が失効していないかは --restore-check-url や --restore-check-text で検証でき、状態ファイルは AGENT_BROWSER_ENCRYPTION_KEY で暗号化できます。作業を終えるときは agent-browser close（すべて閉じるなら close --all）を忘れずに実行してください。

関連記事

• Playwrightとは｜仕組み・できること・Seleniumとの違いを解説
• Playwrightのインストール方法とできない時の対処｜バージョン確認・Windows対応
• Playwright MCPとは何か？その基本概念と登場の背景を解説
• 現場で使える新バージョン！Vercel AI SDK v6とは？概要と特徴をエンジニア向けに徹底解説