Costruisci un agente vocale completo
In questa pagina
Aggiornato il 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati:
tts-1,tts-1-hdegpt-4o-mini-ttscesseranno di funzionare il 6 gennaio 2027 (successore:gpt-realtime-2.1-mini, che la guida TTS di OpenAI indica come non supportato da/v1/audio/speech: la migrazione della sintesi vocale passa alle API Realtime);gpt-realtime,gpt-4o-realtimee i modelli audio legacy il 20 gennaio 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribee/v1/audio/translationsil 26 febbraio 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Per la voce full-duplex, GPT-Live 1 è disponibile nelle API dal 10 settembre 2026.
Corretto il 3 novembre 2026. La trascrizione dell’input utilizzava
gpt-live-transcribe, che funziona solo in una sessione di trascrizione e non supporta néserver_vadnésemantic_vad. In una sessione di conversazione come questa, dove il VAD convalida ogni turno, la documentazione specificagpt-transcribe, che trascrive i turni convalidati e utilizza i turni precedenti come contesto. Fonti: Trascrizione in tempo reale · GPT-Transcribe · GPT-Live-Transcribe.
Costruisci un agente vocale completo
Questa lezione riunisce tutti i concetti affrontati finora per costruire un agente vocale end-to-end pienamente funzionale. Creerai un assistente che ascolta l’utente, comprende la sua richiesta, esegue azioni e risponde vocalmente, il tutto in tempo reale tramite le API Realtime.
Architettura dell’agente
Quattro moduli e, soprattutto, un vincolo che guida l’intera architettura: tutto deve avvenire simultaneamente. Il microfono cattura mentre il modello risponde, gli eventi arrivano mentre l’audio viene riprodotto e l’utente può interrompere in qualsiasi momento. Un agente vocale non è un ciclo domanda-risposta; è un sistema in cui più flussi avanzano in parallelo, motivo per cui faremo ampio uso di asyncio nel seguito.
La classe VoiceAgent
La classe raccoglie lo stato che questi flussi paralleli devono condividere: la connessione, la sessione corrente e la risposta attualmente in riproduzione. Proprio perché più task accedono a questo stato simultaneamente, un oggetto è preferibile a un insieme di variabili globali: quando devi annullare una risposta in corso, devi sapere che esiste.
import asyncio
import json
import base64
import websockets
import sounddevice as sd
import numpy as np
import pyaudio
class VoiceAgent:
"""Agente vocale completo basato sulle API Realtime."""
def __init__(self, api_key: str, instructions: str, tools: list = None):
self.api_key = api_key
self.instructions = instructions
self.tools = tools or []
self.ws = None
self.is_playing = False
self.sample_rate = 24000
self.chunk_size = 2400 # 100ms
async def connect(self):
"""Stabilisce la connessione e configura la sessione."""
url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"
headers = {
"Authorization": f"Bearer {self.api_key}"
}
self.ws = await websockets.connect(url, additional_headers=headers)
# Attendi session.created
event = json.loads(await self.ws.recv())
print(f"Sessione: {event['session']['id']}")
# Configura
await self.ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": self.instructions,
"audio": {
"input": {
"format": {"type": "audio/pcm", "rate": 24000},
"transcription": {"model": "gpt-transcribe", "languages": ["fr"]},
"turn_detection": {
"type": "server_vad",
"threshold": 0.5,
"silence_duration_ms": 600
}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000},
"voice": "marin"
}
},
"tools": self.tools,
"tool_choice": "auto"
}
}))
await self.ws.recv() # session.updated
print("Agente vocale pronto.")
async def start(self):
"""Avvia l'agente vocale."""
await self.connect()
await asyncio.gather(
self._capture_audio(),
self._process_events()
)
Modulo di cattura audio
async def _capture_audio(self):
"""Cattura l'input del microfono e lo invia alle API Realtime."""
loop = asyncio.get_event_loop()
queue = asyncio.Queue()
def callback(indata, frames, time_info, status):
pcm = (indata[:, 0] * 32767).astype(np.int16)
loop.call_soon_threadsafe(queue.put_nowait, pcm)
stream = sd.InputStream(
samplerate=self.sample_rate,
channels=1,
dtype="float32",
blocksize=self.chunk_size,
callback=callback
)
with stream:
while True:
pcm_data = await queue.get()
audio_b64 = base64.b64encode(pcm_data.tobytes()).decode()
await self.ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": audio_b64
}))
Modulo di elaborazione eventi
async def _process_events(self):
"""Elabora tutti gli eventi dal server."""
pa = pyaudio.PyAudio()
player = pa.open(
format=pyaudio.paInt16, channels=1,
rate=self.sample_rate, output=True
)
try:
async for raw in self.ws:
event = json.loads(raw)
t = event["type"]
if t == "response.output_audio.delta":
audio = base64.b64decode(event["delta"])
player.write(audio)
self.is_playing = True
elif t == "response.output_audio.done":
self.is_playing = False
elif t == "response.output_audio_transcript.delta":
print(event["delta"], end="", flush=True)
elif t == "input_audio_buffer.speech_started":
if self.is_playing:
await self.ws.send(json.dumps({
"type": "response.cancel"
}))
self.is_playing = False
elif t == "response.done":
await self._handle_response_done(event)
elif t == "error":
print(f"\nErrore: {event['error']['message']}")
finally:
player.close()
pa.terminate()
Modulo di gestione degli strumenti
Questo modulo trasforma l’agente da un semplice chatbot vocale in un assistente capace di compiere azioni. La differenza rispetto alla chiamata di funzioni classica risiede nel vincolo temporale: l’utente è in linea senza alcun indicatore visivo di avanzamento. Se l’esecuzione richiede più di uno o due secondi, fai parlare l’agente mentre lavora — «Lascia che controlli subito per te» — perché il silenzio in una conversazione vocale sembra un guasto.
async def _handle_response_done(self, event):
"""Gestisce le chiamate di funzione nella risposta."""
response = event["response"]
function_calls = [
o for o in response.get("output", [])
if o["type"] == "function_call"
]
if not function_calls:
print() # Nuova riga dopo la trascrizione
return
for call in function_calls:
name = call["name"]
args = json.loads(call["arguments"])
call_id = call["call_id"]
print(f"\n→ {name}({args})")
# Esegui la funzione (adatta alla tua logica di business)
result = await self._execute_function(name, args)
await self.ws.send(json.dumps({
"type": "conversation.item.create",
"item": {
"type": "function_call_output",
"call_id": call_id,
"output": json.dumps(result)
}
}))
# Chiedi al modello di continuare
await self.ws.send(json.dumps({"type": "response.create"}))
async def _execute_function(self, name: str, args: dict) -> dict:
"""Smista la chiamata di funzione."""
# Implementa secondo la tua logica di business
return {"error": f"Funzione {name} non implementata"}
Avvia l’agente
async def main():
agent = VoiceAgent(
api_key="sk-...",
instructions=(
"Sei un assistente vocale per Corsen AI. "
"Aiuti gli utenti a gestire i loro appuntamenti "
"e a ottenere informazioni sui nostri servizi. "
"Rispondi in francese, in modo conciso e professionale."
),
tools=[
{
"type": "function",
"name": "check_availability",
"description": "Verifica la disponibilità per una fascia oraria",
"parameters": {
"type": "object",
"properties": {
"date": {"type": "string"},
"service": {"type": "string"}
},
"required": ["date"]
}
}
]
)
await agent.start()
asyncio.run(main())
Punti chiave
- Un agente vocale completo combina quattro moduli: audio, sessione, strumenti e gestione dello stato
- La classe
VoiceAgentincapsula tutta la logica dietro un’interfaccia semplice asyncio.gatherabilita la cattura del microfono e l’elaborazione degli eventi in parallelo- La gestione delle interruzioni (annullare una risposta quando l’utente parla) è essenziale
- Gli strumenti trasformano l’agente da un semplice chatbot vocale in un assistente capace di agire