Guida introduttiva alla Gemini Live API

Se hai mai provato a creare un assistente vocale, saprai quanto può essere macchinosa la pipeline tradizionale. Registri la voce dell’utente, la trascrivi con un modello STT, invii quel testo a un LLM, aspetti una risposta e poi la fai passare da un motore TTS. 

Quando l’utente sente la risposta, sono già passati diversi secondi di silenzio imbarazzante. È meno una conversazione e più un lento ciclo richiesta-risposta. 

La Gemini Live API cambia questo flusso permettendoti di trasmettere audio e video in continuo su una connessione WebSocket con stato. Poiché il modello elabora e genera audio in modo nativo, può reagire immediatamente, adattarsi alle sfumature vocali naturali e persino gestire interruzioni (barge-in) a frase in corso. 

In questo tutorial, ti mostrerò come creare un Real-Time AI Travel Concierge usando il Google Agent Development Kit (ADK) orientato al codice. Doteremo il nostro agente di Google Search per il meteo in tempo reale delle destinazioni, lo collegheremo a un database di voli fittizio e avvieremo un’interfaccia locale per sviluppatori per testare come gestisce dialoghi in tempo reale e chiamate agli strumenti.

Se sei nuovo dell’ecosistema, ti consiglio di iniziare dal corso Building AI Agents with Google ADK per stabilire le basi.

Cosa riuscirai a fare: 

• Capire il funzionamento interno, le capacità e i prezzi della Gemini Live API.
• Configurare un ambiente Python con il Google Agent Development Kit. 
• Esporre sia strumenti integrati (Google Search) sia logica personalizzata (query a un database sullo stato dei voli) all’assistente vocale. 
• Avviare una web UI locale per parlare in diretta con il tuo agente di viaggio.

Prerequisiti: 

• Conoscenza di base di Python. 
• Un progetto Google Cloud (per l’accesso a Vertex AI) o una chiave API di Google AI Studio.

Che cos’è la Gemini Live API? 

Alla base, la Gemini Live API è uno strumento per sviluppatori di Google che ti permette di creare interazioni in tempo reale vocali e visive con i modelli Gemini. Invece di attendere risposte testuali a turni, abilita una conversazione continua e naturale tra un utente e un agente AI. 

Tecnicamente, la Gemini Live API è progettata per lo streaming bidirezionale in tempo reale. A differenza delle API REST HTTP standard che usano cicli request-response senza stato, la Live API si basa su una connessione WebSocket (WSS) con stato e persistente. Attraverso questo canale aperto, il client trasmette audio grezzo, video (inviato come frame a ~1 FPS) e testo, mentre il modello restituisce immediatamente audio e testo nativi in streaming.

Funzionalità chiave di Gemini Live

• Barge-in (Interrompibilità): In una conversazione naturale, non aspettiamo che l’altra persona finisca un intero paragrafo prima di intervenire per chiarire. Gemini Live supporta il barge-in nativamente: gli utenti possono interrompere la voce del modello a frase in corso e il server interrompe subito lo streaming audio adattandosi al nuovo input.
• Dialogo affettivo e audio nativo: invece di generare testo e passarlo a un motore Text-to-Speech (TTS), modelli come gemini-live-2.5-flash-native-audio e gemini-3.1-flash-live-preview elaborano e generano audio nativamente. Questo preserva sfumature emotive, risate, adattamento del tono e ritmo del parlato, rendendo le interazioni più umane. 
• Input multimodali e uso di strumenti: la Live API non è limitata all’audio. Può “vedere” l’ambiente tramite frame video e attivare funzioni o strumenti esterni (come Google Search o API personalizzate) in tempo reale, reinserendo i risultati nel flusso vocale.

Prezzi della Gemini Live API

Poiché lo streaming in tempo reale implica una connessione continua full-duplex, il modello di fatturazione differisce dalle API testuali statiche standard. Google offre sia un livello gratuito generoso per prototipazione in Google AI Studio sia un livello a pagamento pronto per la produzione su Vertex AI. 

Il modello gemini-3.1-flash-live-preview è fatturato per milione di token o convertito 

direttamente in una metrica basata sulla durata per contenuti audio e video:

Se stai prototipando, ti consiglio vivamente di testare gratuitamente in Google AI Studio, che offre accesso generoso soggetto a limitazioni di rate. 

Quando sei pronto a scalare, puoi migrare il progetto su Vertex AI per un provisioning in produzione a consumo (Pay-as-you-go), con throughput garantito e SLA di livello enterprise.

Come accedere alla Gemini Live API

Come sviluppatore, hai alcune scelte architetturali nell’implementare la Live API. Poiché si basa su WebSocket, il modo in cui instradi la connessione incide su latenza e sicurezza.

Client-to-server vs server-to-server

• Client-to-server: il tuo frontend (ad esempio, un’app web o mobile) si connette direttamente all’endpoint WebSocket di Google. È l’approccio migliore per ridurre la latenza al minimo, perché lo stream audio non fa salti aggiuntivi. 
• Tuttavia, non puoi esporre le chiavi API raw di Google Cloud in un client frontend; devi implementare un flusso di autenticazione che generi token temporanei ed effimeri per un accesso client sicuro.
• Server-to-server: il tuo frontend trasmette audio al tuo backend, che poi apre il WebSocket verso la Gemini Live API. È molto sicuro e ti consente di inserire logica backend (come autenticazione utente o query al database), ma aggiunge un leggero ritardo di rete allo stream audio.

SDK e integrazioni dei partner

Pur potendo scrivere codice WebSocket raw, il modo più semplice per iniziare è usare il GenAI SDK di Google o l’Agent Development Kit (ADK). 

Per l’ambiente enterprise in produzione, l’ecosistema si è evoluto rapidamente per supportare integrazioni WebRTC. Piattaforme come LiveKit, Pipecat by Daily, Twilio e Voximplant offrono infrastrutture robuste per gestire jitter di rete, cancellazione dell’eco e instradamento audio in tempo reale direttamente verso la Gemini Live API.

Creare un assistente vocale in tempo reale con la Gemini Live API

Mettiamo in pratica. Andremo a creare un AI Travel Concierge. 

Questo agente userà la Gemini Live API per conversare con gli utenti via voce, ma soprattutto avrà accesso a funzioni Python personalizzate per consultare in tempo reale lo stato dei voli durante la conversazione.

Useremo il Google Agent Development Kit (ADK) e il potente modello gemini-3.1-flash-live-preview, ottimizzato sia per turni testuali standard sia per streaming WebSocket in tempo reale.

1. Configurazione dell’ambiente

Per prima cosa, devi creare un ambiente virtuale Python e installare il pacchetto ADK richiesto. Esegui questi comandi nel terminale:

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install the Agent Development Kit
pip install google-adkOfferto da

Poi configura le variabili d’ambiente in modo che l’ADK possa autenticarsi in modo sicuro con il tuo progetto Google Cloud:

export GOOGLE_CLOUD_PROJECT="your-project-id" 
export GOOGLE_CLOUD_LOCATION="us-central1"Offerto da

Se invece stai usando una Gemini API Key di Google AI Studio, crea un file .env nella cartella radice:

GEMINI_API_KEY=your_google_ai_studio_api_keyOfferto da

2. Inizializzare l’agente Gemini Live 

Crea un file chiamato agent.py nella directory del progetto. L’ADK è progettato per rilevare automaticamente ed eseguire la variabile root_agent. In questo codice, definiremo una funzione Python personalizzata per verificare lo stato dei voli e la passeremo direttamente nella toolbelt dell’agente. Inizializza la directory dell’agente: 

mkdir voice_assistant 
touch voice_assistant/__init__.py 
touch voice_assistant/agent.pyOfferto da

Esponi il pacchetto dell’agente dentro voice_assistant/__init__.py:

from . import agentOfferto da

3. Definire l’agente ed esporre strumenti personalizzati 

Apri voice_assistant/agent.py e scrivi la configurazione dell’agente di viaggio. Nel codice seguente, definiamo una funzione Python standard check_flight_status. 

In Google ADK, qualsiasi funzione Python con type hint corretti e una docstring viene convertita automaticamente in uno strumento dell’agente. L’LLM usa la descrizione nella docstring e i parametri per decidere quando e come chiamare la funzione. 

Configurazione del modello 

Sfruttare Gemini 3.1 Flash Live Preview Per supportare entrambe le modalità di interazione nel server di sviluppo ADK—chat testuale standard (che usa gli endpoint REST generateContent) e l’interfaccia microfono WebSocket bidirezionale in tempo reale—impostiamo esplicitamente il modello su gemini-3.1-flash-live-preview.

A differenza dei modelli solo streaming più vecchi, che restituiscono 404 Not Found quando attivati su richieste HTTP REST standard, gemini-3.1-flash-live-preview supporta nativamente sia la generazione di contenuti REST standard sia lo streaming WebSocket con stato.

from google.adk.agents.llm_agent import Agent
from google.adk.tools import google_search
def check_flight_status(flight_no: str) -> str:
   """Check the real-time flight status (e.g. delays, gate info, cancellations).
   Args:
       flight_no: The flight number to look up (e.g., AA120, DL450, UA990).
   """
   flight_no = flight_no.upper().strip()
   if "AA120" in flight_no:
       return "Flight AA120 to Paris is currently delayed by 45 minutes due to air traffic control. New departure time: 3:15 PM. Gate status: B22."
   elif "DL450" in flight_no:
       return "Flight DL450 to London is on time. Gate status: Boarding now at Gate C10."
   elif "UA990" in flight_no:
       return "Flight UA990 to Tokyo is cancelled due to adverse weather conditions at the destination. Passengers are advised to rebook at the counter."
   else:
       return f"Flight {flight_no} is currently scheduled on time. No delay reports found in the flight database."
# Define the root agent with search grounding and custom database flight checks
root_agent = Agent(
   model='gemini-3.1-flash-live-preview',
   name='root_agent',
   description='A real-time AI Travel Concierge with flight tracking and search grounding.',
   instruction=(
       'You are an expert AI Travel Concierge. You assist users with real-time flight status checkups, '
       'destination recommendations, and general travel planning. '
       'Always answer professionally and conversationally. '
       'Use the check_flight_status tool when a user asks about a specific flight status. '
       'Use Google Search to look up weather, transit conditions, or travel advisories at destinations.'
   ),
   tools=[google_search, check_flight_status],
)Offerto da

4. Avviare e testare la dev UI interattiva

L’ADK include un server di sviluppo e una Web UI integrati. Questo ti permette di testare l’agente in locale senza scrivere codice frontend. Avvia il server web dalla tua workspace:

.venv/bin/adk web .Offerto da

Dovresti vedere un output che indica l’avvio del server:

1. Apri http://127.0.0.1:8000 nel browser.
2. Seleziona il tuo agente dall’elenco applicazioni.
3. Clicca sul pulsante Microfono per avviare una sessione live.

Seleziona root_agent dall’elenco applicazioni per aprire l’interfaccia chat.

4. Parla al microfono: Puoi controllare lo stato del volo AA120? L’agente analizzerà la richiesta, riconoscerà che servono informazioni dal database, attiverà la funzione Python personalizzata check_flight_status e mostrerà l’esito della chiamata allo strumento in JSON prima di risponderti a voce.

5. Test del Google Search Grounding:  Ora chiedi al concierge una domanda sul meteo della destinazione: Che tempo c’è a Londra in questo momento? L’agente attiverà lo strumento integrato google_search, esplorerà il web e sintetizzerà le condizioni live nell’output audio.

6. Test della funzione Barge-in: fai una domanda ampia come: Traccontami dei migliori siti storici da visitare a Roma. Quando l’agente inizia a elencare i luoghi, parlaci sopra a voce alta: Aspetta, anzi! Controlla il volo UA990!. L’agente interromperà immediatamente lo stream vocale, troncherà i dettagli su Roma, eseguirà lo strumento personalizzato di tracciamento voli e annuncerà che il volo UA990 è stato cancellato. Questo dimostra la natura a bassa latenza e full-duplex della connessione Live API.

Best practice per la produzione con Gemini Live API

Creare applicazioni vocali in tempo reale introduce requisiti specifici relativi a architettura dei prompt, gestione dello stato di rete, acquisizione audio e scaling delle risorse. Di seguito alcune best practice chiave derivate dalle linee guida ufficiali per sviluppatori.

1. Progettare istruzioni di sistema chiare

Per ottenere le migliori performance da Gemini Live, struttura le tue system instructions (SI) in una gerarchia rigorosa: Persona, Regole conversazionali e Guardrail.

• Personas separate: limita il ruolo di ciascun agente a una singola istruzione di sistema distinta, invece di sovraccaricare un agente con più personas.
• Delinea i flussi di conversazione: separa esplicitamente gli elementi una tantum (es. "chiedi all’utente nome e numero del biglietto una sola volta") dai loop conversazionali aperti (es. "rispondi alle domande sui consigli di viaggio finché desidera").
• Scrivi le invocazioni degli strumenti in frasi: descrivi l’uso degli strumenti in sequenza. Ad esempio: 'Per prima cosa, chiedi all’utente di fornire il numero del biglietto. Poi invoca look_up_ticket con questo numero.'
• Imponi coerenza linguistica: i modelli audio nativi possono cambiare lingua se cambia il contesto. Se il tuo agente è solo in inglese, imponilo nell’istruzione: RESPOND IN English. YOU MUST RESPOND UNMISTAKABLY IN English.

2. Definizioni degli strumenti e condizioni di invocazione precise

Quando esponi strumenti alla Live API:

• Includi sempre annotazioni di tipo e descrizioni dettagliate dei parametri.
• Documenta esplicitamente le Condizioni di Invocazione all’interno dei metadati dello strumento (es. "Invoca questo strumento solo dopo che l’utente ha confermato data di partenza e destinazione"). Ciò evita che l’LLM attivi funzioni prematuramente.

3. Gestire il contesto audio nativo (Compressione)

I token audio nativi si accumulano rapidamente, circa 25 token al secondo di conversazione. Per sessioni vocali lunghe, questo può riempire velocemente la finestra di contesto e aumentare la latenza.

• Abilita ContextWindowCompressionConfig nelle impostazioni di connessione per eliminare la cronologia più vecchia una volta superata una soglia:

from google.genai import types
live_config = types.LiveConnectConfig(
   context_window_compression=types.ContextWindowCompressionConfig(
       trigger_tokens=100_000,
       sliding_window=types.SlidingWindow(target_tokens=4_000),
   ),
)Offerto da

Nota: la compressione del contesto comporterà la perdita della cronologia di conversazione più vecchia.

4. Ripresa di sessione trasparente

Le connessioni mobili in tempo reale sono soggette a perdita di pacchetti e disconnessioni temporanee. Invece di ricominciare da zero con un nuovo stato di conversazione, implementa la ripresa di sessione trasparente:

• Configura lo stream con SessionResumptionConfig(transparent=True).
• Ascolta gli eventi session_resumption_update dal server e salva il new_handle.
• Mantieni un buffer locale dei messaggi in uscita. Quando la connessione cade, intercetta l’APIError o il segnale GoAway, riconnettiti usando l’handle salvato e riproduci solo i messaggi client non riconosciuti (usando il server-reported last_consumed_client_message_index per potare il buffer).

5. Ottimizzazione dello streaming audio

• Buffering lato client: non bufferizzare frame audio lunghi sul client prima dell’invio. Trasmetti piccoli chunk audio (tra 20 ms e 40 ms) in continuo per minimizzare la latenza end-to-end.
• Ricampionamento del microfono: assicurati che l’acquisizione audio lato client ricampioni gli input (tipicamente 44,1 kHz o 48 kHz) a 16 kHz PCM prima dell’invio via WebSocket.
• Segnali VAD espliciti: lascia che il modello gestisca la Voice Activity Detection (VAD). Se il tuo frontend deve mostrare indicatori UI immediati (es. "L’AI sta ascoltando" vs "L’AI sta pensando"), abilita explicit_vad_signal=True nella configurazione per ricevere eventi VAD start/stop direttamente nel flusso di messaggi del server.

6. Sicurezza (gestione dei token)

• Non hardcodare mai le chiavi master: evita di esporre la tua chiave API di AI Studio o le credenziali del Service Account di Google Cloud nel codice lato client (browser o app mobile).
• Implementa uno scambio di token effimeri: costruisci un endpoint di autenticazione sul tuo backend sicuro. Quando un client vuole avviare una sessione vocale, il backend genera un token di accesso OAuth o API a breve durata e con permessi limitati (ad es. tramite Vertex AI IAM) e lo passa al client. Il client usa questa credenziale temporanea per aprire la connessione WebSocket diretta.

Conclusione: l’orizzonte della Conversational AI

Il passaggio da LLM solo testuali e a turni a streaming multimodale a bassa latenza rappresenta un cambio di paradigma nel modo in cui costruiamo interfacce uomo-macchina. Elaborando audio e video nativamente tramite connessioni WebSocket con stato, la Gemini Live API ci permette di creare esperienze agentiche che somigliano meno a programmi statici e più a interazioni umane fluide.

In questa guida, abbiamo esplorato l’architettura interna di Gemini Live, analizzato i modelli di prezzo e creato un AI Travel Concierge pienamente funzionante utilizzando il Google Agent Development Kit (ADK). Abbiamo visto come l’ADK mappi funzioni Python standard in strumenti attivi dell’agente, dando al nostro assistente vocale accesso sia al grounding su web ampio sia a query su database interni privati.

Cosa costruire dopo? 

Ora che hai acquisito le basi degli agenti vocali in tempo reale, valuta di estendere il tuo AI Travel Concierge: 

1. Esporre stream video live: aggiungi il supporto alla trasmissione di immagini dalla fotocamera per permettere al concierge di “vedere” mappe, carte d’imbarco o voucher fisici in tempo reale. 
2. Integrare strumenti transazionali personalizzati: implementa uno strumento book_flight o reserve_hotel che modifica lo stato reale, integrando ambiti di autenticazione per conferme utente sicure. 
3. Instradamento middleware di produzione: passa dai test locali con ADK a un framework basato su WebRTC usando LiveKit o Pipecat per trasmettere chiamate vocali di produzione direttamente da app web e mobile.

Pronto a costruire flussi conversazionali più avanzati? Dai un’occhiata al percorso di competenze AI Agent Fundamentals di DataCamp per approfondire architetture agentiche, uso degli strumenti e deployment di AI generativa.