Guida per gli sviluppatori a Gemini 3.5 Flash

Gemini 3.5 Flash è un modello potente, veloce ed economico della famiglia Gemini 3. Progettato per offrire funzionalità di agenti quasi professionali senza compromettere le prestazioni o il valore, il modello è ora disponibile a livello generale per gli sviluppatori che utilizzano l'API Gemini e per le aziende che utilizzano Gemini Enterprise Agent Platform.

Questo documento descrive 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 è un confronto che copre alcune delle specifiche tra 3.5 Flash, 3.1 Pro e 3.1 Flash-Lite:

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

Suddivisione dei casi d'uso

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

• Gemini Pro: riserva questo modello per compiti cognitivi di elevata complessità che richiedono un ragionamento approfondito, come la pianificazione iniziale della radice, la risoluzione di problemi complessi, la programmazione difficile e il processo decisionale critico.
• Gemini Flash: utilizzalo come "cavallo di battaglia" principale per le attività di esecuzione, la chiamata di strumenti e i passaggi di ragionamento intermedi, offrendo il miglior equilibrio tra prestazioni ed efficienza.
• Gemini Flash-Lite: esegui il deployment per attività di preelaborazione e strutturali a basso costo e latenza elevata, in cui velocità e costi sono fondamentali, ad esempio routing degli intent, estrazione, tagging e classificazione dei dati.

Quali sono le novità di Gemini 3.5 Flash?

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

• Prestazioni all'avanguardia sostenute: il nostro modello Flash più intelligente, ottimizzato per attività agentiche e di programmazione su larga scala.
• Esecuzione agentica: deployment di subagenti, risoluzione dei problemi e cicli agentici rapidi su larga scala.
• Programmazione migliorata: cicli di programmazione iterativi, esplorazione rapida e prototipazione per testare percorsi alternativi ed esplorare dinamicamente le soluzioni.
• Orizzonte lungo: workflow in più passaggi e utilizzo degli strumenti su larga scala.
• Conservazione del pensiero: il modello mantiene automaticamente il ragionamento intermedio nelle conversazioni a più turni. Non sono necessarie modifiche all'API.
• Nuovo livello di pensiero predefinito: il livello di pensiero predefinito è cambiato da HIGH a MEDIUM.
• Miglioramento del LOWpensiero: il livello di pensiero basso è ora notevolmente migliorato per le attività di codice e agentiche che richiedono meno passaggi, offrendo una qualità elevata a latenza e costi inferiori.

Puoi trovare ulteriori dettagli nella sezione Modifiche principali.

Guida rapida

Prima di iniziare, devi autenticarti in Agent Platform utilizzando le Credenziali predefinite dell'applicazione (ADC) o una chiave API. Per saperne di più, consulta la sezione Guida introduttiva a Gemini Enterprise Agent Platform.

Nei seguenti blocchi di codice, sostituisci PROJECT_ID con il tuo ID progetto.

Installazione

Assicurati di utilizzare l'ultima versione dell'SDK google-genai:

pip install --upgrade google-genai

Richiesta di base

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)

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 modo più dettagliato le seguenti modifiche introdotte in Gemini 3.5 Flash:

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

Nuovo livello di ragionamento predefinito

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

I livelli di ragionamento supportati sono:

• MINIMAL: corrisponde all'impostazione "nessun pensiero" per la maggior parte delle query. Il modello potrebbe pensare in modo molto minimale per attività complesse come la programmazione. Riduce al minimo la latenza per le applicazioni di chat o a throughput elevato.
• LOW: ragionamento leggero per la maggior parte delle attività con alta velocità e costi inferiori.
• MEDIUM: (impostazione predefinita) impostazione bilanciata per la maggior parte delle attività che richiedono ragionamento.
• HIGH: massimizza il ragionamento per ottimizzare il rendimento dell'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 complicati in cui il modello deve ragionare in 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).

Conservazione del ragionamento

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

I pensieri dei turni precedenti ora vengono 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 della conversazione, mantieni la coerenza con i turni precedenti: includi il contesto completo (pensieri, chiamate di funzioni, risposte) o omettilo completamente. Il contesto parziale può peggiorare le prestazioni del modello.

Obsoleto: 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 ottenere 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.

Deprecato: thinking_budget

Il parametro numerico non elaborato thinking_budget non è più supportato in tutti i modelli Gemini 3. Utilizza invece l'enumerazione 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:

• Utilizzare la corrispondenza esatta delle risposte per le chiamate di funzioni
• Includi contenuti multimodali nella risposta della funzione parts
• Utilizzare le istruzioni in linea nella risposta della funzione
• Ridurre le chiamate non necessarie allo strumento

Utilizzare la corrispondenza esatta 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 del FunctionCall corrispondente.
• Corrispondenza name: il valore name nella risposta deve corrispondere al valore name nella chiamata.
• Conteggi delle corrispondenze: restituisce 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

Fornire immagini al di fuori della risposta della funzione può portare a un comportamento imprevisto del modello, come la fuoriuscita di pensieri, e a una qualità inferiore. Segui il consiglio incluso in Introduzione alla chiamata di funzioni e includi contenuti multimodali nelle parti di 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,
            )
        ]),
    ],
)

Utilizzare le istruzioni in linea nella risposta della funzione

Fornire istruzioni per la piattaforma insieme alle risposte delle funzioni come parts successivi può portare a un comportamento imprevisto del modello, come la fuoriuscita di pensieri, e <x0A>a una qualità inferiore. Aggiungilo invece alla fine del testo di 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,
            )
        ]),
    ],
)

Ridurre le chiamate allo strumento non necessarie

Se riscontri un utilizzo eccessivo delle chiamate di strumenti, due tecniche aiutano a ridurle al minimo:

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

2. Aggiungi un'istruzione di sistema: se l'uso eccessivo persiste dopo aver modificato il livello di pensiero, 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.
   

Eseguire 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 API stabilite per tutta 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à per frequenza e presenza: rimuovi eventuali configurazioni personalizzate per le penalità per frequenza o presenza per evitare che le chiamate API generino errori di runtime.
   • Assicurati che l'integrazione della chat non tenti il precompilamento del modello: Rivedi gli array della cronologia dei messaggi per assicurarti che il payload dell'API non termini con un turno utente o 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 ritirato e utilizza thinking_level.
   • Applica convenzioni rigorose per la chiamata di funzioni: il FunctionResponse deve corrispondere esattamente a id, name e al conteggio di esecuzione del 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 turni di lavoro:
   • Se la tua applicazione si basa su cicli conversazionali multi-turno, testa i tuoi flussi di lavoro per assicurarti che la nuova concisione del modello non attivi uscite premature.
   • Se crei agenti di scripting di base o frontend, monitora le chiamate esplorative execute_code non necessarie a causa del nuovo bias del modello verso l'ispezione programmatica iniziale.

Soluzioni alternative per i requisiti del testo pre-strumento

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

• (Consigliato) Indica al modello di inserire le note pre-strumento all'interno di una chiamata di funzione update() dedicata anziché in formato 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 di strumenti.

Soluzione consigliata: racchiudi 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 queste istruzioni aggiornate:

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