Chiamata di funzioni in tempo reale
In questa pagina
Aggiornamento 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati:
tts-1,tts-1-hdegpt-4o-mini-ttssmetteranno di funzionare il 6 gennaio 2027 (il sostituto indicato ègpt-realtime-2.1-mini, che la guida TTS di OpenAI specifica non essere supportato da/v1/audio/speech: la migrazione della sintesi vocale passa alla Realtime API);gpt-realtime,gpt-4o-realtimee i modelli audio legacy il 20 gennaio 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribee/v1/audio/translationsil 26 febbraio 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Per la voce full-duplex, GPT-Live 1 è disponibile nelle API dal 10 settembre 2026.
Chiamata di funzioni in tempo reale
La chiamata di funzioni nella Realtime API permette al tuo agente vocale di compiere azioni concrete durante una conversazione: interrogare un database, effettuare un ordine o verificare uno stato. Il meccanismo è simile a quello della Responses API, ma adattato per il flusso di eventi WebSocket.
Dichiarazione degli strumenti nella sessione
Dichiari gli strumenti in session.update, esattamente come istruzioni e voce. Ogni strumento è uno schema JSON che ne descrive i parametri:
tools = [
{
"type": "function",
"name": "get_weather",
"description": "Get the current weather for a given city",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Name of the city"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature unit"
}
},
"required": ["city"]
}
},
{
"type": "function",
"name": "book_appointment",
"description": "Book an appointment",
"parameters": {
"type": "object",
"properties": {
"date": {"type": "string", "description": "Date in YYYY-MM-DD format"},
"time": {"type": "string", "description": "Time in HH:MM format"},
"service": {"type": "string", "description": "Type of service"}
},
"required": ["date", "time", "service"]
}
}
]
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": ["audio"],
"instructions": "You are a voice assistant. Use the available tools.",
"audio": {"output": {"voice": "marin"}},
"tools": tools,
"tool_choice": "auto"
}
}))
Il flusso di chiamata della funzione
Quando il modello decide di chiamare uno strumento, la sequenza di eventi è la seguente:
response.function_call_arguments.delta
Gli argomenti della funzione arrivano in streaming, pezzo per pezzo.
response.function_call_arguments.done
Gli argomenti sono completi. Ora puoi eseguire la funzione.
conversation.item.create (tu)
Invii il risultato della funzione al modello.
response.create (tu)
Chiedi al modello di continuare la sua risposta con il risultato.
Implementazione del gestore di funzioni
Ecco un esempio completo di gestione delle chiamate di funzione:
import json
# Registro delle funzioni disponibili
async def get_weather(city: str, unit: str = "celsius") -> dict:
# Chiama una vera API meteo
return {"city": city, "temperature": 22, "unit": unit, "condition": "sunny"}
async def book_appointment(date: str, time: str, service: str) -> dict:
# Logica di prenotazione
return {"confirmed": True, "date": date, "time": time, "reference": "RDV-2026-0042"}
FUNCTION_REGISTRY = {
"get_weather": get_weather,
"book_appointment": book_appointment,
}
async def handle_function_call(ws, event):
"""Elabora una chiamata di funzione e restituisce il risultato."""
response = event["response"]
for output in response.get("output", []):
if output["type"] != "function_call":
continue
func_name = output["name"]
call_id = output["call_id"]
arguments = json.loads(output["arguments"])
print(f"Calling function: {func_name}({arguments})")
# Esegue la funzione
func = FUNCTION_REGISTRY.get(func_name)
if func:
result = await func(**arguments)
else:
result = {"error": f"Unknown function: {func_name}"}
# Invia il risultato al modello
await ws.send(json.dumps({
"type": "conversation.item.create",
"item": {
"type": "function_call_output",
"call_id": call_id,
"output": json.dumps(result)
}
}))
# Chiedi al modello di continuare con il risultato
await ws.send(json.dumps({
"type": "response.create"
}))
Integrazione nel ciclo degli eventi
Il gestore di funzioni si integra nel tuo ciclo principale:
async def event_loop(ws):
"""Ciclo principale di elaborazione degli eventi."""
async for raw_message in ws:
event = json.loads(raw_message)
event_type = event["type"]
if event_type == "response.done":
response = event["response"]
# Controlla se il modello ha chiamato delle funzioni
has_function_calls = any(
o["type"] == "function_call"
for o in response.get("output", [])
)
if has_function_calls:
await handle_function_call(ws, event)
elif event_type == "response.output_audio.delta":
# Riproduci l'audio della risposta
audio_bytes = base64.b64decode(event["delta"])
player.write(audio_bytes)
elif event_type == "error":
print(f"Error: {event['error']['message']}")
Chiamate di funzioni multiple
Il modello può decidere di chiamare più funzioni in una singola risposta. Il campo output di response.done può contenere più voci di tipo function_call. Elaborale tutte prima di chiamare response.create.
Punti chiave
- Gli strumenti vengono dichiarati in
session.updateutilizzando uno schema JSON standard - Gli argomenti arrivano in streaming tramite
response.function_call_arguments.delta - Dopo l’esecuzione, invia il risultato tramite
conversation.item.createcon ilcall_id - Chiama
response.createaffinché il modello possa formulare la sua risposta vocale con il risultato - Gestisci le chiamate multiple: il modello può chiamare diverse funzioni contemporaneamente