browser-use

Make websites accessible for AI agents — v0.12.3 · Python 3.11+

1 — 概要

何をするライブラリか

browser-use は、自然言語のタスクを受け取り、LLM がブラウザ操作（クリック・入力・ナビゲート等）を自律的に選択・実行する Python ライブラリ。Chrome DevTools Protocol（CDP）経由でブラウザを制御し、DOM スナップショットとスクリーンショットを LLM に渡しながら目標達成まで反復する「ブラウザ自律エージェント」を手軽に構築できる。

CDPブラウザ制御

3.11+Python

async実行モデル

MCP外部連携

対応 LLM は OpenAI・Anthropic・Google Gemini・LiteLLM・Ollama など多数。ローカル Chrome からクラウドブラウザまで対応し、カスタムアクションの追加や MCP サーバーとの統合もサポートする。

公開名の対応: コード上の BrowserSession は公開 API では Browser エイリアス、Controller は Tools エイリアス（v0.12 からリネーム）。既存コードで Controller を使っている場合も動作する。

2 — アーキテクチャ

エージェントループ（1 ステップの流れ）

Agent.run() が max_steps 回までステップを繰り返す。各ステップは「状態取得 → LLM 推論 → アクション実行」の 3 フェーズで構成される。

flowchart TD
  Task["タスク (自然言語)"]
  Run["Agent.run()"]
  Step["step()  ×  max_steps"]
  Ctx["_prepare_context\nDOM + スクリーンショット取得\nMessageManager で会話組み立て"]
  LLM["_get_next_action\nllm.ainvoke() → AgentOutput\n思考・目標・action リスト"]
  Act["multi_act(actions)\nアクションをバッチ実行"]
  Tools["Tools.act()\nRegistry.execute_action()"]
  Browser["BrowserSession\nCDP / EventBus"]
  Done["完了 (is_done = true)"]

  Task --> Run --> Step --> Ctx --> LLM
  LLM -->|"継続"| Act --> Tools --> Browser
  Browser -->|"次ステップへ"| Step
  LLM -->|"is_done"| Done

  classDef agentCls fill:#e0f2fe,stroke:#0891b2,color:#0f172a,rx:6
  classDef llmCls fill:#f0fdf4,stroke:#16a34a,color:#0f172a,rx:6
  classDef browserCls fill:#fff7ed,stroke:#c2410c,color:#0f172a,rx:6
  classDef ioCls fill:#f8fafc,stroke:#64748b,color:#374151,rx:6
  class Run,Step,Ctx,Act agentCls
  class LLM llmCls
  class Tools,Browser browserCls
  class Task,Done ioCls

multi_act の二重ガード

複数アクションのバッチ処理では 2 段階の安全機構が働く。静的フラグ: terminates_sequence=true が付いたナビゲーション系アクション（search / navigate 等）が実行されると、それ以降のアクションをスキップ。動的検知: URL またはフォーカス対象タブが変わった場合も残りをスキップし、古い DOM への誤操作を防ぐ。

補助ロジック

ループ検知 — ActionLoopDetector で同一アクションの繰り返しを検知して脱出
プランニング — enable_planning=True で LLM がステップごとに計画を更新
ジャッジ — use_judge=True で完了後に別 LLM がトレースを評価
メッセージ圧縮 — MessageCompactionSettings で長い会話履歴を圧縮してトークンを節約

3 — モジュール構成

browser_use/ 以下のディレクトリ

パス	役割
`agent/`	`Agent` のメインループ・`MessageManager`（プロンプト組み立て）・`AgentOutput` / `ActionResult` などビュー定義・システムプロンプト
`browser/`	`BrowserSession`（CDP + EventBus の 2 層アーキテクチャ）・`BrowserProfile`・クラウドブラウザ対応・watchdog
`tools/`	`Tools`（旧 `Controller`）・`Registry`・カスタムアクション登録・`act()` 実行
`dom/`	DOM ツリー取得・セレクタマップ・LLM 向け表現への変換
`llm/`	`BaseChatModel` Protocol と各プロバイダ実装（OpenAI / Anthropic / Google / LiteLLM / Ollama 等）
`filesystem/`	エージェント用ファイルシステム抽象（ファイル読み書き操作）
`mcp/`・`integrations/`	MCP（Model Context Protocol）連携・外部サービス統合
`telemetry/`	PostHog を使った利用状況イベント送信
`tokens/`	LLM トークンコスト集計
`config.py`	環境変数・API URL・XDG キャッシュパスなどグローバル設定（`CONFIG` オブジェクト）
`cli.py`・`skill_cli/`	CLI エントリポイント（`browser-use` コマンド）

4 — 使い方

インストール

pip install browser-use
playwright install chromium

最小構成

import asyncio
from browser_use import Agent, Browser, ChatBrowserUse

async def main():
    browser = Browser()
    agent = Agent(
        task="browser-use リポジトリのスター数を調べて",
        llm=ChatBrowserUse(),
        browser=browser,
    )
    result = await agent.run()
    print(result)

asyncio.run(main())

カスタムアクションの追加

@tools.action デコレータでアクションを登録し、Agent に渡す。LLM はこのアクションをブラウザ操作と同列で選択できるようになる。

from browser_use import Agent, Tools

tools = Tools()

@tools.action(description='指定した文字列を外部 API で検索して返す。')
def external_search(query: str) -> str:
    # 実際には API 呼び出し等
    return f"検索結果: {query}"

agent = Agent(
    task="external_search を使って Python の最新バージョンを調べる",
    llm=llm,
    browser=browser,
    tools=tools,
)

5 — 主要 API

Agent コンストラクタ（主なオプション）

引数	型	説明
`task`	`str`	自然言語のタスク指示（必須）
`llm`	`BaseChatModel`	使用する LLM。省略時は `ChatBrowserUse()`
`browser` / `browser_session`	`Browser`	ブラウザセッション（省略時は自動起動）
`tools`	`Tools`	カスタムアクション群（旧 `controller`）
`use_vision`	`bool`	スクリーンショットを LLM に渡す（デフォルト true）
`max_actions_per_step`	`int`	1 ステップで実行する最大アクション数
`enable_planning`	`bool`	ステップごとのプランニングを有効にする
`sensitive_data`	`dict`	パスワード等のマスクデータ（LLM に渡さない値）
`initial_actions`	`list`	最初に実行する固定アクション
`override_system_message`	`str`	システムプロンプトをまるごと差し替え
`extend_system_message`	`str`	システムプロンプトに追記
`fallback_llm`	`BaseChatModel`	メイン LLM が失敗した際のフォールバック
`use_judge`	`bool`	完了後に別 LLM でタスク達成を評価

主要クラスとメソッド

Agent

async run(max_steps=500, on_step_start=None, on_step_end=None) → AgentHistoryList
async step(step_info=None) → None
async multi_act(actions: list[ActionModel]) → list[ActionResult]

Tools（旧 Controller）

action(description: str, **kwargs) — デコレータでカスタムアクション登録
async act(action, browser_session, ...) → ActionResult
exclude_action(action_name: str) → None

BrowserSession（公開名: Browser）

async start() / stop()
async get_browser_state_summary(include_screenshot=True) — DOM + スクリーンショットを返す

AgentOutput（LLM の返す構造）

thinking — 思考過程（文字列）
evaluation_previous_goal — 前ステップの目標評価
next_goal — 次の目標
action: list[ActionModel] — 実行するアクションのリスト

ActionResult（アクション実行結果）

is_done: bool — タスク完了フラグ。true の場合ループを終了
success: bool — アクションの成否
extracted_content: str | None — ページから抽出したコンテンツ
error: str | None — エラーメッセージ
long_term_memory: str | None — 次ステップへ引き継ぐメモ

6 — 参考リンク

公式・関連

GitHub: browser-use/browser-use — 本体リポジトリ（Python）
docs.browser-use.com — 公式ドキュメント
PyPI: browser-use — パッケージページ
examples/ — 公式サンプルコード集