Panduan Lengkap Gemini 2.5 Computer Use (2025): Dari Setup API sampai Agen Pertama

Mengapa Gemini 2.5 Computer Use Penting untuk Bisnis dan Developer

Margabagus.com – Gemini 2.5 Computer Use menghadirkan kemampuan agen yang mengerti tampilan layar, kemudian bertindak di atas antarmuka web, mulai dari mengisi formulir, menekan tombol, sampai menyusun alur kerja multi langkah yang konsisten dengan tujuan pengguna. Model ini tersedia sebagai pratinjau melalui Gemini API dan Vertex AI, sehingga tim produk dapat membangun prototipe cepat sekaligus menyiapkan jalur ke produksi enterprise. Google menegaskan bahwa fokus utamanya adalah kontrol browser, sementara penggunaan pada lingkungan seluler menunjukkan potensi yang kuat, tetapi kontrol level sistem operasi desktop belum menjadi target utama saat ini.^[1][2]

Di rilis Oktober 2025, Google menyebut Computer Use melampaui alternatif terkemuka pada beberapa tolok ukur kontrol web dan seluler, disertai latensi yang lebih rendah yang relevan untuk pengalaman pengguna nyata. Akses tersedia lewat AI Studio dan Vertex AI, dengan demo publik di Browserbase untuk eksplorasi cepat sebelum integrasi dalam lingkungan sendiri.^[1]

Catatan teknis yang penting untuk implementasi, antara lain penggunaan model id gemini-2.5-computer-use-preview-10-2025, masukan gabungan teks dan gambar, keluaran teks dengan token limit masukan hingga ratusan ribu token, serta rekomendasi resolusi layar saat menguji agen yaitu lebar 1440 dan tinggi 900 piksel agar pengenalan elemen lebih stabil.^[2]

Rangkaian rencana, aksi, observasi, dan ulang divisualkan dalam alur 3D

Cara Kerja Computer Use di Gemini API, Dari Rencana sampai Aksi

Pada tingkat arsitektur, Computer Use beroperasi dalam sebuah loop agen yang memadukan pemahaman visual terhadap tangkapan layar, konteks instruksi, serta sejarah aksi yang telah dilakukan. Tujuannya memastikan model membagi tugas besar menjadi langkah yang dapat dieksekusi, kemudian memeriksa ulang hasil setiap langkah sebelum bergerak ke langkah berikutnya.^[1][2]

Model mengembalikan panggilan fungsi untuk tindakan antarmuka yang telah didukung, misalnya menekan pada koordinat tertentu, mengetik pada area masukan, atau membuka halaman web baru. Sebagian tindakan dapat ditandai oleh sistem keamanan agar memerlukan konfirmasi pengguna, misalnya saat langkah berisiko atau berdampak signifikan bagi pengguna. Setelah aksi dijalankan, klien mengirimkan kembali tangkapan layar terbaru dan alamat laman saat ini dalam bentuk tanggapan fungsi agar model dapat menilai keadaan baru.^[1][2]

Arsitektur ringkas:

1. Kirim permintaan ke model dengan tool Computer Use, masukan tujuan pengguna, dan opsional sebuah tangkapan layar awal.
2. Terima rencana model dalam bentuk satu atau beberapa function call yang mewakili aksi antarmuka.
3. Eksekusi aksi di sisi klien kemudian simpan detail hasilnya.
4. Ambil tangkapan layar terkini dan URL saat ini, lalu kirim sebagai function response agar model dapat melanjutkan.
5. Ulangi sampai tujuan terpenuhi, ada kesalahan, atau proses dihentikan oleh sistem keamanan.^[2]

API key dan sandbox sebagai fondasi keamanan sebelum menjalankan agen

Persiapan Lingkungan dan API Key untuk Gemini 2.5 Computer Use

Sebelum menulis agen, siapkan kunci API dari AI Studio, kemudian pilih eksekutor browser yang aman, misalnya Playwright di lingkungan sandbox, mesin virtual, atau profil peramban terpisah. Pendekatan ini mengurangi risiko kebocoran data, mempermudah debugging, dan membantu mengontrol dependensi pada proyek bersama tim.^[2]

Langkah singkat:

1. Dapatkan API Key di AI Studio, simpan sebagai variabel lingkungan GEMINI_API_KEY.
2. Pasang SDK baru Google GenAI dan Playwright sesuai bahasa yang digunakan.
3. Inisialisasi peramban dengan viewport stabil, misalnya 1440 dan 900 piksel.
4. Jalankan agen di profil terisolasi agar kuki dan sesi tidak tercampur dengan sesi harian Anda.^[4][2]

Instalasi Python:

pip install -U google-genai playwright playwright install chromium

Instalasi JavaScript:

npm install @google/genai playwright

Sumber resmi quickstart menunjukkan paket SDK baru untuk Python dan JavaScript, serta tata cara pengambilan kunci dari variabel lingkungan.^[4]

Pemetaan aksi klik dan ketik ditunjukkan dalam komposisi 3D yang bersih

Template Agen Python, Playwright sebagai Eksekutor Aksi UI

Bagian ini menyiapkan agen Python yang berkomunikasi dengan Gemini 2.5 Computer Use, mengeksekusi aksi pada browser Playwright, lalu mengirim function response berisi tangkapan layar agar model dapat melanjutkan perencanaan. Template memetakan aksi umum seperti membuka peramban, menekan pada koordinat, dan mengetik pada bidang masukan. Koordinat yang dikirim model berbentuk nilai terukur nol sampai sembilan ratus sembilan puluh sembilan, sehingga perlu dinormalisasi kembali ke piksel sesuai viewport yang Anda pakai.^[2]

Catatan model: gunakan id gemini-2.5-computer-use-preview-10-2025. Jika memakai model lain pada tool ini, permintaan akan gagal.^[2]

# python 3.10+ # Agen Computer Use minimal: rencana → eksekusi → observasi → ulang from google import genai from google.genai import types from google.genai.types import Content, Part from playwright.sync_api import sync_playwright import time, os API_KEY = os.environ.get("GEMINI_API_KEY") assert API_KEY, "Set GEMINI_API_KEY terlebih dahulu" # 1) Klien Gemini client = genai.Client(api_key=API_KEY) # 2) Konfigurasi tool Computer Use excluded = ["drag_and_drop"] # contoh pembatasan aksi berisiko config = genai.types.GenerateContentConfig( tools=[ types.Tool( computer_use=types.ComputerUse( environment=types.Environment.ENVIRONMENT_BROWSER, excluded_predefined_functions=excluded ) ) ] ) # 3) Inisialisasi Playwright SCREEN_W, SCREEN_H = 1440, 900 pw = sync_playwright().start() browser = pw.chromium.launch(headless=False) context = browser.new_context(viewport={"width": SCREEN_W, "height": SCREEN_H}) page = context.new_page() page.goto("https://www.google.com") # Util: ubah koordinat terukur 0-999 ke piksel def dx(x): return int(x / 1000 * SCREEN_W) def dy(y): return int(y / 1000 * SCREEN_H) # Eksekusi aksi yang diminta model def execute_calls(candidate): results = [] for part in candidate.content.parts: fc = getattr(part, "function_call", None) if not fc: continue name, args = fc.name, fc.args or {} try: if name == "open_web_browser": pass elif name == "click_at": page.mouse.click(dx(args["x"]), dy(args["y"])) elif name == "type_text_at": page.mouse.click(dx(args["x"]), dy(args["y"])) if args.get("clear", True): page.keyboard.press("Meta+A"); page.keyboard.press("Backspace") page.keyboard.type(args["text"]) if args.get("press_enter"): page.keyboard.press("Enter") else: print(f"Peringatan, aksi {name} belum diimplementasikan") page.wait_for_load_state(timeout=5000) time.sleep(0.8) results.append((name, {"ok": True})) except Exception as e: results.append((name, {"error": str(e)})) return results # Siapkan pesan awal contents = [ Content(role="user", parts=[ Part(text=( "Cari di Google Shopping kulkas pintar dua pintu layar sentuh, " "kapasitas sekitar 25 cu ft, harga di bawah 4000 dollar, " "lalu rangkum tiga opsi termurah dalam daftar poin, nama, ringkas, harga" )) # Part.from_bytes(data=page.screenshot(), mime_type="image/png") # opsional ]) ] # Loop multi langkah for turn in range(6): resp = client.models.generate_content( model="gemini-2.5-computer-use-preview-10-2025", contents=contents, config=config ) candidate = resp.candidates[0] contents.append(candidate.content) # Eksekusi aksi yang diminta results = execute_calls(candidate) # Kirim function_response, sertakan screenshot dan URL screenshot = page.screenshot(type="png") url_now = page.url fr_list = [] for name, result in results: payload = {"url": url_now}; payload.update(result) fr_list.append( types.FunctionResponse( name=name, response=payload, parts=[types.FunctionResponsePart( inline_data=types.FunctionResponseBlob( mime_type="image/png", data=screenshot ) )] ) ) # Tambahkan balasan fungsi ke sejarah percakapan contents.append(Content(role="tool", parts=fr_list)) # Tutup browser saat selesai browser.close(); pw.stop()

Kode di atas mengikuti pola resmi, yakni mengambil function call, mengeksekusi, lalu mengirim function response beserta gambar layar terkini dan alamat laman. Anda dapat memperluas pemetaan aksi untuk daftar aksi resmi yang didukung, atau justru mengecualikannya melalui excluded_predefined_functions.^[2]

Baca juga artikel menraik tentang: AlphaEvolve: Agent Coding dari Google DeepMind untuk Desain Algoritma

Versi Node.js untuk Aplikasi Web Modern

Jika aplikasi Anda lebih nyaman di JavaScript, gunakan SDK @google/genai dan Playwright. Prinsipnya sama, yakni membaca function call dari kandidat, lalu mengeksekusi aksi pada halaman, kemudian mengirim function response dengan tangkapan layar dan URL.

// node 18+ import { GoogleGenAI, Schema } from "@google/genai"; import { chromium } from "playwright"; const apiKey = process.env.GEMINI_API_KEY; if (!apiKey) throw new Error("Set GEMINI_API_KEY terlebih dahulu"); const ai = new GoogleGenAI({ apiKey }); const excluded = ["drag_and_drop"]; const browser = await chromium.launch({ headless: false }); const context = await browser.newContext({ viewport: { width: 1440, height: 900 } }); const page = await context.newPage(); await page.goto("https://www.google.com"); const contents = [{ role: "user", parts: [{ text: "Buka situs berita teknologi populer, cari artikel tentang tren AI bisnis pekan ini, lalu rangkum tiga poin utama dan cantumkan tautannya" }] }]; // util normalisasi const dx = x => Math.floor(x / 1000 * 1440); const dy = y => Math.floor(y / 1000 * 900); for (let i = 0; i < 6; i++) { const response = await ai.models.generateContent({ model: "gemini-2.5-computer-use-preview-10-2025", contents, config: { tools: [{ computerUse: { environment: "ENVIRONMENT_BROWSER", excludedPredefinedFunctions: excluded } }] } }); const cand = response.candidates[0]; contents.push(cand.content); const calls = cand.content.parts .filter(p => p.functionCall) .map(p => p.functionCall); // eksekusi aksi for (const fc of calls) { const { name, args } = fc; if (name === "click_at") { await page.mouse.click(dx(args.x), dy(args.y)); } else if (name === "type_text_at") { await page.mouse.click(dx(args.x), dy(args.y)); await page.keyboard.press("Meta+A"); await page.keyboard.press("Backspace"); await page.keyboard.type(args.text || ""); if (args.press_enter) await page.keyboard.press("Enter"); } } // kirim function response const shot = await page.screenshot({ type: "png" }); const url = page.url(); contents.push({ role: "tool", parts: calls.map(c => ({ functionResponse: { name: c.name, response: { url, ok: true }, parts: [{ inlineData: { mimeType: "image/png", data: shot.toString("base64") } }] } })) }); } await browser.close();

Dokumentasi resmi quickstart menjelaskan paket SDK baru untuk JavaScript dan cara kerja generateContent, sedangkan halaman Computer Use mendetailkan daftar aksi, keputusan keamanan, dan tata cara pengembalian function response.^[4][2]

Pagar pengaman dan konfirmasi pengguna divisualkan dengan perisai transparan

Desain Prompt dan Guardrail yang Aman untuk Computer Use

Agen yang mengendalikan antarmuka manusia perlu batasan eksplisit agar tidak melakukan tindakan sensitif, misalnya pembelian, perubahan kredensial, atau manipulasi data bisnis. Computer Use menyediakan safety decision yang dapat menandai aksi tertentu agar memerlukan konfirmasi pengguna, sementara pengembang dapat menyetel kebijakan sistem dan mengecualikan fungsi berisiko dari awal ^[1][2].

Serangan injeksi prompt di lingkungan web semakin sering muncul, termasuk siasat menyisipkan instruksi tersembunyi di surel dan dokumen, sehingga ringkasan otomatis bisa terseret ke arah yang menyesatkan. Praktik terbaik meliputi pemindaian konten tak terlihat, pembatasan domain asal untuk peramban otomatis, serta konfirmasi pengguna pada langkah vital ^[8].

Contoh kebijakan aman:

• Batasi fungsi, misalnya excluded_predefined_functions = ["drag_and_drop", "double_click_at"].

• Tambah instruksi sistem, misalnya meminta konfirmasi tertulis sebelum aksi yang berisiko.

• Terapkan allowlist domain, simpan kuki atau sesi pada profil terisolasi, serta catat seluruh aksi dan hasil layar.

• Tampilkan penjelasan singkat kepada pengguna saat aksi diblokir oleh kebijakan.

Integrasi Vertex AI dan Peran AI Studio untuk Workflow Tim

AI Studio berguna untuk prototipe cepat dan pengujian konsep, sedangkan Vertex AI menambahkan kontrol identitas, quota, penagihan terpusat, serta integrasi jaringan privat dan rahasia perusahaan. Keduanya menyediakan akses pada model Computer Use dan pola penggunaan tool yang sama sehingga perpindahan dari prototipe ke produksi menjadi efisien.^[3][1]

Dokumentasi Vertex AI menjelaskan Computer Use sebagai model dan tool yang menerima tangkapan layar, lalu mengeluarkan aksi antarmuka yang perlu dieksekusi oleh klien, serupa dengan pola pada Gemini API. Pengembang dapat menanamkan executor pada layanan internal yang mematuhi kebijakan keamanan perusahaan.^[3]

Baca juga artikel menarik tentang: Google AI Mode: Cara Kerja, Dampaknya untuk SEO, dan Strategi Muncul di AI Overview

Pengujian, Logging, dan Evaluasi Kualitas Agen Computer Use

Hasil yang konsisten memerlukan tata kelola yang rapi, mulai dari ukuran layar yang tetap, waktu tunggu pemuatan yang realistis, sampai mekanisme ulang saat navigasi gagal. Google menampilkan hasil evaluasi yang menunjukkan kualitas tinggi pada tolok ukur seperti Online Mind2Web dan WebVoyager, disertai latensi rendah yang bermanfaat untuk pengalaman nyata pengguna bisnis.^[1]

Bangun logger yang menyimpan tujuan pengguna, rangkaian aksi, serta pratinjau layar setiap giliran. Data ini menjadi bahan audit dan perbaikan prompt. Untuk pengujian regresi, jalankan skenario yang sama pada versi agen terbaru, lalu bandingkan persentase langkah sukses, waktu selesaikan tugas, serta stabilitas pada berbagai situs target.

Proses penyaringan dan ringkasan opsi divisualkan dengan kartu 3D

Studi Kasus Mini, Agen Mengisi Formulir Produk sampai Ringkas Hasil

Sebagai contoh, minta agen menelusuri katalog sebuah toko, menerapkan filter sesuai kebutuhan bisnis, kemudian merangkum tiga pilihan terbaik yang relevan. Tugas ini memaksa agen mengerti struktur halaman, menilai kesesuaian spesifikasi, serta kembali pada halaman ringkasan untuk menyusun daftar dengan format yang mudah dibaca. Pastikan Anda mengaktifkan konfirmasi pengguna sebelum langkah yang berpotensi menambah item ke keranjang atau mengirimkan formulir pembayaran.^[1]

Contoh tujuan pengguna:

“Telusuri produk monitor kerja tiga puluh dua inci, panel IPS, segarkan minimal enam puluh hertz, harga di bawah lima juta rupiah. Susun ringkasan tiga opsi termurah, tulis nama, spesifikasi penting, tautan produk.”

Troubleshooting, Kesalahan Umum dan Cara Mengatasinya

Salah model id menghasilkan respons kesalahan di server, pastikan menggunakan gemini-2.5-computer-use-preview-10-2025 saat mengaktifkan tool Computer Use ^[2]. Aksi yang tidak diimplementasikan di eksekutor membuat agen berhenti pada giliran berikutnya, lengkapi pemetaan fungsi klik, ketik, gulir, seret jatuhkan, serta tombol papan ketik penting. Ketidakcocokan viewport menyebabkan koordinat meleset, pertahankan ukuran yang konstan sepanjang sesi.^[2]

Jika loop terasa buntu, periksa apakah function response sudah menyertakan tangkapan layar dan URL terakhir. Untuk reliabilitas, tambah ulang otomatis saat pemuatan halaman tertunda, log setiap pengecualian, serta aktifkan backoff waktu tunggu yang meningkat pada situs padat trafik.

Baca juga artikel menarik tentang: Google Veo 3: Ketika Kecerdasan Buatan Mulai “Menyutradarai” Film

Saatnya Mengubah Eksperimen Jadi Manfaat Nyata

Dari eksperimen ke manfaat nyata, agen Gemini 2.5 Computer Use mengalir ke produksi dengan metrik terukur dan guardrail yang aktif.

Dengan pola loop agen yang jelas, eksekutor yang disiplin, dan pagar pengaman yang tegas, Gemini 2.5 Computer Use membuka peluang otomasi antarmuka pada proses yang belum memiliki API resmi, baik untuk riset pasar, pengujian alur, maupun operasional harian. Jika Anda sudah menjalankan contoh di atas, langkah berikutnya adalah menyatukan data log, menata allowlist situs sasaran, serta mendefinisikan standar konfirmasi aksi tinggi resiko. Bagikan pertanyaan dan pengalaman Anda di kolom komentar, agar diskusi kita semakin tajam dan berguna bagi komunitas.