Penggunaan komputer

Alat Penggunaan Komputer memungkinkan Anda membuat agen kontrol browser, seluler, dan desktop yang berinteraksi dengan dan mengotomatiskan tugas. Dengan menggunakan screenshot, model dapat "melihat" layar komputer, dan "bertindak" dengan membuat tindakan UI tertentu seperti klik mouse dan input keyboard. Mirip dengan panggilan fungsi, Anda harus menerapkan lingkungan eksekusi sisi klien untuk menerima dan mengeksekusi tindakan Penggunaan Komputer.

Untuk mengetahui daftar model yang didukung, lihat Versi model. Model Gemini 3.x mendukung beberapa kemampuan lanjutan:

• Dukungan multi-lingkungan: agen build untuk lingkungan browser, seluler, dan desktop.
• Tindakan yang disederhanakan dengan maksud: tindakan mencakup kolom intent yang menjelaskan alasan model di balik setiap langkah.
• Kebijakan keamanan yang dapat dikonfigurasi: sesuaikan perilaku keamanan dengan kategori dan penggantian kebijakan bawaan.
• Deteksi injeksi perintah: aktifkan pemindaian screenshot untuk mendeteksi petunjuk berbahaya tersembunyi.

Dengan Penggunaan Komputer, Anda dapat membuat agen yang:

• Mengotomatiskan entri data atau pengisian formulir yang berulang di situs.
• Melakukan pengujian otomatis aplikasi web dan alur pengguna
• Melakukan riset di berbagai situs (misalnya, mengumpulkan informasi produk, harga, dan ulasan dari situs e-commerce untuk membantu pembelian)

Berikut adalah contoh minimal untuk menginisialisasi klien dan mengirimkan perintah ke model dengan alat computer_use yang diaktifkan untuk lingkungan browser:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input="Search for 'Gemini API' on Google.",
    tools=[{"type": "computer_use", "environment": "browser"}]
)

print(interaction)

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI();

const interaction = await ai.interactions.create({
  model: 'gemini-3.7-flash',
  input: "Search for 'Gemini API' on Google.",
  tools: [{ type: "computer_use", environment: "browser" }]
});

console.log(interaction);

Cara kerja Penggunaan Komputer

Untuk membuat agen dengan model Penggunaan Komputer, Anda perlu menyiapkan loop berkelanjutan antara aplikasi dan API. Berikut adalah fungsi kode Anda di setiap langkah:

1. Mengirim permintaan ke model
   • Aplikasi Anda mengirimkan permintaan API yang berisi alat Penggunaan Komputer, setelan konfigurasi Anda (seperti lingkungan target), perintah pengguna, dan screenshot layar saat ini.
2. Menerima respons model
   • Model menganalisis layar dan perintah, lalu menampilkan respons yang mencakup function_call yang disarankan yang merepresentasikan tindakan UI (seperti klik, scroll, atau penekanan tombol).
   • Untuk model Gemini 3.x, respons juga mencakup alasan intent yang menjelaskan mengapa model memilih tindakan tersebut.
   • Respons juga dapat mencakup safety_decision dari sistem keamanan internal yang mengklasifikasikan tindakan sebagai reguler/diizinkan, require_confirmation (memerlukan persetujuan pengguna), atau diblokir.
3. Jalankan tindakan yang diterima
   • Jika tindakan diizinkan (atau pengguna mengonfirmasinya), kode sisi klien Anda akan mengurai function_call, menskalakan koordinat yang dinormalisasi agar sesuai dengan area tampilan, dan menjalankan tindakan di lingkungan target menggunakan alat otomatisasi (seperti Playwright). Jika tindakan diblokir, klien Anda harus menghentikan eksekusi atau menangani gangguan.
4. Merekam status lingkungan baru
   • Setelah tindakan selesai dieksekusi, aplikasi Anda akan mengambil screenshot baru dan mengirimkannya kembali ke model dalam function_result untuk meminta langkah berikutnya.

Kemudian, proses ini diulang dari langkah 2, terus-menerus meminta tindakan berikutnya dari model hingga tugas selesai atau dihentikan.

Cara menerapkan Penggunaan Komputer

Sebelum membangun dengan alat Penggunaan Komputer, Anda harus menyiapkan:

• Lingkungan eksekusi yang aman: Jalankan agen Anda di VM atau container sandbox untuk mengisolasinya dari sistem host Anda dan membatasi potensi dampaknya. Penerapan referensi mencakup sandbox berbasis Docker yang siap digunakan dan dapat Anda gunakan sebagai titik awal.
• Handler tindakan sisi klien: Terapkan logika sisi klien untuk menjalankan koordinat, mengetik teks, dan mengambil screenshot.

Contoh di bawah menggunakan browser web sebagai lingkungan eksekusi dan Playwright sebagai handler sisi klien.

0. Menyiapkan Playwright

Pertama, instal paket yang diperlukan:

pip install google-genai playwright
playwright install chromium

Kemudian, inisialisasi instance browser Playwright untuk digunakan dalam eksekusi:

from playwright.sync_api import sync_playwright

# 1. Configure screen dimensions for the target environment
SCREEN_WIDTH = 1440
SCREEN_HEIGHT = 900

# 2. Start the Playwright browser
# In production, utilize a sandboxed environment.
playwright = sync_playwright().start()
# Set headless=False to see the actions performed on your screen
browser = playwright.chromium.launch(headless=False)

# 3. Create a context and page with the specified dimensions
context = browser.new_context(
    viewport={"width": SCREEN_WIDTH, "height": SCREEN_HEIGHT}
)
page = context.new_page()

# 4. Navigate to an initial page to start the task
page.goto("https://www.google.com")

# The 'page', 'SCREEN_WIDTH', and 'SCREEN_HEIGHT' variables
# will be used in the steps below.

1. Mengirim permintaan ke model

Lakukan inisialisasi library klien dan konfigurasi alat Penggunaan Komputer. Perhatikan bahwa tidak perlu menentukan ukuran tampilan saat mengeluarkan permintaan; model memprediksi koordinat piksel yang diskalakan ke tinggi dan lebar layar.

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model='gemini-3.7-flash',
    input="Find a flight from SF to Hawaii on Jun 30th, coming back on Jul 6th",
    tools=[
        {
            "type": "computer_use",
            "environment": "browser",
            "enable_prompt_injection_detection": True
        }
    ]
)

print(interaction)

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI();

const interaction = await ai.interactions.create({
  model: 'gemini-3.7-flash',
  input: "Find a flight from SF to Hawaii on Jun 30th, coming back on Jul 6th",
  tools: [
    {
      type: "computer_use",
      environment: "browser",
      enable_prompt_injection_detection: true
    }
  ]
});

console.log(interaction);