Agentic Vision in Gemini 3: een praktische tutorial

Je stuurt een afbeelding naar een vision-API met de vraag om een klein prijslabel te lezen. Het antwoord komt zelfverzekerd terug—en fout. Hetzelfde bij het tellen van objecten in een rommelige foto: het model kijkt één keer naar de volledige afbeelding en gokt een totaal dat er ver naast zit.

Gemini 3 Flash pakt dit anders aan. Met code-executie ingeschakeld kan het halverwege een antwoord Python schrijven en uitvoeren om afbeeldingen te croppen, in te zoomen en te annoteren voordat het zich vastlegt op een antwoord. Google noemt dit agentic vision en meldt een kwaliteitswinst van 5–10% op vision-benchmarks.

Deze tutorial loopt door vier voorbeelden die steeds lastiger worden: piepkleine tekst lezen in een supermarktstelling, dranknamen van een schemerig barmenu halen, verspreide munten tellen en tabeldata extraheren naar een grafiek.

Wat is agentic vision? De "Think, Act, Observe"-loop

Het idee is eenvoudig. Met code-executie actief kan Gemini 3 halverwege stoppen, Python schrijven en uitvoeren in een sandbox, kijken wat de code opleverde en bepalen wat de volgende stap is. 

Voor vision-taken betekent dit meestal dat het model delen van een afbeelding uitsnijdt, ze vergroot, bounding boxes tekent of het contrast aanpast om details naar voren te halen die op de oorspronkelijke resolutie niet zichtbaar zijn.

Dit verloopt als een driefasige loop.

Tijdens Think kijkt het model naar wat het heeft (de originele afbeelding, of een versie die al is gecropt of geannoteerd) en plant de volgende stap. Het kan besluiten dat een prijslabel te klein is om te lezen en moet worden gecropt en vergroot.

Act zet dat plan om in Python. De sandbox heeft 43 voorgeïnstalleerde libraries (PIL, OpenCV, matplotlib en meer), dus het model kan de beeldbewerkingscode schrijven die het nodig heeft.

Na het uitvoeren van de code sluit Observe de loop. Output (nieuwe afbeeldingen, geprinte tekst, berekende waarden) stroomt terug de context in. Vanaf daar geeft het model ofwel antwoord, of het gaat nog een ronde.

Eén API-call kan meerdere keren door deze loop gaan. In de komende voorbeelden zie je dat het in één request zeven stellingregio’s cropt. In een ander voorbeeld extraheert het tabeldata naar een pandas DataFrame en genereert het een staafdiagram, allemaal binnen dezelfde call. 

Als het agentic-loopconcept nieuw voor je is, behandelt DataCamps AI Agent Fundamentals-track dit uitvoerig.

Beperkingen en grenzen

• Code-executie en custom function calling kunnen niet in hetzelfde request worden gebruikt.
• Volgens Google’s documentatie kan code-executie de prestaties bij niet-visuele taken verslechteren. Schakel het alleen in als de taak baat heeft bij beeldmanipulatie.
• Segmentatie op pixelniveau (maskers, contouren) maakt geen deel uit van agentic vision en blijft bij Gemini 2.5.
• Het model slaat soms code-executie over als één blik genoeg is. Dat is met opzet, geen bug.

Je omgeving inrichten voor agentic vision

Haal een API-sleutel bij ai.google.dev en sla die op als GOOGLE_API_KEY in je omgeving of een .env-bestand. Installeer daarna de SDK en beeldbibliotheken:

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

Begin met het aanmaken van de client:

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"

Die timeout=600_000 is belangrijk. Agentic-vision-calls omvatten meerdere rondes van codegeneratie en -uitvoering in de sandbox, en één request kan ongeveer vier minuten duren. 

De standaard httpx-timeout verbreekt de verbinding ruim daarvoor, waardoor je achterblijft met een stille ReadTimeout en geen idee wat er is gebeurd.

Stel vervolgens de agentic-config in:

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,
)

tools is de schakelaar voor code-executie. Het geeft het model een gesandboxte Python-omgeving met 43 libraries (numpy, pandas, PIL, matplotlib, OpenCV en meer). Elk codeblok krijgt 30 seconden om te draaien, en de sandbox probeert bij fouten tot 5 keer opnieuw.

thinking_level="HIGH" geeft het model meer ruimte om te plannen voordat het code schrijft. Voor meerstaps vision-werk maakt dit merkbaar verschil. include_thoughts=True toont die redenatie in de response-onderdelen, handig voor debugging.

media_resolution bepaalt hoeveel tokens de invoerafbeelding krijgt voordat de loop überhaupt start. MEDIA_RESOLUTION_HIGH is een goede standaard. Je kunt opschalen naar MEDIA_RESOLUTION_ULTRA_HIGH voor zeer dichte afbeeldingen of terugschakelen naar MEDIA_RESOLUTION_LOW wanneer snelheid belangrijker is dan detail.

Dezezelfde setup werkt op Vertex AI met minimale aanpassingen. Voor een bredere walkthrough van de Gemini 3 API buiten vision om, zie de bijbehorende tutorial.

Agentic Vision in Gemini 3: fijne details lezen met crop en zoom

De onderstaande afbeelding is een Duitse supermarktstelling met drie rijen producten. Langs de rand van elke plank staan prijslabels, en onderaan staat een "Liebe Kunden"-mededeling. De labels zijn leesbaar als je zelf inzoomt, maar klein genoeg dat een model dat naar de volledige afbeelding kijkt, moet bepalen wat het wel en niet kan ontcijferen.

De meerledige response parsen

Agentic-responses zijn geen losse tekstblokken. Ze komen binnen als een lijst met onderdelen: denken, code die het model schreef, uitvoerresultaten, gegenereerde afbeeldingen en het eindantwoord. Deze helper loopt ze langs:

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)

Elk voorbeeld in deze tutorial gebruikt dezelfde functie, dus definieer hem één keer en hergebruik hem.

Laad nu de stellingafbeelding en schrijf een prompt die het model vraagt de mededeling te lezen en elk product met prijs op te sommen.

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."
)

Draai het eerst zonder code-executie:

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)

Hier is een ingekorte versie van de output:

[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
...

De vertaling van de mededeling klopt, en het model leest de Uncle Ben’s-labels die het herkent. Maar ongeveer een derde van de items is "(Label obscured)", en merken als Oryza, Reis-fit en Reiskugeln komen helemaal niet voor.

Nu dezelfde prompt met de agentic-config:

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

De outputstructuur is anders. In plaats van één [ANSWER] doorloopt het de volledige Think/Act/Observe-loop:

[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 bytes

De zeven crops die het model genereerde:

Na het observeren van die crops geeft het model een volledig antwoord:

[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 €
...

De volledige niet-ingekorte output voor beide calls staat in deze gist.

De agentic-response leest 30+ producten over alle drie planken. De Oryza-, Reis-fit-, Madras Curry-, Reiskugeln- en Steam Basmati-items die standaard vision als "(obscured)" labelde, verschijnen nu met namen en prijzen.

Het verschil gaat niet om hallucinatie versus nauwkeurigheid; standaard vision is eerlijk over wat het niet kan lezen. Agentic vision accepteert die beperking simpelweg niet en zoomt in tot het wel kan.

De prompt speelt hier een rol. Door het model te vragen "alle zichtbare productnamen en hun prijzen" op te sommen, leg je de lat voor compleetheid hoger en duw je het richting croppen. 

Een vagere prompt zoals "beschrijf deze afbeelding" zou waarschijnlijk een eenmalig antwoord opleveren, zelfs met code-executie aan, omdat het model geen reden ziet om verder te gaan.