Programa
Fundamentos de agentes de IA
6 h
Você envia uma imagem para uma API de visão pedindo para ler um rótulo de preço minúsculo. A resposta vem confiante e errada. O mesmo acontece ao contar objetos em uma foto bagunçada: o modelo olha a imagem inteira uma vez e chuta um número bem distante do real.
Gemini 3 Flash lida com isso de outro jeito. Com execução de código ativada, ele pode escrever e rodar Python no meio da resposta para recortar, dar zoom e anotar imagens antes de cravar uma resposta. O Google chama isso de visão agentiva e relata um ganho de 5–10% em benchmarks de visão.
Este tutorial percorre quatro exemplos que ficam progressivamente mais difíceis: ler letras miúdas em uma prateleira de supermercado, extrair nomes de bebidas de um cardápio em um bar com pouca luz, contar moedas espalhadas e extrair dados de uma tabela para um gráfico.
O que é visão agentiva? O loop "Think, Act, Observe"
A ideia é simples. Com a execução de código ativa, Gemini 3 pode parar no meio da resposta, escrever e rodar Python em um sandbox, olhar o que o código produziu e decidir o próximo passo.
Para tarefas de visão, isso geralmente significa recortar regiões da imagem, ampliá-las, desenhar bounding boxes ou ajustar contraste para ressaltar detalhes que não aparecem na resolução original.
Isso acontece em um loop de três fases.
Na fase Think, o modelo analisa o que tem (a imagem original ou uma versão já recortada/anotada) e planeja o próximo movimento. Ele pode decidir que um rótulo de preço está pequeno demais para ler e precisa ser recortado e ampliado.
Act transforma o plano em Python. O sandbox tem 43 bibliotecas pré-instaladas (PIL, OpenCV, matplotlib e outras), então o modelo pode escrever o código de processamento de imagem que precisar.
Depois que o código roda, Observe fecha o loop. A saída (novas imagens, texto impresso, valores calculados) volta para o contexto. A partir daí, o modelo responde ou dá mais uma volta.
Uma única chamada de API pode percorrer esse loop várias vezes. Nos exemplos a seguir, você verá o modelo recortar sete regiões da prateleira em um único pedido. Em outro, ele extrai dados de uma tabela para um DataFrame do pandas e gera um gráfico de barras, tudo na mesma chamada.
Se o conceito de loop agentivo é novo para você, a trilha AI Agent Fundamentals da DataCamp aprofunda o tema.
Limitações e cuidados
- Execução de código e chamadas de função personalizadas não podem ser usadas no mesmo pedido.
- A documentação do Google alerta que a execução de código pode prejudicar o desempenho em tarefas não visuais. Ative apenas quando a tarefa se beneficiar de manipulação de imagem.
- Segmentação em nível de pixel (máscaras, contornos) não faz parte da visão agentiva e permanece no Gemini 2.5.
- O modelo às vezes pula a execução de código se um único olhar for suficiente. É proposital, não é bug.
Configurando seu ambiente para visão agentiva
Pegue uma chave de API em ai.google.dev e armazene como GOOGLE_API_KEY no seu ambiente ou em um arquivo .env. Depois instale o SDK e as bibliotecas de imagem:
pip install google-genai python-dotenv Pillow matplotlib opencv-pythonComece criando o 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"Esse timeout=600_000 é importante. Chamadas de visão agentiva envolvem várias rodadas de geração e execução de código dentro do sandbox, e um único pedido pode levar cerca de quatro minutos.
O timeout padrão do httpx vai encerrar a conexão bem antes disso, deixando você com um ReadTimeout silencioso e sem pista do que aconteceu.
Em seguida, configure o modo agentivo:
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 é o interruptor que liga a execução de código. Ele dá ao modelo um ambiente Python em sandbox com 43 bibliotecas (numpy, pandas, PIL, matplotlib, OpenCV e mais). Cada bloco de código tem 30 segundos para rodar e o sandbox faz até 5 tentativas em caso de erro.
thinking_level="HIGH" dá ao modelo mais espaço para planejar antes de escrever código. Para trabalho de visão em várias etapas, isso faz diferença. Definir include_thoughts=True expõe esse raciocínio nas partes da resposta, útil para depuração.
media_resolution define quantos tokens a imagem de entrada recebe antes mesmo do loop começar. MEDIA_RESOLUTION_HIGH é um bom padrão. Você pode aumentar para MEDIA_RESOLUTION_ULTRA_HIGH para imagens muito densas ou reduzir para MEDIA_RESOLUTION_LOW quando a velocidade importa mais que o detalhe.
Essa mesma configuração funciona no Vertex AI com mudanças mínimas. Para uma visão mais ampla da Gemini 3 API além de visão, veja o tutorial complementar.
Visão agentiva no Gemini 3: lendo detalhes finos com recorte e zoom
A imagem abaixo é uma prateleira de supermercado na Alemanha com três fileiras de produtos. Etiquetas de preço acompanham a borda de cada prateleira, e um aviso "Liebe Kunden" (Prezados clientes) fica perto da parte de baixo. Dá para ler as etiquetas se você mesmo der zoom, mas elas são pequenas o suficiente para que um modelo olhando a imagem completa precise decidir o que consegue ou não distinguir.
Analisando a resposta multipartes
Respostas agentivas não vêm como um único bloco de texto. Elas chegam como uma lista de partes: pensamento, código escrito pelo modelo, resultados da execução, imagens geradas e a resposta final. Este helper percorre todas elas:
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)Todo exemplo deste tutorial usa a mesma função, então defina uma vez e reutilize.
Agora carregue a imagem da prateleira e escreva um prompt pedindo para o modelo ler o aviso e listar cada produto com seu preço.
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."
)Rode primeiro sem execução de código:
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)Aqui vai uma versão resumida da saída:
[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
...A tradução do aviso está correta, e o modelo lê as etiquetas do Uncle Ben's que consegue reconhecer. Mas cerca de um terço das entradas ficam como "(Label obscured)", e marcas como Oryza, Reis-fit e Reiskugeln nem aparecem.
Agora o mesmo prompt com a configuração agentiva:
agentic_response = client.models.generate_content(
model=MODEL,
contents=[image_part, prompt],
config=agentic_config,
)
print_response(agentic_response, show_thoughts=True)A estrutura da saída muda. Em vez de um único [ANSWER], ela percorre todo o 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 bytesOs sete recortes que o modelo gerou:
Depois de observar esses recortes, o modelo produz uma resposta 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 €
...A saída completa e sem cortes de ambas as chamadas está disponível neste gist.
A resposta agentiva lê mais de 30 produtos nas três prateleiras. Os itens Oryza, Reis-fit, Madras Curry, Reiskugeln e Steam Basmati, que a visão padrão marcou como "(obscured)", aparecem com nomes e preços.
A diferença não é alucinação vs. acurácia; a visão padrão é honesta sobre o que não consegue ler. A visão agentiva simplesmente não aceita esse limite e dá zoom até conseguir.
O prompt ajuda nisso. Pedir para "listar todos os nomes de produtos visíveis e seus preços" define uma barra de completude que incentiva o modelo a recortar.
Um prompt mais vago como "descreva esta imagem" provavelmente geraria uma resposta de passada única mesmo com execução de código ligada, porque o modelo não veria motivo para ir além.
Lendo apesar de pouca luz e obstruções
Esta imagem é um cardápio de bar brasileiro fotografado em ambiente escuro. Três painéis de vidro listam bebidas em texto dourado, mas luminárias pendentes bloqueiam partes do painel esquerdo, o painel direito mal aparece na borda do enquadramento e reflexos no vidro se espalham pela superfície.
O prompt não menciona brilho, recorte ou nenhuma técnica específica. Ele só pede o conteúdo:
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."
)A visão padrão lê sem problemas o painel central bem iluminado, extraindo oito cervejas da seção "FRUTADAS" e quatro de "CHOPP". Já o painel esquerdo sai assim:
[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]Seis entradas, a maioria com nomes ilegíveis e todas sem o estilo. O modelo percebe que há texto ali, mas não consegue ler.
A chamada agentiva roda duas rodadas de código. Primeiro, recorta os três painéis:
[CODE]
middle_panel = [200, 320, 950, 780]
left_panel = [200, 0, 950, 260]
right_panel = [200, 840, 700, 1000]
# ... crops and saves each region
Depois de observar esses recortes, o modelo decide que os painéis esquerdo e direito precisam de mais zoom. Ele roda uma segunda rodada:
[CODE]
left_panel_top = [100, 0, 500, 250]
left_panel_bottom = [500, 0, 980, 250]
right_panel_top = [100, 800, 600, 1000]
Com esse zoom extra, o modelo recupera nomes que a visão padrão marcou como ilegíveis: Amber Lager, Honkers Ale (Goose Island) e Demoiselle (Colorado) no painel esquerdo, além de Wals Dubbel, Tripel, Quadrupel e Petroleum no direito. Ele também identifica o título do painel esquerdo como "MISTURAS" e o do direito como "ALCOÓLICAS".
O prompt nunca disse "recorte os painéis" ou "dê zoom nas áreas escuras". Ele pediu as bebidas e seus estilos, e o modelo trabalhou de trás para frente a partir desse objetivo.
O que diferencia este exemplo da prateleira do mercado é a segunda passada. Após a primeira rodada de recortes, o modelo avaliou o que tinha, decidiu que os painéis esquerdo e direito ainda estavam difíceis de ler e fez outra rodada de zooms mais fechados sem ser instruído.
O loop se autocorrigiu.
Esse é o ganho de deixar o método em aberto: o modelo não faz só um pré-processamento, ele itera até os resultados atingirem a barra definida pelo prompt.
Contagem e anotação com visão agentiva no Gemini 3
O cardápio funcionou porque o prompt deixou o método em aberto e o modelo descobriu o que fazer. Nem sempre é assim. Às vezes o modelo precisa de instruções explícitas sobre qual ferramenta usar, e o próximo exemplo mostra onde está essa linha.
A imagem abaixo tem moedas espalhadas por uma mesa e uma pasta preta. Algumas se sobrepõem, outras estão parcialmente escondidas, e a mistura de cobre e prata facilita perder a conta.
Uma primeira abordagem razoável é pedir ao modelo para anotar cada moeda, para que ele conte a partir de suas próprias marcações. A documentação do Google confirma que a visão agentiva pode desenhar bounding boxes e rótulos diretamente nas imagens usando PIL e OpenCV no sandbox. Então:
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)O modelo recorta cinco regiões, analisa cada uma e retorna uma contagem de 34. Mas veja o formato da resposta:
[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"},
...
]Ele retornou coordenadas de bounding boxes em JSON em vez de desenhar algo na imagem. O prompt dizia "draw", mas o modelo tratou como uma tarefa de descrição e entregou texto estruturado.
A documentação de execução de código dá a pista: "Enquanto o modelo lida automaticamente com zoom para detalhes pequenos, você deve instruí-lo explicitamente a usar código para outras tarefas." A palavra "draw" é ambígua o suficiente para o modelo escolher o caminho só de texto.
Descrever a tarefa nos termos do código que você quer que ele rode remove essa ambiguidade:
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)Desta vez, o modelo escreve código que realmente desenha:
[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.
Cada moeda recebe uma caixa vermelha e um número. A contagem real é 35 ou 36, dependendo de como você considera duas moedas sobrepostas perto da borda inferior.
O modelo chegou a 34, deixando passar uma ou duas naquele aglomerado. Mas a anotação funciona como um rascunho visual: em vez de um número que você precisa aceitar na confiança, você recebe um artefato verificável para checar, caixa por caixa.
A saída completa e sem cortes de ambas as chamadas está disponível neste gist.
Extração em várias etapas e plotagem
Os exemplos anteriores envolviam uma tarefa principal cada (ler texto, contar objetos). Aqui encadeamos várias: recortar uma tabela de uma foto, extrair os números para um DataFrame e gerar um gráfico. A imagem é uma tabela de impostos no estilo IRS fotografada sobre uma mesa com uma calculadora.
O prompt descreve o pipeline completo de uma vez:
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)O modelo leva quatro rodadas de código para ir da foto completa a um gráfico pronto. As três primeiras são zooms progressivos: ele recorta a tabela "Single or Married Filing Separately", depois os cabeçalhos de coluna e, em seguida, as primeiras 10 linhas de dados, gerando cinco imagens intermediárias. Aqui está o primeiro recorte, isolando a tabela:
Na quarta rodada, ele já leu detalhes suficientes para extrair os números. Constrói um DataFrame do pandas, imprime a tabela e gera um gráfico de barras agrupadas em um único bloco de código:
[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')A tabela extraída:
|
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 |
E o gráfico de barras gerado:
A saída completa e sem cortes está disponível neste gist.
Uma única chamada de API produziu um DataFrame estruturado, um resumo com as linhas de maior/menor valor e um gráfico de barras pronto para publicação. O prompt listou quatro coisas (recortar, extrair, plotar, resumir), e o modelo tratou cada uma como uma etapa de um pipeline em que a saída de um passo alimenta o seguinte.
Os exemplos anteriores usaram o loop para refinar uma operação (melhores recortes, melhores anotações). Aqui, o loop encadeia operações diferentes, cada uma construindo em cima do que a rodada anterior produziu.
Conclusão
A visão agentiva transforma uma única chamada de API em um loop de feedback no qual o modelo escreve código, olha o que produziu e decide o próximo passo.
O exemplo da prateleira mostrou o padrão básico: recortar regiões pequenas demais para ler e responder a partir das versões ampliadas. O do cardápio adicionou uma segunda dimensão, em que o modelo fez uma rodada de recortes, decidiu que não bastava e deu zoom adicional nas áreas problemáticas por conta própria.
No caso das moedas, a anotação transformou um chute em um artefato verificável. A tabela de impostos encadeou quatro operações distintas (recortar, extrair, calcular, plotar) dentro de um único pedido.
Cada exemplo também trouxe aprendizados de prompting. Definir uma barra de completude ("listar todos os produtos") empurra o modelo para a exaustividade. Deixar o método em aberto permite que ele escolha o próprio caminho de pré-processamento.
Mas verbos ambíguos como "draw" às vezes o desviam, e trocar por "Use Python to draw" resolve.
O padrão é: descreva o que você quer de saída, seja específico sobre a ferramenta quando a tarefa for ambígua e deixe o loop cuidar do resto.
Todo o código deste tutorial roda com gemini-3-flash-preview e o SDK google-genai. Para ir além, o curso Introduction to AI Agents da DataCamp aborda o padrão de loop por trás de tudo isso.
