Gemini 4 Computer Useの設定方法：ブラウザー・デスクトップ・Android

Gemini 4 Computer Useは画面上の操作を提案します。実行と新しい観察結果の返送は、アプリケーションの役割です。 GoogleのInteractions API、gemini-4-hydrogenなどの対応モデル、実行器に合ったenvironmentを持つcomputer_useツールから始めます。environment: "desktop"を設定しても、モデルにPCの制御権が渡ったり、OS用ドライバーがインストールされたりはしません。

この記事では小さなブラウザー構成を作り、デスクトップとAndroidへの移行で変わる部分を説明します。承認と停止条件を明示したコントローラーもダウンロードできます。文書とパッケージの確認日は2026年11月13日です。Googleの現行Computer UseドキュメントではCarbon、Argon、Hydrogenが対応モデルに含まれます。例ではHydrogenを使います。選び分けはGemini 4モデル選択ガイドを参照してください。引用する提供元の資料は英語です。

この記事の発行元はOfoxです。検証したのは、合成モデル応答を使う22件のオフラインテストと、別のUIツールで実際にChromeを操作したローカルテストページです。同梱のPython Playwrightランナーはモデルに接続して実行しておらず、エンドツーエンドでは未検証です。有料推論、デスクトップやAndroidの実行器テスト、モデル性能測定も行っていません。再利用できる部分と、自分の環境で確認すべき部分を分けてください。

実行環境より先にAPIの形式を決める

Computer Useエージェントには、モデルによるアクションの提案、実行器による対応アクションの実行、検証器によるアプリケーション結果の確認という3つの仕事があります。後の2つは利用側で用意します。モデルの「完了」という返答だけでは、フォーム送信、ファイル保存、ボタンのクリックが実際に行われた証拠になりません。

一連の処理で同じAPI形式を使ってください。この記事はInteractionsのsteps、function_call、function_result、previous_interaction_idを使います。確認した公式リファレンスリポジトリのコミット77c9797e943aad63bbc963b7fd092a9e51c07863はGenerateContentを使い、現行アクションと古いプレビュー版のアクションも区別しています。参考にはなりますが、応答パーサーをそのままInteractionsループへ移すことはできません。

Googleプロジェクトとキーの準備はHydrogen API接続ガイドで確認できます。この例ではGoogleキーをGEMINI_API_KEYに保存します。Ofoxキーは、別途説明されているOfoxの認証手順で使用します。

OfoxにはChat CompletionsとGeminiネイティブAPIの文書があります。ただし一般的なプロトコル対応だけでは、Googleの現行Interactions Computer Use形式への対応を確認したことになりません。そのため本例はGoogleのネイティブルートを使い、Base URLをOfoxに差し替えるだけでブラウザーループが動くとは説明しません。リポジトリ内のファイルツールだけが必要なら、別の接続方法を扱うHydrogenのCline・OpenCode設定ガイドを参照してください。

ローカルキットを入れ、モデルキーなしで検証する

Computer Useのテストキット一式をダウンロードし、展開してgemini-computer-use-kitディレクトリへ移動します。コントローラー、オフラインテスト、ローカルHTMLページ、任意のライブランナー、READMEが含まれています。断片コードの省略部分を自分で補う必要はありません。コードのコメントとREADMEは英語ですが、操作手順は以下で説明します。

確認済みパッケージにはPython 3.11以降を使います。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'google-genai==3.3.0'
python test_controller.py

WindowsのPowerShellでは、sourceの代わりに.venv\Scripts\Activate.ps1で環境を有効化します。オフライン確認にはPlaywrightもAPIキーも不要で、期待する結果は22件のテスト成功です。作業ディレクトリだけでなく、配布ZIPを新たに展開した状態でも実行しました。

テストは実際のgoogle-genai応答クラスに合成データを入れ、操作を記録する模擬ページを使います。座標検証、呼び出しIDの対応、副作用前の拒否、承認と拒否、重複呼び出し、未完了応答、タイムアウト、操作上限を確認します。ブラウザーは起動せず、実際のリクエストがGoogleに受理されることも証明しません。

別工程のブラウザー接続には、Playwrightとブラウザーを追加します。

python -m pip install playwright
python -m playwright install chromium

キットのディレクトリから別のターミナルを開き、ページをローカル配信します。

python -m http.server 8877 --bind 127.0.0.1

http://127.0.0.1:8877/fixture.htmlを開きます。英語のページにORANGE-42を求める説明、空のMarker欄、Check markerボタンが表示されるはずです。値を入力してボタンを押し、ページ自体の動作を確認してください。その後は再読み込みして、エージェントが完了済み画面ではなく空の欄から始められるようにします。

1000 × 700のビューポートで、別のUIツールを介して操作した実際のChrome画面です。ページの表示動作を示すもので、Hydrogenや同梱Pythonランナーが完了した証拠ではありません。この撮影ではモデルに接続していません。

任意のGoogleブラウザー接続を実行する

ローカルHTTPサーバーを動かしたまま、有効化済みのPython環境で通常の秘密情報管理方法を使ってGoogleのGEMINI_API_KEYを設定します。キーをテストページに書いたり、ソース管理へコミットしたりしないでください。次のコマンドは実サービスを呼び出し、プロジェクトの割当量や有料利用を消費する可能性があります。オフラインテストとは異なり、モデルを使わない検証ではありません。

python run_live.py

ランナーは1000 × 700 CSSピクセル、デバイススケール1の新しいブラウザーコンテキストを作り、service workerをブロックし、ダウンロードを無効化します。ブラウザーのリクエストフィルターはテストページの完全一致URLだけを許可します。デモの範囲を小さくするための設定であり、OSサンドボックスや任意のWebサイト向けの汎用防御ではありません。

ランナーに入っているタスク指示の全文は次のとおりです。

Read the local page instructions. Enter the marker in its field and click Check marker. Stop when the page shows PASS. Stay on this page.

ページの説明を読み、マーカーを入力してCheck markerを押し、PASSが表示されたら止まり、同じページに留まるという指示です。最初のリクエストにはこの指示、初期スクリーンショット、Computer Useツールを含めます。主要な設定は以下です。

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "text", "text": task_prompt},
        {"type": "image", "data": screenshot_base64, "mime_type": "image/png"}
    ],
    tools=[{
        "type": "computer_use",
        "environment": "browser",
        "enable_prompt_injection_detection": True
    }],
    timeout=120.0,
    automatic_continuation=False
)

これはリクエスト形式を説明する抜粋です。実行時は完全なキットを使ってください。キットは未実装の定義済みアクションを除外し、実行器側でも拒否します。このページ向けに実装しているのはclick、type、wait、take_screenshotです。未対応アクションを黙って成功扱いにはしません。

承認が必要な場合、ターミナルに意図と説明が表示されます。表示された操作を許可するときだけAPPROVEを入力します。それ以外は停止します。アプリケーション側の成功条件は、結果要素が正確にPASS: ORANGE-42になることです。その後result.pngを保存します。モデルが停止してもページが「Waiting for input」のままなら、この確認は失敗します。

このライブランナーは未実行なので、自分のアカウントでの成功結果を新たな証拠として記録してください。クライアントの版、モデルID、実結果、使用量を残します。オフラインテストの時間をモデル速度として使ったり、模擬応答を請求データとして使ったりしてはいけません。

座標・画像・呼び出しIDを揃える

Googleの現行アクションは、1000単位の軸に対する0〜999の正規化整数座標を使います。実行器が実際に使う観察画像の寸法で変換します。

def to_pixel(value, size):
    if type(value) is not int or not 0 <= value <= 999:
        raise ValueError("Expected an integer coordinate from 0 to 999")
    return int(value * size / 1000)

1000 × 700の画像なら、合成アクションの(400, 500)はCSSピクセルの(400, 350)になります。これは変換例であり、記録したHydrogenの予測ではありません。キットは実行前に座標を検証し、scale="css"で画像を取得してブラウザー座標系を揃えます。

デスクトップ全体の画像をブラウザーのビューポート座標と混ぜたり、画像を切り抜いた後でオフセットを忘れたりしないでください。高DPI環境では画像のピクセルと入力座標が異なり、モバイルの回転でも変換が必要です。APIリクエストが成功しても、実行器が誤った座標系でクリックする問題は解決しません。

各呼び出しを実行したら、そのID、現在のURL、新しい画像を返します。キットの結果構造は次のとおりです。

{
  "type": "function_result",
  "name": "click",
  "call_id": "the-id-from-the-model-function-call",
  "result": [
    {"type": "text", "text": "{\"url\":\"http://127.0.0.1:8877/fixture.html\"}"},
    {"type": "image", "data": "BASE64_OF_NEW_SCREENSHOT", "mime_type": "image/png"}
  ]
}

上のプレースホルダーは説明用で、そのまま送れる応答ではありません。複数の呼び出しを受け取ったら、実行した各呼び出しに対応する結果が必要です。次のリクエストでは、それらの呼び出しを含むinteractionをprevious_interaction_idで指定します。interaction IDと関数の呼び出しIDは交換できません。

この例は保存されたinteraction状態を使います。Interactionsドキュメントに従って履歴処理を設計し直す前に、store=Falseを追加しないでください。別プロトコルや自前の履歴管理では、必要なモデル状態と署名をそのまま保持します。Geminiの思考署名不足の対処ガイドは関連する故障例を扱いますが、本例のライブ署名テストが成功した証拠ではありません。

デスクトップとAndroid向けに実行器を適合させる

環境指定はモデルに使うアクション体系を伝えるもので、ブラウザー、VM、デスクトップセッション、端末を用意するものではありません。Googleの環境リファレンスでは次の3種類を区別します。

配布キットが実装するのはブラウザーのテストページだけです。デスクトップ用に接続するには、リクエストと結果のループを残し、ブラウザーのpage操作を置き換えます。

1. 専用のテストデスクトップかVMを選び、最初は単一ディスプレイ、固定サイズにします。無関係なウィンドウがある個人セッションは避けます。
2. 画面取得を単独で確認し、画像の幅と高さを記録します。モデル接続前に、ローカルテストアプリで無害な入力操作も単独検証します。
3. 正規化座標を入力側の座標系に変換します。画像取得がデバイスピクセル、入力が論理座標なら、観察画像のリサイズか明確な倍率変換を一貫して使います。
4. クリック、文字挿入、キー操作、スクロール、新規画像取得を、それぞれ明示的なハンドラーへ対応付けます。未実装操作は除外または拒否します。ブラウザーのナビゲーションは汎用デスクトップ操作ではありません。
5. ツール設定をdesktopへ変え、呼び出しIDと結果の対応を維持し、最初の操作後にアプリ状態を確認します。カーソルが動くだけで成功と判断しません。

macOSでは画面収録の権限とアクセシビリティ制御は別です。画面が取れても、そのプロセスがクリックや入力をできるとは限りません。自分で導入した実行器に必要なアクセスだけを許可します。これらの設定に別のGemini APIキーは不要です。WindowsとLinuxには各環境の取得・入力バックエンドとセッション確認が必要で、ブラウザーキットはそのドライバーを提供しません。

Android端末またはエミュレーターでは、まず公式のAndroid Debug Bridge手順で接続と画像取得経路を準備します。認証済みテスト端末を接続したら、以下で端末を識別し、Geminiを呼ばずに画像を取得できます。

adb devices
adb -s YOUR_TEST_SERIAL shell screencap /sdcard/computer-use-test.png
adb -s YOUR_TEST_SERIAL pull /sdcard/computer-use-test.png ./computer-use-test.png

シリアルは対象のテスト端末に置き換え、複数端末の一覧から適当に選ばないでください。unauthorizedなら端末側で許可してから続けます。取得したPNGを開き、期待するテストアプリが写っていることを確認し、最初の実行では画面方向を固定します。

続いて、その端末向けにアクションを実装します。clickは座標変換後のタップ、typeはフォーカス欄への入力、go_backは端末の戻る操作です。open_appとlist_appsには実在するパッケージ識別子の解決が必要です。ドラッグや長押しを有効にする場合も動作を明示します。実行後に新しい端末画像を返し、environmentをmobileにして小さなテストアプリのタスクを試します。Googleのモバイル操作はAndroid向けに最適化されており、このADB手順でiPhoneを制御できるという意味ではありません。

この記事ではデスクトップとAndroidの実機検証を行っていません。上の手順は実装作業と確認地点を示すもので、環境文字列を1つ変えるだけで移植が終わるとは説明していません。

承認・停止・復旧を明示的に扱う

モデルのintentは操作の説明であり、許可ではありません。関数呼び出しにsafety_decision.decision: "require_confirmation"がある場合はユーザーを待ちます。Googleの安全判断の文書では、承認後に確認済みの情報を返します。キットもユーザーが承認した後だけ、操作結果のテキスト内にsafety_acknowledgement: trueを追加します。

コントローラーはバッチ全体を検証し、どの操作も実行する前に必要な承認をすべて取得します。未対応アクション、不正な安全メタデータ、それ以外の明示的な判断状態では停止します。これはテストページ用の保守的な方針です。安全判断がないことは、ユーザーのタスク許可に関するアプリ固有の規則を代替しません。

既定値は12アクションバッチ、モデルへの1リクエストにつき120秒で、自動継続は無効です。全体の所要時間や料金の上限ではありません。人の承認待ちは続き、1バッチに複数操作が含まれ、画像や繰り返す文脈も使用量に影響します。SDKが通信層で再試行する場合もあるため、再試行ゼロや固定料金は保証していません。

クリック後のリクエストがタイムアウトしても、クリック自体は済んでいる可能性があります。アプリは自動で同じ操作を再生しません。停止して実ページを確認し、interactionと呼び出しIDを保持して、元の会話を継続するか新規タスクにするか判断します。送信結果不明のフォームを盲目的にやり直さないでください。このテストページなら欄と出力を確認し、再読み込みして状態を消してから新しく試せます。

操作後の画像取得やブラウザーの故障では、実行済み操作は取り消せません。本番用途では保存レコードIDや文書値の変更など、アプリに適した独立確認を定義します。画面のマーカーはこの単純なページにだけ十分な条件であり、汎用トランザクション検証器ではありません。以前のオフラインComputer Useコントローラー実験では、OpenAI向けの別のコントローラーと受信側確認方法を扱っています。

問題が発生した層から診断する

認証、割当量、不正なリクエストはGemini APIエラーガイドも参照できます。Argonを中心に書かれているため、モデル固有の説明をすべて転用せず、実際のHydrogen応答に一般的な分類を当てはめてください。別のOfoxルートを調べるなら、そのルートのOfoxエラー処理文書を使います。Googleプロジェクトの診断を置き換えるものではありません。

APIループと完成済みエージェントのどちらが必要か決める

実行器、承認動作、観察、アプリ検証器を自分で管理するなら、このAPI方式が適しています。すぐ使えるデスクトップ製品が目的なら、Antigravityプラットフォーム概要 (英語)が別の出発点になります。Chrome拡張・Computer Use・リモート制御の比較でも製品カテゴリーを区別しています。

テストページを超える前に、モデルとSDKの版、API、環境、画像寸法、実装済みアクション、承認方針、独立した成功条件を保存します。オフラインコントローラー確認、ブラウザー操作、実モデル推論を区別した記録を残してください。このキットで証拠があるのは最初の2つだけで、ブラウザー確認はPythonランナーとは別に行いました。

次の到達点は、対象アカウント、実行器、検証器を組み合わせた1つのライブタスクです。結果を観察・再現できてから、操作を増やしたりデスクトップ・モバイルへ移したりします。モデルが高性能になっても、どの操作が実行され、何が変わったかを確認する必要はなくなりません。