早期割引(12月25日まで)、契約を続ける限りこの価格のまま:Go は月 $10(通常 $20)、Opus 5.5 が使える Plus は月 $30(通常 $50)今すぐ申し込む →

Browser-Use 1.0:セットアップと移行ガイド

browser-use 0.xで組んだコードを使っているなら、1.0への更新は単なるバージョンアップではありません。アーキテクチャとデフォルト設定が変わり、24個のブラウザー操作は1つの永続Python REPLに置き換わりました。さらに、何気なく書いたBrowser()は、いまやクラウドブラウザーを意味します。この記事では、1.0.7への固定、初回実行、0.xコードの移行を、1.0.7のリリースノート、MIGRATING.md、11月20日の開発チームの投稿をもとに整理します。

5分で1.0を動かす

まずはバージョンを固定しましょう。1.0.0は2026年11月10日に公開され、11月20日時点の安定版タグは1.0.7でした。1.0.8rc1はプレリリースです(リリース一覧)。READMEでも、マイナーバージョン間でAPIが壊れるため、>=は絶対に使わないよう明記されています。

bash
uv add 'browser-use==1.0.7'
# または
pip install 'browser-use==1.0.7'

必要なPythonのバージョンは3.11以上、4.0未満です(README、PyPI)。依存パッケージもすべて==で固定されているため再現性は高まりますが、アプリ側で別バージョンのpydantic、mcp、google-genaiが必要な場合は衝突する可能性があります。

認証は最初に一度だけ行います。cloud.browser-use.comでキーを作成し、環境変数に設定するか、ログイン用ヘルパーを実行してください。

bash
export BROWSER_USE_API_KEY=bu_...
# または
browser-use login

ログイン情報は~/.config/browser-harness/auth.jsonに保存され、CLI、MCPサーバー、browser-harnessで共有されます(MIGRATING.md)。コンテナではBROWSER_USE_AUTO_LOGIN=trueを使います。SSHやヘッドレス環境では、1.0.8のリリース候補版がリンクと承認コードを表示するため、別のデバイスから承認できます(1.0.8rc1のノート)。

初回実行は3行で済みます。

python
from browser_use import Agent

result = Agent(
    "Find the number of stars of the browser-use repo"
).run_sync()

print(result.final_result())

ただし、このコードはデフォルトでは課金対象です。Browser Use Cloudのブラウザーと、デフォルトのゲートウェイモデルを使うためです(READMEのPath 1 / Path 3、MIGRATING.mdのデフォルト設定)。動作確認でクラウド費用をゼロにしたいなら、最初からBrowser('chromium')と自分のllmを指定してください。

24個の操作は何に置き換わったのか

browser-use 0.xでは、DOMのダンプを見たモデルが、各ステップでメニューから1つの操作を選んでいました。1.0ではこのメニュー自体がなくなっています。代わりにモデルへ渡されるのは、browser-harnessのヘルパーとraw cdp()をあらかじめ読み込んだ、永続REPLのメインツールpythonです(開発チームの投稿)。

python
async def python(ctx: RunContext[Session], code: str) -> list[Any]:
    """Run Python in the persistent REPL
    (browser-harness helpers and raw cdp() pre-imported)."""

この整理によって554ファイルをまたぐ136,905行が削除され、29,601行が追加されました。Pythonファイルは178個から43個になっています(開発チームの投稿)。

変化がよく分かるのが、ページの読み込みが止まった場合の復旧です。エージェントはPage.stopLoadingを呼び、固まったスクリプトをブロックしてページを再読み込み。その後、ページ内部の非公開JSONPエンドポイントを見つけ、730件の日付をバッチで取得し、失敗したバッチだけを再試行しました。これらの処理専用ツールは1つも使っていません。最終的に4,720行を返しています(開発チームの投稿)。

チームが残した判断基準は明快です。モデルが一度読めば書き直せるものは、専用ヘルパーにしない。ただしCAPTCHAは例外です。小規模なステージングテストでは、hCaptchaに対する文章の指示は0/3でしたが、専用のsolve_captchaツールは6/6。ページからは触れないソルバーのスイッチをツールが切り替えられるためです(開発チームの投稿)。

コストと速度については、見出しだけで判断しないでください。11月20日の投稿では、同じ3モデルを使った比較で、1.0は0.xより14〜33ポイント高いスコアを取り、コストは2.7〜5.2倍低かったと報告されています。対象は11月8日に実施した200タスクで、そのうち180タスクを採点しました。ただし、各モデル1回の実行であり、デフォルト設定も変わっているため、結果のすべてをツール設計の変更だけに帰すべきではないと明記されています(開発チームの投稿)。

より条件の絞られた比較もあります。1.0.4のスコアは1.0.3の76.0に対して76.1。バッチ処理でスクリーンショットを削減しつつプロンプトキャッシュを維持した結果、モデルコストはタスクあたり$0.434から$0.208に下がりました(1.0.4のノート)。BU Bench v2では、1.0のultrafastが62.5、$0.070、650秒。Browser Use Piは56.3、$0.082、743秒でした。ただし、プロバイダーのエラーを除外すると、この差は統計的な意味を失うと著者らは説明しています。期待すべきなのは、必ずしも賢くなることではなく、安く速くなることです。

請求額とブラウザーをひそかに変えるデフォルト設定

以下の表はMIGRATING.mdと1.0.6のリリースノートをもとにまとめたものです。1.0.7の設定と、古いガイドでは見落とされがちな1.0途中のデフォルトモデル変更を反映しています。

設定0.x1.0.7
llm=Noneモデルの指定が必要Browser Useゲートウェイ経由でbu-4.0
bu-4.0の価格該当なし入力1Mトークンあたり$1.80、出力1Mトークンあたり$9.00
bu-fastの価格該当なし入力1Mトークンあたり$0.12、出力1Mトークンあたり$0.60
Browser()ローカルChromiumBrowser Use Cloudブラウザー
ローカルブラウザーデフォルトBrowser('chromium')を明示
APIキープロバイダーごとに1つBROWSER_USE_API_KEYを1つ
max_steps500100(配信用に1ステップ確保)
エージェントのタイムアウト未指定1,700秒。起動・終了処理を除く
Judgeオプトインデフォルトでjudge=True
推論 / モード該当なしbu-fast / bu-ultrafastではreasoning='medium'、mode='ultrafast'
ゲートウェイモデルの100万トークンあたりの価格比較。bu-4.0とbu-fast

特に注意したい落とし穴は3つあります。1つ目は、1.0の途中でデフォルトモデルが変わったこと。1.0.5までのリリースではbu-fastがデフォルトでしたが、1.0.6でbu-4.0に変更され、トークン単価は15倍になりました。プロジェクトの例では、同じ短いテストでもbu-4.0は$0.022、bu-fastは$0.0014です。以前のコスト感を維持したいなら、llm='bu-fast'を明示してください。2つ目は、引数なしのBrowser()が、ブラウザー時間あたり$0.06に加えてモデル料金と検索ごとの料金が発生するクラウドブラウザーを起動すること(README)。クラウドブラウザーからlocalhostやプライベートIPには接続できません(MIGRATING.md)。3つ目は、1ステップがモデルへの1リクエストとPythonセル1つに相当することです。100ステップへの上限引き下げは、そのまま支出上限としても機能します。max_steps < 1やtimeout <= 0を指定すると、ブラウザー起動前に失敗します(MIGRATING.md)。

もう1つ見落としやすい費用がJudgeです。1ステップ以上実行した場合、実行トレース最大120,000文字に加え、ビジョンを有効にしていれば最後のページを含む直近4枚の異なる画像を、マスクなしで送信して自分のモデルに追加の低負荷リクエストを1回行います(MIGRATING.md)。結果はresult.judgementに入り、success、failure_reason、gotchas、ボット/CAPTCHAフラグを確認できます。料金はresult.cost_usdにも含まれます。judge=Falseで無効にするか、期待する答えをjudge_contextで渡してください。スクリーンショットを自分の環境外へ出したくない場合はuse_vision=Falseを設定します。

ローカル実行が必要ならクラウドを使わない

ブラウザーは習慣ではなく、接続先のネットワークで選びましょう。次のモデル識別子は、READMEのローカルブラウザー例で使われているプロバイダー例です(README)。

python
from browser_use import Agent, Browser, ChatOpenAI

agent = Agent(
    "Summarize the dashboard at http://localhost:3000",
    llm=ChatOpenAI("gpt-6-luna"),
    browser=Browser("chromium"),
)
print(agent.run_sync().final_result())

localhost、プライベートネットワーク、カスタムビューポートを使う場合、またはクラウド側のデバイスメトリクスでは実際のページのビューポートが変わらない場合は、Browser('chromium')を指定します。既存のログイン状態を使って開いているChromeを操作するならBrowser('chrome')です。Browser('chrome', profile='Work')はログイン状態を引き継いだ一時コピーを起動しますが、Syncへの書き戻しはありません。WindowsではCookieをロックするため、先に元のChromeを終了してください(MIGRATING.md)。管理されたステルス機能、プロキシ、CAPTCHA処理、ローカル環境を用意しない運用が必要なら、クラウドが引き続き適しています(README)。ただしブラウザー時間の料金はトークン料金とは別に見積もりましょう。

カスタムモデルも利用できますが、指定方法には注意が必要です(MIGRATING.md)。

  • ゲートウェイのエイリアス:bu-4.0、bu-4.0-mini、bu-4.0-pro、bu-fast、bu-ultrafast、bu-smart
  • プロバイダー:ChatOpenAI、ChatAnthropic、ChatGoogle、またはgroq:llama-3.3-70b-versatileのようなPydantic AI文字列
  • Azure:AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_KEY、OPENAI_API_VERSIONを設定し、llm='azure:<deployment>'を使用

LangChainのチャットオブジェクトをAgent(llm=...)に渡すと、いまはTypeErrorになります。bu-2-0のような廃止済みのゲートウェイ名も、ブラウザー起動前に拒否されます。並列実行するエージェントには、それぞれ専用のBrowser()が必要です。2つのエージェントで共有するとRuntimeErrorになります。ただし、keep_alive=Trueのブラウザー1つを順番に再利用することは可能です(MIGRATING.md)。

推測で移行せず、エラーを手がかりにする

1.0が意図的に早い段階で失敗するのは、移行箇所を分かりやすくするためです。削除されたインポートは置き換え先を示すImportErrorを返し、対応していないAgent(...)引数はTypeErrorになります。1.0で扱えない設定も、ブラウザーが起動したり課金されたりする前にエラーになります(MIGRATING.md)。一方、use_vision=True、vision_detail_level、max_actions_per_step、flash_mode、max_failures、highlight_elementsなど、一部の調整用フラグは受け付けられますが無視され、各項目につき1回だけ警告が出ます。なお、use_vision=Falseは意味があり、スクリーンショットをモデルに送らない設定です。

起動後の挙動は逆になります。run()は通常、例外を投げるのではなくエラー結果を返し、status='error'と詳細をresult.errorに格納します。伝播するのはキャンセルだけです。判定処理も更新してください。

python
# 0.x
history = await agent.run(max_steps=500)
ok = history.is_successful()

# 1.0
result = await agent.run(max_steps=100)
ok = result.is_done() and result.success is not False

is_done()が意味するのは、実行が完了したということだけです。成功かどうかはモデルのfinish(result, success)判定に入り、モデルが判定を返さなければis_successful()はNoneを返します。古いステップ単位の履歴ヘルパー(action_names()、model_actions()、extracted_content()、save_as_playwright_script()など、削除された履歴APIの一覧はMIGRATING.mdを参照)はなくなりました。代わりにresult.messages、result.status、result.partial、agent.workspace内のファイル、result.judgementを読み取ります。

まずは3点を直しましょう。max_stepsをAgent(...)からagent.run(max_steps=...)へ移すこと。削除されたコールバック(on_step_start、pause、stop、multi_act、save_history)を、INFOレベルのlogging.getLogger('browser_use')、またはBROWSER_USE_LOGGING_LEVEL=warningに置き換えること。そしてシークレットの扱いを見直すことです。ドメイン限定のシークレットは一致するページでのみ入力され、名前がbu_2fa_codeで終わるものはTOTPシードとして扱われます。古い<secret>name</secret>プレースホルダーはエラーになるため、type_secret('name')に変更してください。セルや結果では値が<secret:name>としてマスクされますが、これはサンドボックスではありません。モデルが書いたPythonからは、引き続き読み取れます(MIGRATING.md)。時間が必要なら、pip install 'browser-use<1'で固定し、ブランチ上で移行を進めましょう。

「browser use is more a python framework for building your own browsing agent」 — r/ClaudeCodeのu/Starks1293

この捉え方は、Reddit上のユーザーの説明とも一致します。browser-useはブラウジングエージェントを組み立てるためのフレームワークであり、ボット対策のあるサイトや、コードレベルでの制御を目的に挙げる人が多いようです。ただし、信頼性はモデルとサイトに左右されます。ある本番利用の報告では、基本的なフォーム入力に5分かかり、9ステップ失敗したとされています。

本番前に確認したいJudge、シークレット、安定性

高度な用途で重要になるのは次の機能です。

  • output_model_schemaによる型付き結果。result.structured_outputから読み取れます
  • ワークスペースへのアップロードとworkspace/downloads。ダウンロード結果はresult.downloadsで取得できます
  • ドメイン制御(allowed_domains、prohibited_domains、block_ip_addresses)。ただし、これは適切に動作するモデルを守るものであり、ネットワークをサンドボックス化するものではありません
  • オプトインのweb_search=True。検索ごとに課金され、result.cost_usdに反映されます
  • browser-use --cli-mcp、browser-use skill install、browser-use --doctorによるCLI/MCP

1.0は変化の速いフレームワークとして扱いましょう。バージョンは完全一致で固定し、長いタスクにはjudge_contextを追加。checkpoint('titles.json', titles, partial=True)で途中結果を保存し、信頼できないタスクはコンテナで実行してください。ドメイン制限やシークレットのマスキングは、隔離機能ではありません(README)。

いま移行するか、固定するか、0.xに残るか

状況推奨する対応
新規エージェントでクラウド利用に問題がない==1.0.7で開始し、bu-4.0をデフォルトのまま使い、Judgeも有効にする
コスト重視のバッチ処理llm='bu-fast'とjudge=Falseを指定し、スケールさせる前に計測する
localhost/イントラネット/カスタムビューポートBrowser('chromium')と自分のモデルを使い、引数なしのBrowser()は使わない
既存の0.xを本番利用中メイン環境ではbrowser-use<1に固定し、フェイルファストのエラーを手がかりにブランチで移行する
CAPTCHAの多いフロー専用ソルバーの費用を見込む。チームのテストでは文章による指示だけでは0/3だった

固まったスクリプトを止めたり、専用ツールを用意していない非公開APIを呼び出したりできるエージェントを得られる一方、固定された操作メニューによるガードレールは失われます。そのトレードオフがサイトに合うなら移行しましょう。合わない場合は、既存の本番システムではbrowser-use<1に固定したまま評価を続けるほうが安全です。

FAQ

browser-use 1.0の新機能は何ですか?

0.xの24個の操作メニューが、browser-harnessのヘルパーとraw CDPを備えた永続Python REPLに置き換わりました。ライブラリのおよそ80%が削除され、Pythonファイルは178個から43個になっています。デフォルトはBrowser Use Cloud、ゲートウェイモデル、単一のBROWSER_USE_API_KEYに変わりました。

0.xのコードは壊れますか?

Agent、Browser、run()、final_result()など主要な入口は残っています。ただし、削除されたインポートやオプションは課金前にImportErrorまたはTypeErrorを返し、max_stepsはrun()へ移動しました。また、Browser()はクラウドを意味します。そのまま使い続けるならbrowser-use<1に固定し、移行するならまずブランチで試してください。

自分のモデルとローカルブラウザーは引き続き使えますか?

使えます。ChatOpenAI、ChatAnthropic、ChatGoogleなどのプロバイダー、またはPydantic AI文字列を渡し、ローカルの新しいブラウザーにはBrowser('chromium')、開いているChromeにはBrowser('chrome')を使います。クラウドブラウザーからlocalhostへは接続できません。

browser-use 1.0に必要なPythonのバージョンは?

Python 3.11以上、4.0未満です。依存パッケージが完全一致で固定されているため、ほかのパッケージと衝突する可能性があります。まずは新しい仮想環境でインストールしてください。

実行後のJudgeを無効にするには?

judge=Falseを渡すと追加の判定リクエストをスキップできます。判定を有効にする場合は、受け入れ条件をjudge_contextで渡すと結果を役立てやすくなります。Judgeにスクリーンショットを送信したくない場合はuse_vision=Falseを設定してください。