agent-browserの使い方｜Vercel製CLIのプロキシ設定・インストール・MCP連携【0.39対応】

agent-browserは、Vercel Labs（vercel-labs）が公開しているAIエージェント向けのブラウザ操作CLIです。Rust製のCLIと常駐デーモンがChrome DevTools Protocol（CDP）でChromeを直接動かし、デーモンはPlaywrightにもNode.jsにも依存しません（npm・npxで入れた場合は、起動時にNode.js製のランチャーを通ります）。この記事では最新版0.39.1（2026年10月13日リリース）を前提に、導入、基本操作、社内ネットワークで詰まりやすいプロキシ設定、Vercelの保護されたプレビューを安全に開く方法、MCP連携を整理します。プロキシの挙動は、2026年10月22日にmacOS・agent-browser 0.39.1・Chrome for Testing 156.0.8078.47（mac-x64）で、検証用プロキシの接続ログを使って確認しました。

まとめ

• 操作の型は「openで開く→snapshot -iで参照ID（@e1など）を得る→IDに対して操作する」の3手です。
• プロキシは--proxyかAGENT_BROWSER_PROXYで明示します。標準のHTTP_PROXYとHTTPS_PROXYを両方入れると、HTTPSのページでもHTTP_PROXY側が使われます。
• socks5://user:pass@...は通りません。ChromeがSOCKS5のユーザー名認証を提示しないためです。
• install・doctor・URL指定のreadは--proxyを使いません。通したいならシェルのHTTPS_PROXYを設定します。
• Vercelの保護されたプレビューは、短命のOIDCトークンをヘッダーで渡して開きます。保護を外したり、公開例外を作ったりはしません。

agent-browserの仕組み：RustデーモンとCDPによるChrome操作

Playwright・Node.jsに依存しないRust製デーモン

agent-browserは、コマンドを受け取るCLIと、コマンド間で生き続けるデーモンに分かれています。デーモンはRustで書かれ、ChromeへCDPで直接つながります。公式リポジトリのREADMEは「No Playwright or Node.js required for the daemon」と明記しており、ソースからのビルドにはNode.js 24以降・pnpm 11以降・Rustが必要です。npm・npxで導入する場合もNode.jsが必要で、0.39.1のnpmパッケージはNode.js 24以降を要求しています。「Node.jsデーモンがPlaywrightを動かす」という2026年初めの解説は、現行版には当てはまりません。

デーモンが常駐するので、CLIを何十回叩いてもブラウザの起動は最初の1回で済みます。エンジンはChrome以外にlightpandaと、0.39.0で実験的に加わったobscuraを--engineで選べます。

snapshotと@refによる要素の指定

snapshotはアクセシビリティツリーを出力し、要素に@e1・@e2という参照ID（ref）を振ります。エージェントはclick @e2のようにIDで操作します。-iを付けると操作できる要素だけに絞られます。

HTMLを丸ごと渡すより入力が小さく、クラス名の変更でも壊れません。0.38.0（2026年9月16日）からrefは同じ文書内のDOM変化を越えて保たれますが、要素の置き換えやページ遷移で無効になるため、画面が変わったらsnapshotを取り直します。同じ版のsnapshot --deltaは2回目以降の変化分だけを返します。

Playwright・Playwright MCP・Stagehandとの使い分け

決まったシナリオを回すCIのE2Eテストは、アサーションとレポートを持つPlaywright（プレイライト）とは？仕組み・できること・Seleniumとの違いを解説の領分です。agent-browserは、次の操作をLLMがその場で決める用途の道具です。

エージェント向けでも、MCPのツールとして渡すのがPlaywright MCPとは？設定・使い方からDify連携まで実務ガイド【2026年版】、TypeScriptのコードから自然言語で操作を書くのがStagehandとは｜AIブラウザ自動化の使い方とPlaywrightとの違い【v3対応】です。シェルを実行できるエージェント（Claude Code・Codex・Cursorなど）にBashのコマンドとして渡すならagent-browserで、ツール定義でコンテキストを埋めずに済みます。Next.js DevTools MCPの使い方｜next-devtools-mcp 0.4の設定と/_next/mcpの9ツールも、ブラウザ操作はagent-browserに任せる構成です。

agent-browserのインストール（npm・Homebrew・Cargo・Windows）

npm・Homebrew・Cargoによる導入とChromeの取得

どの経路でも、初回にagent-browser installでChrome for Testingを取得します。既存のChrome・Brave・Playwright・Puppeteerのブラウザが見つかれば、それを使います。

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

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

# Rustツールチェーンがある場合（ソースからビルド・2〜3分）
cargo install agent-browser
agent-browser install

# インストールせずに試す
npx agent-browser install
npx agent-browser open example.com

macOSで0.39.1のinstallを実行すると、196MBのChrome 156.0.8078.47をstorage.googleapis.comから取得し、~/.agent-browser/browsers/に置きました。npmパッケージには各OS向けのネイティブバイナリが同梱されており、npm 11.17.0でpostinstallが承認待ちの警告を出してもローカル導入はそのまま動きました。

Linuxの依存ライブラリとWindowsの注意点

Linuxのサーバーやコンテナでは、Chromeが要る共有ライブラリが足りないことが多く、agent-browser install --with-depsで依存パッケージごと入れます。1つでも入れられなければ0以外で終わります。

Windowsはx64のバイナリが配布されています。ARM64機では、ネイティブのARM64実行ファイルがあればそれを、無ければx64版をエミュレーションで動かします（0.35.1で修正）。0.37.1からヘッドレスのChromeは非表示の別デスクトップで起動し、画面に空の枠が残らなくなりました。

agent-browserの更新・診断・アンインストール

agent-browser upgrade                    # 導入経路（npm・Homebrew・Cargo）を判別して更新
agent-browser doctor                     # 環境・Chrome・デーモン・設定・ネットワーク・起動テスト
agent-browser doctor --offline --quick   # ネットワークと起動テストを省く
agent-browser doctor --fix               # Chrome再取得・古い状態ファイル削除など破壊的な修復も行う

アンインストール専用のコマンドはありません。npm uninstall -g agent-browserかbrew uninstall agent-browserで本体を消し、完全に消すなら設定・状態・取得したChromeが入った~/.agent-browser/も削除します。Playwright側のブラウザ取得の問題はPlaywrightのインストール方法とできない時の対処｜バージョン確認・Windows・Pythonで扱っています。

agent-browserの基本コマンドと操作手順

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

agent-browser open https://example.com
agent-browser snapshot -i              # 操作できる要素だけ（@e1, @e2 …）
# フォームのあるページで、snapshotに表示された入力欄のrefを使う例:
# agent-browser fill @e2 "[email protected]"
agent-browser click "a"
agent-browser snapshot -i
agent-browser get text body
agent-browser screenshot shot.png
agent-browser close                    # 全セッションなら close --all

待ち合わせはwaitで、セレクタ・ミリ秒・--text・--url・--load networkidleを指定できます。公式はnetworkidleを通信が静まると分かっているページに限り、通常はページ固有のセレクタや文字列で待つよう勧めています。操作の既定タイムアウトは25秒（AGENT_BROWSER_DEFAULT_TIMEOUT・ミリ秒）で、CLIの応答待ちは通常30秒を下限としますが、wait系などtimeoutを持つコマンドでは、指定タイムアウトに10秒を加えた値と30秒の大きいほうになります。

batch・JSON出力・readによる一括実行と結果取得

agent-browser batch "open https://example.com" "snapshot -i" "get title"
agent-browser snapshot -i --json
agent-browser read https://example.com/article --outline

--jsonで結果を機械可読にし、batchで往復を減らします。readはURLの本文をMarkdownやllms.txtを優先して取得し、URLを省けば開いているタブの描画後のDOMを読みます。

agent-browserのプロキシ設定と通信経路

プロキシ設定の指定方法と優先順位

公式のProxyページが挙げる指定方法は、CLIフラグ、専用の環境変数、標準のプロキシ環境変数の3系統です。どれが勝つかをソース（cli/src/flags.rs）で確かめ、ログを取る検証用プロキシを2つ（AとB）立ててopen https://example.comがどちらに届くかを見ました。

つまずきやすいのは4と5です。見つけた1つ目の値がChromeの--proxy-serverに渡るだけで、スキーム別には使い分けません。HTTP_PROXYとHTTPS_PROXYが別のシェルでは、HTTPSのページもHTTP_PROXY側へ流れます。除外は--proxy-bypass→AGENT_BROWSER_PROXY_BYPASS→設定ファイル→NO_PROXYの順で、NO_PROXY=example.comを入れた回はexample.comがプロキシに来ませんでした。

# フラグで指定（最優先）
agent-browser --proxy "http://proxy.example.com:8080" \
  --proxy-bypass "*.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="$PROXY_PASSWORD"
export AGENT_BROWSER_PROXY_BYPASS="*.internal.example.com"

設定ファイルは~/.agent-browser/config.json（ユーザー単位）と./agent-browser.json（プロジェクト単位）の2か所で、後者が勝ちます。公式の設定ページにある「環境変数が設定ファイルより強い」はAGENT_BROWSER_*の話で、標準のHTTP_PROXYは設定ファイルに負けます。

認証付きプロキシとSOCKS5

Basic認証を要求するプロキシに--proxy "http://u1:[email protected]:18733"で接続すると、agent-browserはURLから資格情報を外してChromeに渡し、407が返った時点で認証を送ります。検証では407の後に認証付きのCONNECTが通り、ページ取得まで成功しました。AGENT_BROWSER_PROXY_USERNAMEと_PASSWORDに分けても同じ結果です。資格情報を渡さなかった回はnet::ERR_INVALID_AUTH_CREDENTIALSで止まりました。

SOCKS5はALL_PROXY="socks5://127.0.0.1:1080"のような認証なしなら通ります。ところが公式ページにあるsocks5://user:pass@...の形は、ユーザー名認証を必須にした検証用SOCKS5サーバーではnet::ERR_SOCKS_CONNECTION_FAILEDになりました。サーバー側のログでは、Chromeが提示した認証方式は「認証なし（0）」だけで、ユーザー名・パスワード方式（2）を一度も出していません。Chromiumのプロキシ解説も「No authentication methods are supported for SOCKSv5 in Chrome」と書いています。認証が要るSOCKSしか無い環境では、手元に認証を肩代わりするHTTPプロキシを挟むか、HTTPプロキシに切り替えてください。

プロキシを通らない通信：install・doctor・read・localhost

「設定したのに通らない」の多くはブラウザ以外の通信です。Chromeの取得やURL指定のreadはCLIがRustのHTTPクライアント（reqwest）で行い、--proxyもAGENT_BROWSER_PROXYも読みません。

--proxy付きでinstallを実行するとプロキシ側には1件も届かず、Chromeは直接ダウンロードされました。HTTPS_PROXYを入れてdoctor --quickを実行すると、googlechromelabs.github.ioへのCONNECTがプロキシに届きました。直結が禁止されたネットワークでinstallするなら、シェルにHTTPS_PROXYを入れたうえで、googlechromelabs.github.ioとstorage.googleapis.comを許可してもらいます。

また、プロキシを指定してread <URL>を実行すると、本文はプロキシを通らないのにChromeが1つ起動しました（ドキュメント上はChromeを起動しない）。ローカルの開発サーバーは、HTTP_PROXYを入れていてもhttp://localhost:18740・http://127.0.0.1:18740ともプロキシを通りませんでした。Chromeは72以降、ループバックを暗黙の除外ルールとしてプロキシの対象から外します（前掲のChromiumのプロキシ解説の「Implicit bypass rules」）。

TLSインスペクションする社内プロキシとCA証明書

通信を復号して検査するプロキシでは、社内CAを信頼させないとHTTPSが失敗します。0.35.0と0.39.0でCA証明書を指定できるようになりました（v0.39.0のリリースノート）。

• CLI自身の通信（read・install・upgrade・doctor）：全OSで--ca-cert <PEM>か、OSの信頼ストアを使う--use-system-caが効きます。CAファイルの明示指定や保持済み指定がなく、明示的に解除もしていなければ、SSL_CERT_FILEを読みます。--use-system-caとの併用も可能です。
• ブラウザ：--ca-certが効くのはLinuxで起動したChromiumだけです。セッション専用のNSSデータベースに取り込み、ホスト名と有効期限の検証は残します。certutilが要るので、install --with-depsかlibnss3-toolsを入れます。

macOSで--ca-cert付きのopenを実行すると、「--ca-cert browser trust is currently supported only on Linux (read, install, upgrade, and doctor accept it on every platform)」で止まりました。macOSとWindowsのChromeはOSの信頼ストアを使うので、MDMで配った社内CAで通ります。--ignore-https-errorsは改ざんを検知できなくなるため、本番の資格情報を扱うセッションでは使いません。

プロキシの切り替えと通信経路の確認

同じセッションで--proxyの値を変えると、ブラウザが再起動して新しいプロキシに切り替わりました。一方、次のコマンドでフラグを省いても、直前のプロキシは残ります。プロキシを外したいときは、環境変数と設定ファイルに残るプロキシ指定も解除し、agent-browser closeでセッションを閉じてから開き直します。

agent-browser --proxy "http://proxy.example.com:8080" open https://httpbin.org/ip
agent-browser get text body    # プロキシの出口IPが表示されれば経路は通っている

プロキシのログには、開いたページ以外にaccounts.google.com・update.googleapis.com・www.gstatic.comなど、Chrome自身の通信も載りました。これらは開いたページの読み込みとは別の通信です。プロキシのログを監査に回すなら、Chromeの背景通信とページ由来の通信を区別して集計します。監査用の原本は残し、宛先ドメインだけで一律に除外しないようにします。

Vercelの保護されたプレビューにAIエージェントを安全に接続する方法

Vercelのプレビューは、Deployment Protection（Vercel認証）でログイン画面へリダイレクトされます。agent-browserには、保護を外さずに通る手順書がprotected-vercel-deploymentsスキルとして同梱されています（0.35.0で追加）。保護の無効化、公開例外の作成、固定シークレットの要求は最初の手段にしない、という方針です。

export AGENT_BROWSER_SESSION="$(agent-browser session id --scope worktree --prefix vercel-preview)"
(
  TOKEN="$(vc project token my-app --scope my-team)"   # Vercel CLI 53.3.0以降
  test -n "$TOKEN" || exit 1
  agent-browser open "https://my-app-git-feature.vercel.app" --headers \
    "{\"x-vercel-trusted-oidc-idp-token\":\"$TOKEN\"}"
)
agent-browser snapshot -i

• 同じプロジェクトのPreviewなら、Vercel CLIが発行する短命のOIDCトークンで通ります。VercelのTrusted Sourcesは既定で、development環境からpreviewへの呼び出しを許可しています。
• スキルによると、Vercel CLIの50.25.0〜53.2.xはvc project tokenがトークンを標準エラーへ書くため、変数に入らずログに残るおそれがあります。53.3.0未満なら更新してから使います。
• ヘッダー名はx-vercel-trusted-oidc-idp-tokenです。x-vercel-oidc-tokenは関数へワークロードIDを渡すためのもので、保護の通過には使えません。
• Productionや別プロジェクトへ通すにはTrusted Sourcesのルール追加が要り、ダッシュボードでしか変えられません。エージェントに操作させず、人が設定します。

OIDCが使えないときの代替が、Protection Bypass for Automationのシークレットをx-vercel-protection-bypassヘッダーで送る方法です。有効化はアクセス制御の変更なので、先に権限者の承認を得ます。x-vercel-set-bypass-cookie: trueを足すと_vercel_jwtクッキーが作られるので、それを含む保存済みの状態ファイルは資格情報として扱います。Vercel自体の仕組みはVercel（ヴァーセル）とは？サーバー不要の仕組みとできること・料金【2026年】で解説しています。

agent-browserのセッション管理とログイン状態の保存

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

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で検出できます。0.37.0からは、新しく開いたタブにもヘッダーや資格情報などのセッション設定が引き継がれます。

状態ファイルは既定で平文

READMEは、保存される状態ファイルがセッショントークンを平文で含むと明記しています。暗号化キーを入れない限り、~/.agent-browser/配下のファイルを読めばログイン状態を持ち出せます。共有マシンやCIでは先に鍵を設定します。

# 初回に生成した鍵をシークレット管理へ保存し、復元時も同じ鍵を設定する
export AGENT_BROWSER_ENCRYPTION_KEY="${SAVED_AGENT_BROWSER_KEY:?保存済みの暗号化キーを設定してください}"   # AES-256-GCM用の64桁の16進
# doctor --fix は暗号化キー設定の代替ではない。修復が必要な場合だけ実行する
# agent-browser doctor --fix   # 鍵が無ければ ~/.agent-browser/.encryption-key を0600で作る（上書きはしない）

古い状態ファイルはAGENT_BROWSER_STATE_EXPIRE_DAYS（既定30日）を過ぎるとdoctor --fixで消されます。使い捨ての操作なら--restoreを付けず、終わったらclose --allで落とすほうが安全です。

agent-browserのMCPサーバー起動とツール範囲

agent-browser mcp                        # 既定のcoreプロファイル
agent-browser mcp --tools core,network   # 必要な範囲だけ足す
agent-browser mcp --tools all            # CLIとほぼ同じ範囲を公開

プロファイルはcore・network・state・debug・tabs・react・mobile・webmcp・allの9種です。allはeval・クッキー・認証・install・upgradeまで公開するので、モデルが誤って触れる範囲も最大になります。既定のcoreで始め、必要な分だけ足します。MCPで外部ツールを渡すときの危険性はPlaywright MCPのセキュリティ｜危険性とCVE-2025-9611対策が参考になります。

0.36.0からは、ページ自身が公開するツールを呼べる実験的なWebMCPに対応しました。ローカルで起動したChromeでは既定で有効で、--no-webmcpかAGENT_BROWSER_NO_WEBMCPで止められます。自作エージェントから子プロセスでagent-browser ... --jsonを呼ぶ形も一般的です（Vercel AI SDK v6とは？新機能（ToolLoopAgent・needsApproval）とv7との違い・移行【2026】のツール定義から呼べます）。業務に組み込むエージェントの設計はAIエージェント開発でも支援しています。

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

エージェントの操作権限と通信先の制限

--allowed-domainsは遷移だけでなく、許可外ドメインへのスクリプト・fetch・WebSocket・sendBeaconも遮断します。ただし公式のSecurityページのとおり、WebSocketなどの遮断はコンストラクタの差し替えによるベストエフォートで、OSのファイアウォールの代わりにはなりません。--action-policyでevalを禁止し、ホストやネットワーク側の送信制御と組み合わせます。また--cdpでの既存Chromeへの接続、--auto-connect、Chromeプロファイル、状態の復元とは併用できません。0.39.1からは、応答が途中で失われた変更系コマンドは自動で再実行されず、outcome_unknownが返ります。エージェント側は結果を確かめてから再試行する作りにします。

クラウド実行と手元のChromeへの接続

並列数を増やす、手元にブラウザを置けないといった場合は、-p（--provider）でBrowserless・Browserbase・Browser Use・Kernel・AWSのAgentCoreに寄せます。Python中心ならBrowser Useとは？使い方・料金・Playwright MCPとの違いまで実装ガイド【2026年版】も候補です。ログイン済みの手元のChromeを使うなら--cdp 9222か--auto-connectで、0.39.0からはChrome 144以降のリモートデバッグ許可ダイアログを最大30秒待ちます。

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

CIの回帰テストには使いません。合否判定を持つPlaywrightやCypressの領分です。

短命なサーバーレス関数の中で毎回起動する使い方も合いません。常駐デーモン前提の設計なので、呼び出しごとに破棄される環境では毎回Chromeの起動を待ちます。Vercel上ならVercel Sandboxか外部プロバイダへ逃がします。

手順が一切変わらない定型処理にLLMを挟む理由はありません。決め打ちのスクリプトのほうが速く、壊れたときの原因も追えます。

よくある質問

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

--proxy "http://proxy.example.com:8080"を付けるか、AGENT_BROWSER_PROXYを設定します。認証はAGENT_BROWSER_PROXY_USERNAMEとAGENT_BROWSER_PROXY_PASSWORDで分けて渡せ、除外は--proxy-bypassかNO_PROXYです。標準のHTTP_PROXYなどは、それらが無いときだけ使われます。

agent-browser install がプロキシ環境で失敗するのはなぜですか？

installは--proxyを使いません。シェルにHTTPS_PROXYを設定し、googlechromelabs.github.ioとstorage.googleapis.comへの通信を許可してください。TLSを復号する社内プロキシなら--ca-certか--use-system-caを足します。

Windowsでも使えますか？

使えます。x64のバイナリが配布され、ARM64機ではネイティブ版が無ければx64版をエミュレーションで動かします。画面を出したいときは--headedを付けます。

npxとグローバルインストール、brewのどれが良いですか？

試すだけならnpx agent-browserで足ります。エージェントに繰り返し叩かせるなら、呼び出しごとのパッケージ解決が挟まらないnpm install -g agent-browserかbrew install agent-browserです。

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

いいえ。CLIとデーモンはRustで実装され、ChromeへCDPで直接つながります。Rust製デーモン自体はNode.jsに依存しませんが、npm・npxで導入する場合はNode.jsが必要です。0.39.1のnpmパッケージはNode.js 24以降を要求しています。

Vercelのプレビューをエージェントに安全に開かせるには？

Deployment Protectionは外さず、vc project token（Vercel CLI 53.3.0以降）で得た短命のOIDCトークンをx-vercel-trusted-oidc-idp-tokenヘッダーでagent-browser openに渡します。Productionへ通すルールの追加は人がダッシュボードで行います。

関連記事

• Playwright（プレイライト）とは？仕組み・できること・Seleniumとの違いを解説
• Playwright MCPとは？設定・使い方からDify連携まで実務ガイド【2026年版】
• Stagehandとは｜AIブラウザ自動化の使い方とPlaywrightとの違い【v3対応】
• Chrome DevTools MCPの導入手順と設定｜58ツールの絞り込みと接続方式を実装目線で解説
• Browser Useとは？使い方・料金・Playwright MCPとの違いまで実装ガイド【2026年版】