Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Architettura del function calling nelle Responses API

Lezione 1 di 20 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Architettura del function calling nelle Responses API
  2. Il principio fondamentale
  3. Anatomia di una risposta
  4. Il ciclo completo
  5. Differenze chiave rispetto alle Chat Completions
  6. Quando il modello chiama una funzione?
  7. Punti chiave

Aggiornato il 2 novembre 2026 sulla base della documentazione OpenAI: lo strumento Code Interpreter richiede ora un parametro container (aggiunto a tutti gli esempi), le parti di testo in input utilizzano il tipo input_text e la ricerca web usa lo strumento web_search (web_search_preview è ora uno strumento legacy senza filtri per dominio). I file generati vengono recuperati utilizzando le funzioni fichiers_generes e telecharger della Lezione 10. Fonti: Code Interpreter · Ricerca web.

Architettura del function calling nelle Responses API

Il function calling è il meccanismo fondamentale che consente ai modelli OpenAI di interagire con il mondo esterno. Nelle Responses API, questo meccanismo è stato riprogettato per essere più robusto, più prevedibile e nativamente integrato con strumenti incorporati come la Ricerca Web e il Code Interpreter.

Il principio fondamentale

Il modello non esegue mai alcuna azione direttamente. Emette intenzioni strutturate che il tuo codice intercetta ed esegue. Detto così, potrebbe sembrare una limitazione tecnica; in realtà, è la scelta progettuale che rende possibile tutto il resto.

Considera l’alternativa. Se il modello eseguisse le azioni da solo, dovresti fornirgli le credenziali del database, le chiavi API e i permessi di scrittura, senza avere alcun punto in cui verificare qualcosa. Con il disaccoppiamento, ogni intenzione passa attraverso il tuo codice: tu validi gli argomenti, applichi le regole di business e rifiuti se necessario. Il modello propone, il tuo codice dispone, ed è questo confine che ti permette di mettere in produzione il function calling senza perdere il controllo.

from openai import OpenAI

client = OpenAI()

# Dichiarazione di uno strumento personalizzato
tools = [{
    "type": "function",
    "name": "rechercher_client",
    "description": "Search for a client in the CRM by name or email",
    "parameters": {
        "type": "object",
        "properties": {
            "terme": {
                "type": "string",
                "description": "Client name, email, or ID"
            },
            "champ": {
                "type": "string",
                "enum": ["nom", "email", "id"],
                "description": "Field to search in"
            }
        },
        "required": ["terme"]
    }
}]

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Find the client Jean Dupont",
    tools=tools
)

Anatomia di una risposta

Una risposta non contiene né solo testo né solo chiamate di strumenti: output è una lista eterogenea che può mescolare entrambi. L’abitudine da acquisire fin dalla prima riga di codice è iterare su questa lista invece di leggere output[0]: un modello che spiega il suo ragionamento prima di chiamare una funzione produce esattamente questo caso, e un codice che legge solo il primo elemento si romperà il giorno in cui inizierà ad aggiungere commenti.

for item in response.output:
    if item.type == "function_call":
        print(f"Call ID  : {item.call_id}")
        print(f"Function : {item.name}")
        print(f"Args     : {item.arguments}")

Il call_id è essenziale: collega la chiamata al suo risultato quando invii la risposta al modello. Con una singola chiamata, barely lo noti; con tre chiamate parallele, è l’unica cosa che ti impedisce di attribuire il meteo di Lione alla richiesta su Marsiglia. Restituisci sempre il risultato con il call_id che hai ricevuto, mai con un ID che ricostruisci lato tuo.

Il ciclo completo

Questo ciclo di quattro passaggi è invariante: vale per una funzione o per venti, per una chiamata semplice o per un agente che concatena dieci strumenti. Tutta la complessità che incontrerai in seguito—parallelismo, errori, fallback—consiste nell’strumentare questo ciclo, mai nel sostituirlo.

import json

# 1. Prima chiamata con gli strumenti dichiarati
response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the balance for client [email protected]?",
    tools=tools
)

# 2. Rilevamento ed esecuzione delle chiamate di funzione
resultats = []
for item in response.output:
    if item.type == "function_call":
        if item.name == "rechercher_client":
            args = json.loads(item.arguments)
            resultat = votre_crm.rechercher(args["terme"])
            resultats.append({
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(resultat)
            })

# 3. Invio dei risultati al modello
response_finale = client.responses.create(
    model="gpt-5.6-terra",
    input=response.output + resultats,
    tools=tools
)

# 4. Il modello formula la sua risposta naturale
print(response_finale.output_text)

Differenze chiave rispetto alle Chat Completions

Le Responses API introducono diversi miglioramenti architetturali.

Gestione nativa degli strumenti incorporati

Gli strumenti incorporati vengono dichiarati esattamente come le tue funzioni, ma vengono eseguiti lato OpenAI. La conseguenza pratica è piacevole: non scrivi alcun ciclo per loro. Il modello chiama, ottiene il risultato e continua, tutto in un singolo round trip. Il ciclo descritto sopra riguarda solo le tue funzioni, quelle che girano sulla tua macchina.

# Mix di strumenti incorporati e personalizzati
tools = [
    {"type": "web_search"},
    {"type": "code_interpreter", "container": {"type": "auto"}},
    {
        "type": "function",
        "name": "ma_fonction",
        "description": "My custom function",
        "parameters": {"type": "object", "properties": {}}
    }
]

Identificatori di chiamata stabili

Ogni chiamata di funzione riceve un call_id univoco che ti permette di tracciare con precisione quale risultato corrisponde a quale chiamata, anche con chiamate parallele.

Flusso semplificato

Non c’è bisogno di gestire manualmente i ruoli assistant e tool nei messaggi. Il campo input accetta direttamente la concatenazione degli output precedenti con i risultati delle funzioni.

Quando il modello chiama una funzione?

Il modello decide di chiamare una funzione quando la richiesta dell’utente richiede informazioni che non possiede, quando la descrizione della funzione corrisponde al bisogno identificato e quando i parametri richiesti possono essere dedotti dal contesto.

Tre condizioni devono quindi essere soddisfatte simultaneamente, e questo è utile per il debug: quando una funzione non viene chiamata anche se dovrebbe esserlo, la causa è quasi sempre la seconda: una descrizione che non copre il modo in cui l’utente ha formulato la sua richiesta. Il parametro tool_choice ti permette di forzare il comportamento quando la descrizione non è sufficiente:

# Lascia decidere al modello
tool_choice = "auto"

# Forza una chiamata a una funzione specifica
tool_choice = {"type": "function", "name": "rechercher_client"}

# Vieta tutte le chiamate di funzione
tool_choice = "none"

# Richiede almeno una chiamata senza specificare quale
tool_choice = "required"

Punti chiave

  • Il function calling è un protocollo di intenzione, non un protocollo di esecuzione
  • Il ciclo chiamata-esecuzione-ritorno è il pattern fondamentale
  • Strumenti incorporati e personalizzati coesistono nello stesso array tools
  • Il call_id garantisce la tracciabilità di ogni chiamata
  • tool_choice ti permette di controllare finemente il comportamento del modello