Eseguire la migrazione dall'API Gemini 2.5 Flash Live Native Audio a Gemini 3.8 Live

Questo documento descrive le modifiche necessarie per la migrazione dall'audio nativo dell'API Gemini 2.5 Flash Live a Gemini 3.8 Live.

Modifiche alle chiamate di funzione

Il server audio nativo dell'API Gemini 2.5 Flash Live consente chiamate asincrone agli strumenti. Al contrario, Gemini 3.8 Live supporta la chiamata di funzione asincrona con le seguenti modifiche al comportamento:

• Gemini 3.8 Live supporta le chiamate di funzione di blocco quando la dichiarazione della funzione dichiara behavior=BLOCKING nella configurazione. Se viene ricevuto un nuovo input durante l'esecuzione della chiamata di funzione di blocco, il server dell'API Live annulla la chiamata di funzione corrente.

• L'opzione scheduling=interrupt per FunctionResponse ha modificato il comportamento:

  Pianificazione di FunctionResponse	Chi sta parlando	Audio nativo dell'API Gemini 2.5 Flash Live	Gemini 3.8 Live
  interrompi	modello	Interrompe immediatamente la risposta del modello attivo; riproduce la risposta dello strumento.	Interrompe immediatamente la risposta del modello attivo; riproduce la risposta dello strumento.
  interrompi	utente	Interrompe immediatamente; riproduce la risposta dello strumento sopra l'utente.	Attende che l'utente finisca prima di riprodurre la risposta dello strumento.

Mitigazione delle scansioni ridondanti e dei nuovi tentativi di chiamata di funzione

Gemini 3.8 Live a volte effettua chiamate di funzione consecutive ridondanti all'interno di un singolo turno quando uno strumento non restituisce risultati. Ciò può includere la ripetizione di parametri diversi, con una scansione da due a cinque volte, prima di rispondere. Questo comportamento aumenta il tempo al primo audio (TTFA) e produce un parlato di riserva impreciso.

Le chiamate di funzione ridondanti consecutive sono causate dal tentativo di Gemini 3.8 Live di risolvere le query. Quando uno strumento restituisce una risposta non informativa o vuota, come {"results": [], "total_available": 0} o None, il modello non è in grado di distinguere tra "esaurito definitivamente", "finestra di query troppo stretta" o "argomento non valido". Il modello tenta di ampliare o variare la query nel tentativo di migliorare i risultati e inizia la scansione.

Applica le seguenti pratiche complementari:

• Restituisci risposte informative sulle funzioni: ogni risposta dello strumento deve contenere informazioni sull'errore o sui risultati, per guidare il modello Gemini 3.8 Live su come procedere.

  La tabella seguente descrive i casi, il modo in cui il modello deve rispondere e l'esempio di payload richiesto per assistere il modello:

  Richiesta	Cosa deve fare il modello	Contenuto del payload obbligatorio
  Query valida che non restituisce risultati. Riprovare non servirà.	Interrompi la ricerca, informa l'utente e offri alternative.	status: 'no_results', retryable: false, e un messaggio esplicativo chiaro in linguaggio naturale.
  Argomento non valido o inesistente (ad esempio "provider errato").	Interrompi la ricerca e chiedi all'utente di chiarire o confermare.	status: 'invalid_argument', reason_code, retryable: false ed elenco valid_options
  Query valida con una finestra vuota. Una query più ampia è davvero utile.	Esegui un nuovo tentativo ragionevole.	status: 'no_results_in_range', retryable: true e retry_hint

  L'esempio seguente mostra un payload in cui viene chiamato search_appointment, ma tutte le date potenziali non sono disponibili. L'utente si aspetta di provare un fornitore invece di scorrere le date:

  def search_appointment(vendor: str, date: Datetime):
  
  # BEFORE (Invites Sweeping):
  {
    "results": [],
    "total_available": 0
  }
  
  # AFTER - Exhausted / Dead End (Stops Sweeping):
  {
    "results": [],
    "status": "no_availability",
    "retryable": false,
    "message": "No appointments are available for this provider for the foreseeable future. Searching other dates will not surface anything; openings only come from cancellations.",
    "suggested_next_step": "offer_waitlist_or_a_different_provider"
  }
  
  # AFTER - Invalid Argument (Prompts User Clarification):
  {
    "results": [],
    "status": "invalid_argument",
    "reason": "no_such_provider",
    "retryable": false,
    "message": "There is no provider named 'Mr. Johnson'. Ask the caller to confirm the name.",
    "valid_options": ["Dr. Johnson", "Dr. Chen"]
  }
  

  L'esempio seguente mostra la gestione quando check_user_account non restituisce corrispondenze esatte. Il risultato previsto è la modifica della query di ricerca o il trasferimento del controllo all'utente anziché riprovare:

  def check_user_account(user_name: str, phone_suffix: str):...
  
  # Checked user account but not existing
  # BEFORE: insufficient error information
  {
   "found": false,
   "matches": []
  }
  
  # AFTER: providing sufficient information to the LiveAPI to avoid further retries because the retries have been exhausted.
  {
   "status": "EXHAUSTED",
   "retryable": false,
   "search_criteria": {
     "name": "Alex Rivera",
     "phone_suffix": "4921"
   },
   "search_scope": "Checked active orders, archived accounts, and guest checkouts across all regions.",
   "guidance": "Exhaustive search completed with 0 matches. Do NOT retry with parameter substrings or variations. Inform the user that no account was found matching those details, and ask if they have an Order ID or billing email."
  }
  

• Policy di ripetizione dei tentativi per le istruzioni di sistema: integra le risposte informative con un vincolo esplicito nell'istruzione di sistema:

  "When a tool returns no results, tell the user the result before calling the
  tool again. If a call fails for a reason fundamental to the arguments (for
  example, the entity does not exist), do not silently retry with variations;
  ask the user to clarify or confirm. You may broaden a query once when a
  result set is simply empty. Do not run repeated searches with different
  parameters on your own initiative. Hard cap: Never issue more than two
  consecutive function calls without saying something back to the user."
  

Scambio della cronologia delle sessioni

In Gemini 2.5 Flash Live API Native Audio, send_client_content viene utilizzato per configurare il seeding della cronologia prima del primo turno e per aggiungere cronologia aggiuntiva durante la sessione.

In Gemini 3.8 Live, se vuoi utilizzare il metodo send_client_content per configurare il seeding della cronologia, nella sezione HistoryConfig del messaggio di configurazione, imposta initial_history_in_client_content=True. Dopo aver ricevuto setup_complete. Puoi quindi chiamare send_client_content ripetutamente per creare la cronologia fino all'ultimo messaggio in cui è impostato turn_complete=True.

Aggiornamenti degli strumenti e delle istruzioni di sistema durante la sessione

In Gemini 2.5 Flash Live API Native Audio, aggiorni le istruzioni di sistema durante una sessione inviando i contenuti del client con il ruolo system.

In Gemini 3.8 Live, chiama send_context_update nell'SDK Google Gen AI o invia un messaggio context_update tramite WebSocket. Può sostituire l'istruzione di sistema, l'elenco degli strumenti o entrambi. Per i dettagli, consulta Aggiorna le istruzioni di sistema e gli strumenti con Gemini 3.8 Live.

Differenze di comportamento del modello

La seguente tabella descrive le differenze di comportamento del modello per audio, multimodale e output tra l'API Gemini 2.5 Flash Live Native Audio e Gemini 3.8 Live:

Il seguente codice Python mostra l'impostazione di media_resolution e custom_vocabulary:

# Example: Setting media_resolution for image frames in Gemini 3.8 Live
from google import genai
from google.genai import types

client = genai.Client()

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW,  # or MEDIA_RESOLUTION_LOW or MEDIA_RESOLUTION_MEDIUM
)

async with client.aio.live.connect(
    model="gemini-3.8-live",
    config=config,
) as session:
    # Send image frames with the configured resolution budget
    ...


# Example: Setting custom_vocabulary for domain-specific word biasing in Gemini 3.8 Live
from google import genai
from google.genai import types

client = genai.Client()

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    input_audio_transcription=types.AudioTranscriptionConfig(
        custom_vocabulary=["Gemini", "MagicWord", "Lagrangian"],
    ),
)

async with client.aio.live.connect(
    model="gemini-3.8-live",
    config=config,
) as session:
    ...

Compatibilità con framework di terze parti

Le sezioni seguenti descrivono il funzionamento dei framework di terze parti con Gemini 3.8 Live:

LiveKit

Il plug-in Google RealtimeModel di LiveKit supporta Gemini 3.8 Live, ma le seguenti impostazioni non sono supportate nel plug-in Google di LiveKit:

• thinking_level
• enable_affective_dialog
• proactivity

Ti consigliamo di prestare particolare attenzione quando utilizzi il plug-in Google di LiveKit, perché richiede un adattamento accurato per funzionare con Gemini 3.8 Live.

Pipecat

Pipecat supporta Gemini 3.8 Live, con le seguenti modifiche:

• Configurazione del ragionamento: rimuovi il livello di ragionamento, poiché non è supportato da Gemini 3.8 Live.

• Pipecat connette gli endpoint di Agent Platform utilizzando GoogleVertexLLMService tramite il connettore GeminiLiveLLMService.

Telemetria dell'utilizzo dei token a livello di rete

Ogni turno del server restituisce un frame usage_metadata. Questo vale per l'API Gemini 2.5 Flash Live Native Audio e Gemini 3.8 Live. I metadati di utilizzo sono più categorizzati, ad esempio token memorizzati nella cache, token di utilizzo degli strumenti, token in diverse modalità e così via.

Limitazioni e mitigazioni note del modello

Per informazioni sulle limitazioni e sulle mitigazioni note durante lo sviluppo di applicazioni con Gemini 3.8 Live, consulta Limitazioni note.

Elenco di controllo per la migrazione

Di seguito è riportato un elenco di controllo per la migrazione dei client che puoi utilizzare durante la migrazione da Gemini 2.5 Flash Live API Native Audio a Gemini 3.8 Live:

• Chiamata di funzione:

  • Risposte informative degli strumenti: rifattorizza tutti i gestori degli strumenti per restituire codici di stato espliciti, flag di ripetizione e spiegazioni in linguaggio naturale. Non restituire mai None vuoti o {} vuoti.

  • Policy delle istruzioni di sistema: aggiungi vincoli espliciti che vietano i nuovi tentativi silenziosi degli strumenti, richiedono la conferma dell'utente in caso di errori degli argomenti e limitano le chiamate consecutive degli strumenti.

  • Corrispondenza dell'ID della chiamata allo strumento: assicurati che FunctionResponse passi id=fc.id in ogni risposta dello strumento.

  • Modifica del comportamento di pianificazione delle funzioni: quando l'utente parla, scheduling=interrupt esegue il downgrade a scheduling=when_idle per offrire un'esperienza utente più fluida.

• Sessione: limita send_client_content: utilizza send_client_content per impostare la cronologia iniziale fornendo un HistoryConfig sensato.

• Sessione: aggiorna il contesto con context_update: sostituisci gli aggiornamenti delle istruzioni di sistema in sessione che utilizzano il ruolo system con chiamate send_context_update nell'SDK Google Gen AI o messaggi context_update su WebSocket.

• Ragionamento: elimina i trucchi di ragionamento a livello di prompt: per evitare interruzioni dell'audio, rimuovi tutto il testo del prompt che tenta di applicare schemi di ragionamento passo passo o limiti di token.