Cursus
Principes fondamentaux des agents IA
6 h
Vous envoyez une image à une API de vision pour lire une petite étiquette de prix. La réponse revient sûre d’elle… et fausse. Même scénario pour compter des objets dans une photo encombrée : le modèle jette un coup d’œil global et propose un nombre à côté de la plaque.
Gemini 3 Flash s’y prend autrement. Avec l’exécution de code activée, il peut écrire et exécuter du Python au milieu de la réponse pour recadrer, zoomer et annoter les images avant de s’engager sur une réponse. Google appelle cela agentic vision et annonce un gain de 5 à 10 % sur les benchmarks de vision.
Ce tutoriel parcourt quatre exemples de difficulté croissante : lire des caractères minuscules sur un rayon de supermarché, extraire des noms de boissons d’un menu de bar peu éclairé, compter des pièces éparpillées et convertir les données d’un tableau en graphique.
Qu’est-ce que l’agentic vision ? La boucle "Think, Act, Observe"
L’idée est simple. Avec l’exécution de code activée, Gemini 3 peut s’interrompre au milieu de la réponse, écrire et exécuter du Python dans un bac à sable, regarder ce que le code a produit, puis décider de la suite.
Pour les tâches de vision, cela signifie généralement découper des régions de l’image, les agrandir, tracer des boîtes englobantes ou ajuster le contraste pour faire ressortir des détails invisibles à la résolution d’origine.
Le tout se déroule en une boucle en trois phases.
Pendant Think, le modèle examine ce qu’il a (l’image originale, ou une version déjà recadrée/annotée) et planifie son prochain mouvement. Il peut décider qu’une étiquette de prix est trop petite pour être lue et qu’il faut la recadrer et l’agrandir.
Act transforme ce plan en code Python. Le bac à sable inclut 43 bibliothèques préinstallées (PIL, OpenCV, matplotlib, etc.), de quoi écrire le traitement d’image nécessaire.
Après exécution du code, Observe boucle la démarche. La sortie (nouvelles images, texte imprimé, valeurs calculées) réintègre le contexte. À partir de là, le modèle répond ou repart pour un tour.
Un seul appel d’API peut exécuter cette boucle plusieurs fois. Dans les exemples à suivre, vous le verrez recadrer sept zones de rayon en une requête. Dans un autre, il extrait un tableau vers un DataFrame pandas et génère un diagramme en barres, toujours dans le même appel.
Si le concept de boucle agentique est nouveau pour vous, le parcours AI Agent Fundamentals de DataCamp l’explique en détail.
Limites et contraintes
- L’exécution de code et l’appel de fonctions personnalisées ne peuvent pas être utilisés dans la même requête.
- La documentation de Google prévient que l’exécution de code peut dégrader les performances sur des tâches non visuelles. Activez-la uniquement quand la manipulation d’images apporte un bénéfice.
- La segmentation au niveau du pixel (masques, contours) ne fait pas partie de l’agentic vision et reste sur Gemini 2.5.
- Le modèle saute parfois l’exécution de code si un seul coup d’œil suffit. C’est voulu, pas un bug.
Préparer votre environnement pour l’agentic vision
Récupérez une clé API sur ai.google.dev et stockez-la sous GOOGLE_API_KEY dans votre environnement ou un fichier .env. Installez ensuite le SDK et les bibliothèques d’image :
pip install google-genai python-dotenv Pillow matplotlib opencv-pythonCommencez par créer le 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"Ce timeout=600_000 est important. Les appels d’agentic vision impliquent plusieurs cycles de génération et d’exécution de code dans le bac à sable, et une requête peut prendre environ quatre minutes.
Le timeout par défaut d’httpx coupera la connexion bien avant, vous laissant avec un ReadTimeout silencieux, sans indication de ce qui s’est passé.
Ensuite, configurez l’agent :
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 est l’interrupteur d’activation de l’exécution de code. Il donne au modèle un environnement Python isolé avec 43 bibliothèques (numpy, pandas, PIL, matplotlib, OpenCV, etc.). Chaque bloc de code dispose de 30 secondes d’exécution, avec jusqu’à 5 retries en cas d’erreur.
thinking_level="HIGH" laisse plus de marge au modèle pour planifier avant d’écrire du code. Pour des tâches visuelles multi-étapes, la différence est notable. En définissant include_thoughts=True, vous exposez ce raisonnement dans la réponse, utile pour le débogage.
media_resolution règle le nombre de tokens alloués à l’image d’entrée avant même que la boucle ne démarre. MEDIA_RESOLUTION_HIGH est un bon défaut. Vous pouvez monter à MEDIA_RESOLUTION_ULTRA_HIGH pour des images très denses, ou descendre à MEDIA_RESOLUTION_LOW quand la vitesse prime sur le détail.
Cette même configuration fonctionne sur Vertex AI avec des ajustements mineurs. Pour une présentation plus large de l’ API Gemini 3 au-delà de la vision, consultez le tutoriel associé.
Agentic vision dans Gemini 3 : lire les détails fins avec recadrage et zoom
L’image ci-dessous montre un rayon de supermarché en Allemagne avec trois rangées de produits. Des étiquettes de prix bordent chaque étagère, et un avis "Liebe Kunden" (Chers clients) se trouve près du bas. En zoomant manuellement, les étiquettes sont lisibles, mais elles restent suffisamment petites pour qu’un modèle regardant l’image entière doive décider ce qu’il peut ou non déchiffrer.
Analyser la réponse multi-parties
Les réponses agentiques ne sont pas des blocs de texte uniques. Elles arrivent sous forme d’une liste de parties : réflexion, code généré, résultats d’exécution, images produites et réponse finale. Ce helper les parcourt :
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)Chaque exemple de ce tutoriel utilise la même fonction : définissez-la une fois et réutilisez-la.
Chargez maintenant l’image du rayon et rédigez une consigne demandant au modèle de lire l’avis et de lister chaque produit avec son prix.
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."
)Exécutez-le d’abord sans exécution de code :
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)Voici une version abrégée de la sortie :
[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
...La traduction de l’avis est correcte, et le modèle lit les étiquettes Uncle Ben’s qu’il reconnaît. Mais environ un tiers des entrées restent "(Label obscured)" et des marques comme Oryza, Reis-fit et Reiskugeln n’apparaissent pas.
Reprenez la même consigne avec la configuration agentique :
agentic_response = client.models.generate_content(
model=MODEL,
contents=[image_part, prompt],
config=agentic_config,
)
print_response(agentic_response, show_thoughts=True)La structure de sortie change. Au lieu d’un unique [ANSWER], la réponse parcourt l’intégralité de la boucle 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 bytesLes sept recadrages générés par le modèle :
Après observation de ces recadrages, le modèle produit une réponse complète :
[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 €
...La sortie complète non tronquée des deux appels est disponible dans ce gist.
La réponse agentique lit plus de 30 produits sur les trois étagères. Les articles Oryza, Reis-fit, Madras Curry, Reiskugeln et Steam Basmati que la vision standard marquait comme "(obscured)" apparaissent avec noms et prix.
La différence n’est pas une opposition hallucination vs. exactitude ; la vision standard admet honnêtement ce qu’elle ne lit pas. L’agentic vision refuse cette limite et zoome jusqu’à pouvoir lire.
La consigne joue un rôle ici. Demander de "lister tous les produits visibles et leurs prix" fixe un niveau d’exhaustivité qui pousse au recadrage.
Une consigne plus vague comme "décrivez cette image" produirait probablement une réponse en un seul passage, même avec l’exécution de code activée, car le modèle n’y verrait aucune raison d’aller plus loin.
Lire malgré la faible luminosité et les obstructions
Cette image montre un menu de bar brésilien photographié dans une lumière tamisée. Trois panneaux en verre listent des boissons en lettres dorées, mais des suspensions masquent une partie du panneau de gauche, celui de droite est à peine visible en bord de cadre, et des reflets parsèment la surface.
La consigne ne mentionne ni luminosité, ni recadrage, ni technique précise. Elle demande simplement le contenu :
image_path = Path("images/bar_menu.jpg")
image_part = types.Part.from_bytes(
data=image_path.read_bytes(), mime_type="image/jpeg"
)
prompt = (
"Read every drink listed on this menu board, including the ones "
"partially hidden behind the lamps and on the side panels. For "
"each drink, give me the name and beer style."
)La vision standard lit sans difficulté le panneau central bien éclairé, en récupérant huit bières de la section "FRUTADAS" et quatre de "CHOPP". Mais le panneau de gauche ressort ainsi :
[ANSWER]
### Left Panel (Partially visible)
* **[Unreadable] LAGER** | [Style unreadable]
* **RED LAGER** | [Style unreadable]
* **[Unreadable] LAGER** | [Style unreadable]
* **[Unreadable]GER** | [Style unreadable]
* **HONKERS ALE** | [Style unreadable]
* **[Unreadable]SELLE** | [Style unreadable]Six entrées, la plupart illisibles et toutes sans style. Le modèle voit du texte mais ne parvient pas à le déchiffrer.
L’appel agentique exécute deux tours de code. D’abord, il recadre les trois panneaux :
[CODE]
middle_panel = [200, 320, 950, 780]
left_panel = [200, 0, 950, 260]
right_panel = [200, 840, 700, 1000]
# ... crops and saves each region
Après observation de ces recadrages, le modèle décide que les panneaux gauche et droit nécessitent plus de zoom. Il lance une seconde passe :
[CODE]
left_panel_top = [100, 0, 500, 250]
left_panel_bottom = [500, 0, 980, 250]
right_panel_top = [100, 800, 600, 1000]
Avec ce zoom supplémentaire, le modèle retrouve des noms que la vision standard marquait comme illisibles : Amber Lager, Honkers Ale (Goose Island) et Demoiselle (Colorado) sur le panneau de gauche, ainsi que Wals Dubbel, Tripel, Quadrupel et Petroleum sur le droit. Il identifie aussi l’intitulé de gauche comme "MISTURAS" et celui de droite comme "ALCOÓLICAS".
La consigne n’a jamais dit "recadrez les panneaux" ni "zoomez dans les zones sombres". Elle a demandé les boissons et leurs styles, et le modèle a raisonné à rebours pour atteindre cet objectif.
Ce qui différencie cet exemple du rayon, c’est la seconde passe. Après le premier tour de recadrages, le modèle a examiné le résultat, jugé les panneaux gauche et droit encore trop difficiles à lire, puis a relancé une série de zooms plus serrés sans y être invité.
La boucle s’est auto-corrigée.
C’est l’intérêt de laisser la méthode ouverte : le modèle ne se contente pas d’un prétraitement unique, il itère jusqu’à ce que le résultat atteigne le niveau d’exigence fixé par la consigne.
Comptage et annotation avec l’agentic vision dans Gemini 3
Le menu de bar a fonctionné parce que la consigne laissait la méthode ouverte, et le modèle a trouvé quoi faire. Ce n’est pas toujours le cas. Parfois, le modèle a besoin d’instructions explicites sur l’outil à utiliser, et l’exemple suivant montre où se situe la limite.
L’image ci-dessous montre des pièces éparpillées sur un bureau et un classeur noir. Certaines se chevauchent, quelques-unes sont partiellement masquées, et le mélange cuivre/argent complique le comptage.
Une approche raisonnable consiste à demander au modèle d’annoter chaque pièce pour compter à partir de ses propres marquages. La documentation de Google confirme que l’agentic vision peut tracer des boîtes et des libellés directement sur les images via PIL et OpenCV dans le bac à sable. Donc :
image_path = Path("images/coins.jpg")
image_part = types.Part.from_bytes(
data=image_path.read_bytes(), mime_type="image/jpeg"
)
prompt_v1 = (
"Count every coin in this image. Draw a bounding box or circle "
"around each one and number them. Check for overlapping or "
"partially hidden coins. Give me the final count."
)
response_v1 = client.models.generate_content(
model=MODEL,
contents=[image_part, prompt_v1],
config=agentic_config,
)
print_response(response_v1, show_thoughts=True)Le modèle recadre cinq régions, les analyse et renvoie un total de 34. Mais regardez le format de la réponse :
[ANSWER] Final Count: 34 coins in total.
[
{"box_2d": [387, 175, 451, 236], "label": "1"},
{"box_2d": [356, 196, 407, 248], "label": "2"},
{"box_2d": [319, 231, 375, 274], "label": "3"},
...
]Il a renvoyé des coordonnées de boîtes au format JSON au lieu de dessiner sur l’image. La consigne disait "draw", mais le modèle l’a interprétée comme une demande de description et a produit une sortie structurée.
La documentation sur l’exécution de code donne un indice : "Bien que le modèle gère automatiquement le zoom pour les petits détails, vous devez le solliciter explicitement pour d’autres tâches." Le mot "draw" est assez ambigu pour que le modèle choisisse la voie texte uniquement.
Décrire la tâche en termes du code à exécuter lève l’ambiguïté :
prompt_v2 = (
"Count every coin in this image. Use Python to draw a numbered "
"bounding box on the image around each coin you find. Check for "
"overlapping or partially hidden coins. After annotating, give "
"me the final count."
)
response_v2 = client.models.generate_content(
model=MODEL,
contents=[image_part, prompt_v2],
config=agentic_config,
)
print_response(response_v2, show_thoughts=True)Cette fois, le modèle écrit un vrai code de dessin :
[CODE]
import PIL.Image
import PIL.ImageDraw
img = PIL.Image.open('input_file_0.jpeg')
width, height = img.size
coins = [
[383, 175, 452, 227], [352, 196, 411, 255], ... # 34 total
]
draw = PIL.ImageDraw.Draw(img)
for i, coin in enumerate(coins):
ymin, xmin, ymax, xmax = coin
left, top, right, bottom = (xmin*width/1000, ymin*height/1000,
xmax*width/1000, ymax*height/1000)
draw.rectangle([left, top, right, bottom], outline='red', width=3)
draw.text((left, top), str(i + 1), fill='red')
[RESULT] (Outcome.OUTCOME_OK)
Total coins detected: 34
[IMAGE] image/png, 3,685,043 bytes
[ANSWER] I have identified and counted a total of 34 coins.
Chaque pièce reçoit un cadre rouge et un numéro. Le compte réel est de 35 ou 36, selon la façon de juger deux pièces qui se chevauchent en bas de l’image.
Le modèle aboutit à 34, en manquant une ou deux pièces dans ce groupe. Mais l’annotation fait office de brouillon visuel : plutôt qu’un nombre à accepter sur parole, vous obtenez un artefact vérifiable, contrôlable boîte par boîte.
La sortie complète non tronquée des deux appels est disponible dans ce gist.
Extraction multi-étapes et visualisation
Les exemples précédents portaient chacun sur une tâche principale (lire du texte, compter des objets). Celui-ci en enchaîne plusieurs : recadrer un tableau depuis une photo, extraire les nombres dans un DataFrame, puis générer un graphique. L’image représente un tableau fiscal de type IRS photographié sur un bureau avec une calculatrice.
La consigne décrit tout le pipeline d’un seul tenant :
image_path = Path("images/data_table.jpg")
image_part = types.Part.from_bytes(
data=image_path.read_bytes(), mime_type="image/jpeg"
)
prompt = (
"Crop and zoom into the table in this image. Extract the first "
"10 rows of data into a structured format. Identify the column "
"headers. Then create a bar chart comparing the values in the "
"numeric columns for those 10 rows. Summarize which row has the "
"highest and lowest values."
)
response = client.models.generate_content(
model=MODEL,
contents=[image_part, prompt],
config=agentic_config,
)
print_response(response, show_thoughts=True)Le modèle effectue quatre tours de code pour passer de la photo complète au graphique final. Les trois premiers sont des zooms progressifs : il recadre le tableau "Single or Married Filing Separately", puis les en-têtes de colonnes, puis les 10 premières lignes, générant cinq images intermédiaires. Voici le premier recadrage où il isole le tableau :
Au quatrième tour, il a suffisamment d’information pour extraire les nombres. Il construit un DataFrame pandas, imprime le tableau et génère un diagramme en barres groupées dans un seul bloc de code :
[CODE]
import matplotlib.pyplot as plt
import pandas as pd
data = [
{"Higher Paying Job Wage": "$0 - 9,999",
"$0 - 9,999": 0, "$10,000 - 19,999": 940,
"$20,000 - 29,999": 1020, "$30,000 - 39,999": 1020},
... # 10 rows total
]
df = pd.DataFrame(data)
df.set_index("Higher Paying Job Wage").plot(kind='bar', figsize=(12, 6))
plt.title('Tax Table: Single or Married Filing Separately')
plt.ylabel('Tax Amount')
plt.savefig('tax_bar_chart.png')Le tableau extrait :
|
Higher Paying Job Wage |
$0 - 9,999 |
$10,000 - 19,999 |
$20,000 - 29,999 |
$30,000 - 39,999 |
|
$0 - 9,999 |
$0 |
$940 |
$1,020 |
$1,020 |
|
$10,000 - 19,999 |
$940 |
$1,540 |
$1,620 |
$2,020 |
|
$20,000 - 29,999 |
$1,020 |
$1,620 |
$2,100 |
$3,100 |
|
$30,000 - 39,999 |
$1,020 |
$2,020 |
$3,100 |
$4,100 |
|
$40,000 - 59,999 |
$1,870 |
$3,470 |
$4,550 |
$5,550 |
|
$60,000 - 79,999 |
$1,870 |
$3,470 |
$4,690 |
$5,890 |
|
$80,000 - 99,999 |
$2,000 |
$3,810 |
$5,090 |
$6,290 |
|
$100,000 - 124,999 |
$2,040 |
$3,840 |
$5,120 |
$6,320 |
|
$125,000 - 149,999 |
$2,040 |
$3,840 |
$5,120 |
$6,910 |
|
$150,000 - 174,999 |
$2,220 |
$4,830 |
$6,910 |
$8,910 |
Et le diagramme en barres généré :
La sortie complète non tronquée est disponible dans ce gist.
Un seul appel d’API a produit un DataFrame structuré, un résumé identifiant les lignes max/min, et un graphique prêt à publier. La consigne énonçait quatre actions (recadrer, extraire, tracer, résumer), et le modèle a traité chacune comme une étape d’un pipeline où la sortie de l’une alimente la suivante.
Les exemples précédents utilisaient la boucle pour affiner une opération (meilleurs recadrages, meilleures annotations). Celui-ci montre la boucle enchaînant des opérations différentes, chacune s’appuyant sur la précédente.
Conclusion
L’agentic vision transforme un seul appel d’API en une boucle de feedback où le modèle écrit du code, observe le résultat et décide de la suite.
L’exemple du rayon illustrait le schéma de base : recadrer les zones trop petites à lire, puis répondre à partir des versions agrandies. Le menu de bar a ajouté une seconde dimension : une première passe de recadrages, jugée insuffisante, suivie d’un zoom plus poussé sur les zones problématiques, de sa propre initiative.
Pour les pièces, l’annotation a transformé une estimation en artefact contrôlable. Le tableau fiscal a enchaîné quatre opérations distinctes (recadrer, extraire, calculer, tracer) dans une seule requête.
Chaque exemple a aussi apporté des enseignements de prompting. Fixer une barre d’exhaustivité ("lister tous les produits") a poussé le modèle vers la complétude. Laisser la méthode ouverte lui a permis de choisir sa voie de prétraitement.
Mais des verbes ambigus comme "draw" l’ont parfois mis sur une fausse piste, et passer à "Use Python to draw" a levé l’ambiguïté.
La règle : décrivez ce que vous voulez obtenir, soyez précis sur l’outil quand la tâche est ambiguë, et laissez la boucle faire le reste.
Tout le code de ce tutoriel s’exécute avec gemini-3-flash-preview et le SDK google-genai. Pour aller plus loin, le cours Introduction to AI Agents de DataCamp couvre le schéma de boucle sous-jacent.