Browser Use

Browser Use は、AI エージェントによる Web ブラウザの操作を可能にするオープンソースプロジェクトです。Web ナビゲーションの自動化やデータ抽出などのタスクを実行できます。

前提条件

作業を始める前に、以下の環境を準備してください。

Python 3.11 以上。Browser Use は requires-python >=3.11 を宣言しているため、それより古いインタープリターでは、明確なエラーが報告されるのではなくパッケージの解決自体が失敗します
SambaCloud の API キー。SambaCloud アカウントを作成し、API keys タブでキーを生成して取得してください

Browser Use がモデルに求める要件は 2 つあり、それぞれ別個の機能です。use_vision=True (デフォルト) の間はすべてのスクリーンショットをモデルに送信するため、モデルは画像入力を受け付ける必要があります。また、次に実行するアクションを、type: json_schema を指定した response_format により JSON で要求するため、モデルは構造化出力に対応している必要があります。ツール呼び出しは使用しないため、Function calling の対応モデル一覧に載っていないモデルでも利用できないとは限りません。本ガイドでは gemma-4-31B-it を使用します。このモデルは画像入力を受け付け、制約付きデコーディング (constrained decoding) が有効なため、応答の生成中に json_schema が強制されます。テキスト専用の代替モデルについてはモデルの選択をご参照ください。

1. Browser Use のインストール

create environment

pip install uv
uv venv --python 3.12

activate environment

source .venv/bin/activate
# On Windows use `.venv\Scripts\activate`

install browser-use and chromium

uv pip install "browser-use>=0.13,<0.14"
browser-use install

2 つ目のコマンドは独立したステップであり、見落としがちです。Browser Use は独自の Chromium ビルドを使用しますが、これは uv pip install では取得されないため、このコマンドを実行しないと、初回実行時にブラウザを起動しようとした時点で失敗します。約 180 MB のダウンロードと数分の時間がかかり、完了すると Installation complete. と表示されます。

browser-use install は、uvx browser-use install としてではなく、有効化した仮想環境の中で実行してください。uvx は現在の環境を無視して独自に Browser Use のコピーを解決するため、コードが import するバージョンとは異なるバージョン向けにブラウザがインストールされてしまう可能性があります。

2. SambaCloud キーの設定

プロジェクトディレクトリに .env ファイルを作成します。

.env

touch .env

Windows では echo. > .env を使用してください

SambaCloud の API キーを追加します。

.env

SAMBANOVA_API_KEY=your-sambanova-api-key

3. 最初のエージェントの実行

Browser Use に SambaNova 専用のクラスはありません。カスタムの base_url を指定した ChatOpenAI を通じて SambaCloud に接続します。これは、Browser Use が OpenAI 互換プロバイダー全般に対して使用するのと同じパターンです。

agent.py

from browser_use import Agent, ChatOpenAI
from dotenv import load_dotenv
import asyncio
import os
 
load_dotenv()
 
llm = ChatOpenAI(
    model="gemma-4-31B-it",
    base_url="https://api.sambanova.ai/v1",
    api_key=os.getenv("SAMBANOVA_API_KEY"),
)
 
async def main():
    task = "Find the number 1 post on Show HN"
    agent = Agent(task=task, llm=llm)
    result = await agent.run(max_steps=25)
    print(result.final_result())
 
if __name__ == "__main__":
    asyncio.run(main())

実行します。

python agent.py

Browser Use は Chromium のウィンドウを開き、実行する各ステップをターミナルにログ出力し、タスクが完了するとウィンドウを閉じます。ステップのログは Browser Use 自身が出力するものであり、タスクに対する回答は final_result() が返す値です。この例で result を破棄せずに受け取っているのはそのためです。

必ず max_steps を渡してください。デフォルトは 500 で、Vision (視覚) モデルではステップごとに新たなスクリーンショットが送信されるため、収束しないタスクはこの上限に達するまでモデルを呼び出し続けます。まずは 25 程度の低い値から始め、本当に多くのナビゲーションが必要なタスクに限って値を引き上げてください。

認証情報をプロンプトに含めない

機密情報はタスクに直接書き込むのではなく sensitive_data を通じて渡し、その受け渡しを許可するドメインにスコープを限定してください。Browser Use はフィールドへの入力時に値を代入するため、機密情報そのものがモデルに渡ることはありません。

from browser_use import BrowserProfile

agent = Agent(
    task="Log in to the dashboard and download this month's invoice",
    llm=llm,
    sensitive_data={"https://*.example.com": {"x_password": os.getenv("PORTAL_PASSWORD")}},
    browser_profile=BrowserProfile(allowed_domains=["https://*.example.com"]),
)

sensitive_data を使用する場合は、必ず allowed_domains を設定してください。設定しない場合、Browser Use は Agent(sensitive_data=••••••••) was provided but Browser(allowed_domains=[...]) is not locked down! とログに記録し、エージェントが訪問した任意のページでのプロンプトインジェクション攻撃によって認証情報が漏えいするおそれがあると警告します。機密情報を保持したままエージェントが自由にブラウジングする状態は、この連携における最大のセキュリティリスクです。

ブラウザはデフォルトで画面に表示された状態で実行されるため、開発中の確認に便利です。無人実行する場合は、プロファイルで headless=True を設定します。

agent = Agent(task=task, llm=llm, browser_profile=BrowserProfile(headless=True))

モデルの選択

Browser Use における SambaCloud モデルの対応状況は、タスクによって異なります。

タスク	推奨モデル	備考
スクリーンショットを伴う一般的なブラウジング	`gemma-4-31B-it`	画像入力を受け付けるため、デフォルトの `use_vision=True` で動作します。制約付きデコーディングが有効なため、`json_schema` の応答形式が生成中に強制されます
テキストのみのフロー	`Meta-Llama-3.3-70B-Instruct`	テキスト専用のため、`Agent` で `use_vision=False` を設定する必要があります。Vision を有効にしたままだと、画像を読み取れないモデルに画像が送信されます

use_vision=False は以下のように設定します。

agent = Agent(task=task, llm=llm, use_vision=False)

現在のモデル一覧は SambaCloud モデルをご参照ください。また、モデル ID は時間の経過とともに提供終了となるため、古いガイドに記載のモデル ID を再利用する前にモデルの提供終了をご確認ください。

トラブルシューティング

AuthenticationError: Incorrect API key

.env に SAMBANOVA_API_KEY が設定されていること、および ChatOpenAI を構築する前に load_dotenv() が実行されていることを確認してください。末尾にスペースや改行が付いた状態でコピーされたキーでも、このエラーが発生します。

エージェントが有効なアクションを取らずにループする、または画像入力でエラーになる

原因は 2 つ考えられます。画像入力でエラーになる場合、モデルはテキスト専用です。gemma-4-31B-it に切り替えるか、現在のモデルのまま use_vision=False を設定してください。実行はされるものの有効なアクションを選択できない場合は、Browser Use が各アクションの要求に使用する json_schema 応答形式にモデルが従っていない可能性が高いため、構造化出力に対応したモデルを選択してください。

NotFoundError: model not found

モデル文字列は、現在の SambaCloud モデル ID と正確に一致している必要があります。ID は大文字と小文字を区別し、プロバイダーのプレフィックスは付けません。SambaCloud モデルと照合するか、curl https://api.sambanova.ai/v1/models でカタログを直接一覧表示してください (API キーは不要です)。提供終了したモデルは、古いガイドに記載が残っていてもこのエラーを返します。

Chromium の起動に失敗する

browser-use install を、有効化した仮想環境の中で実行してください。Browser Use は独自の Chromium ビルドを使用しますが、これは uv pip install browser-use では取得されません。コマンドが成功すると Installation complete. と表示されます。uvx browser-use install として実行してしまった場合は、環境内でもう一度実行してください。uvx は独自に Browser Use のコピーを解決するため、インストールされたブラウザが、コードが import するバージョンとは異なるバージョンのものである可能性があります。

次のステップ

クイックスタート – SambaCloud API を単体で呼び出します。ブラウザを組み合わせる前のキーの動作確認に便利です
SambaCloud モデル – 現在のモデル ID、コンテキスト長、画像入力対応の有無
構造化出力 – Browser Use が各アクションで利用する response_format の仕組み
API リファレンス – エンドポイントとパラメータ
Browser Use の公式ドキュメント（英語） – 高度な設定、カスタムブラウザ、本番デプロイ
Browser Use 対応モデルリファレンス（英語） – ネイティブ連携と OpenAI 互換連携の全リスト

概要

開発者ツール

フレームワーク

インターフェースとローコード

データとインフラ

マルチモーダル

評価とモニタリング

前提条件

1. Browser Use のインストール

2. SambaCloud キーの設定

3. 最初のエージェントの実行

認証情報をプロンプトに含めない

モデルの選択

トラブルシューティング

次のステップ

​前提条件

​1. Browser Use のインストール

​2. SambaCloud キーの設定

​3. 最初のエージェントの実行

​認証情報をプロンプトに含めない

​モデルの選択

​トラブルシューティング

​次のステップ

前提条件

1. Browser Use のインストール

2. SambaCloud キーの設定

3. 最初のエージェントの実行

認証情報をプロンプトに含めない

モデルの選択

トラブルシューティング

次のステップ