API di OpenAI in Python: chat, streaming e tool con GPT-5.5

Questa guida porta da zero a un programma funzionante in Python che parla con GPT-5.5, il modello attualmente di default sull'API di OpenAI. Useremo la libreria ufficiale openai, la nuova Responses API consigliata per qualunque uso che vada oltre la chat semplice, lo streaming dei token e i tool (function calling). Tutto il codice è copia-incollabile.

A chi serve, prerequisiti e cosa otterrai

Il tutorial è pensato per chi sa programmare in Python a un livello base e vuole integrare GPT-5.5 in script, bot, dashboard o piccoli agenti. Ti serviranno:

• Python 3.9 o superiore (consigliato 3.11+) installato sul tuo sistema. Verifica con python3 --version.
• Un account su platform.openai.com con almeno 5 dollari di credito a bordo. La fattura va caricata in Billing → Add to credit balance: senza credito, anche il piano gratuito di prova non basta a chiamare GPT-5.5.
• Una chiave API: si crea in Dashboard → API Keys → Create new secret key. Copiala subito: il sito la mostra una sola volta.

Al termine avrai un set di script che gestiscono: conversazioni multi-turno, output token per token in tempo reale, chiamate a funzioni esterne (per esempio: cerca su un database, leggi un file), e un piccolo agente che capisce quando usare quale strumento.

Quale modello usare per quale compito

OpenAI a maggio 2026 offre più tagli di GPT-5.5. La scelta dipende da costo, latenza e qualità del ragionamento:

Per i tuoi primi test conviene partire da gpt-5.5-mini per non bruciare credito; passerai a gpt-5.5 quando vorrai qualità su agenti e tool calling. La documentazione modelli di OpenAI riporta sempre i prezzi aggiornati.

Setup: installazione e chiave

Crea una cartella di progetto e un ambiente virtuale:

mkdir openai-tutorial && cd openai-tutorial
python3 -m venv .venv
source .venv/bin/activate     # su Windows: .venv\Scripts\activate
pip install --upgrade openai python-dotenv

Crea un file .env con la tua chiave (non committarlo mai su Git):

OPENAI_API_KEY=sk-...la-tua-chiave...

Primo programma: una chat che mantiene il contesto

La Responses API è il nuovo endpoint consigliato da OpenAI: tiene il contesto nel server, supporta i tool nativi, gestisce gli stati di un agente. Crea 01_chat.py:

import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI()  # legge OPENAI_API_KEY dall'env

resp = client.responses.create(
    model="gpt-5.5-mini",
    input="Spiegami in 4 punti che cos'è la Responses API e perché differisce dal classico chat.completions.",
)
print(resp.output_text)

Esegui con python 01_chat.py. Otterrai una risposta lunga 4 punti. Il campo magico è resp.output_text: appiattisce gli output strutturati in stringa, comodissimo per script semplici.

Conservare il contesto tra una chiamata e l'altra

Per una conversazione di più turni usa previous_response_id: la sessione resta sui server di OpenAI e non devi rispedire tu la cronologia.

r1 = client.responses.create(
    model="gpt-5.5-mini",
    input="Mi chiamo Andrea e lavoro come giornalista."
)
r2 = client.responses.create(
    model="gpt-5.5-mini",
    previous_response_id=r1.id,
    input="Qual è il mio nome e cosa faccio?"
)
print(r2.output_text)
# Atteso: "Ti chiami Andrea e fai il giornalista."

Streaming dei token in tempo reale

Quando il modello deve scrivere risposte lunghe, lo streaming dà subito feedback all'utente. Crea 02_stream.py:

from openai import OpenAI
client = OpenAI()

with client.responses.stream(
    model="gpt-5.5",
    input="Scrivi un racconto di 300 parole su un faro abbandonato."
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
    final = stream.get_final_response()
print("\n\nToken usati:", final.usage.total_tokens)

Lo streaming è quasi obbligatorio in produzione: la latenza percepita scende da 3-5 secondi a una manciata di millisecondi prima del primo token. L'oggetto event ha tipi diversi (creazione, delta, completion, tool call): in agenti complessi conviene tenere uno switch sul campo type.

Tool calling: far chiamare al modello le tue funzioni

Qui le cose si fanno serie. Definisci una funzione locale e descrivila al modello con uno schema JSON; GPT-5.5 capirà quando chiamarla. Esempio: una funzione che restituisce il meteo. Crea 03_tools.py:

import json
from openai import OpenAI
client = OpenAI()

def get_weather(city: str, unit: str = "celsius") -> dict:
    # in produzione qui chiameresti un servizio reale
    fake = {"Milano": 22, "Roma": 25, "Palermo": 28}
    temp = fake.get(city, 20)
    return {"city": city, "temp": temp, "unit": unit}

tools = [{
    "type": "function",
    "name": "get_weather",
    "description": "Restituisce la temperatura attuale di una città italiana.",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "Nome della città"},
            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
        },
        "required": ["city"]
    }
}]

resp = client.responses.create(
    model="gpt-5.5",
    input="Che tempo fa oggi a Milano e Roma?",
    tools=tools
)

for item in resp.output:
    if item.type == "function_call":
        args = json.loads(item.arguments)
        result = get_weather(**args)
        # invia il risultato del tool al modello
        followup = client.responses.create(
            model="gpt-5.5",
            previous_response_id=resp.id,
            input=[{
                "type": "function_call_output",
                "call_id": item.call_id,
                "output": json.dumps(result)
            }]
        )
        print(followup.output_text)

Il modello sceglie da solo quante volte chiamare get_weather - una per Milano, una per Roma - e poi sintetizza un'unica risposta in linguaggio naturale. In agenti più complessi si gestiscono i loop di tool con un ciclo while fino a che resp.output non contiene più function_call.

Prompt che funzionano sul tool calling

Per ridurre gli errori, scrivi una system instruction che chiarisce i confini del modello. Tre prompt che danno buoni risultati:

Sei un assistente che risponde alle domande sul meteo. Quando manca una città, chiedila. Non inventare temperature: usa sempre lo strumento get_weather.

Hai accesso allo strumento search_documents. Per qualsiasi domanda su materiale aziendale chiamalo prima di rispondere. Cita la fonte alla fine fra parentesi quadre.

Sei un agente che prenota voli. Per ogni richiesta esegui in ordine: cerca_voli, mostra_risultati, conferma_prenotazione. Non saltare passaggi.

Errori comuni e come risolverli

• 401 Unauthorized: chiave assente o sbagliata. Controlla che OPENAI_API_KEY sia esportato nella shell corrente con echo $OPENAI_API_KEY.
• 429 Rate limit: troppe richieste o troppi token al minuto. Aggiungi un retry con backoff: la libreria ufficiale gestisce già 2 retry automatici, puoi alzarli a 5 con OpenAI(max_retries=5).
• insufficient_quota: il credito è zero. Vai su Billing e ricarica.
• context_length_exceeded: hai mandato troppo testo. GPT-5.5 ha 400.000 token di contesto in input e 128.000 in output. Riduci il prompt o splitta in più chiamate.
• Tool ignorato: il modello non chiama la funzione. In genere succede quando la descrizione del tool è vaga. Sii esplicito su quando usarlo e dai un esempio in linguaggio naturale.

Strutturare l'output in JSON puro

Per pipeline di estrazione dati la parte più fragile è il parsing. Usa il parametro response_format con uno schema pydantic:

from pydantic import BaseModel

class Persona(BaseModel):
    nome: str
    anno_nascita: int
    professione: str

resp = client.responses.parse(
    model="gpt-5.5-mini",
    input="Estrai i dati: Mario Rossi, nato nel 1985, fa l'avvocato.",
    text_format=Persona
)
print(resp.output_parsed)
# Persona(nome='Mario Rossi', anno_nascita=1985, professione='avvocato')

Il vantaggio è che OpenAI garantisce la corrispondenza allo schema: niente più JSONDecodeError da gestire a valle.

Buone pratiche per il costo e la sicurezza

1. Usa il modello giusto: ogni euro speso su gpt-5.5-mini ne vale 16-25 su gpt-5.5. Sfrutta il mini come default e passa al "grande" solo quando serve.
2. Caching dei prompt: per i prompt lunghi e ripetuti OpenAI applica uno sconto automatico (fino al 90% sui token in cache). Tieni la parte stabile in cima al messaggio.
3. Mai chiavi nel codice: sempre in .env o in un secret manager. Aggiungi .env al .gitignore immediatamente.
4. Limita gli scope: in API Keys puoi creare chiavi con permessi ristretti (solo lettura, solo certi modelli). Usalo se condividi codice in team.
5. Log e tracing: in produzione conserva almeno response.id e usage.total_tokens per ogni chiamata. Servono per diagnosticare bug e contestare addebiti.

Quando non usare l'API di OpenAI

Tre casi reali: se i tuoi dati non possono uscire dall'UE, valuta Mistral o un modello open in locale (Ollama, vLLM, LM Studio). Se il costo per token è il primo vincolo, prova DeepSeek V4 Flash o Gemini 3.5 Flash, che danno qualità simile a una frazione del prezzo. Se ti serve cucire generazione e ricerca proprietaria, Claude di Anthropic offre tool nativi e ricerca file allegati con flussi più semplici da implementare.

Cosa fare adesso

Tre piste per andare oltre questa guida: leggi la documentazione ufficiale sul function calling, prova l'Agents SDK di OpenAI se vuoi costruire agenti multi-step senza scrivere tu il loop, integra una memoria persistente con un piccolo database vettoriale (Qdrant, Chroma) per dare al tuo assistente la capacità di ricordare interazioni passate. Con quello che hai fatto qui dentro, sei già in grado di costruire bot, classificatori e mini agenti pronti a essere messi in produzione.