Visione agentica in Gemini 3: un tutorial pratico

Invii un’immagine a una API di visione chiedendole di leggere una piccola etichetta prezzo. La risposta torna sicura e sbagliata. Stessa storia con il conteggio di oggetti in una foto disordinata: il modello guarda una volta l’immagine intera e indovina un numero del tutto fuori scala.

Gemini 3 Flash si comporta in modo diverso. Con l’esecuzione di codice attivata, può scrivere ed eseguire Python a metà risposta per ritagliare, zoomare e annotare immagini prima di impegnarsi in una risposta. Google lo chiama visione agentica e segnala un incremento qualitativo del 5-10% nei benchmark di visione.

Questo tutorial illustra quattro esempi via via più difficili: leggere le scritte minute da uno scaffale del supermercato, estrarre i nomi delle bevande da un menu di bar poco illuminato, contare monete sparse ed estrarre i dati di una tabella per creare un grafico.

Cos’è la visione agentica? Il ciclo "Think, Act, Observe"

L’idea è semplice. Con l’esecuzione di codice attiva, Gemini 3 può fermarsi a metà risposta, scrivere ed eseguire Python in un sandbox, guardare cosa ha prodotto il codice e decidere cosa fare dopo. 

Per i compiti di visione, di solito significa che il modello ritaglia regioni di un’immagine, le ingrandisce, disegna riquadri di delimitazione o regola il contrasto per far emergere dettagli non visibili alla risoluzione originale.

Questo si svolge in un ciclo in tre fasi.

Durante Think, il modello guarda cosa ha (l’immagine originale o una versione già ritagliata o annotata) e pianifica la mossa successiva. Potrebbe decidere che un’etichetta prezzo è troppo piccola per essere letta e che serve ritagliarla e ingrandirla.

Act trasforma quel piano in Python. Il sandbox ha 43 librerie preinstallate (PIL, OpenCV, matplotlib e altre), quindi il modello può scrivere il codice di elaborazione immagini di cui ha bisogno.

Dopo l’esecuzione del codice, Observe chiude il ciclo. L’output (nuove immagini, testo stampato, valori calcolati) rientra nel contesto. Da lì, il modello risponde oppure riparte per un altro giro.

Una singola chiamata API può ripetere più volte questo ciclo. Negli esempi che seguono, lo vedrai ritagliare sette regioni dello scaffale in una richiesta. In un altro, estrae i dati di una tabella in un DataFrame pandas e genera un grafico a barre, tutto nella stessa chiamata. 

Se il concetto di ciclo agentico è nuovo per te, il percorso AI Agent Fundamentals di DataCamp lo tratta in profondità.

Limitazioni e confini

• Esecuzione di codice e chiamata di funzioni personalizzate non possono essere usate nella stessa richiesta.
• La documentazione di Google avverte che l’esecuzione di codice può peggiorare le prestazioni su compiti non visivi. Attivala solo quando il task beneficia della manipolazione di immagini.
• La segmentazione a livello di pixel (maschere, contorni) non fa parte della visione agentica e resta su Gemini 2.5.
• A volte il modello salta l’esecuzione di codice se basta uno sguardo. È voluto, non un bug.

Configurare l’ambiente per la visione agentica

Ottieni una chiave API da ai.google.dev e salvala come GOOGLE_API_KEY nel tuo ambiente o in un file .env. Poi installa l’SDK e le librerie per le immagini:

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

Inizia creando il 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"Offerto da

Quel timeout=600_000 è importante. Le chiamate di visione agentica prevedono più cicli di generazione ed esecuzione di codice nel sandbox, e una singola richiesta può durare circa quattro minuti. 

Il timeout predefinito di httpx interromperà la connessione ben prima, lasciandoti con un silenzioso ReadTimeout e senza indizi su cosa sia successo.

Poi configura l’agentic config:

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

tools è l’interruttore per l’esecuzione di codice. Fornisce al modello un ambiente Python in sandbox con 43 librerie (numpy, pandas, PIL, matplotlib, OpenCV e altro). Ogni blocco di codice ha 30 secondi per l’esecuzione e il sandbox riprova fino a 5 volte in caso di errori.

thinking_level="HIGH" dà al modello più spazio di pianificazione prima di scrivere il codice. Per lavori di visione a più step, fa una differenza sensibile. Impostare include_thoughts=True espone quel ragionamento nelle parti della risposta, utile per il debugging.

media_resolution definisce quanti token ottiene l’immagine in input prima ancora che il ciclo inizi. MEDIA_RESOLUTION_HIGH è un buon default. Puoi spingere su MEDIA_RESOLUTION_ULTRA_HIGH per immagini molto dense o scendere a MEDIA_RESOLUTION_LOW quando la velocità conta più del dettaglio.

Questa stessa configurazione funziona su Vertex AI con modifiche minime. Per una panoramica più ampia della Gemini 3 API oltre la visione, vedi il tutorial complementare.

Visione agentica in Gemini 3: leggere i dettagli fini con ritaglio e zoom

L’immagine qui sotto mostra uno scaffale di un supermercato tedesco con tre file di prodotti. Etichette prezzo corrono lungo il bordo di ogni ripiano, e un avviso "Liebe Kunden" (Cari clienti) si trova vicino al fondo. Le etichette si leggono se zoomi manualmente, ma sono abbastanza piccole che un modello che osserva l’immagine intera deve decidere cosa riesce e cosa non riesce a distinguere.

Analizzare la risposta multi-parte

Le risposte agentiche non sono blocchi di testo unici. Arrivano come un elenco di parti: thinking, codice scritto dal modello, risultati dell’esecuzione, immagini generate e risposta finale. Questo helper le percorre:

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)Offerto da

Ogni esempio in questo tutorial usa la stessa funzione, quindi definiscila una volta e riutilizzala.

Ora carica l’immagine dello scaffale e scrivi un prompt che chieda al modello di leggere l’avviso e di elencare ogni prodotto con il relativo prezzo.

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

Eseguilo prima senza esecuzione di codice:

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)Offerto da

Ecco una versione ridotta dell’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
...Offerto da

La traduzione dell’avviso è corretta e il modello legge le etichette Uncle Ben’s che riconosce. Ma circa un terzo delle voci risultano "(Label obscured)" e marchi come Oryza, Reis-fit e Reiskugeln non compaiono affatto.

Ora lo stesso prompt con la configurazione agentica:

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

La struttura dell’output è diversa. Invece di un unico [ANSWER], attraversa l’intero ciclo 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 bytesOfferto da

I sette ritagli generati dal modello:

Dopo aver osservato quei ritagli, il modello produce una risposta completa:

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

L’output completo non troncato per entrambe le chiamate è disponibile in questa gist.

La risposta agentica legge oltre 30 prodotti su tutti e tre i ripiani. Gli articoli Oryza, Reis-fit, Madras Curry, Reiskugeln e Steam Basmati che la visione standard etichettava come "(obscured)" compaiono con nomi e prezzi.

La differenza non riguarda allucinazioni vs accuratezza; la visione standard è onesta su ciò che non riesce a leggere. La visione agentica semplicemente non accetta quel limite e ingrandisce finché può.

Qui il prompt ha un ruolo. Chiedere al modello di "elencare tutti i nomi dei prodotti visibili e i relativi prezzi" fissa un livello di completezza che lo spinge verso il ritaglio. 

Un prompt più vago come "descrivi questa immagine" probabilmente produrrebbe una risposta a passaggio singolo anche con l’esecuzione di codice attiva, perché il modello non vede motivo per andare oltre.