OpenAI Assistants API function calling e retrieval guida operativa • Meteora Web Agency

Hai mai provato a costruire un assistente AI che risponda con dati aggiornati o interagisca con sistemi esterni? Se sì, sai quanto è complesso gestire contesto, token e chiamate API. Con l'Assistants API di OpenAI, puoi delegare tutto questo a un'architettura professionale, senza reinventare la ruota ogni volta.

Noi, di Meteora Web, lo abbiamo messo in produzione per clienti che gestiscono cataloghi complessi, FAQ dinamiche e automazioni di back‑office. E ti diciamo subito una cosa: la differenza tra un assistente “fatto in casa” con Chat Completion e un Assistente configurato con retrieval e function calling è abissale. Non solo per la qualità delle risposte, ma per il tempo che risparmi in sviluppo e manutenzione.

Questa guida parte dalla pratica. Se vuoi prima capire dove si inserisce nel panorama dell'AI agentica, dai un’occhiata alla nostra guida completa all’AI agentica. Qui andiamo dritti al codice.

Cos'è un Assistente AI e perché ti cambia la giornata

Un Assistente AI (Assistant) è un'entità preconfigurata su OpenAI, con un modello, istruzioni di sistema, strumenti abilitati e una memoria persistente via thread e run. Rispetto a una semplice chiamata a chat.completions.create, hai tre vantaggi enormi:

Gestione automatica del contesto: ogni thread mantiene la cronologia dei messaggi, tu non devi più concatenare manualmente gli scambi.
Retrieval integrato: carichi uno o più file (PDF, CSV, TXT) e l'assistente cerca al loro interno per rispondere. Niente vettorizzazione manuale, niente chunking personalizzato.
Function calling nativo: definisci funzioni in JSON Schema, l'assistente decide quando chiamarle, tu gestisci l'output e glielo restituisci. Tutto in un unico flusso di run.

Per un'azienda che ha già database, ERP o documenti interni, questo significa passare da un prototipo “da laboratorio” a un agente che lavora su dati reali in poche ore.

Configurazione pratica: Assistente con Python

Partiamo da una configurazione minima ma completa. Ti serve una API key di OpenAI (con accesso al modello gpt-4o o gpt-4-turbo) e la libreria openai aggiornata:

pip install openai --upgrade

Creare l'Assistente

Definiamo un assistente per un fittizio negozio di abbigliamento – tema che conosciamo bene, ricordi? Abbiamo gestito l'ERP di un negozio reale per anni.

from openai import OpenAI

client = OpenAI(api_key="sk-proj-...")

assistant = client.beta.assistants.create(
    name="Supporto Negozio",
    instructions="Sei un assistente per un e-commerce di abbigliamento.\nRispondi in italiano e sii cordiale. Se non conosci un'informazione, usa gli strumenti a disposizione.",
    model="gpt-4o",
    tools=[
        {
            "type": "function",
            "function": {
                "name": "get_prezzo_prodotto",
                "description": "Ottieni il prezzo di un prodotto dato il suo ID",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "product_id": {"type": "string", "description": "ID del prodotto"}
                    },
                    "required": ["product_id"]
                }
            }
        },
        {"type": "retrieval"}
    ],
    file_ids=[]  # aggiungeremo dopo
)
print(f"Assistente creato con ID: {assistant.id}")

Nota: abbiamo abilitato sia function calling (con la funzione get_prezzo_prodotto) sia retrieval. Ora carichiamo un file per il retrieval.

Caricare file per Retrieval

Supponiamo di avere un PDF con le domande frequenti del negozio (faq_negozio.pdf). Lo carichiamo e lo associamo all'assistente:

file = client.files.create(
    file=open("faq_negozio.pdf", "rb"),
    purpose="assistants"
)

# Aggiorniamo l'assistente con il file
assistant = client.beta.assistants.update(
    assistant_id=assistant.id,
    file_ids=[file.id]
)

Ora l'assistente può cercare testualmente all'interno del PDF per rispondere a domande di tipo “quanto tempo per il reso?” o “come tracciare un ordine?”.

Creare un thread e avviare una conversazione

Il thread è la conversazione tra utente e assistente. Ogni thread è indipendente e mantiene la cronologia automaticamente.

thread = client.beta.threads.create()

# Inserisce un messaggio dell'utente
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Qual è il prezzo del prodotto con ID 'MAG-123'?"
)

Ora dobbiamo eseguire una run che fa sì che l'assistente processi il messaggio e decida se chiamare una funzione o rispondere direttamente.

run = client.beta.threads.runs.create(
    thread_id=thread.id,
    assistant_id=assistant.id
)

# Polling fino al completamento
import time
def wait_for_run(client, thread_id, run_id):
    while True:
        run = client.beta.threads.runs.retrieve(thread_id=thread_id, run_id=run_id)
        if run.status == "completed":
            return run
        elif run.status == "requires_action":
            return run
        elif run.status == "failed":
            raise Exception(f"Run fallito: {run.last_error}")
        time.sleep(1)

run = wait_for_run(client, thread.id, run.id)
print(run.status)

Se lo status è requires_action, l'assistente ha deciso di chiamare una funzione. Dobbiamo eseguire la funzione locale e restituire il risultato.

Function calling in azione

Nel nostro esempio, la funzione get_prezzo_prodotto deve essere implementata da noi. Ecco la funzione simulata e come gestire la risposta:

# Implementazione della funzione (simula accesso a database)
def get_prezzo_prodotto(product_id):
    prezzi = {
        "MAG-123": 29.99,
        "PAN-456": 49.90,
        "SCA-789": 14.50
    }
    prezzo = prezzi.get(product_id)
    if prezzo is None:
        return {"errore": "Prodotto non trovato"}
    return {"prodotto": product_id, "prezzo": prezzo}

# Se la run richiede azione
if run.status == "requires_action":
    tool_calls = run.required_action.submit_tool_outputs.tool_calls
    outputs = []
    for tool_call in tool_calls:
        if tool_call.function.name == "get_prezzo_prodotto":
            args = json.loads(tool_call.function.arguments)
            result = get_prezzo_prodotto(args["product_id"])
            outputs.append({
                "tool_call_id": tool_call.id,
                "output": json.dumps(result)
            })
    
    # Inviamo i risultati alla run
    run = client.beta.threads.runs.submit_tool_outputs(
        thread_id=thread.id,
        run_id=run.id,
        tool_outputs=outputs
    )
    
    # Attendiamo di nuovo il completamento
    run = wait_for_run(client, thread.id, run.id)

Ora possiamo leggere la risposta finale dell'assistente:

messages = client.beta.threads.messages.list(thread_id=thread.id)
for msg in messages:
    if msg.role == "assistant":
        print(msg.content[0].text.value)

L'assistente risponderà qualcosa come: “Il prodotto MAG-123 costa 29,99 €.”

Retrieval: risposte sui documenti

Se l'assistente non ha una funzione adatta, può attingere ai file caricati. Basta fare una domanda come “qual è la politica di reso?”. L'assistente cercherà nel PDF e risponderà con un estratto citato. Non devi scrivere codice aggiuntivo: è tutto gestito automaticamente dal retrieval.

Noi lo abbiamo usato per creare un chatbot per una catena di negozi: abbiamo caricato manuali prodotto, politiche di spedizione e listini. Il risultato? Risposte precise, senza lunghe mail al supporto.

Costi e considerazioni operative

Attenzione: l'Assistants API ha un costo per run, oltre ai token di input/output. I file caricati per retrieval vengono indicizzati una tantum (costo di storage). Ecco alcune stime per un caso d'uso di piccola impresa:

Run semplici (senza retrieval o funzioni): ~0.01‑0.03 $ per conversazione di 5‑6 scambi (modello gpt‑4o).
Run con retrieval: il costo sale se il documento è grande, perché ogni domanda esegue una query testuale. Conviene mantenere file sotto 50 pagine.
Function calling: aggiunge solo i token per la definizione e chiamata; se la funzione ritorna dati piccoli, l'impatto è minimo.

Noi consigliamo di testare su un ambiente di sviluppo con gpt-4o-mini (più economico) e solo in produzione passare a modelli più potenti. Monitora sempre i costi con il dashboard di OpenAI.

Errori comuni e come evitarli

Dimenticare di gestire requires_action: la run rimane in sospeso per sempre. Implementa sempre il polling con controllo dello stato.
Non validare gli input delle funzioni: i parametri arrivano come JSON, possono essere manipolati. Controlla tipi e range.
Caricare file troppo lunghi: il retrieval ha un limite di 20 MB per file e 500 file per assistente. Ma file enormi degradano la qualità della ricerca.
Usare la stessa API key in produzione e sviluppo: meglio separare gli account per non mischiare costi e limiti di rate.

Cosa fare adesso

Ecco una checklist operativa per iniziare:

Ottieni una API key e assicurati di avere un modello con supporto Assistants (gpt‑4o, gpt‑4‑turbo).
Installa o aggiorna la libreria openai.
Crea un assistente con istruzioni chiare e almeno uno strumento (retrieval o funzione).
Carica un file di esempio (un PDF con FAQ aziendali).
Scrivi una funzione reale (es. query a un database o API esterna).
Simula una conversazione con polling e submit delle funzioni.
Monitora i costi con il log di OpenAI.

Se vuoi approfondire l'integrazione con strumenti di automazione e altri provider, sei nel posto giusto. La nostra guida pillar sull’AI agentica è il punto di partenza per vedere come OpenAI Assistants si collega a strumenti come LangChain, n8n e agenti autonomi.

Noi di Meteora Web, con la nostra doppia anima tecnica e contabile, sappiamo che ogni implementazione deve avere un ritorno misurabile. Se hai un progetto concreto, parlane con noi. Intanto, prova il codice qui sopra: una run funzionante vale più di mille slide.