Strumenti e chiamata di funzioni nella voce
In questa pagina
Un agente che agisce, non solo parla
Un assistente vocale limitato alla conversazione raggiunge presto un vicolo cieco: risponde educatamente a “Dov’è il mio ordine?” senza saperne nulla. Il vero valore dell’Agente Vocale risiede nella sua capacità di agire nel mezzo di una conversazione (interrogare un database, eseguire una ricerca web, chiamare un’API aziendale, raggiungere un server MCP) e leggere il risultato come se nulla fosse.
I cinque tipi di strumenti
La ricerca web, nella sua forma più semplice, non richiede parametri:
{ "type": "web_search" }
L’agente cerca quindi sul web in tempo reale, coprendo domande fattuali, notizie e qualsiasi dato che cambia troppo spesso per essere inserito in un prompt.
La ricerca su X funziona allo stesso modo, con l’opzione di limitarla a determinati account:
{
"type": "x_search",
"allowed_x_handles": ["corsen_ai"]
}
Il parametro allowed_x_handles è opzionale, ma cambia la natura dello strumento. Senza di esso, l’agente cerca sull’intera piattaforma; con esso, l’agente diventa un portavoce che cita solo i tuoi post ufficiali.
La ricerca file interroga collezioni di documenti vettorializzati, come manuali, procedure e documentazione di prodotto:
{
"type": "file_search",
"vector_store_ids": ["vs_abc123"],
"max_num_results": 10
}
Le funzioni personalizzate aprono le porte ai tuoi sistemi interni. Questo è il tipo di strumento che userai più spesso e vale la pena dichiararlo con cura:
{
"type": "function",
"name": "check_order",
"description": "Checks the status of a customer order",
"parameters": {
"type": "object",
"properties": {
"order_number": {
"type": "string",
"description": "The order number, in the format CMD-XXXX"
}
},
"required": ["order_number"]
}
}
Puoi collegare un CRM, un ERP, un calendario o un database interno allo stesso modo. Infine, i server MCP forniscono accesso a strumenti standardizzati tramite il Model Context Protocol, così non devi riscrivere un’integrazione per ogni servizio:
{
"type": "mcp",
"server_url": "https://mcp.example.com/sse",
"server_label": "My MCP server"
}
Il ciclo completo di chiamata di funzione
Quando l’agente decide di chiamare una funzione, non la esegue: chiede a te di farlo, e la tua app svolge il lavoro. Gli argomenti arrivano prima in streaming tramite response.function_call_arguments.delta. Poi l’evento response.function_call_arguments.done segna la fine della richiesta e ti fornisce il call_id insieme agli argomenti completi. Spetta a te eseguire la funzione, quindi restituire il risultato come un conversation.item.create di tipo function_call_output:
{
"type": "conversation.item.create",
"item": {
"type": "function_call_output",
"call_id": "call_abc123",
"output": "{\"status\": \"shipped\", \"delivery_date\": \"2026-04-05\"}"
}
}
Un ultimo passaggio è essenziale, ed è quello che tutti dimenticano: invia response.create affinché l’agente integri il risultato nella sua risposta vocale. Senza di esso, il risultato raggiunge sì la conversazione, ma non succede nulla. L’utente sente silenzio e tu cerchi il bug nel posto sbagliato.
Quando più funzioni si attivano contemporaneamente
Il modello potrebbe decidere di chiamare due o tre funzioni contemporaneamente, ad esempio per verificare un ordine e consultare il programma di consegna. Riceverai quindi diversi eventi function_call_arguments.done, ognuno con il proprio call_id. Eseguili tutti, in parallelo se possibile per evitare che le latenze si sommino, invia ogni risultato nel suo conversation.item.create dedicato e invia un unico response.create alla fine. Un response.create per funzione attiverebbe altrettante risposte vocali in competizione e l’agente inizierebbe a sovrapporsi.
// Ricevi ed esegui tutte le funzioni
const results = await Promise.all(
pendingCalls.map(call => executeFunction(call))
);
// Invia tutti i risultati
for (const result of results) {
ws.send(JSON.stringify({
type: "conversation.item.create",
item: {
type: "function_call_output",
call_id: result.callId,
output: JSON.stringify(result.data)
}
}));
}
// Attiva la risposta
ws.send(JSON.stringify({ type: "response.create" }));
Vincoli specifici della voce
Ciò che passa inosservato in un’interfaccia testuale diventa evidente nel parlato, a cominciare dal tempo. Nessuno aspetta più di tre-cinque secondi nel mezzo di una conversazione. Oltre questo limite, gli utenti pensano che la linea sia caduta e iniziano a parlare. Se la tua funzione interroga un sistema lento, fai dire all’agente una frase di attesa durante la chiamata invece di lasciare un silenzio morto.
Anche la dimensione dei risultati conta. L’agente deve riassumere ad alta voce qualsiasi cosa tu gli fornisca, e una lista di quaranta ordini produce o un recital infinito o un sommario approssimativo. Restituisci dati strutturati, ma limitati all’essenziale. Fai attenzione anche alla descrizione di ogni funzione, poiché è l’unica cosa su cui il modello si basa per scegliere: una descrizione vaga come “gestisce gli ordini” lo fa esitare o scegliere lo strumento sbagliato. E prevedi i fallimenti. Quando una funzione crasha, restituisci un messaggio di errore esplicito in output invece di nulla, altrimenti l’agente improvviserà una risposta senza sapere che la chiamata è fallita.
Punti chiave
- L’Agente Vocale supporta cinque tipi di strumenti: ricerca web, ricerca su X, ricerca file, funzioni e MCP
- Una chiamata di funzione attraversa quattro passaggi: ricevere gli argomenti, eseguire la funzione, restituire il risultato e attivare la risposta
- Le chiamate parallele sono possibili: esegui tutto, invia tutto, poi manda un unico
response.create - Nella voce, il tempo di risposta della funzione è critico: punta a meno di 3 secondi