agent-browser

Agent Browser

エージェントが見ているものを確認しましょう。

AI エージェント向けのセルフホスト可能な Chrome。
エージェントは実際のブラウザーセッションを1つ操作します。その様子を見たり、途中で操作に加わったりできます。

クイックスタート · API · MCP · セキュリティモデル · Node クライアント · Python クライアント · コントリビューション · 変更履歴

_{18秒間の録画デモです。エージェントはサインインし、答える手段のない二要素認証のプロンプトに到達すると停止します。人間が表示されたセッションにコードを入力すると、エージェントは処理を続行します。
記録の出所、チェックサム、独立して検証可能な制限事項については、ドキュメントに記載しています。  ·  録画方法}

このプロジェクトの目的

エージェント向けのブラウザーツールの多くは、人間には見えないブラウザーをモデルに渡します。ページの読み違いやログイン時の停止が起きても、手元に残るのは記録と推測だけです。

Agent Browser は画面表示ありの Chrome セッションを1つ実行します。エージェントは小規模な JSON API を通じてそのセッションを操作し、同じセッションのライブ画面が目の前に表示されます。エージェントが行き詰まったら、すでに使用中のウィンドウで操作を引き継ぎ、その後エージェントに戻せます。

ランタイムを起動します。

docker compose up --build

あとは、好きな方法で接続できます。

npm install aether-browser    # TypeScript
pip install aether-browser    # Python
claude mcp add agent-browser -- npx -y aether-browser mcp    # any MCP client

クイックスタート

Compose v2 を使用した Linux の Docker Engine で、コマンドを1つ実行します。ソースのチェックアウトからビルドし、Xvfb、x11vnc、noVNC、API を起動します。これらは画面表示ありの Chrome セッションを1つ管理するスタックです。ユーザー向けの両方のリスナーは、数値形式のループバックアドレスにバインドされます。

docker compose up --build

ヘルスチェックに応答があったら、ライブ画面を 127.0.0.1:6080/vnc.html で開き、別のターミナルから API を確認します。

curl -fsS http://127.0.0.1:8092/browser/health | jq .

Ctrl+C で停止します。

初回のビルドには数分かかります。 ハッシュで固定された Python 環境をインストールした後、Patchright を使用して最新の Google Chrome Stable パッケージをインストールします。採用された各イメージには正確なブラウザーのバージョンが記録されるため、後日同じソースを再ビルドしても、より新しい Stable が取得される場合があります。

Linux ホストネットワークの使用は意図的なものです。 認証のない v0.x の noVNC を数値形式のループバックに限定できます。Docker Desktop とリモートホストへのデプロイは、このクイックスタートの対象外です。

4 回の呼び出しで使う API

ランタイムが正常に動作し、curl と jq がインストールされていれば使えます。設計上、ローカルのループバック接続にベアラートークンは不要です。デプロイ形態を変更する前に、権限の契約をお読みください。

# Open the session. This is the browser you are about to watch.
SESSION_ID="$(curl -fsS -X POST http://127.0.0.1:8092/browser/session/create \
  -H 'Content-Type: application/json' \
  -d '{"api_version":"v1"}' | jq -er '.session_id')"

# Go somewhere. The page changes in the live view as this runs.
curl -fsS -X POST http://127.0.0.1:8092/browser/navigate \
  -H 'Content-Type: application/json' \
  -d "{\"api_version\":\"v1\",\"session_id\":\"${SESSION_ID}\",\"url\":\"https://example.com\"}" \
  | jq '{status, final_url, title, readable_text}'

# Read it back as structure, not pixels.
curl -fsS -X POST http://127.0.0.1:8092/browser/snapshot \
  -H 'Content-Type: application/json' \
  -d "{\"api_version\":\"v1\",\"session_id\":\"${SESSION_ID}\"}" \
  | jq '{status, url, title, sequence, vision_steps_remaining}'

# Give the browser back.
curl -fsS -X POST http://127.0.0.1:8092/browser/session/end \
  -H 'Content-Type: application/json' \
  -d "{\"api_version\":\"v1\",\"session_id\":\"${SESSION_ID}\"}" | jq .

実行した内容：session/create がヘッド付きの Chrome セッションを開始し、その UUID とローカル表示用 URL を返しました。navigate は遷移先を検証し、許可されたアドレスを固定して、共有ディスプレイ上のページを切り替えました。snapshot は、同じページの上限付きテキスト、アクセシビリティの状態、ビューポートのメタデータ、カウンター、PNG を返しました。API と人間向けの表示が別々のブラウザーを立ち上げることは一度もなく、どちらも同じ所有セッションを利用しました。

同じフローは examples/curl.sh としても提供されています。

MCP クライアントから使う

Claude Code、Claude Desktop、Cursor、Windsurf など、どの MCP クライアントからでもセッションを操作しながら画面を確認でき、行き詰まったときは操作を引き継げます。

claude mcp add agent-browser -- npx -y aether-browser mcp

すでに Python クライアントをお使いの場合は、aether-browser mcp で同じ 9 つのツールを利用できます。

{
  "mcpServers": {
    "agent-browser": {
      "command": "npx",
      "args": ["-y", "aether-browser", "mcp"]
    }
  }
}

9 つのツール — browser_open · browser_navigate · browser_read · browser_click · browser_type · browser_press · browser_scroll · browser_status · browser_close

browser_open はライブ表示用 URL を返し、それ以降のすべての応答にも同じ URL が含まれるため、常に確認すべき場所がわかります。接続時、サーバーはモデルに対し、ログイン、支払い、または 2FA プロンプトが表示された場合は推測せず停止し、操作を引き継ぐよう求めます。これは上の録画にある一連の動作です。

セットアップと制限事項については、docs/MCP.mdをご覧ください。

Node および TypeScript クライアント

型と、忘れずに実行できるクリーンアップを備えた、Node からの同じ API です。

npm install aether-browser

import { AgentBrowser, withSession } from 'aether-browser'

const browser = new AgentBrowser({ controllerToken: process.env.AGENT_BROWSER_CONTROLLER_TOKEN })

await withSession(browser, async (session) => {
  const page = await session.navigate('https://example.com')
  await session.click({ selector: '#login' })
  await session.type({ selector: '#user', text: 'ada' })
  console.log(page.title, session.viewUrl)
})

withSession は、コールバックが例外をスローした場合も含め、必ずセッションを終了するため、クラッシュしても唯一のスロットが占有されたままになりません。ランタイム依存関係はなく、サーバーに接続できる環境ならどこでも実行できます。小規模な CLI も付属しています。初回実行前に不足しているものを確認するには npx aether-browser doctor を、Linux ホストでランタイムをビルドして起動するには up を実行します。

clients/node/README.mdをご覧ください。

Python クライアント

同じクライアント、同じ名前、同じコマンドを、npm パッケージと同じバージョンごとにリリースしています。

pip install aether-browser

import os

from aether_browser import AgentBrowser, session

browser = AgentBrowser(controller_token=os.environ["AGENT_BROWSER_CONTROLLER_TOKEN"])

with session(browser) as live:
    page = live.navigate("https://example.com")
    live.click(selector="#login")
    live.type("ada", selector="#user")
    print(page["title"], live.view_url)

session コンテキストマネージャーは、本文で例外が発生した場合も含め、必ずセッションを終了します。ランタイム依存関係はなく、標準ライブラリの urllib をトランスポートに使用し、型ヒントを備えています。Python 3.10 以降で、サーバーに接続できる環境ならどこでも実行できます。CLI は npm パッケージと同じです。aether-browser doctor、up、status、open、down を利用できます。

clients/python/README.mdをご覧ください。

オプションの Jev ウェブ判定（Python）

Python クライアントには、Jev → 選択したモデルのためのオプトイン型 aether_browser.jev レイヤーがあります。 Jev は呼び出し側が選択したテキスト抜粋を読み、呼び出し側が承認した最大 3 つの URL、制御の引き継ぎ、または人間による操作のいずれかを選択します。ブラウザーが移動するのは呼び出し側が指定した URL だけであり、通常の移動先チェックも引き続き適用されます。制御を引き継ぐ際、コールバックには現在のページの証拠と、Jev のリクエスト ID、トークン数、コストが渡されます。アプリケーションは選択した推論モデルを呼び出して、文章の作成、分析、またはブラウジングの続行を行います。Jev が返すのは判定であり、文章や視覚的な判断ではないため、スクリーンショットや複雑なページ操作は、選択したモデルまたはライブブラウザーを見ている人間に任せます。

import os

from aether_browser import AgentBrowser, session
from aether_browser.jev import HumanTakeover, JevWebAgent, NavigationOption, OpenRouterJev

browser = AgentBrowser(controller_token=os.environ["AGENT_BROWSER_CONTROLLER_TOKEN"])
with session(browser) as live:
    first_page = live.navigate("https://example.com")
    result = JevWebAgent(OpenRouterJev(os.environ["OPENROUTER_API_KEY"])).run(
        live,
        goal="Read the site's documentation",
        initial_page=first_page,
        options_for=lambda page: (
            [NavigationOption("https://example.com/docs", "Official documentation")]
            if page["final_url"] == "https://example.com/"
            else []
        ),
        excerpt_for=lambda page: page["readable_text"][:6000],
        selected_model=lambda handoff: your_model(handoff),  # Supply your own model callback.
    )
    if isinstance(result, HumanTakeover):
        print("Take control at", result.view_url)
        input("Press Enter when the human is done to close this session: ")
    else:
        print(result)

この例の your_model はアプリケーション定義の関数であり、このパッケージには含まれていません。excerpt_for コールバックは OpenRouter に送信するテキストを明示的に選択し、options_for は候補 URL を明示的に選択します。アプリケーションがそのプロバイダーへの送信を意図していない限り、非公開のページコンテンツや署名付き URL を返さないでください。OpenRouter のキーは呼び出し元のプロセスに保持され、ブラウザーサーバーには保存されません。このオプションのレイヤーを呼び出さない限り、Jev リクエストは発生しません。Jev が失敗するか無効な判定を返した場合、選択したモデルのコールバックには reason="jev_unavailable" を伴う制御の引き継ぎが渡され、ブラウザーはそれ以上の操作を行いません。認証ページや支払いページと認識された場合、Jev にテキストが渡される前に人間による操作を促します。セッションはコードが所有したままです。人間が操作を引き継いでいる間は、セッションを開いたままにしてください。契約と制限の全容については、docs/JEV.md を参照してください。

特長

• 1 つのセッション、2 人の参加者。 エージェントは JSON を通じて操作します。同じ画面を見ながら、いつでも操作を引き継げます。
• ピクセルより先に構造。 スクリーンショットに対する視覚処理を行う前に、読み取り可能なテキストと上限付きのアクセシビリティツリーが返されます。
• 小さな操作インターフェース。 v0.x API が公開するのは明示的なブラウザー操作であり、シェルでも、任意の JavaScript でも、生の DevTools でもありません。
• モデル非依存でセルフホスト可能。 すでに利用しているフレームワークを使い、管理下にあるハードウェアでブラウザーを実行できます。

現在できること

リクエストとレスポンスの形式、制限、安定したエラーコードについては、docs/API.md を参照してください。

アーキテクチャ

flowchart LR
    Agent["Agent client"] -->|bounded JSON API| API["FastAPI"]
    API --> Guard["authority + navigation policy"]
    Guard --> Session["single-session manager"]
    Session --> Chrome["Patchright + headed Google Chrome"]
    Chrome --> State["text · accessibility · PNG"]
    State --> Agent
    Chrome --> Display["shared Xvfb display"]
    Display -->|loopback noVNC| Human["Human observer / takeover"]

セッションマネージャーは、ページ、ブラウザーコンテキスト、一時プロファイル、タイマー、カウンター、クリーンアップを管理します。API とライブ表示は、共有リソースに対する別々のインターフェースであり、独立した 2 つの自動化経路ではありません。docs/ARCHITECTURE.md を参照してください。

重要

Agent Browser v0.2.3 はソースコード優先のセルフホスト型です。 ホステッドサービスではありません。また、v0.x の noVNC インターフェースは認証されておらず、管理下にあるマシンの数値形式のループバックアドレスでの利用を想定しています。 Chrome を含むイメージ、イメージ tar、公開レイヤーキャッシュは、別途再配布の許可が文書化されていない限り配布されません。

セキュリティ境界

• API と noVNC はデフォルトで数値形式のループバックアドレスをリッスンします。v0.x 系では noVNC は引き続きループバックのみで利用できます。
• リモート API クライアントには、別途運用される同一ホスト上の HTTPS リバースプロキシ、信頼できる正確なループバックピア、厳格な Host 検証、そして区別された強力なオブザーバー用／コントローラー用トークンが必要です。
• 宛先の検証では、認証情報、未サポートのスキーム、ブロック対象のアドレスクラス、安全でないリダイレクト、DNS リバインディングを拒否します。ブラウザーの外向き通信は、所有する TCP プロキシを経由するよう固定されます。
• TCP の外向き通信境界を暗黙に迂回できないよう、プロキシを経由しない WebRTC UDP は無効になっています。
• 入力、出力、操作、タイムアウト、ライフタイム、スクリーンショットの予算には上限があります。
• セッション終了、期限切れ、起動失敗、アプリケーションの終了、プロセス障害のいずれの場合も、クリーンアップが収束します。

信頼に関する前提と残存リスクについては、docs/SECURITY.md に詳述されています。脆弱性は SECURITY.md を通じて非公開で報告してください。公開のセキュリティ課題は作成しないでください。

ソースの再利用と除外対象

ソース再利用のルールは、非公開のドメイン固有コードではなく、汎用的なブラウザーの挙動を再利用することです。 ライフサイクル、構造化状態、操作、クリーンアップのパターンは、承認された参考資料から適用できます。一方、ATS／取引連携、ブローカーまたはアカウントのセレクター、注文操作、シークレット、認証情報の注入は、公開コアから除外されます。出典のステータスは docs/SOURCE-RECOVERY.md で追跡されています。

対応しないこと

• ホスト型クラウドサービス、クラウド制御プレーン、本番環境でのリモートホスティングに関する主張はありません。
• 同梱 LLM やデフォルトのモデル呼び出し、アカウントシステム、ダッシュボード、認証情報保管庫、認証情報の注入はありません。
• CAPTCHA の回避、アンチ検出の保証、ステルスに関する主張、プロキシのローテーションはありません。
• 任意の JavaScript、シェル、ファイルシステム、アップロード、クリップボード、ダウンロード、raw CDP API はありません。
• 複数セッションのプール、ATS 連携、取引連携、証券会社関連の機能はありません。

ロードマップ

リリース済み。 両方のクライアントとその CLI は、clients/node から npm に、clients/python から PyPI に、それぞれ同じバージョンで aether-browser として公開されています。 0.2.0 以降は、どちらも MCP サーバーを提供しています。

課題が登録されている、取り組み可能なトラックが 2 つあります。どちらも初めての貢献に適しています。

1. 複数セッションのワーカープール — 明確な分離と容量のセマンティクス。
2. セッショントレースと記録のエクスポート — 明確なプライバシー制御を備えます。

これらは候補であり、リリース済みの機能ではありません。

貢献

まず CONTRIBUTING.md、行動規範、現在の API 契約 をご確認ください。権限の境界を狭く保つ、小規模で十分にテストされた変更を歓迎します。最初の貢献には、上記のロードマップにある 2 つの課題が最適です。セキュリティ報告は、公開の課題ではなく、SECURITY.md に記載された非公開のプロセスを通じてお寄せください。

ライセンスとサードパーティに関する告知

Aether が所有するソースコードは Apache License 2.0 に基づいてライセンスされています。Google Chrome は別途 Google の Chrome 利用規約に基づいてライセンスされており、Aether の Apache ライセンスの対象ではありません。依存関係、システムパッケージ、フォント、ウェブアセットも、それぞれの利用規約に従います。詳細は THIRD_PARTY_NOTICES.md をご覧ください。 Aether は Google とは提携しておらず、Google からの推奨も受けていません。v0.x の配布対象はローカルでビルドするソースコードです。このリポジトリでは、Chrome を含むビルド済みイメージは配布していません。

_{Agent Browser · エージェントが見ているものを見ましょう。}