Grok Voice Agent API: un modo per creare assistenti vocali in tempo reale

Gli agenti vocali di AI sono sotto i riflettori. Gli utenti vogliono parlare con le app invece di digitare, e la tecnologia è finalmente abbastanza matura da rendere naturali quelle conversazioni.

Se vuoi crearne uno, la Grok Voice Agent API di xAI è un ottimo punto di partenza. Offre tempi di risposta sotto il secondo e costi inferiori rispetto a molte alternative, oltre alla compatibilità immediata con il codice OpenAI esistente.

Questo tutorial ti mostra come costruire da zero un agente vocale funzionante. Configurerai l'autenticazione, imposterai personalità e opzioni vocali, aggiungerai il tool calling e distribuirai in produzione con LiveKit Cloud. L'API gira su Grok 3, che xAI ha adattato per la conversazione vocale in tempo reale invece del consueto flusso di lavoro testo in ingresso, testo in uscita.

Che cos'è la Grok Voice Agent API?

La Grok Voice Agent API è la piattaforma di conversazione vocale in tempo reale di xAI, rilasciata a dicembre 2025. Elabora direttamente l'audio senza la consueta conversione tra speech-to-text e viceversa, riducendo i tempi di risposta e mantenendo un suono naturale nelle conversazioni.

I sistemi vocali tradizionali concatenano tre passaggi distinti: trascrivere il parlato in testo, far passare quel testo attraverso un modello linguistico, quindi sintetizzare la risposta di nuovo in audio. Questo approccio funziona, ma ogni passaggio tra i componenti aggiunge ritardo. Considerando trascrizione, elaborazione e sintesi, servono tra 500 ms e 1.000 ms prima che l'utente riceva una risposta. Queste pause si sommano e rendono le conversazioni meccaniche.

Grok Voice Agent salta del tutto le conversioni. Il sistema riceve audio, ragiona nel dominio audio e produce audio usando un unico modello addestrato sul parlato conversazionale. Questa architettura offre un time-to-first-audio medio di 0,78 secondi supportando al contempo la comunicazione full-duplex (audio bidirezionale simultaneo in cui l'agente può ascoltare e parlare nello stesso momento), così l'agente può rispondere senza attendere rigidi turni di parola.

Configurare l'ambiente per il tuo Grok Voice Agent

Per creare un agente vocale con Grok serve affiancarlo a LiveKit, una piattaforma WebRTC open-source. Grok fornisce il modello di AI conversazionale, mentre LiveKit gestisce l'infrastruttura audio in tempo reale che collega gli utenti al tuo agente. In questa sezione vediamo come configurare entrambi i servizi.

Configurare Grok

Visita console.x.ai e crea un account usando X, email, Google o Apple. La console di xAI richiede crediti prepagati prima di poter effettuare chiamate API. Acquista crediti dalla sezione Billing.

Con i crediti sul tuo account, vai su API Keys e genera una nuova chiave. La console mostra la chiave una sola volta, quindi copiala subito e conservala in modo sicuro. Se la perdi, dovrai generare una sostituta e aggiornare le tue applicazioni. Per una guida più dettagliata all'ecosistema API di xAI, vedi il tutorial sull'API Grok 3.

Configurare LiveKit

LiveKit è un'infrastruttura WebRTC per audio e video in tempo reale. Gestisce il livello di trasporto audio di cui Grok ha bisogno per connettersi con gli utenti. Quando crei un agente vocale, LiveKit gestisce le room in cui avvengono le conversazioni, instrada i flussi audio tra i partecipanti e fornisce l'infrastruttura di deployment. Il framework LiveKit Agents incapsula questa complessità, permettendoti di concentrarti sul comportamento dell'agente mentre si occupa di gestione delle connessioni, codifica audio e rilevamento dei turni.

Il framework supporta diversi provider di AI, compreso xAI. Include un playground di test accessibile via interfaccia web, che userai per validare il tuo agente prima del deployment.

Registrati su cloud.livekit.io. Il piano gratuito offre risorse sufficienti per sviluppo e test. Crea un progetto dalla dashboard. Vai su Settings, poi API Keys. Copia tre credenziali: LIVEKIT_URL (l'endpoint WebSocket del tuo progetto), LIVEKIT_API_KEY (l'identificatore pubblico) e LIVEKIT_API_SECRET (la chiave privata di autenticazione). Queste credenziali autenticano il codice del tuo agente con il progetto LiveKit Cloud.

Installare dipendenze e configurazione

Installa i pacchetti richiesti:

uv add "livekit-agents[xai,openai]>=1.3.10" python-dotenv

Questo installa il framework LiveKit Agents con sia il plugin xAI sia le dipendenze OpenAI (il plugin xAI si basa sulla compatibilità con la Realtime API di OpenAI), più python-dotenv per la gestione delle variabili d'ambiente.

Crea un file .env nella root del progetto:

XAI_API_KEY=xai-YourActualKeyHere
 LIVEKIT_URL=wss://your-project.livekit.cloud
 LIVEKIT_API_KEY=APIYourKeyHere
 LIVEKIT_API_SECRET=YourSecretHere

Sostituisci i segnaposto con le tue credenziali reali. Carica queste credenziali nel tuo codice Python:

from dotenv import load_dotenv
 load_dotenv()

In questo modo le credenziali sono disponibili sia per le librerie xAI sia per LiveKit. Aggiungi .env al tuo .gitignore per evitare perdite di credenziali nel controllo versione.

Creare il tuo primo Grok Voice Agent

Con l'ambiente configurato, puoi creare un agente vocale funzionante. Inizia con gli import e la classe dell'agente in un nuovo file chiamato agent.py:

from livekit.agents import Agent, AgentSession, AgentServer, JobContext, cli
from livekit.plugins.xai import realtime
from dotenv import load_dotenv

load_dotenv()

class ResearchAssistant(Agent):
	def __init__(self):
    	super().__init__(
        	instructions="You are a research assistant who helps users find information.",
 	)

La tua sottoclasse di Agent contiene solo le istruzioni che definiscono come l'agente risponde. Funzionano come un prompt di sistema, dicendo all'agente che ruolo interpretare. La configurazione del modello sta altrove.

Poi, imposta il server e l'handler di connessione:

server = AgentServer()


@server.rtc_session()
async def entrypoint(ctx: JobContext):
	await ctx.connect()

 	session = AgentSession(
         llm=realtime.RealtimeModel(voice="ara"),
 	)

 	await session.start(
     	room=ctx.room,
     	agent=ResearchAssistant(),
 	)

Il decorator @server.rtc_session() dice a LiveKit di eseguire la tua funzione entrypoint ogni volta che qualcuno si connette. All'interno, AgentSession riceve la configurazione del modello, incluso quale delle sette voci di Grok usare (Ara, Eve, Leo, Sal, Rex, Mika o Valentin). Quando session.start() viene eseguito, collega il tuo agente alla room di LiveKit in cui avviene la conversazione.

Le conversazioni vocali richiedono di attendere input e output audio senza bloccare il programma, quindi la funzione usa async def e await per gestire queste operazioni in modo concorrente.

Infine, aggiungi il punto di ingresso:

if __name__ == "__main__":
 	cli.run_app(server)

Esegui il tuo agente in modalità sviluppo:

uv run agent.py dev

Il terminale mostra la sequenza di avvio: inizializzazione del worker, server HTTP in ascolto su una porta locale e registrazione con il tuo progetto LiveKit Cloud.

Per testare l'agente, vai alla dashboard di LiveKit Cloud su cloud.livekit.io. Seleziona il tuo progetto, poi fai clic sulla scheda Sandbox nella sidebar. Scegli Web Voice Agent tra i template.

La pagina del template mostra un'anteprima dell'interfaccia vocale insieme ai dettagli su cosa include. Clicca sul pulsante Create sandbox.

Nel modale che appare, puoi configurare un URL personalizzato, abilitare funzionalità come fotocamera e condivisione schermo e regolare le impostazioni di aspetto. I valori predefiniti vanno bene per i test, quindi clicca Create, poi Done.

Tornando alla pagina Sandbox, il tuo nuovo sandbox appare sotto Sandbox apps. Clicca Launch per aprirlo.

Clicca Start Call e concedi i permessi al microfono quando richiesto. Guarda il terminale per questo messaggio di log, che indica che l'agente è pronto a ricevere audio:

DEBUG livekit.agents start reading stream {"participant": "...", "source": "SOURCE_MICROPHONE", ...}

Dopo la comparsa di questo messaggio, le risposte arrivano velocemente.

Quando chiedi qualcosa a cui l'agente non può accedere (come il meteo attuale in una città specifica), spiega i suoi limiti invece di inventare risposte.

Come aggiungere strumenti ai tuoi Grok Voice Agent

L'agente di base può sostenere una conversazione ma non può cercare informazioni. Il tool calling permette a Grok di eseguire funzioni durante la conversazione e parlare dei risultati. Puoi usare gli strumenti integrati di xAI o definirne di tuoi.

Usare gli strumenti integrati

Il plugin xAI include WebSearch per ricerche web generiche e XSearch per cercare post su X. Importali e passali a AgentSession:

from livekit.agents import Agent, AgentSession, AgentServer, JobContext, cli
from livekit.plugins.xai import realtime
from livekit.plugins.xai.realtime import WebSearch, XSearch
from dotenv import load_dotenv

load_dotenv()


class ResearchAssistant(Agent):
 	def __init__(self):
     	super().__init__(
             instructions="""You are a research assistant with access to web search and X search.

- Use web search for general queries and current information
- Use X search when users ask about posts or what people are saying on X/Twitter

Always mention your sources when providing information.""",
     	)


server = AgentServer()


@server.rtc_session()
async def entrypoint(ctx: JobContext):
	await ctx.connect()

	session = AgentSession(
         llm=realtime.RealtimeModel(voice="ara"),
     	tools=[
         	WebSearch(),
         	XSearch(),
     	],
 	)

 	await session.start(
     	room=ctx.room,
     	agent=ResearchAssistant(),
 	)


if __name__ == "__main__":
 	cli.run_app(server)

Il parametro tools accetta una lista di oggetti strumento. Esegui l'agente e testa con domande come "Quali sono le ultime notizie sull'AI?" o "Cosa si dice di Grok su X?" I log a terminale possono mostrare avvisi su funzioni di AI sconosciute come web_search_with_snippets o x_semantic_search, ma gli strumenti restituiscono comunque informazioni aggiornate.

L'audio full-duplex di Grok diventa evidente anche usando gli strumenti. Puoi interrompere l'agente mentre parla: si ferma, ascolta e adatta la risposta. Questo rende le conversazioni meno robotiche rispetto ai sistemi che impongono di aspettare la fine della risposta.

Aggiungere strumenti personalizzati

Gli strumenti integrati coprono casi d'uso comuni, ma definire strumenti personalizzati ti dà controllo su parametri, gestione degli errori e API da chiamare. Questa sezione mostra la creazione di strumenti personalizzati usando l' endpoint di ricerca di Firecrawl, che offre opzioni di filtro come limit, lang e country non esposte dalla ricerca web integrata.

Registrati su firecrawl.dev. Il piano gratuito include 500 crediti e non richiede carta di credito. Installa l'SDK e aggiungi la tua chiave al file .env:

uv add firecrawl-py

FIRECRAWL_API_KEY=fc-your-key-here

Gli strumenti personalizzati sono metodi decorati con @function_tool(). Aggiorna gli import in search_agent.py:

from livekit.agents import (
 	Agent,
 	AgentSession,
 	AgentServer,
 	JobContext,
 	cli,
 	function_tool,
 	RunContext,
 )

from livekit.plugins.xai import realtime
from livekit.plugins.xai.realtime import XSearch
from firecrawl import FirecrawlApp
from dotenv import load_dotenv

import os 
load_dotenv()

Le aggiunte sono function_tool per il decorator, RunContext che viene passato alle funzioni strumento, e FirecrawlApp per il client Firecrawl. WebSearch viene rimosso perché sostituito dallo strumento personalizzato.

Definisci lo strumento come metodo nella tua classe agente:

class ResearchAssistant(Agent):
 	def __init__(self):
     	super().__init__(
             instructions="""You are a research assistant with access to web search and X search.

 - Use Firecrawl search for general queries and current information
 - Use X search when users ask about posts or what people are saying on X/Twitter

 Always mention your sources when providing information.""",
     	)
     	self.firecrawl = FirecrawlApp(api_key=os.getenv("FIRECRAWL_API_KEY"))

 	@function_tool()
     async def search_web(
     	self,
     	context: RunContext,
     	query: str,
 	) -> dict:
     	"""Search the web for current information using Firecrawl.

     	Args:
         	query: The search query
     	"""
     	result = self.firecrawl.search(query, limit=3)
     	return {
         	"results": [
             	{
                 	"title": item.title,
                 	"url": item.url,
                     "description": item.description,
             	}
             	for item in result.web
         	]
     	}

Grok legge la docstring per capire cosa fa lo strumento. Quando chiedi "Qual è il tasso di cambio attuale USD/EURO?", Grok estrae la query, chiama la tua funzione e integra i risultati nella risposta.

I metodi decorati con @function_tool() si registrano automaticamente, quindi rimuovi WebSearch() dalla lista degli strumenti:

session = AgentSession(
     llm=realtime.RealtimeModel(voice="ara"),
 	tools=[
     	XSearch(),
 	],
 )

Esegui l'agente aggiornato:

uv run search_agent.py dev

Il terminale mostra l'esecuzione dello strumento:

DEBUG livekit.agents executing tool {
 	"function": "search_web",
 	"arguments": "{\"query\":\"current USD to EURO exchange rate\"}",
 	...
 }
DEBUG livekit.agents tools execution completed {...}

Nei miei test, Firecrawl ha restituito i risultati in circa due secondi. Puoi combinare più strumenti personalizzati con quelli integrati nello stesso agente. Un agente di supporto clienti, ad esempio, potrebbe usare XSearch insieme a strumenti personalizzati lookup_order() e check_inventory() che si connettono a database interni.

Personalizzare il rilevamento dei turni

Le impostazioni predefinite del rilevamento dei turni gestiscono bene le conversazioni tipiche. Le regolazioni diventano necessarie quando l'ambiente o il comportamento dell'utente si discostano dalla norma. Una stanza rumorosa può far rispondere l'agente ai suoni di fondo, mentre un utente che si ferma a raccogliere le idee potrebbe essere interrotto prima di finire.

from livekit.plugins.xai import realtime
from openai.types.beta.realtime.session import TurnDetection

session = AgentSession(
 	llm=realtime.RealtimeModel(
     	voice="ara",
     	turn_detection=TurnDetection(
         	type="server_vad",
         	threshold=0.5,
         	prefix_padding_ms=300,
         	silence_duration_ms=200,
     	),
 	),
 )

Il parametro threshold imposta quanto deve essere alto il volume prima di contare come parlato, da 0,0 a 1,0. Alzare questo valore a 0,7 o più aiuta in ambienti rumorosi in cui i suoni di fondo potrebbero altrimenti attivare risposte.

Il parametro prefix_padding_ms determina quanta parte di audio catturare prima dell'inizio del parlato rilevato. Il valore predefinito di 300 ms evita che la prima sillaba venga tagliata. Aumentalo se gli utenti segnalano che le parole iniziali vengono troncate.

Il parametro silence_duration_ms controlla quanto a lungo l'agente aspetta dopo che smetti di parlare prima di rispondere. A 200 ms, le conversazioni risultano reattive. Portarlo a 400 o 500 ms aiuta gli utenti che fanno pause a metà frase o parlano a un ritmo più lento.

Per interfacce push-to-talk o sistemi di telefonia dove serve controllo esplicito del flusso della conversazione, disattiva il rilevamento automatico dei turni:

session = AgentSession(
 	llm=realtime.RealtimeModel(
     	voice="ara",
     	turn_detection=None,
 	),
 )

L'agente aspetta quindi un segnale programmatico prima di rispondere, invece di ascoltare il silenzio.

Distribuire Grok Voice Agent in produzione

La modalità sviluppo lega l'agente alla tua macchina locale. Per un deployment in produzione che giri 24/7 e si adatti alla domanda, LiveKit Cloud ospita il tuo agente sulla propria infrastruttura.

Preparazione al deployment

La CLI di LiveKit rileva il tipo di progetto attraverso i file delle dipendenze. Crea un requirements.txt nella directory del tuo agente:

livekit-agents[xai,openai]>=1.3.10
python-dotenv>=1.2.1
firecrawl-py>=4.12.0

Crea un file separato per i secret di produzione. LiveKit Cloud fornisce automaticamente LIVEKIT_URL, LIVEKIT_API_KEY e LIVEKIT_API_SECRET, quindi devi includere solo le altre chiavi API:

XAI_API_KEY=xai-your-key-here
FIRECRAWL_API_KEY=fc-your-key-here

Salvalo come .env.production e aggiungilo al .gitignore.

Deployment dell'agente

Autentica la CLI con il tuo account LiveKit Cloud:

lk cloud auth

Si apre il browser per collegare la CLI al tuo progetto. Una volta autenticato, distribuisci l'agente:

lk agent create --secrets-file .env.production

La CLI registra il tuo agente, genera un Dockerfile, costruisce l'immagine del container e la distribuisce su LiveKit Cloud. I log scorrono nel terminale mentre l'agente si avvia:

{"message": "registered worker", "level": "INFO", "name": "livekit.agents", "url": "https://your-project.livekit.cloud", "region": "Germany 2", ...}

Controlla lo stato del deployment:

lk agent status

┌─────────────────┬─────────────────┬────────────┬─────────┬────────┬─────────┬───────────┐
 │ ID          	│ Version     	│ Region 	│ Status  │ CPU	│ Mem 	│ Replicas  │
 ├─────────────────┼─────────────────┼────────────┼─────────┼────────┼─────────┼───────────┤
 │ CA_AAVy5WbUYpmA │ v20260109102531 │ eu-central │ Running │ 0m / 2 │ 0 / 4GB │ 0 / 1 / 1 │
 └─────────────────┴─────────────────┴────────────┴─────────┴────────┴─────────┴───────────┘

Come gli utenti accedono al tuo agente

L'URL nei log di deployment (https://your-project.livekit.cloud) è il backend WebSocket, non un'interfaccia utente. Gli utenti interagiscono con il tuo agente tramite un frontend che si connette a questo backend.

Il sandbox che hai creato prima serve a questo scopo. Vai alla tua dashboard LiveKit, apri la sezione Sandbox e copia l'URL del tuo sandbox. Questo URL è pubblicamente accessibile e funziona senza autenticazione. Condividilo con gli utenti e potranno parlare subito con il tuo agente.

Per un'esperienza brandizzata, personalizza l'aspetto del sandbox nella dashboard (logo, colori, testo dei pulsanti) o crea un tuo frontend usando il JavaScript SDK di LiveKit.

Gestire i deployment

Visualizza i log in tempo reale del tuo agente distribuito:

lk agent logs

Distribuisci aggiornamenti dopo aver modificato il codice:

lk agent deploy --secrets-file .env.production

LiveKit usa deployment progressivi. Le nuove istanze gestiscono le nuove sessioni mentre le istanze esistenti completano le conversazioni attive, quindi gli aggiornamenti non causano downtime.

Ripristina una versione precedente se qualcosa si rompe:

lk agent rollback

L'agente distribuito funziona indipendentemente dalla tua macchina locale. Chiudi il terminale, spegni il computer e l'agente continuerà a rispondere agli utenti. LiveKit Cloud gestisce lo scaling, quindi i picchi di traffico avviano automaticamente ulteriori istanze.

Costi di deployment

Eseguire un agente vocale Grok in produzione comporta due costi: l'API di xAI e l'hosting di LiveKit.

xAI addebita 0,05 $ al minuto di conversazione vocale. LiveKit Cloud addebita 0,01 $ al minuto di tempo di sessione dell'agente. Insieme, aspettati circa 0,06 $ al minuto quando il tuo agente è attivamente in servizio.

Il piano gratuito di LiveKit (Build) include 1.000 minuti di sessione agente al mese senza necessità di carta di credito. Questo copre circa 16 ore di conversazione, sufficienti per test e applicazioni a basso traffico. I piani a pagamento partono da 50 $/mese con 5.000 minuti inclusi e limiti di concorrenza più alti.

L'agente non costa nulla quando è inattivo. I costi si applicano solo durante le conversazioni attive, quindi un deployment inattivo durante la notte non comporta spese LiveKit. La fatturazione xAI segue lo stesso schema, misurando solo l'effettivo utilizzo dell'API. Durante i miei esperimenti per scrivere questo articolo, ho speso in totale 78 centesimi su xAI, con LiveKit coperto dal piano gratuito.

Conclusione

Ora hai un agente vocale che ascolta, ragiona e risponde. L'agente si connette a dati live tramite strumenti, adatta il proprio ascolto a diversi ambienti e gira su un'infrastruttura che si scala senza interventi manuali.

Gli schemi di codice descritti qui si estendono ad altri casi d'uso. Sostituisci le istruzioni dell'assistente di ricerca con linee guida per il supporto clienti e aggiungi strumenti che interroghino il tuo database ordini. Crea un tutor di lingua che cerchi frasi di esempio. Realizza un'interfaccia vocale per la tua API esistente.

xAI prevede di rilasciare endpoint standalone di text-to-speech e speech-to-text, che apriranno ad architetture ibride in cui combinare le capacità vocali di Grok con altri modelli linguistici. Per ora, la voice agent API gestisce l'intera pipeline.

La documentazione di LiveKit Agents copre funzionalità aggiuntive come i passaggi multi-agente e la persistenza delle sessioni. La documentazione di xAI approfondisce i formati audio e le funzionalità enterprise.