Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Chiamata di funzioni vocali

Lezione 13 di 16 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Esegui funzioni da una conversazione vocale
  2. Dichiarare una funzione
  3. Ricevere e gestire una chiamata di funzione
  4. Chiamate di funzioni parallele
  5. Migliori pratiche
  6. Punti chiave

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.

1

L'agente identifica la necessità

L'utente dice qualcosa che richiede una chiamata di funzione. L'agente genera gli argomenti.

2

La tua app esegue la funzione

Ricevi gli argomenti tramite l'evento function_call_arguments.done ed esegui la tua logica di business.

3

Invii il risultato

Invia conversation.item.create con il tipo function_call_output e il call_id.

4

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 è:

  1. Risolvere ogni funzione prima di rispondere
  2. Inviare ogni risultato, con un conversation.item.create per risultato
  3. Inviare un singolo response.create alla 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.update con uno schema JSON per i loro parametri
  • Il risultato deve essere inviato tramite conversation.item.create con type: "function_call_output"
  • Invia sempre response.create dopo aver inviato i risultati
  • Per le chiamate parallele, attendi ogni risultato prima di inviare un singolo response.create