Gemini 4 Computer Use 설정: 브라우저·데스크톱·Android

Gemini 4 Computer Use는 화면 동작을 제안합니다. 실제 실행과 새로운 관찰 결과 반환은 애플리케이션이 담당해야 합니다. Google Interactions API, gemini-4-hydrogen 같은 지원 모델, 실행기와 environment가 일치하는 computer_use 도구로 시작하세요. environment: "desktop"을 설정한다고 모델에 컴퓨터 제어 권한이 생기거나 운영체제 드라이버가 설치되지는 않습니다.

이 글에서는 작은 브라우저 예제를 구성하고, 데스크톱과 Android로 옮길 때 달라지는 부분을 설명합니다. 승인 및 중단 동작을 명시한 전체 컨트롤러도 제공합니다. 문서와 패키지 확인일은 2026년 11월 13일입니다. Google의 현재 Computer Use 문서는 Carbon, Argon, Hydrogen을 지원 모델에 포함합니다. 예제는 Hydrogen을 사용하며, 모델 선택은 Gemini 4 모델 선택 가이드에서 별도로 다룹니다. 인용한 공급사 문서는 영문입니다.

이 글의 발행자는 Ofox입니다. 검증 근거는 합성 모델 응답을 사용한 오프라인 테스트 22개와 별도의 UI 도구로 Chrome에서 로컬 테스트 페이지를 실제 조작한 기록입니다. 제공하는 Python Playwright 실행기는 모델에 연결해 실행하지 않았으며 엔드투엔드 검증도 하지 않았습니다. 유료 추론, 데스크톱·Android 실행기 테스트, 모델 성능 측정도 하지 않았습니다. 재사용 가능한 부분과 자신의 환경에서 추가 검증해야 할 부분을 구분해야 합니다.

실행 환경보다 API 형식을 먼저 정하기

Computer Use 에이전트에는 세 가지 역할이 있습니다. 모델은 동작을 제안하고, 실행기는 지원 동작을 수행하며, 검증기는 애플리케이션 결과를 확인합니다. 뒤의 두 요소는 직접 제공해야 합니다. 모델의 마지막 “완료” 메시지만으로는 폼 전송, 파일 저장, 버튼 클릭을 입증할 수 없습니다.

전체 루프에서 하나의 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만 허용합니다. 이는 데모 범위를 제한하는 설정이지, 운영체제 샌드박스나 임의의 웹사이트를 위한 일반적인 보호 장치가 아닙니다.

실행기에 들어 있는 전체 작업 프롬프트는 다음과 같습니다.

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에 맞게 바꾸기

환경은 모델에 사용할 동작 종류를 알려 줍니다. 브라우저, 가상 머신, 데스크톱 세션이나 휴대폰을 마련해 주지는 않습니다. Google의 환경 참고 문서는 세 대상을 구분합니다.

다운로드 키트는 브라우저 테스트 페이지만 구현합니다. 데스크톱 어댑터를 연결하려면 요청·결과 루프를 유지하고 브라우저 page 작업을 교체하세요.

1. 전용 테스트 데스크톱이나 가상 머신을 선택하고 단일 디스플레이를 사용합니다. 첫 실행은 크기를 고정하고, 무관한 창이 열린 개인 세션은 피하세요.
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 절차를 장치로 테스트하지는 않았습니다. 실제 통합 작업과 검증 지점을 드러내기 위한 설명이지, 환경 문자열 하나를 바꾸면 이식이 끝난다는 뜻이 아닙니다.

승인·중단·복구를 명시적으로 처리하기

모델의 intent는 제안된 동작의 설명이며 허가가 아닙니다. 함수 호출에 safety_decision.decision: "require_confirmation"이 들어 있으면 사용자를 기다리세요. Google의 안전 판단 문서는 승인 후 확인 정보를 반환하도록 설명합니다. 키트도 사용자가 승인한 뒤에만 동작 결과 텍스트 안에 safety_acknowledgement: true를 넣습니다.

컨트롤러는 전체 배치를 검증하고 필요한 승인을 모두 받은 후에 동작을 실행합니다. 미지원 동작, 잘못된 안전 메타데이터, 그 밖의 명시적인 판단 상태에서는 중단합니다. 테스트 페이지에 맞춰 보수적으로 설계한 것입니다. 안전 판단 필드가 없다고 해서 사용자가 허용한 작업에 관한 앱의 자체 규칙을 대체할 수는 없습니다.

기본값은 동작 배치 12개, 모델 요청당 120초이며 자동 이어가기는 비활성화합니다. 전체 시간 제한이나 금액 예산은 아닙니다. 사람의 승인을 기다릴 수 있고, 배치에 여러 동작이 들어갈 수 있으며, 스크린샷과 반복 컨텍스트도 사용량에 영향을 줍니다. SDK의 전송 계층 재시도도 있을 수 있으므로 재시도 0회나 고정 비용을 주장하지 않습니다.

클릭 후 요청이 타임아웃되면 클릭은 이미 실행되었을 수 있습니다. 앱은 그 동작을 자동 재생하지 않습니다. 중단하고 실제 페이지를 확인한 다음 interaction·호출 ID를 보존해 원래 대화를 이어갈지 새 작업을 시작할지 판단하세요. 결과를 모르는 폼 제출을 무작정 다시 시작하지 마세요. 로컬 테스트 페이지에서는 필드와 출력을 확인한 뒤 새로고침해 상태를 지우고 새 테스트를 시작할 수 있습니다.

동작 후의 스크린샷 오류나 브라우저 장애는 이미 실행한 작업을 되돌리지 못합니다. 운영 환경에는 저장된 레코드 ID나 문서 값 변경처럼 앱에 맞는 독립적 결과 검사가 필요합니다. 눈에 보이는 마커는 이 단순한 페이지에만 충분하며, 범용 트랜잭션 검증기가 아닙니다. 이전의 오프라인 Computer Use 컨트롤러 실습은 OpenAI 중심의 다른 컨트롤러와 수신 측 확인 방식을 다룹니다.

오류가 발생한 계층에서 진단하기

인증, 할당량, 잘못된 요청은 Gemini API 오류 가이드에서도 다룹니다. Argon 중심 문서이므로 모델별 세부사항을 모두 그대로 적용하지 말고, 실제 Hydrogen 응답에 일반 오류 범주를 적용하세요. 별도의 Ofox 경로를 조사한다면 그 경로의 Ofox 오류 처리 문서를 사용하세요. Google 프로젝트 진단을 대체하지는 않습니다.

API 루프와 완성형 에이전트 중 필요한 것 선택하기

실행기, 승인 방식, 관찰, 앱 검증기를 직접 관리해야 한다면 이 API 접근이 적합합니다. 바로 사용할 수 있는 데스크톱 제품이 목적이라면 Antigravity 플랫폼 개요 (영문)가 다른 출발점을 설명합니다. Chrome 확장 프로그램·Computer Use·원격 제어 비교도 제품 범주를 구분합니다.

테스트 페이지를 벗어나기 전에 모델과 SDK 버전, API, 환경, 이미지 크기, 구현한 동작, 승인 정책, 독립적인 성공 조건을 저장하세요. 오프라인 컨트롤러 검사, 브라우저 조작, 실제 모델 추론을 구별해 기록합니다. 이 키트에는 앞의 두 항목만 근거가 있으며, 브라우저 검사는 Python 실행기와 별도로 수행했습니다.

다음 목표는 대상 계정, 실행기, 검증기가 함께 작동하는 실제 작업 하나입니다. 결과를 관찰하고 재현할 수 있을 때 동작을 추가하거나 데스크톱·모바일로 확장하세요. 모델 기능이 좋아져도 어떤 동작이 실제 실행되었고 무엇이 바뀌었는지 확인하는 과정은 필요합니다.