agent-browser 入門 ~ AIエージェントのためのブラウザ自動化CLI ~

はじめに

株式会社パレットリンクの@t-yonefuです。早速これは個人的な意見なのですが、開発で一番面白くない工程ってテスト工程だと思いませんか？コーディングは技量が伴えば早く済みますが、テストに関してはそうはいかず、かと言って飛ばすこともできないので大変面倒だなと思います。最近はAIを使ってテストの自動化をするようになったのですが、今一度整理しつつ、普段お世話になっているツールを紹介します。

エージェントによるブラウザ自動化とは

エージェントによるブラウザ自動化とは、Cursor や Claude Code などのコーディングエージェントが、ブラウザを開き、ページを読み、クリックや入力を繰り返すことです。長い E2E を先に書かずに「この URL を開いて確認して」と頼むことでテストや修正を簡略化することができます。
本稿では、エージェントによるブラウザ自動化の一例として agent-browser の概要と使い分けを扱います。

agent-browser とは

agent-browser（Vercel Labs）は、Rust 製のブラウザ自動化 CLI です。Chrome を CDP（Chrome DevTools Protocol）で直接制御し、ページをアクセシビリティツリー(ウェブページの構造/DOMからツールが解析しやすくしたもの)に要約してエージェントに渡します。

項目	内容
リポジトリ	vercel-labs/agent-browser
形態	ネイティブ Rust CLI + 常駐デーモン
ブラウザ	Chrome for Testing（CDP）
想定ユーザー	Cursor、Claude Code などの AI エージェント

インストールは次の2行で行えます。

npm install -g agent-browser
agent-browser install   # Chrome for Testing を取得（初回のみ）

agent-browser doctor で環境診断、agent-browser upgrade で更新ができます。

アーキテクチャ：CLI + デーモン + CDP

agent-browser は以下の図のようなクライアント・デーモンで構成されています。

1. Rust CLI — コマンドをパースし、デーモンに依頼する
2. Rust Daemon — ブラウザセッションを保持。Node.js ランタイムは不要
3. Chrome — CDP で操作。初回は agent-browser install で Chrome for Testing を取得

初回コマンドでデーモンが起動し、以降のコマンドは同じブラウザセッションを再利用するため、連続操作が速いのが特徴です。

スナップショットと ref：ページの「見取り図」

agent-browser がエージェントに返すのは、HTML全文ではなくスナップショット（エージェントが操作しやすい形にしたテキスト）です。画面上のボタン・入力欄・リンクなど、人が操作できる部分を中心に、アクセシビリティツリーとして短くまとめたものです。ボタンや入力欄には @e1、@e2 のように ref（参照番号）が付き、エージェントは「いま画面にある3番のボタンを押す」といった形で操作を指示できます。

ポイントは次の2つです。

• 毎回「いまの画面」を見る — エージェントは操作のたびにスナップショットを取り直し、そこに書かれた ref だけを使う。あらかじめ DOM の構造を覚えておく必要がない。
• ref はその場限り — リンクを踏んで画面が変わったり、フォーム送信後に表示が切り替わったりすると、以前の @e3 はもう存在しないことがある。だから「一度見て → 操作 → また見る」という短いサイクルが基本になる。

人間がブラウザを触るときと同じで、目で確認してから手を動かすイメージに近い設計です。HTMLを丸ごと解析させるより、トークンを抑えつつ、操作対象をはっきりさせることができます。

他のツールとの比較

いずれもブラウザをプログラムから動かす点は同じです。整理の軸は、誰が手順を決めるか（人間が書いたテストか、エージェントか）と、エージェント向けの公式の入り口があるかです。

ツール	形態	誰が使う	ページの見え方	向いていること
Playwright（テスト API）	@playwright/test などの Node ライブラリ	開発者	コード内のセレクタ・ロケータ	.spec.ts を書き、npx playwright test で回帰テスト。テストケースを資産として残す
playwright-cli	ターミナル CLI（@playwright/cli）	エージェント	スナップショット + eN ref	シェルから短いコマンドで操作。触った流れを Playwright テストコードに落としやすい
Playwright MCP	MCP サーバー	エージェント	ツール経由（スナップショット、HTML全体等）	MCP で操作。（トークンは CLI より重めになりがち）
Puppeteer	Node ライブラリ	開発者	自分で書いたセレクタ	小さな自動化・スクレイピング（公式のエージェント用 CLI はなし）
agent-browser	Rust CLI + デーモン	エージェント	スナップショット + @eN ref	その場確認を素早く回す。Vault やドメイン制限などエージェント運用向けの機能が厚い

Playwright には入り口が3つあります。いずれも同じエンジンの上で動きますが、目的や操作方法が違います。

Puppeteer は Node から Chrome を操るライブラリで、エージェント操作でなく、自分でスクリプトに書く前提のツールです。

エージェント向け：playwright-cli と agent-browser

どちらも「スナップショットを見て ref で触る」基本は同じです。差をまとめると以下の表のようになります。

観点	playwright-cli	agent-browser
土台	Playwright 公式（Node）	Vercel 製の Rust CLI（Playwright 不要）
ブラウザ	Chrome / Firefox / WebKit / Edge	Chrome（CDP）
強み	操作から Playwright テストを生成、マルチブラウザ	React / Web Vitals、ページ差分（diff）、エージェント向けの安全機能の一式

また、ログイン処理などのセキュリティ面で差がありますが、そちらは次章に記載します。

ログイン状態の保存

一度ログインしたあと、Cookie や localStorage などを JSON に書き出して次回から使い直すやり方は、Playwright でもよく使われます。

	Playwright（テスト API）	playwright-cli	agent-browser
仕組みの名前	storageState	state-save / state-load	state save / state load（--state で読み込み）
ファイル例	playwright/.auth/user.json など	任意の JSON	任意の JSON
中身	ログイン済みセッション（Cookie 等）	同左	同左

いずれも「パスワードを JSON に書く」わけではなく、ブラウザが保持しているセッション情報を再利用するイメージです。Playwright テストでは global setup で一度ログインして JSON を作り、以降のテストで storageState を指定するパターンが定番です。

セッション JSON だけではログインは完結しません。Cookie の期限切れやログアウトなどでセッションが切れると、保存した JSON は使えなくなり、もう一度ログインする必要があります。Playwright では global setup の再実行や、環境変数・CI の secrets から資格情報を渡してログインし直すのが一般的です。agent-browser でも後述の機能を使わない場合は同様で、初回ログインやセッション切れのたびに、エージェントが画面を見ながらログイン手順を踏む（または人が一度ログインしてから state save する）形になります。

agent-browser だけの追加層として Auth Vault（auth save / auth login）があります。ユーザー名・パスワードを ~/.agent-browser/auth/ に暗号化して保持し、セッション切れ時に auth login で CLI がフォーム入力まで任せられるため、毎回エージェントにログイン手順を説明し直す負担を減らす用途向きです。セッション JSON と併用してログイン/セッション管理を簡略化できます。

使い分けの目安

ざっくり言うと、Playwright は「形式としてテストを残す」、agent-browser は「その場の確認を素早く回す」に向きます。

Playwright（テスト API / playwright-cli）は、ログインや購入フローなどを決まった手順として固定し、テストケースや .spec.ts などの資産として残すときに有効です。CI で同じ条件を繰り返し検証したり、リグレッションを追いかけたりする形式的なテストに向いています。

agent-browser は、あらかじめ長いテストを書き切るより、エージェントがスナップショットを見ながら短いループで進める運用に合います。Rust 製の CLI + 常駐デーモンで起動や連続操作が軽く、Auth Vault があればセッション切れ時の再ログインも CLI 側に寄せられるため、仕様変更のたびにテストコードを直すより、アジャイル的に「いま動くか」を確認する場面で効きやすいです。

やりたいこと	向いている選択
テストケースを残し、CI で同じ手順を何度も検証したい	Playwright（テスト API。必要なら playwright-cli でコード生成）
回帰やリリース前の形式的な品質担保が目的	Playwright
エージェントに「この画面を確認して」とその場で素早く試したい	agent-browser
ログインや確認をテスト資産化せず、反復しながら進めたい（アジャイル寄り）	agent-browser
セッション切れ時も Vault で再ログインを CLI に任せたい	agent-browser
触った流れを Playwright のテストコードに落としたい	playwright-cli

AIエージェントとの統合

agent-browser には多くのコマンドがありますが、本稿ではコマンドの詳細には踏み込みません。エージェントが Rules や Skills として手順を取り込み、対話的に進める想定のためです。

以下に Rules の例を示します。プロジェクトの Rules などとして取り込み、必要に応じて追記・調整してください。

Rules：バージョンと同期する手順の例

---

alwaysApply: true

---


# ブラウザ自動化（agent-browser）の利用ルール
ブラウザの操作、E2E テスト、または Web スクレイピングを実行する際は `agent-browser` を使用してください。
タスクを開始する前に、必ず以下のコマンドを実行して最新のワークフロー仕様（スキル）を取得し、その内容に厳密に従ってください：

`agent-browser skills get core`

agent-browser skills get core を実行すると、インストール済みの agent-browser のバージョンに一致した仕様が取得できます。リリースごとに内容が変わる可能性があるため、実行時に取得する方法が推奨されています。

まとめ

本稿で押さえたポイントは次のとおりです。

agent-browser とは、Rust 製の CLI が Chrome を CDP で動かし、ページをスナップショット（テキストの見取り図）と @eN ref でエージェントに渡すツールです。HTML 全文ではなく「いま触れるもの」に絞ることで、エージェントが「見る → 操作する → また見る」短いループで進められます。

Playwright との関係では、どちらもブラウザ自動化ですが役割が違います。Playwright はテストケースや spec を形式的に残し CI で繰り返すのに向き、agent-browser はエージェントがその場で素早く確認する（アジャイル寄り）のに向きます。ログイン済み状態の JSON（storageState / state save）は両方にあり、Auth Vault は agent-browser 固有で、セッション切れ時の再ログイン負担を減らす任意の層です。Vault がなくても使えますが、その場合は Playwright と同様に都度ログイン手順が必要になります。

運用面では、Cursor などでは Rules や agent-browser skills get core で手順を CLI バージョンと揃えられます。必要に応じてドメイン制限や Vault など、エージェントに何を触らせるかも設計できます。

agent-browser は Playwright の置き換えではなく、「テスト資産より、いま動くかをエージェントと早く確かめたい」ときの選択肢のひとつです。playwright-cli / MCP と併用するプロジェクトも現実的です。

さいごに

パレットリンクでは、日々のつながりや学びを大切にしながら、さまざまなお役立ち記事をお届けしています。よろしければ、ぜひ「Organization」のページもご覧ください。
また、私たちと一緒に未来をつくっていく仲間も募集中です。ご興味をお持ちの方は、ぜひお気軽にお問い合わせください。一緒に新しいご縁が生まれることを楽しみにしています。

参考リンク

• GitHub — vercel-labs/agent-browser
• Playwright