TL;DR: la Assistants API verrà spenta il 26 agosto 2026. Se un chatbot, un plugin WordPress o un’automazione usa ancora Assistant, Thread e Run, non basta cambiare endpoint. Responses API sposta più responsabilità nell’applicazione: configurazione, stato, tool loop, retry e osservabilità. La migrazione più sicura parte dai nuovi utenti, mantiene il vecchio percorso come rollback, confronta gli output su casi reali e sposta il traffico solo quando conversazioni e azioni producono risultati equivalenti.

Il 3 agosto 2026 mancano 23 giorni allo shutdown della Assistants API. La guida ufficiale di migrazione OpenAI indica il 26 agosto 2026 come data di spegnimento e propone la nuova mappa: Assistant diventa una configurazione, Thread diventa Conversation, Run diventa Response, mentre i Run step diventano Item.

Letta così, sembra una rinomina. Non lo è. Il cambiamento importante è il confine operativo. Con Assistants molte decisioni vivevano dentro oggetti persistenti gestiti dall’API. Con Responses l’applicazione deve sapere con più precisione quale configurazione sta usando, quali item appartengono alla conversazione, quando eseguire un tool, come registrare l’esito e cosa fare se una chiamata fallisce a metà.

Per una PMI questo non richiede una riscrittura totale. Richiede una migrazione con inventario, adapter, test di parità e rollback. Il rischio maggiore non è ricevere una risposta leggermente diversa. È perdere lo stato di una conversazione, eseguire due volte un’azione su WordPress o scoprire il 26 agosto che una parte del flusso dipendeva da un Run che nessuno aveva censito.

Prima domanda: dove usi davvero Assistants API?

Non partire dal codice nuovo. Parti dall’inventario del vecchio sistema. Cerca gli identificativi asst_, thread_ e run_ nel codice, nelle variabili di ambiente, nei log, nei database e nelle configurazioni di n8n, Make o plugin custom. Un’integrazione nata come prototipo può essere finita in più punti di quanto ricordi.

Per ogni flusso registra almeno:

  • Assistant usato, istruzioni, modello, strumenti e formato dell’output;
  • origine della richiesta: form, area clienti, back office, cron o webhook;
  • dove viene conservato il thread_id e a quale utente o pratica è associato;
  • azioni esterne possibili, come creare una bozza, aggiornare un CRM o inviare una notifica;
  • timeout, retry, polling del Run e comportamenti in caso di errore;
  • dati che devono restare disponibili per audit, assistenza o obblighi contrattuali.

Questo inventario separa tre classi. I flussi senza stato sono i più facili: una richiesta entra, una risposta esce. I flussi conversazionali richiedono una strategia per Threads e Conversations. I flussi con tool sono i più delicati, perché una migrazione sbagliata può generare effetti esterni anche quando la risposta testuale sembra corretta.

La nuova mappa cambia le responsabilità

La documentazione OpenAI descrive quattro passaggi principali:

  • Assistants → configurazione o prompt versionato;
  • Threads → Conversations composte da item;
  • Runs → Responses;
  • Run steps → Items, che possono rappresentare messaggi, chiamate tool e relativi output.

La differenza utile è negli item. Un Thread conteneva messaggi. Una Conversation può contenere anche chiamate a strumenti e risultati. Questo rende il tracciamento più coerente, ma obbliga l’applicazione a distinguere ciò che il modello ha detto da ciò che ha chiesto di eseguire e da ciò che il codice ha davvero eseguito.

Anche il Run cambia forma. Una Response può essere usata da sola oppure collegata a una Conversation. Il ciclo delle chiamate tool è esplicito: l’applicazione deve ricevere la richiesta, validare gli argomenti, decidere se l’azione è autorizzata, eseguirla, registrare l’output e continuare la risposta. È lo stesso principio che applico alle integrazioni MCP e REST per WordPress: il modello propone un’azione; il confine applicativo decide se e come eseguirla.

Caso studio: assistente che prepara bozze WordPress

Immagina un assistente interno che trasforma una nota commerciale in una bozza WordPress. L’utente descrive servizio, pubblico e punti tecnici. L’assistente chiede chiarimenti, propone titolo ed excerpt, poi chiama un tool create_wordpress_draft. Il tool valida il JSON e crea un post con status=draft.

Nel vecchio percorso l’applicazione salva un thread_id, aggiunge il messaggio, avvia un Run e interroga lo stato finché il Run termina o richiede un’azione. Nel nuovo percorso crea o recupera una Conversation, invia gli item a Responses API e gestisce l’eventuale chiamata tool.

La migrazione non deve cambiare nello stesso momento API, prompt, modello e logica WordPress. Se lo fai, quando il risultato peggiora non sai quale variabile ha causato il problema. Mantieni invarianti il contratto del tool, la validazione e il payload WordPress. Cambia prima l’orchestrazione. La guida su come validare l’output AI in JSON prima di WordPress resta valida: la nuova API non rende affidabili campi, tassonomie o URL per magia.

Il contratto minimo del tool dovrebbe includere una chiave idempotente. Se la Response viene ritentata dopo un timeout, l’applicazione deve poter riconoscere che la bozza esiste già. Una chiave come tenant_id + session_id + operation_id, salvata nei metadati del post o in una tabella applicativa, evita che due esecuzioni creino due bozze.

Costruisci un adapter, non riscrivere tutto

La strada più corta è introdurre un’interfaccia interna che nasconda il fornitore e la versione dell’API al resto dell’applicazione. Il form, il plugin o il workflow inviano sempre la stessa richiesta al tuo adapter. È l’adapter a scegliere il backend legacy o Responses.

request -> ai_adapter -> assistants_backend
                      \-> responses_backend

normalized_result = {
  text,
  conversation_id,
  tool_requests,
  usage,
  status,
  error
}

Normalizza solo ciò che serve al prodotto. Non provare a riprodurre ogni campo dei vecchi oggetti. Se l’interfaccia utente usa testo, stato, identificativo conversazione e richieste tool, sono questi i dati da stabilizzare. Il resto può restare nei log tecnici del backend.

L’adapter permette tre operazioni decisive: eseguire gli stessi casi sui due percorsi, spostare una quota di traffico senza modificare il frontend e tornare al legacy con una configurazione. Il rollback deve cambiare un flag o una regola di routing, non richiedere un deploy d’emergenza.

Thread e Conversation: migra prima i nuovi utenti

OpenAI specifica che non fornirà uno strumento automatico per convertire tutti i Thread in Conversation. La raccomandazione è spostare le nuove chat sul nuovo sistema e recuperare quelle vecchie solo quando serve. Per la maggior parte delle PMI è anche la scelta più economica.

Definisci una data di taglio. Le sessioni create dopo quella data ricevono un conversation_id. Le sessioni precedenti continuano sul vecchio Thread finché sono attive oppure vengono migrate quando l’utente le riapre. Conserva nel database un campo esplicito come backend=assistants|responses; non dedurre il backend dal prefisso dell’ID in ogni punto del codice.

Prima di importare una conversazione storica, decidi quanto passato serve davvero. Copiare anni di messaggi aumenta costo, latenza e superficie dati senza garantire una risposta migliore. Per un’assistenza WordPress può bastare un riepilogo verificato, gli ultimi scambi e i riferimenti alla pratica. Per un audit, invece, la cronologia integrale può essere un requisito. La retention va scelta per caso d’uso, non per comodità dell’API.

Tool loop: il punto in cui si rompono le migrazioni

Una risposta testuale sbagliata si corregge. Un tool eseguito due volte può inviare due email, creare due ordini o pubblicare due contenuti. Per questo il percorso tool merita test separati.

Userei una macchina a stati piccola e persistente:

received -> model_called -> tool_requested -> authorized
                                      \-> rejected
authorized -> tool_executed -> output_recorded -> completed
                           \-> retryable_error
                           \-> manual_review

Ogni richiesta tool deve avere nome consentito, schema degli argomenti, limite di tempo, policy di retry e classe di rischio. Le letture possono procedere in automatico. Le scritture su WordPress devono restare in bozza. Publish, delete, invii e pagamenti richiedono un gate esterno al modello.

La stessa cautela vale per i timeout. Se il client non riceve la risposta, non significa che il tool non sia stato eseguito. Prima di ritentare, interroga il registro tramite la chiave idempotente. Un retry cieco è una duplicazione in attesa di accadere.

Come misurare la parità prima dello switch

Prepara un set di casi reali anonimizzati, non una demo inventata il giorno del test. Per un assistente collegato a WordPress includerei richieste semplici, conversazioni lunghe, input incompleti, JSON malformato, tool rifiutato, timeout, duplicato e recupero dopo errore.

Confronta almeno:

  • correttezza e completezza dell’output;
  • validità dello schema strutturato;
  • percentuale di tool call corrette e autorizzabili;
  • duplicati o azioni mancanti;
  • latenza mediana e coda lunga;
  • token e costo per caso completato;
  • capacità di ricostruire nei log input, decisione, tool e risultato.

La parità non significa testo identico. Significa stesso esito operativo entro tolleranze dichiarate. Se entrambi producono una bozza valida, assegnano la categoria corretta e rispettano il gate di pubblicazione, la formulazione può cambiare. Se uno dei due salta un controllo, non sono equivalenti.

Il tema è lo stesso affrontato nell’articolo su AI e qualità oltre il volume: più output non equivale a più lavoro completato. Conta la percentuale di casi che attraversano tutti i controlli senza correzioni o incidenti.

Rollout in cinque fasi con rollback reale

  1. Shadow. Il legacy serve l’utente; Responses elabora gli stessi casi senza eseguire tool esterni. Confronti gli esiti offline.
  2. Nuove sessioni. Le nuove conversazioni entrano su Responses. I Thread esistenti restano sul percorso legacy.
  3. Canary. Una quota piccola e identificabile usa il nuovo backend. Gli errori e i tool rifiutati generano alert.
  4. Default. Responses diventa il percorso principale; Assistants resta disponibile solo per rollback e sessioni non migrate.
  5. Chiusura. Disattivi la creazione di nuovi Thread, esporti ciò che devi conservare, rimuovi polling e credenziali non più usate.

Ogni fase deve avere una condizione di uscita numerica e una soglia di rollback. Esempio: nessuna azione duplicata, almeno il 98% di output conforme allo schema, tasso di errore non superiore al legacy e log completi per tutte le tool call. Le soglie vanno adattate al rischio del flusso; un generatore di bozze e un sistema che aggiorna ordini non hanno lo stesso margine.

La mia take: non affidare la migrazione a un nuovo oggetto persistente

La documentazione propone di convertire gli Assistant in prompt versionati, ma avverte anche che i reusable prompt object sono a loro volta in deprecazione. Tratterei quindi il prompt gestito come un ponte, non come l’unica fonte di verità del prodotto.

Conserva una specifica esportabile e revisionabile: istruzioni, tool schema, formato dell’output, modello compatibile ed eval associati. L’ID remoto può puntare alla versione attiva, ma il contratto deve poter essere ricostruito senza inseguire un oggetto nel dashboard. Questa scelta riduce il prossimo lock-in e rende possibile confrontare due versioni con un diff comprensibile.

La scadenza del 26 agosto crea urgenza, non giustifica una migrazione cieca. Il lavoro minimo sensato è censire, isolare l’orchestrazione, migrare le nuove sessioni, provare i tool senza effetti esterni e definire il rollback. Se oggi non sai quale Run ha creato una bozza o perché un tool è stato ritentato, Responses API non risolverà il problema. Lo renderà soltanto più visibile.

Cosa fare oggi

  1. Cercare tutti gli ID e gli endpoint Assistants nel codice e nelle automazioni.
  2. Classificare i flussi in stateless, conversazionali e tool-based.
  3. Bloccare nuovi sviluppi sulla Assistants API.
  4. Creare un adapter con backend legacy e Responses.
  5. Instradare le nuove conversazioni su Conversation senza migrare tutto lo storico.
  6. Eseguire i test di parità con tool in modalità shadow.
  7. Attivare un canary con soglie di rollback scritte prima dello switch.

Ventitré giorni bastano per un passaggio controllato se il perimetro è chiaro. Non bastano per scoprire dipendenze nascoste la settimana dello shutdown.

Fonti