Eventi client-server
In questa pagina
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.updateconfigura la sessione e può essere inviato più volteconversation.item.createti permette di aggiungere testo, cronologia o risultati di funzioneresponse.createè richiesto in modalità manuale e automatico in modalità VADresponse.cancelti permette di interrompere l’agente quando l’utente ricomincia a parlare