Guida per gli sviluppatori a Gemini 3.5 Flash

Gemini 3.5 Flash è un modello potente, ad alta velocità ed economico della famiglia Gemini 3. Progettato per offrire capacità agentiche quasi pari a quelle di Pro senza compromettere le prestazioni o il valore, il modello è ora in disponibilità generale (GA) per gli sviluppatori che utilizzano l'API Gemini e per le aziende che utilizzano Gemini Enterprise Agent Platform.

Questo documento illustra le novità di 3.5 Flash, quando utilizzarlo, come eseguire la migrazione a 3.5 Flash e fornisce una guida rapida per l'utilizzo di 3.5 Flash.

Come si inserisce nella famiglia Gemini?

La seguente tabella mette a confronto alcune delle specifiche di 3.5 Flash, 3.1 Pro e 3.1 Flash-Lite:

	Gemini 3.5 Flash	Gemini 3.1 Pro	Gemini 3.1 Flash-Lite
ID modello	gemini-3.5-flash	gemini-3.1-pro-preview	gemini-3.1-flash-lite
Fase di lancio	GA	Anteprima	GA
Tipi di input	Testo, immagine, audio, video	Testo, immagine, audio, video	Testo, immagine, audio, video
Tipi di output	Testo	Testo	Testo
Finestra contestuale	1.048.576	1.048.576	1.048.576
Lunghezza massima dei token di output	65.536	65.536	65.536
Aree geografiche supportate	Globale, Multiregionale, Americhe, Europa, Asia Pacifico	Globale	Globale, multiregionale
Livelli di ragionamento supportati	MINIMAL, LOW, MEDIUM, HIGH (Predefinito: MEDIUM)	LOW, MEDIUM, HIGH (Predefinito: HIGH)	MINIMAL, LOW, MEDIUM, HIGH (Predefinito: MINIMAL)
Scopo principale	Attività bilanciate, chiamate agli strumenti e ragionamento intermedio	Ragionamento approfondito, attività ad alta complessità	Attività ad alto volume, sensibili ai costi e alla latenza

Consulta la pagina del modello 3.5 Flash per l'elenco completo delle funzionalità, degli strumenti e delle opzioni di consumo supportati.

Suddivisione dei casi d'uso

La strategia consigliata per gli Agentic Workflow utilizza un approccio a più livelli per ottimizzare qualità, velocità e costi:

• Gemini Pro: riservalo per compiti cognitivi ad alta complessità che richiedono un ragionamento approfondito, come la pianificazione iniziale, la risoluzione di problemi complessi, la programmazione difficile e il processo decisionale critico.
• Gemini Flash: utilizzalo come "motore" principale per le attività di esecuzione, le chiamate agli strumenti e i passaggi di ragionamento intermedi, offrendo il miglior equilibrio tra prestazioni ed efficienza.
• Gemini Flash-Lite: esegui il deployment per attività strutturali e di pre-elaborazione a bassa latenza e ad alto volume in cui la velocità e i costi sono fondamentali, come il routing degli intent, l'estrazione dati, il tagging e la classificazione.

Quali sono le novità di Gemini 3.5 Flash?

Gemini 3.5 Flash apporta le seguenti modifiche e i seguenti miglioramenti alla gamma di modelli Gemini:

• Prestazioni all'avanguardia sostenute: il nostro modello Gemini Flash più intelligente, ottimizzato per attività agentiche e di programmazione su larga scala.
• Esecuzione agentica: deployment di sub-agenti, risoluzione dei problemi e loop dell'agente rapidi su larga scala.
• Coding migliorato: cicli di coding iterativi, esplorazione rapida e prototipazione per testare percorsi alternativi ed esplorare dinamicamente le soluzioni.
• A lungo termine: workflow in più passaggi e utilizzo degli strumenti su larga scala.
• Conservazione del ragionamento: il modello mantiene automaticamente il ragionamento intermedio nelle conversazioni multi-turn. Non sono necessarie modifiche alle API.
• Nuovo livello di ragionamento predefinito: il livello di ragionamento predefinito è cambiato da HIGH a MEDIUM.
• Ragionamento di LOW migliorato: il livello di ragionamento basso è ora notevolmente migliorato per le attività di programmazione e agentiche che richiedono meno passaggi, offrendo una qualità elevata con latenza e costi inferiori.

Puoi trovare ulteriori dettagli nella sezione Modifiche principali.

Nota: potresti notare un aumento del numero di token segnalati. L'infrastruttura aggiornata conteggia con precisione tutti i componenti della richiesta, inclusi i metadati complessi come gli schemi di risposta e le chiamate di funzione, che erano conteggiati in modo errato nelle versioni precedenti.

Guida rapida

Prima di iniziare, devi autenticarti su Agent Platform utilizzando le Credenziali predefinite dell'applicazione (ADC) o una chiave API. Per saperne di più, consulta Inizia a utilizzare Gemini Enterprise Agent Platform.

Nei blocchi di codice seguenti, sostituisci PROJECT_ID con l'ID progetto.

Installazione

Assicurati di utilizzare l'SDK google-genai più recente:

pip install --upgrade google-genai

Richiesta di base

Python

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
  model="gemini-3.5-flash",
  contents="How does AI work?",
)
print(response.text)

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

Modifiche principali

Questa sezione descrive in maggiore dettaglio le seguenti modifiche introdotte in Gemini 3.5 Flash:

• Nuovo livello di ragionamento predefinito (MEDIUM)
• Conservazione del ragionamento
• Ritirati: parametri di campionamento
• Deprecato: thinking_budget

Nuovo livello di ragionamento predefinito

Il livello di ragionamento predefinito per i modelli Gemini 3 è ora MEDIUM, modificato da HIGH nella versione di anteprima di Gemini 3 Flash. Il livello di ragionamento MEDIUM produce risultati eccellenti in un'ampia gamma di attività, pur essendo più veloce ed efficiente in termini di costi.

I livelli di ragionamento supportati sono:

• MINIMAL: corrisponde all'impostazione "Nessun ragionamento" per la maggior parte delle query. Il modello potrebbe riflettere molto poco per attività complesse come la programmazione. Riduce al minimo la latenza per le applicazioni di chat o con throughput elevato.
• LOW: ragionamento leggero per la maggior parte delle attività con velocità elevata e costi ridotti.
• MEDIUM: (predefinito) impostazione bilanciata per la maggior parte delle attività che richiedono ragionamento.
• HIGH: massimizza il ragionamento per ottimizzare le prestazioni delle attività. Il modello potrebbe impiegare più tempo rispetto all'impostazione MEDIUM per generare il primo token, ma l'output sarà più completo.

Ad esempio, utilizza HIGH per puzzle logici, problemi matematici formulati a parole o scenari complessi in cui il modello deve ragionare attraverso più passaggi:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.5-flash",
   contents="A farmer has chickens and rabbits. There are 35 heads and 94 legs. How many chickens and how many rabbits does he have? Show your step-by-step logic.",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.HIGH
       )
   ),
)
print(response.text)

Il parametro thinking_level è facoltativo. Se omesso, 3.5 Flash utilizzerà l'impostazione predefinita (MEDIUM).

Nota: il parametro thinking_level e il parametro precedente thinking_budget sono esclusivi l'uno rispetto all'altro. Se li utilizzi entrambi in una richiesta, verrà restituito un errore 400.

Conservazione del ragionamento

Il modello mantiene automaticamente il ragionamento intermedio nelle conversazioni multi-turno. Quando è presente nella cronologia delle conversazioni, il contesto di ragionamento viene trasferito automaticamente, migliorando le prestazioni in attività complesse in più passaggi come il debug iterativo e il refactoring del codice. Non sono necessarie modifiche alle API.

I pensieri dei turni precedenti vengono ora conservati per impostazione predefinita. Il servizio non cancella più la cronologia dei pensieri dal contesto della conversazione prima di passarla al modello.

Quando invii la cronologia delle conversazioni, mantieni la coerenza con i turni precedenti: includi il contesto completo (pensieri, chiamate di funzione, risposte) o omettilo del tutto. Un contesto parziale può ridurre le prestazioni del modello.

Nota: la conservazione del ragionamento potrebbe aumentare l'utilizzo dei token e il tempo di risposta. Per query semplici e indipendenti, può essere utile cancellare i pensieri tra un turno e l'altro.

Ritirato: parametri di campionamento

I seguenti parametri di campionamento non sono più consigliati per i modelli Gemini 3:

• temperature
• top_p
• top_k

Il modello gestisce il proprio campionamento per risultati ottimali. Rimuovi questi parametri da tutte le richieste. Per garantire il determinismo, definisci un'istruzione di sistema con regole esplicite per il tuo caso d'uso specifico.

Ritirato: thinking_budget

Il parametro numerico non elaborato thinking_budget non è più supportato in tutti i modelli Gemini 3. Utilizza invece l'enum di stringhe thinking_level.

# ⚠️ Before (not recommended)
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_budget=7500)
)

# ✅ After
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_level="MEDIUM")
)

Best practice

Questa sezione descrive le seguenti best practice per l'utilizzo di 3.5 Flash:

• Utilizza la corrispondenza rigorosa delle risposte per le chiamate di funzione
• Includi contenuti multimodali nella risposta della funzione parts
• Utilizza le istruzioni incorporate nella risposta della funzione
• Riduci le chiamate agli strumenti non necessarie

Utilizza la corrispondenza rigorosa delle risposte per le chiamate di funzione

Le risposte non corrispondenti fanno sì che il modello restituisca risposte vuote con finish_reason: STOP nella maggior parte dei casi. Segui sempre queste convenzioni:

• Includi id: ogni FunctionResponse deve includere id dell'elemento FunctionCall corrispondente.
• Corrispondenza di name: il name nella risposta deve corrispondere al name nella chiamata.
• Conteggi delle corrispondenze: restituisci esattamente un FunctionResponse per ogni FunctionCall ricevuto.

Il seguente codice è un esempio di chiamata di funzione corretta:

# ✅ Include matching id and name in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result},
                id=tool_call.id,
            )
        ]),
    ],
)

Includi contenuti multimodali nella risposta della funzione parts

La fornitura di immagini al di fuori della risposta della funzione può portare a un comportamento imprevisto del modello, come la fuga di pensieri, e a una qualità inferiore. Segui il suggerimento incluso in Introduzione alla chiamata di funzione e includi contenuti multimodali nelle parti della risposta della funzione che invii al modello. Il modello può elaborare questi contenuti multimodali nel turno successivo per produrre una risposta più informata.

Ad esempio:

# ✅ Include multimodal content in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={
                    "result": "instrument.jpg",
                    "image": base64_image_data,
                },
                id=tool_call.id,
            )
        ]),
    ],
)

Utilizza le istruzioni in linea nella risposta della funzione

Fornire istruzioni della piattaforma insieme alle risposte della funzione come parts successive può portare a un comportamento imprevisto del modello, come la fuga di pensieri, e a una qualità inferiore. Invece, aggiungilo alla fine del testo della risposta della funzione, separato da due nuove righe.

Ad esempio:

# ✅ Append inline instructions to the end of the function response separated by two newlines
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result_text},
                id=tool_call.id,
            )
        ]),
    ],
)

Riduci le chiamate agli strumenti non necessarie

Se riscontri un utilizzo eccessivo delle chiamate agli strumenti, puoi ridurlo al minimo con due tecniche:

1. Riduci il livello di ragionamento: livelli di ragionamento più elevati incoraggiano il modello a utilizzare più strumenti per esplorare e verificare, quindi abbassare il livello può ridurre le chiamate allo strumento.

2. Aggiungi un'istruzione di sistema: se l'utilizzo eccessivo persiste dopo aver regolato il livello di ragionamento, valuta la possibilità di utilizzare un prompt che limiti l'utilizzo dello strumento. Ad esempio:

   You have a limited action budget of <n> tool calls. Use them efficiently.
   

Esegui la migrazione a 3.6 Flash da 3.5 Flash o 3.1 Pro

Per eseguire la migrazione a 3.6 Flash da 3.5 Flash o 3.1 Pro, segui questi passaggi:

1. Aggiorna l'ID modello: modifica la stringa del modello nelle chiamate API in gemini-3.6-flash.
2. Adatta il tuo codice alle nuove regole dell'API della famiglia Gemini 3: Gemini 3.6 Flash applica rigorosamente le regole dei parametri e le convenzioni dell'API stabilite per la famiglia Gemini 3:
   • Rimuovi temperatura, top-K e top-P: rimuovi questi parametri personalizzati dal payload. Anche se non generano un errore, il modello li ignorerà completamente. Utilizza invece il parametro thinking_level o gli output strutturati json_schema per controllare il determinismo dell'output.
   • Rimuovi le penalità di frequenza e presenza: rimuovi eventuali configurazioni personalizzate per le penalità di frequenza o presenza per evitare che le chiamate API generino errori di runtime.
   • Assicurati che l'integrazione della chat non tenti il pre-riempimento del modello: esamina gli array della cronologia dei messaggi per assicurarti che il payload dell'API non termini con un turno utente o un turno modello vuoto. Se l'ultimo oggetto nell'array della cronologia è un ruolo "model" (API GenerateContent) o un tipo "model_output" (API Interactions), ristruttura la sequenza per evitare di attivare un errore di convalida rigorosa.
   • Utilizza thinking_level: rimuovi le istanze del parametro thinking_budget deprecato e utilizza thinking_level.
   • Applica convenzioni di chiamata di funzione rigorose: FunctionResponse deve corrispondere rigorosamente a id, name e al numero di esecuzioni di FunctionCall precedente. Se devi aggiungere istruzioni in linea, inseriscile direttamente nel testo della risposta della funzione, separate da due nuove righe (\n\n).
3. Tieni conto dei cambiamenti nel flusso di lavoro:
   • Se la tua applicazione si basa su loop di conversazione a più turni, testa i tuoi workflow per assicurarti che la nuova concisione dei passaggi del modello non attivi uscite premature.
   • Se crei agenti di frontend o di scripting di base, monitora le chiamate execute_code esplorative non necessarie dovute al nuovo bias del modello verso l'ispezione programmatica iniziale.

Soluzioni alternative per i requisiti di testo pre-strumento

Se il prompt richiede che il modello generi testo strutturato (XLM, YAML, Json, ecc.) (ad esempio, <UPDATE>...</UPDATE>) immediatamente prima di effettuare una chiamata allo strumento, la chiamata allo strumento potrebbe occasionalmente non riuscire con un errore Malformed_Function_Call. Per risolvere il problema, puoi utilizzare una delle seguenti soluzioni alternative:

• (Consigliato) Chiedi al modello di inserire le note pre-strumento all'interno di una chiamata di funzione update() dedicata anziché di testo non elaborato. Per istruzioni dettagliate sull'implementazione, consulta la sezione successiva.
• Chiedi al modello di scrivere le note come intestazioni Markdown (ad esempio, # UPDATE, ## PLAN) anziché come testo strutturato.
• Non richiedere al modello di generare testo prima delle chiamate allo strumento.

Soluzione consigliata: inserisci le note di lavoro in una chiamata di funzione dedicata

Invece dell'istruzione originale:

Before calling a tool, in every response you MUST first output a single
`<UPDATE>` part as specified, don't skip this part or any of required sub-tags
within `<UPDATE>`.

Utilizza questa istruzione aggiornata:

Before calling any other tool, in every response you MUST first call `update`
with all required parameters (previous_step, plan, next_step, external).

Aggiorna tutti i riferimenti al vecchio formato XML <UPDATE> nella richiesta del cliente. Poi aggiungi la dichiarazione di funzione corrispondente per la funzione di aggiornamento:

{
  "name": "update",
  "description": "Update working notes (previous step analysis, plan, next step, external note).",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "previous_step": {
        "type": "STRING",
        "description": "Key findings and outcomes since the previous step."
      },
      "plan": {
        "type": "STRING",
        "description": "The current status of the plan."
      },
      "next_step": {
        "type": "STRING",
        "description": "Brief explanation of the immediate next action according to the plan."
      },
      "external": {
        "type": "STRING",
        "description": "A short, plain-language note shown to the User about what you are ABOUT TO DO next."
      }
    },
    "required": [
      "previous_step",
      "plan",
      "next_step",
      "external"
    ]
  }
}

Il modello effettuerà due chiamate nello stesso passaggio: la chiamata update() che sostituisce l'XML strutturato e la chiamata di funzione effettiva che vuole effettuare.

Risorse aggiuntive

• Pagina del modello Gemini 3.5 Flash
• Notebook introduttivo