Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Costruisci un agente vocale completo

Lezione 14 di 18 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Costruisci un agente vocale completo
  2. Architettura dell’agente
  3. La classe VoiceAgent
  4. Modulo di cattura audio
  5. Modulo di elaborazione eventi
  6. Modulo di gestione degli strumenti
  7. Avvia l’agente
  8. Punti chiave

Aggiornato il 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati: tts-1, tts-1-hd e gpt-4o-mini-tts cesseranno 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-realtime e 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-transcribe e /v1/audio/translations il 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_vad né semantic_vad. In una sessione di conversazione come questa, dove il VAD convalida ogni turno, la documentazione specifica gpt-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.

Audio
Cattura e riproduzione
Sessione
WebSocket e configurazione
Strumenti
Azioni di business
Stato
Gestione della conversazione

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 VoiceAgent incapsula tutta la logica dietro un’interfaccia semplice
  • asyncio.gather abilita 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