Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Eventi client-server

Lezione 9 di 16 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. I messaggi che invii
  2. conversation.item.create
  3. conversation.item.delete
  4. response.create e response.cancel
  5. Punti chiave

I messaggi che invii

L’API Voice Agent funziona scambiando eventi JSON tramite WebSocket. In questa lezione, esaminerai ogni evento che la tua app può inviare al server. Ognuno ha un ruolo specifico nel ciclo di conversazione.

Evento Descrizione Quando usarlo
session.update Configura la sessione All'avvio e per modificare la configurazione
input_audio_buffer.append Invia un chunk audio in base64 Continuamente durante la registrazione
input_audio_buffer.commit Esegue il commit del buffer audio In modalità push-to-talk
input_audio_buffer.clear Svuota il buffer senza elaborazione Per annullare una registrazione
conversation.item.create Aggiungi un messaggio o un risultato di funzione Cronologia, contesto, risultati di funzione
conversation.item.delete Elimina un elemento per ID Pulizia della cronologia conversazionale
response.create Richiedi una risposta In modalità manuale (automatico con VAD)
response.cancel Annulla una risposta in corso Quando l'utente interrompe

conversation.item.create

Questo evento ti permette di inserire messaggi nella conversazione senza passare attraverso il flusso audio. Copre tre casi principali.

Aggiungere un messaggio di testo utente

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "What's the status of my order 12345?"
      }
    ]
  }
}

Inserire la cronologia della conversazione

Prima che la conversazione vocale inizi, puoi precompilare la cronologia con scambi precedenti per fornire contesto all’agente:

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello, I'm your assistant. How can I help you?"
      }
    ]
  }
}

Restituire un risultato di funzione

Dopo l’esecuzione di una chiamata di funzione, invii il risultato con questo evento (vedi la lezione 13 sulle chiamate di funzione):

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": "{\"status\": \"shipped\", \"tracking\": \"FR123456789\"}"
  }
}

conversation.item.delete

Elimina un elemento della conversazione tramite il suo ID:

{
  "type": "conversation.item.delete",
  "item_id": "item_audio_001"
}

Questo è utile per rimuovere un messaggio errato o per evitare che la cronologia della conversazione diventi troppo grande.

response.create e response.cancel

response.create chiede esplicitamente al server di generare una risposta. In modalità VAD, il server lo fa autonomamente una volta rilevata la fine del discorso:

{
  "type": "response.create"
}

response.cancel interrompe una risposta in fase di generazione. È utile quando l’utente parla sopra l’agente:

{
  "type": "response.cancel"
}

Punti chiave

  • Otto tipi di eventi possono essere inviati dal client al server
  • session.update configura la sessione e può essere inviato più volte
  • conversation.item.create ti permette di aggiungere testo, cronologia o risultati di funzione
  • response.create è richiesto in modalità manuale e automatico in modalità VAD
  • response.cancel ti permette di interrompere l’agente quando l’utente ricomincia a parlare