Visi Agen di Gemini 3: Tutorial Praktis

Anda mengirim gambar ke API visi dan memintanya membaca label harga kecil. Respons yang kembali terdengar yakin namun salah. Hal serupa terjadi saat menghitung objek di foto yang berantakan: model melihat sekilas seluruh gambar lalu menebak angka yang meleset jauh.

Gemini 3 Flash menanganinya dengan cara berbeda. Dengan eksekusi kode diaktifkan, ia dapat menulis dan menjalankan Python di tengah respons untuk melakukan crop, pembesaran, dan anotasi gambar sebelum memberikan jawaban. Google menyebutnya visi agen (agentic vision) dan melaporkan peningkatan kualitas 5–10% pada tolok ukur visi.

Tutorial ini membahas empat contoh yang makin menantang: membaca tulisan kecil di rak bahan makanan, mengambil nama minuman dari menu bar yang remang, menghitung koin yang berserakan, dan mengekstrak data tabel ke dalam bagan.

Apa Itu Visi Agen? Loop "Think, Act, Observe"

Idenya sederhana. Dengan eksekusi kode aktif, Gemini 3 dapat berhenti di tengah respons, menulis dan menjalankan Python di sandbox, melihat apa yang dihasilkan kode, lalu memutuskan langkah berikutnya. 

Untuk tugas visi, ini biasanya berarti model memotong area gambar, memperbesarnya, menggambar bounding box, atau menyesuaikan kontras untuk menonjolkan detail yang tidak terlihat pada resolusi awal.

Ini berjalan sebagai loop tiga fase.

Selama Think, model melihat apa yang dimilikinya (gambar asli, atau versi yang sudah dipotong atau dianotasi) dan merencanakan langkah berikut. Ia mungkin memutuskan label harga terlalu kecil untuk dibaca dan perlu dipotong serta diperbesar.

Act menerjemahkan rencana itu menjadi Python. Sandbox memiliki 43 pustaka prainstal (PIL, OpenCV, matplotlib, dan lainnya), sehingga model dapat menulis kode pemrosesan gambar apa pun yang dibutuhkannya.

Setelah kode berjalan, Observe menutup loop. Output (gambar baru, teks yang dicetak, nilai yang dihitung) masuk kembali ke konteks. Dari sana, model bisa menjawab atau mengulang lagi.

Satu panggilan API dapat berputar melalui loop ini beberapa kali. Di contoh berikut, Anda akan melihatnya melakukan crop tujuh area rak dalam satu permintaan. Pada contoh lain, ia mengekstrak data tabel ke pandas DataFrame dan menghasilkan bagan batang, semuanya dalam panggilan yang sama. 

Jika konsep loop agen baru bagi Anda, alur AI Agent Fundamentals dari DataCamp membahasnya secara mendalam.

Keterbatasan dan batasan

• Eksekusi kode dan pemanggilan fungsi kustom tidak dapat digunakan dalam permintaan yang sama.
• Dokumentasi Google memperingatkan bahwa eksekusi kode dapat menurunkan performa pada tugas non-visual. Aktifkan hanya saat tugas diuntungkan dari manipulasi gambar.
• Segmentasi tingkat piksel (masker, kontur) bukan bagian dari visi agen dan tetap berada di Gemini 2.5.
• Model terkadang melewatkan eksekusi kode jika sekali lihat sudah cukup. Sesuai desain, bukan bug.

Menyiapkan Lingkungan Anda untuk Visi Agen

Ambil kunci API dari ai.google.dev dan simpan sebagai GOOGLE_API_KEY di lingkungan Anda atau berkas .env. Lalu pasang SDK dan pustaka gambar:

pip install google-genai python-dotenv Pillow matplotlib opencv-pythonDidukung oleh

Mulailah dengan membuat klien:

from google import genai
from google.genai import types
from dotenv import load_dotenv
 
load_dotenv()
 
client = genai.Client(
    http_options=types.HttpOptions(timeout=600_000)
)
MODEL = "gemini-3-flash-preview"Didukung oleh

Parameter timeout=600_000 penting. Panggilan visi agen melibatkan beberapa putaran pembuatan dan eksekusi kode di dalam sandbox, dan satu permintaan bisa memakan waktu sekitar empat menit. 

Batas waktu default httpx akan memutus koneksi jauh sebelum itu, meninggalkan Anda dengan ReadTimeout yang sunyi tanpa petunjuk apa yang terjadi.

Selanjutnya, siapkan konfigurasi agen:

agentic_config = types.GenerateContentConfig(
    tools=[types.Tool(code_execution=types.ToolCodeExecution())],
	thinking_config=types.ThinkingConfig(
    	thinking_level="HIGH",
    	include_thoughts=True
	),
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_HIGH,
)Didukung oleh

tools adalah tombol untuk menyalakan eksekusi kode. Ini memberi model lingkungan Python tersandbox dengan 43 pustaka (numpy, pandas, PIL, matplotlib, OpenCV, dan lainnya). Setiap blok kode mendapat 30 detik untuk berjalan, dan sandbox mencoba ulang hingga 5 kali saat terjadi kesalahan.

thinking_level="HIGH" memberi model ruang lebih untuk merencanakan sebelum menulis kode. Untuk pekerjaan visi multi-langkah, ini memberi perbedaan yang terasa. Menetapkan include_thoughts=True menampilkan penalaran itu di bagian respons, berguna untuk debugging.

media_resolution mengatur berapa banyak token yang didapat gambar input sebelum loop dimulai. MEDIA_RESOLUTION_HIGH adalah default yang baik. Anda dapat menaikkan ke MEDIA_RESOLUTION_ULTRA_HIGH untuk gambar yang sangat padat atau menurunkan ke MEDIA_RESOLUTION_LOW saat kecepatan lebih penting daripada detail.

Pengaturan yang sama ini berfungsi di Vertex AI dengan perubahan minimal. Untuk panduan yang lebih luas tentang Gemini 3 API di luar visi, lihat tutorial pendampingnya.

Visi Agen di Gemini 3: Membaca Detail Halus dengan Crop dan Zoom

Gambar di bawah adalah rak toko bahan makanan Jerman dengan tiga baris produk. Label harga berjajar di tepi setiap rak, dan pemberitahuan "Liebe Kunden" (Pelanggan yang Terhormat) berada di dekat bagian bawah. Label dapat dibaca jika Anda memperbesar sendiri, tetapi cukup kecil sehingga model yang melihat seluruh gambar harus memutuskan apa yang bisa dan tidak bisa dibacanya.

Mengurai respons multi-bagian

Respons agen bukan satu blok teks. Respons datang sebagai daftar bagian: pemikiran, kode yang ditulis model, hasil eksekusi, gambar yang dihasilkan, dan jawaban akhir. Pembantu ini menelusurinya:

def print_response(response, show_thoughts=False):
	for part in response.candidates[0].content.parts:
    	if part.thought and show_thoughts:
        	print("[THINK]", part.text[:500])
    	elif part.executable_code:
        	print("[CODE]")
        	print(part.executable_code.code)
    	elif part.code_execution_result:
        	print(f"[RESULT] ({part.code_execution_result.outcome})")
            print(part.code_execution_result.output)
    	elif part.inline_data:
        	print(f"[IMAGE] {part.inline_data.mime_type}, "
                  f"{len(part.inline_data.data):,} bytes")
    	elif part.text:
        	print("[ANSWER]", part.text)Didukung oleh

Setiap contoh dalam tutorial ini menggunakan fungsi yang sama, jadi definisikan sekali dan gunakan ulang.

Sekarang muat gambar rak dan tuliskan prompt yang meminta model membaca pengumuman dan mencantumkan setiap produk beserta harganya.

from pathlib import Path
 
image_path = Path("images/grocery_shelf.jpg")
image_part = types.Part.from_bytes(
	data=image_path.read_bytes(), mime_type="image/jpeg"
)
 
prompt = (
	"Read the 'Liebe Kunden' sign at the bottom of the shelf. "
	"What does it say? Also list all visible product names "
	"and their prices from the shelf labels."
)Didukung oleh

Jalankan terlebih dahulu tanpa eksekusi kode:

standard_config = types.GenerateContentConfig(
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_HIGH,
)
 
standard_response = client.models.generate_content(
	model=MODEL,
	contents=[image_part, prompt],
	config=standard_config,
)
print_response(standard_response)Didukung oleh

Berikut versi keluaran yang dipangkas:

[ANSWER] Based on the image provided, here is the information requested:
 
### The 'Liebe Kunden' Sign
> "Dear Customers, unfortunately, we must inform you that due to
> increased demand, we cannot currently offer all products..."
 
### Product Names and Prices (from shelf labels)
 
**Top Row Labels:**
*   Uncle Ben's Express Reis Mexi-Scharf 250g: 1,69
*   Uncle Ben's Express Reis Griechisch 250g: 1,69
*   Uncle Ben's Express Reis Curry 250g: 1,69
*   Channa Masala 300g (partially obscured): 2,49
*   (Label obscured): 2,49
*   (Label obscured): 1,29
*   (Label obscured): 0,99
...
 
**Second Row Labels:**
*   Uncle Ben's Express Reis Chili con Carne 250g: 2,49
*   Uncle Ben's Spitzen-Langkorn Reis 10 Min 500g: 1,79
*   (Label obscured): 2,99
*   (Label obscured): 2,79
...Didukung oleh

Terjemahan pengumuman benar, dan model membaca label Uncle Ben yang bisa dikenalinya. Namun sekitar sepertiga entri bertuliskan "(Label obscured)," dan merek seperti Oryza, Reis-fit, dan Reiskugeln sama sekali tidak muncul.

Sekarang prompt yang sama dengan konfigurasi agen:

agentic_response = client.models.generate_content(
	model=MODEL,
	contents=[image_part, prompt],
	config=agentic_config,
)
print_response(agentic_response, show_thoughts=True)Didukung oleh

Struktur keluarannya berbeda. Alih-alih satu [ANSWER], ia menelusuri penuh loop Think/Act/Observe:

[THINK] Okay, so the primary goal here is twofold: First, I need to
decipher that "Liebe Kunden" sign down there. Then, I need to build a
comprehensive list of what's on this shelf...
 
[CODE]
import PIL.Image
 
img = PIL.Image.open('input_file_0.jpeg')
width, height = img.size
 
crops = [
	{'box_2d': [630, 447, 887, 559], 'label': 'liebe_kunden_sign'},
	{'box_2d': [80, 40, 240, 560], 'label': 'shelf1_left'},
	{'box_2d': [190, 550, 310, 980], 'label': 'shelf1_right'},
	{'box_2d': [400, 0, 480, 450], 'label': 'shelf2_left'},
	{'box_2d': [410, 450, 480, 1000], 'label': 'shelf2_right'},
	{'box_2d': [630, 130, 760, 460], 'label': 'shelf3_left'},
	{'box_2d': [550, 600, 660, 990], 'label': 'shelf3_right'},
]
# ... crops and saves each region
 
[IMAGE] image/png, 135,953 bytes
[IMAGE] image/png, 90,395 bytes
[IMAGE] image/png, 125,816 bytes
[IMAGE] image/png, 102,288 bytes
[IMAGE] image/png, 173,606 bytes
[IMAGE] image/png, 283,263 bytes
[IMAGE] image/png, 100,522 bytesDidukung oleh

Tujuh hasil crop yang dihasilkan model:

Setelah mengamati hasil crop tersebut, model menghasilkan jawaban lengkap:

[ANSWER]
**Top Shelf (Left to Right):**
*   Uncle Ben's Express Reis Mexi. Scharf 250g: 1,69 €
*   Channa Masala 285g: 2,49 €
*   Madras Curry 285g: 2,49 €
*   Steam Basmati Reis Kochbeutel 250g: 1,99 €
*   Reiskugeln Pur 4x2 St: 1,99 €
...
 
**Middle Shelf (Left to Right):**
*   Uncle Ben's Express Reis Chili con Carne 250g: 2,49 €
*   Oryza Langkorn & Wildreis 500g Kochbeutel: 2,99 €
*   Oryza Basmati & Wildreis 500g Kochbeutel: 2,79 €
*   Oryza Jasmin Reis 500g Kochbeutel: 2,79 €
...
 
**Bottom Shelf (Left to Right):**
*   Uncle Ben's Natur Reis 10-Min. Kochbeutel 1kg: 3,69 €
*   Reis-fit 10 Minuten Natur-Reis 500g: 1,89 €
*   Reis-fit Langkorn & Wildreis 500g: 1,89 €
...Didukung oleh

Keluaran lengkap tanpa dipangkas untuk kedua panggilan tersedia di gist ini.

Respons agen membaca 30+ produk di ketiga rak. Item Oryza, Reis-fit, Madras Curry, Reiskugeln, dan Steam Basmati yang diberi label "(obscured)" oleh visi standar semuanya muncul lengkap dengan nama dan harga.

Perbedaannya bukan soal halusinasi vs. akurasi; visi standar jujur tentang apa yang tidak bisa dibacanya. Visi agen menolak menerima batas itu dan memperbesar hingga bisa membaca.

Prompt berperan di sini. Meminta model untuk "mencantumkan semua nama produk yang terlihat beserta harganya" menetapkan standar kelengkapan yang mendorongnya untuk melakukan crop. 

Prompt yang lebih samar seperti "deskripsikan gambar ini" kemungkinan akan menghasilkan jawaban sekali lewat meskipun eksekusi kode aktif, karena model tidak melihat alasan untuk melangkah lebih jauh.