Как настроить Gemini 4 Computer Use: браузер, рабочий стол и Android

Gemini 4 Computer Use предлагает действия на экране; ваше приложение должно выполнить их и вернуть новое наблюдение. Начните с Google Interactions API, поддерживаемой модели, например gemini-4-hydrogen, и инструмента computer_use, у которого environment соответствует исполнителю. Установка environment: "desktop" сама по себе не даёт модели управление компьютером и не устанавливает драйвер ОС.

В руководстве мы собираем небольшой браузерный пример, объясняем изменения для рабочего стола и Android и предоставляем готовый контроллер с явными правилами подтверждения и остановки. Документация и пакеты проверены 13 ноября 2026 года. Текущая документация Computer Use Google включает Carbon, Argon и Hydrogen в список поддерживаемых моделей. Здесь используется Hydrogen; выбор между ними рассматривается отдельно в руководстве по моделям Gemini 4. Документы разработчиков, на которые мы ссылаемся, — на английском.

Статью публикует Ofox. Наши свидетельства — 22 офлайн-теста с синтетическими ответами модели и реальная проверка локальной страницы в Chrome через отдельный инструмент управления интерфейсом. Поставляемый Python-раннер Playwright не запускался с моделью и не проходил сквозную проверку. Мы не выполняли платный инференс, не испытывали исполнители для рабочего стола или Android и не измеряли производительность модели. Это важно для понимания того, что можно переиспользовать, а что ещё нужно проверить в своей среде.

Сначала выберите формат API, затем среду исполнения

У агента Computer Use три задачи: модель предлагает действия, исполнитель выполняет поддерживаемые действия, а проверяющий компонент подтверждает результат в приложении. Последние два компонента предоставляете вы. Финальное «готово» от модели не доказывает, что форма отправлена, файл сохранён или кнопка нажата.

Используйте один формат API на протяжении всего цикла. Это руководство основано на Interactions: steps, function_call, function_result и previous_interaction_id. Проверенная нами версия официального примера, коммит 77c9797e943aad63bbc963b7fd092a9e51c07863, использует GenerateContent. Код также различает современные действия и действия старой preview-версии. Это полезный пример, но его парсер ответов нельзя без изменений перенести в цикл Interactions.

Подготовка проекта и ключа Google описана в руководстве по Hydrogen API. Для этого примера храните ключ Google в GEMINI_API_KEY. Ключ Ofox относится к отдельно документированному процессу аутентификации Ofox.

У Ofox есть документация Chat Completions и нативного маршрута Gemini. Общая поддержка протокола ещё не подтверждает поддержку текущего контракта Google Interactions Computer Use. Поэтому руководство использует нативный маршрут Google и не утверждает, что цикл заработает после простой замены Base URL на Ofox. Если нужны только файловые инструменты репозитория, другой вариант подключения описан в руководстве по Hydrogen для Cline и OpenCode.

Установите локальный комплект и проверьте его без ключа модели

Скачайте полный комплект Computer Use, распакуйте архив и перейдите в каталог gemini-computer-use-kit. В нём есть контроллер, офлайн-тесты, локальная HTML-страница, необязательный live-раннер и 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 активируйте окружение через .venv\Scripts\Activate.ps1 в PowerShell вместо source. Для офлайн-проверок не нужны Playwright и API-ключ. Ожидаемый результат — 22 успешных теста. Мы повторили их после новой распаковки распространяемого архива, а не только в рабочем каталоге.

Тесты используют настоящие классы ответов 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. Введите маркер и нажмите кнопку, чтобы проверить саму страницу. Затем перезагрузите её: агент должен начинать с пустого поля, а не с уже выполненной задачи.

Реальный снимок Chrome с областью просмотра 1000 × 700; страница управлялась отдельным UI-инструментом. Он подтверждает видимое поведение страницы, но не выполнение задачи Hydrogen или поставляемым Python-раннером. Для этого снимка модель не подключалась.

Запустите необязательную браузерную интеграцию Google

Оставьте локальный HTTP-сервер работающим. В активированном Python-окружении задайте Google GEMINI_API_KEY обычным для вас способом управления секретами. Не помещайте ключ в тестовую страницу и не коммитьте его в репозиторий. Следующая команда обращается к реальному сервису и может расходовать квоту проекта или платное использование. В отличие от офлайн-тестов, это уже не проверка без модели.

python run_live.py

Раннер создаёт новый браузерный контекст с областью просмотра 1000 × 700 CSS-пикселей, масштабом устройства 1, заблокированными service worker и отключёнными загрузками. Фильтр браузерных запросов разрешает только точный URL тестовой страницы. Это ограничивает демонстрацию, но не является песочницей ОС или универсальной защитой для произвольных сайтов.

Полный текст задания в раннере:

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», проверка считается неуспешной.

Мы не запускали этот live-раннер, поэтому успешный запуск в вашем аккаунте будет новым свидетельством. Запишите версию клиента, ID модели, фактический результат и использование. Не представляйте время офлайн-теста как скорость модели, а имитированные ответы — как данные счёта.

Согласуйте координаты, снимки и ID вызовов

Текущие действия Google используют нормализованные целые координаты от 0 до 999 на оси из 1000 единиц. Пересчитывайте их по размерам наблюдения, которое реально использует исполнитель:

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) соответствует (400, 350) CSS-пикселям. Это пример пересчёта, а не записанное предсказание 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"}
  ]
}

Плейсхолдеры выше служат объяснением, а не готовым к отправке ответом. Если пришло несколько вызовов, каждому выполненному вызову нужен соответствующий результат. Следующий запрос использует previous_interaction_id того interaction, который содержал эти вызовы. ID interaction нельзя подменять ID вызова функции.

Пример опирается на сохранённое состояние interaction. Не добавляйте store=False, не переработав хранение истории по документации Interactions. Для другого протокола или клиентской истории сохраняйте требуемое состояние модели и подписи без изменений. Руководство по отсутствующим thought signatures Gemini объясняет один из сценариев ошибки, но не подтверждает, что этот пример прошёл реальный тест подписей.

Адаптируйте исполнитель для рабочего стола или Android

Среда сообщает модели, какой набор действий использовать. Она не создаёт браузер, виртуальную машину, сеанс рабочего стола или телефон. В справке по средам Google различаются три цели:

Комплект реализует только браузерную тестовую страницу. Для рабочего стола оставьте цикл запросов и результатов, но замените операции браузерного page:

1. Выберите отдельный тестовый рабочий стол или VM с одним дисплеем. На первом запуске зафиксируйте размер и не используйте личный сеанс с посторонними окнами.
2. Независимо проверьте захват экрана и запишите ширину и высоту изображения. До подключения модели отдельно проверьте безвредный ввод в локальном тестовом приложении.
3. Переведите нормализованные координаты в систему ввода. Если библиотека захвата возвращает физические пиксели, а библиотека ввода использует логические, последовательно масштабируйте наблюдение или применяйте документированное преобразование.
4. Явно свяжите поддерживаемые действия с обработчиками: клик указателя, вставка текста, клавиши, прокрутка и новый захват. Исключайте или отклоняйте нереализованное; браузерная навигация не является универсальным действием рабочего стола.
5. Измените среду инструмента на desktop, сохраните соответствие ID и результатов и после первого действия проверьте состояние приложения. Одного перемещения курсора недостаточно для вывода об успехе.

В macOS доступ к записи экрана и управление через Accessibility — разные разрешения. Возможность получить снимок не доказывает, что процесс может нажимать и печатать. Разрешайте только доступ, нужный намеренно установленному исполнителю; эти настройки не требуют другого 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 не проверялись на устройстве в рамках статьи. Они определяют реальные задачи интеграции и точки приёмки, а не обещают перенос одной заменой строки среды.

Явно обрабатывайте подтверждение, остановку и восстановление

intent модели — объяснение предлагаемого действия, а не разрешение. Если вызов содержит safety_decision.decision: "require_confirmation", дождитесь пользователя. Документация решений безопасности Google предусматривает подтверждение после одобрения. Комплект добавляет safety_acknowledgement: true внутрь текста результата действия только после согласия пользователя.

Контроллер сначала проверяет весь пакет и получает необходимые подтверждения, а уже затем выполняет любое действие. Неподдерживаемые действия, некорректные метаданные безопасности и другие явные состояния решения приводят к остановке. Для этой тестовой страницы выбран консервативный подход. Отсутствие решения безопасности не заменяет собственных правил приложения о разрешённых пользователем задачах.

По умолчанию допускаются 12 пакетов действий и 120 секунд на запрос модели при отключённом автоматическом продолжении. Это не общий лимит времени и не бюджет в долларах: ожидание пользователя может затянуться, пакет может содержать несколько действий, а снимки и повторяемый контекст влияют на использование. У SDK также возможны транспортные повторные попытки. Мы не обещаем нулевые повторы или фиксированную стоимость.

Если запрос после клика завершился таймаутом, сам клик уже мог произойти. Приложение не повторяет действие автоматически. Остановитесь, проверьте реальную страницу, сохраните ID interaction и вызова и решите, продолжать ли сохранённый диалог или начать новую задачу. Не перезапускайте вслепую отправку формы с неизвестным результатом. Для локального примера проверьте поле и вывод, затем перезагрузите страницу для чистого теста.

Ошибка снимка или браузера после действия не отменяет уже сделанное. В рабочем процессе нужна независимая проверка результата, подходящая приложению: например, ID сохранённой записи или изменение значения документа. Видимый маркер достаточен только для этой простой страницы, а не для любой транзакции. В прежнем офлайн-разборе контроллера Computer Use рассмотрен другой, ориентированный на OpenAI контроллер и проверка принимающей стороны.

Ищите ошибку на том уровне, где она появилась

Аутентификация, квоты и некорректные запросы также разобраны в руководстве по ошибкам Gemini API. Оно написано вокруг Argon: применяйте общие категории к фактическому ответу Hydrogen, не предполагая полного совпадения модельных деталей. При диагностике отдельного маршрута Ofox используйте документированную обработку ошибок Ofox; она не заменяет диагностику проекта Google.

Определите, нужен ли API-цикл или готовый агент

Этот подход подходит, когда вы должны управлять исполнителем, подтверждениями, наблюдениями и проверкой результата приложения. Если нужно просто начать пользоваться готовым настольным продуктом, другой отправной точкой служит обзор платформы Antigravity (на английском). Сравнение расширения Chrome, Computer Use и удалённого управления также разделяет эти категории.

Прежде чем выйти за рамки тестовой страницы, сохраните версии модели и SDK, API, среду, размеры снимка, реализованные действия, политику подтверждения и независимое условие успеха. В журнале различайте офлайн-проверку контроллера, работу браузера и реальный инференс. Для этого комплекта есть свидетельства только первых двух, причём браузер проверялся отдельно от Python-раннера.

Следующая цель — одна реальная задача, в которой нужный аккаунт, исполнитель и проверяющий компонент работают вместе. Расширяйте набор действий или переходите на рабочий стол и мобильные устройства только после наблюдаемого и воспроизводимого результата. Рост возможностей модели не отменяет необходимости знать, какое действие выполнено и что оно изменило.