Gemini 3.5 Flash, rilasciato da Google al I/O del 19 maggio 2026, è veloce, economico e gestisce un milione di token di contesto: l'ideale per costruire applicazioni concrete. In questa guida partiamo da zero e arriviamo a tre risultati utili in Python: un chatbot con memoria della conversazione, un analizzatore di PDF e un piccolo agente che usa il function calling per chiamare i nostri strumenti.

A chi serve e cosa ti serve prima di iniziare

Questa guida è pensata per chi conosce le basi di Python e vuole integrare un modello linguistico nelle proprie applicazioni o automazioni. Prerequisiti reali:

  • Python 3.10 o superiore installato (verifica con python --version).
  • Un account Google per ottenere la chiave API gratuita da Google AI Studio.
  • Un terminale e un editor di testo. Nessuna GPU: tutto il calcolo avviene sui server di Google.

Sul piano dei costi, AI Studio offre un piano gratuito con limiti di frequenza, sufficiente per imparare e per piccoli progetti. Quando si passa in produzione, l'API a consumo costa 1,50 dollari per milione di token in ingresso e 9 dollari per milione in uscita: vale la pena tenere d'occhio l'uso, perché allegare PDF e contesti lunghi consuma molti token.

Passo 1: ottenere la chiave e installare la libreria

Vai su Google AI Studio (aistudio.google.com), accedi e crea una nuova chiave API dalla sezione dedicata. Poi installa l'SDK ufficiale e salva la chiave in una variabile d'ambiente, così da non scriverla nel codice:

pip install google-genai
# su Linux/macOS:
export GEMINI_API_KEY="incolla-qui-la-tua-chiave"
# su Windows (PowerShell):
setx GEMINI_API_KEY "incolla-qui-la-tua-chiave"

Verifica che tutto funzioni con uno script minimo, test.py:

from google import genai

client = genai.Client()  # legge automaticamente GEMINI_API_KEY

risposta = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Spiega in due frasi cos'e' un token in un modello linguistico."
)
print(risposta.text)

Esegui con python test.py: dovresti vedere una risposta di due frasi in pochi secondi. Se ricevi un errore di autenticazione, controlla che la variabile d'ambiente sia impostata nel terminale in uso.

Passo 2: un chatbot con memoria della conversazione

Una singola chiamata non ricorda i messaggi precedenti. Per un dialogo continuo si usa una sessione di chat, che mantiene lo storico in automatico:

from google import genai

client = genai.Client()
chat = client.chats.create(model="gemini-3.5-flash")

print("Scrivi 'esci' per terminare.")
while True:
    domanda = input("Tu: ")
    if domanda.strip().lower() == "esci":
        break
    risposta = chat.send_message(domanda)
    print("Gemini:", risposta.text)

Adesso il modello ricorda il contesto: se prima chiedi "Chi ha scritto la Divina Commedia?" e poi "In che secolo e' vissuto?", capira' che ti riferisci a Dante. Per dare al modello una personalita' o delle regole, si usa l'istruzione di sistema:

from google import genai
from google.genai import types

client = genai.Client()
chat = client.chats.create(
    model="gemini-3.5-flash",
    config=types.GenerateContentConfig(
        system_instruction="Sei un tutor di italiano. Rispondi in modo semplice e correggi gli errori."
    )
)
print(chat.send_message("Ieri io ho andato al mare.").text)

Risultato atteso: il modello segnala che la forma corretta e' "sono andato" e spiega brevemente il perche'.

Passo 3: analizzare un PDF

Grazie al contesto da un milione di token, Gemini 3.5 Flash puo' leggere documenti lunghi. Carichiamo un PDF e facciamoci un riassunto:

from google import genai

client = genai.Client()

# carica il file (utile per documenti grandi o riusati piu' volte)
documento = client.files.upload(file="contratto.pdf")

risposta = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        documento,
        "Riassumi questo contratto in 8 punti e segnala eventuali clausole di rinnovo automatico."
    ]
)
print(risposta.text)

Risultato atteso: un elenco di otto punti con i contenuti principali e l'evidenziazione delle clausole richieste. Lo stesso schema funziona per immagini, fatture o relazioni. Suggerimento: chiedi sempre al modello di citare la sezione o la pagina da cui trae un'informazione, per poterla verificare.

Passo 4: function calling, l'agente che usa i tuoi strumenti

Il function calling permette al modello di decidere quando chiamare una nostra funzione, per esempio per ottenere dati aggiornati. Definiamo una funzione e lasciamo che Gemini la usi quando serve:

from google import genai
from google.genai import types

def meteo(citta: str) -> str:
    """Restituisce il meteo attuale per una citta'."""
    # qui chiameresti una vera API meteo; per l'esempio e' fisso
    return f"A {citta} ci sono 22 gradi e cielo sereno."

client = genai.Client()
risposta = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Che tempo fa a Bologna? Consigliami come vestirmi.",
    config=types.GenerateContentConfig(tools=[meteo])
)
print(risposta.text)

L'SDK gestisce in automatico il ciclo: Gemini capisce che deve chiamare meteo("Bologna"), riceve il risultato e formula la risposta finale, per esempio suggerendo un abbigliamento leggero. Sostituendo il corpo della funzione con una vera chiamata di rete, hai la base di un agente che interroga sistemi esterni.

Passo 5: risposte in streaming e output in JSON

Per un'esperienza piu' reattiva, soprattutto in un'app con interfaccia, conviene ricevere la risposta a pezzi man mano che viene generata, invece di attendere il testo completo. Si usa il metodo in streaming:

from google import genai

client = genai.Client()
for blocco in client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="Scrivi una breve storia per bambini sul mare."
):
    print(blocco.text, end="")

Vedrai il testo comparire progressivamente, come nelle chat moderne. Quando invece ti serve un dato strutturato da usare nel codice (per esempio per popolare un database), puoi chiedere a Gemini di rispondere in JSON valido secondo uno schema. Indica nella configurazione il tipo di risposta atteso e descrivi i campi nel prompt:

from google import genai
from google.genai import types

client = genai.Client()
risposta = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Estrai nome, prezzo e categoria da: 'Caffe' espresso, 1,20 euro, bevande'.",
    config=types.GenerateContentConfig(response_mime_type="application/json")
)
print(risposta.text)

Risultato atteso: un oggetto JSON con i campi nome, prezzo e categoria, pronto da convertire in dizionario con json.loads(). E' il modo piu' affidabile per integrare il modello in un flusso automatico.

Errori comuni e come risolverli

  • "API key not valid" o errore 401: la chiave non e' impostata o e' sbagliata. Ricontrolla la variabile d'ambiente nel terminale corrente.
  • Errore 429 (Resource exhausted): hai superato i limiti del piano gratuito. Attendi qualche minuto o passa al piano a consumo.
  • Risposte troncate: aumenta il limite di token in uscita con max_output_tokens nella configurazione.
  • Costi inattesi: ricorda che ogni PDF e contesto lungo pesa molti token; monitora l'uso dalla dashboard.

Varianti e come proseguire

Se i compiti diventano molto complessi e di lunga durata, valuta il fratello maggiore Gemini 3.5 Pro. Per ridurre costi e latenza su richieste semplici, abbassa il livello di ragionamento (impostando un thinking minimo o basso nella configurazione). Da qui puoi costruire molto: un assistente che risponde sui tuoi documenti aziendali, un'automazione che classifica le email, o un agente che combina piu' strumenti. Il modello e' lo stesso che alimenta l'app Gemini: quello che impari qui vale per applicazioni reali.