Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Chiamata di funzioni in tempo reale

Lezione 4 di 18 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Chiamata di funzioni in tempo reale
  2. Dichiarazione degli strumenti nella sessione
  3. Il flusso di chiamata della funzione
  4. Implementazione del gestore di funzioni
  5. Integrazione nel ciclo degli eventi
  6. Punti chiave

Aggiornamento 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati: tts-1, tts-1-hd e gpt-4o-mini-tts smetteranno 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-realtime e 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-transcribe e /v1/audio/translations il 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:

1

response.function_call_arguments.delta

Gli argomenti della funzione arrivano in streaming, pezzo per pezzo.

2

response.function_call_arguments.done

Gli argomenti sono completi. Ora puoi eseguire la funzione.

3

conversation.item.create (tu)

Invii il risultato della funzione al modello.

4

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.update utilizzando uno schema JSON standard
  • Gli argomenti arrivano in streaming tramite response.function_call_arguments.delta
  • Dopo l’esecuzione, invia il risultato tramite conversation.item.create con il call_id
  • Chiama response.create affinché il modello possa formulare la sua risposta vocale con il risultato
  • Gestisci le chiamate multiple: il modello può chiamare diverse funzioni contemporaneamente