Chiamata di funzioni vocali
In questa pagina
Esegui funzioni da una conversazione vocale
La chiamata di funzioni vocali permette al tuo agente di attivare azioni reali durante una conversazione: interrogare un database, effettuare un ordine, inviare un’email o chiamare un’API esterna. L’agente decide quando chiamare una funzione in base a ciò che dice l’utente.
L'agente identifica la necessità
L'utente dice qualcosa che richiede una chiamata di funzione. L'agente genera gli argomenti.
La tua app esegue la funzione
Ricevi gli argomenti tramite l'evento function_call_arguments.done ed esegui la tua logica di business.
Invii il risultato
Invia conversation.item.create con il tipo function_call_output e il call_id.
L'agente prosegue la conversazione
Invia response.create affinché l'agente integri il risultato nella sua risposta vocale.
Dichiarare una funzione
Dichiari le funzioni nell’array tools di session.update:
{
"type": "session.update",
"session": {
"tools": [
{
"type": "function",
"name": "get_balance",
"description": "Gets the balance of a customer's bank account",
"parameters": {
"type": "object",
"properties": {
"client_id": {
"type": "string",
"description": "Customer ID"
}
},
"required": ["client_id"]
}
}
]
}
}
Ricevere e gestire una chiamata di funzione
Quando l’agente decide di chiamare una funzione, ricevi gli argomenti come stream, poi tutti insieme:
let functionArgs = "";
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "response.function_call_arguments.delta":
functionArgs += event.delta;
break;
case "response.function_call_arguments.done":
const args = JSON.parse(event.arguments);
const callId = event.call_id;
const functionName = event.name;
// Esegui la funzione
handleFunctionCall(functionName, args, callId);
break;
}
});
async function handleFunctionCall(name, args, callId) {
let result;
switch (name) {
case "get_balance":
result = await getBalance(args.client_id);
break;
default:
result = { error: "Unknown function" };
}
// Invia il risultato
ws.send(JSON.stringify({
type: "conversation.item.create",
item: {
type: "function_call_output",
call_id: callId,
output: JSON.stringify(result)
}
}));
// Chiedi all'agente di continuare
ws.send(JSON.stringify({
type: "response.create"
}));
}
Chiamate di funzioni parallele
L’agente potrebbe decidere di chiamare diverse funzioni contemporaneamente. Riceverai quindi diversi eventi function_call_arguments.done. La regola è:
- Risolvere ogni funzione prima di rispondere
- Inviare ogni risultato, con un
conversation.item.createper risultato - Inviare un singolo
response.createalla fine
const pendingCalls = new Map();
let expectedCalls = 0;
case "response.function_call_arguments.done":
const result = await executeFunction(event.name, event.arguments);
pendingCalls.set(event.call_id, result);
if (pendingCalls.size === expectedCalls) {
// Ogni funzione è risolta
for (const [callId, output] of pendingCalls) {
ws.send(JSON.stringify({
type: "conversation.item.create",
item: {
type: "function_call_output",
call_id: callId,
output: JSON.stringify(output)
}
}));
}
// Un singolo response.create per tutti gli output
ws.send(JSON.stringify({ type: "response.create" }));
pendingCalls.clear();
}
break;
Migliori pratiche
- Descrizioni chiare: la qualità delle descrizioni delle tue funzioni determina quando l’agente le utilizza
- Esecuzione rapida: una funzione che impiega più di 2 o 3 secondi crea un silenzio imbarazzante
- Gestione degli errori: restituisci un messaggio di errore leggibile piuttosto che un’eccezione tecnica
- Conferma vocale: per azioni sensibili (pagamenti, eliminazioni), fai confermare l’utente prima di eseguirle
Punti chiave
- La chiamata di funzioni vocali segue un ciclo di quattro passaggi: rilevamento, esecuzione, restituzione del risultato, continuazione
- Dichiari le funzioni in
session.updatecon uno schema JSON per i loro parametri - Il risultato deve essere inviato tramite
conversation.item.createcontype: "function_call_output" - Invia sempre
response.createdopo aver inviato i risultati - Per le chiamate parallele, attendi ogni risultato prima di inviare un singolo
response.create