> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Use

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

## 前提条件

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

* Python 3.11 以上。Browser Use は `requires-python >=3.11` を宣言しているため、それより古いインタープリターでは、明確なエラーが報告されるのではなくパッケージの解決自体が失敗します
* SambaCloud の API キー。[SambaCloud](https://cloud.sambanova.ai?utm_source=browseruse\&utm_medium=external\&utm_campaign=cloud_signup) アカウントを作成し、API keys タブでキーを生成して取得してください

<Note>
  Browser Use がモデルに求める要件は 2 つあり、それぞれ別個の機能です。`use_vision=True` (デフォルト) の間はすべてのスクリーンショットをモデルに送信するため、モデルは画像入力を受け付ける必要があります。また、次に実行するアクションを、`type: json_schema` を指定した `response_format` により JSON で要求するため、モデルは [構造化出力](/docs/ja/features/function-calling) に対応している必要があります。ツール呼び出しは使用しないため、Function calling の対応モデル一覧に載っていないモデルでも利用できないとは限りません。

  本ガイドでは `gemma-4-31B-it` を使用します。このモデルは画像入力を受け付け、制約付きデコーディング (constrained decoding) が有効なため、応答の生成中に `json_schema` が強制されます。テキスト専用の代替モデルについては [モデルの選択](#モデルの選択) をご参照ください。
</Note>

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

```bash create environment theme={}
pip install uv
uv venv --python 3.12
```

```bash activate environment theme={}
source .venv/bin/activate
# On Windows use `.venv\Scripts\activate`
```

```bash install browser-use and chromium theme={}
uv pip install "browser-use>=0.13,<0.14"
browser-use install
```

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

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

## 2. SambaCloud キーの設定

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

```bash .env theme={}
touch .env
```

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

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

```bash .env theme={}
SAMBANOVA_API_KEY=your-sambanova-api-key
```

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

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

```python agent.py theme={}
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())
```

実行します。

```bash theme={}
python agent.py
```

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

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

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

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

```python theme={}
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"]),
)
```

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

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

```python theme={}
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` は以下のように設定します。

```python theme={}
agent = Agent(task=task, llm=llm, use_vision=False)
```

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

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

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

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

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

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

## 次のステップ

* [クイックスタート](/docs/ja/get-started/quickstart) – SambaCloud API を単体で呼び出します。ブラウザを組み合わせる前のキーの動作確認に便利です
* [SambaCloud モデル](/docs/ja/models/sambacloud-models) – 現在のモデル ID、コンテキスト長、画像入力対応の有無
* [構造化出力](/docs/ja/features/function-calling) – Browser Use が各アクションで利用する `response_format` の仕組み
* [API リファレンス](/docs/ja/api-reference/overview) – エンドポイントとパラメータ
* [Browser Use の公式ドキュメント](https://docs.browser-use.com/quickstart)（英語） – 高度な設定、カスタムブラウザ、本番デプロイ
* [Browser Use 対応モデルリファレンス](https://github.com/browser-use/browser-use/blob/main/skills/open-source/references/models.md)（英語） – ネイティブ連携と OpenAI 互換連携の全リスト