La Decisions API di OpenAI entra in beta pubblica

OpenAI ha aperto al pubblico la beta della sua Decisions API: un endpoint dedicato che restituisce probabilità, scelte e punteggi da rubrica invece di testo generato, circa 10 volte più veloce della Responses API. Ecco cosa espone e dove si colloca nelle pipeline per agenti e automazione.

La Decisions API di OpenAI è ora in beta pubblica. Valuta testo, immagini o entrambi tramite l'endpoint dedicato /v1/decisions e restituisce risposte tipizzate: una probabilità predicate da 0 a 1, una choice da un insieme fisso o uno score calcolato come media pesata per probabilità di livelli ordinati. OpenAI la documenta come circa 10 volte più veloce della Responses API, con gpt-6-luna come unico modello della beta. È pensata per classificazione, routing e prioritizzazione.

Classificazione, routing e triage sono tra i compiti più comuni affidati ai modelli linguistici, e finora significavano quasi sempre usare un endpoint di generazione come motore di decisioni: si invoca il modello, si analizza il testo libero o il JSON restituito e si valida la struttura a mano. OpenAI ora offre una superficie più ristretta pensata esattamente per questo tipo di lavoro. L'azienda ha aperto al pubblico la beta di una Decisions API, documentata nelle guide della sua piattaforma per sviluppatori, e il lancio ha attirato subito l'attenzione su Hacker News, raccogliendo circa 250 punti e oltre cento commenti.

Cosa espone la Decisions API

Secondo la documentazione di OpenAI, la Decisions API valuta testo, immagini o entrambi e restituisce risposte tipizzate circa 10 volte più velocemente della Responses API. Opera su un endpoint dedicato POST /v1/decisions e, durante la beta, l'unico modello supportato è gpt-6-luna. OpenAI dichiara che la disponibilità generale è attesa nelle prossime settimane, quindi la superficie potrebbe ancora cambiare prima di stabilizzarsi.

Una richiesta ha tre parti. Il campo model indica il modello che valuta la richiesta. L'input trasporta le evidenze condivise per tutte le domande, come stringa di testo o come messaggi utente contenenti testo e immagini. L'array questions descrive cosa valutare, includendo tipo, istruzioni ed eventuali opzioni o livelli di punteggio ammessi per ciascuna domanda. La risposta contiene un array answers in cui ogni voce è identificata dal nome univoco assegnato alla domanda corrispondente, poiché l'API restituisce quel nome.

Tre tipi di domanda, tre forme di risposta

L'API offre tre tipi di domanda, ognuno con una forma di risposta diversa. La documentazione è esplicita su quale scegliere.

• predicate: verifica se una condizione è vera, come un danno visibile in una foto o la pertinenza di un passaggio, e restituisce una stima di probabilità da 0 a 1.

• choice: seleziona un'opzione da un insieme fisso fornito dall'utente, come un reparto o una categoria di contenuto, e restituisce uno di quei valori.

• score: valuta un input su livelli ordinati, come la gravità di un problema, e restituisce la media degli indici dei livelli pesata per probabilità.

La distinzione tra gli ultimi due conta in pratica. Sia choice che score restituiscono probabilità su opzioni discrete, ma choice serve per categorie senza ordine, mentre score per livelli ordinati. Poiché uno score è la media pesata per probabilità di indici numerici, il risultato può cadere tra due livelli, il che si adatta meglio a scale graduate come la gravità rispetto a una scelta forzata.

Un esempio pratico: controllo di una foto di prodotto

L'esempio principale della guida è una domanda predicate che ispeziona la foto di un prodotto alla ricerca di danni visibili. L'input combina un'istruzione testuale con un'immagine codificata in base64, e la domanda chiede se il prodotto presenta crepe, strappi o ammaccature, indicando esplicitamente al modello di ignorare ombre e danni alla confezione. Lo stesso schema si estende al testo: la guida mostra controlli di pertinenza sui messaggi dei clienti, dove una richiesta chiaramente correlata ottiene 1.00 e una domanda sui resi dopo 30 giorni ottiene 0.90 rispetto a una risposta di policy.

import { readFile } from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI();
const imageBase64 = (await readFile("product.png")).toString("base64");

const decision = await client.decisions.create({
  model: "gpt-6-luna",
  input: [
    {
      role: "user",
      content: [
        { type: "input_text", text: "Inspect the product in this photo." },
        { type: "input_image", image_url: `data:image/png;base64,${imageBase64}` },
      ],
    },
  ],
  questions: [
    {
      type: "predicate",
      name: "visible_damage",
      instructions:
        "Does the product have visible damage, such as a crack, tear, or dent? " +
        "Ignore shadows and damage to the packaging.",
    },
  ],
});

const answer = decision.answers[0];
if (answer.type === "refusal") {
  console.log(`Refused: ${answer.name}`);
} else if (answer.type === "predicate") {
  console.log(`Visible damage probability: ${answer.probability}`);
}

Un dettaglio da notare per il codice di produzione: l'array answers può contenere un refusal. Gli esempi degli SDK verificano il tipo di risposta prima di leggere una probabilità, una differenza piccola ma reale rispetto al trattare ogni risposta del modello come output utilizzabile.

Come si differenzia da completions e Structured Outputs

OpenAI traccia il confine con chiarezza. Usate Decisions quando l'applicazione richiede uno dei tre tipi di risposta descritti. Usate Structured Outputs con la Responses API quando dovete generare un oggetto che segua il vostro schema JSON, come campi estratti o una spiegazione scritta. Usate la chiamata di funzioni quando serve che il modello richieda una tool call con argomenti. In altre parole, Decisions non sostituisce la generazione: è un endpoint specializzato per domande le cui risposte sono probabilità, categorie o punteggi.

La conseguenza pratica è architetturale. Una pipeline che oggi chiede a un modello conversazionale di classificare un ticket e rispondere in JSON può spostare il passo di classificazione su un endpoint tipizzato e riservare la generazione ai passi che richiedono davvero testo. Questa separazione rende anche i punti decisionali più facili da testare, poiché ogni domanda ha un nome, un tipo e una risposta misurabile invece di un blocco di testo da analizzare.

Dove si colloca nelle architetture per agenti e automazione

I casi d'uso documentati sono classificazione, instradamento delle richieste e prioritizzazione del lavoro. In uno stack di agenti sono esattamente i punti decisionali frequenti e sensibili alla latenza che si collocano tra passi di generazione più costosi: decidere quale flusso gestisce un messaggio in arrivo, valutare la gravità di un problema secondo una rubrica o subordinare una revisione umana a una soglia di probabilità.

• Triage dell'assistenza: valutare i ticket in arrivo rispetto ai livelli di gravità e instradare prima agli umani i punteggi più alti.

• Content operations: classificare documenti o immagini in un insieme fisso di categorie prima dell'archiviazione o della revisione.

• Quality gate: usare un predicate come controllo economico prima di avviare un passo di generazione più lungo e costoso.

• Filtraggio di pertinenza: misurare se una domanda dell'utente è davvero soddisfatta da un articolo della knowledge base, come negli esempi documentati.

Poiché l'input è un'evidenza condivisa per tutte le domande, una singola richiesta può porre più quesiti contemporaneamente, ad esempio se un'immagine mostra danni, a quale categoria appartiene il problema e quanto è grave, senza tre chiamate di generazione separate. Le risposte arrivano come array nominato che si mappa direttamente sulla logica di ramificazione del codice.

Supporto SDK e primi passi

La funzionalità è disponibile tramite gli SDK ufficiali, con versioni minime indicate nella guida: Python 3.26.0, JavaScript 7.30.0, Go 3.73.0, Ruby 0.101.0 e Java 4.78.0. OpenAI suggerisce anche di provare l'API nel Playground per sperimentare domande e input prima di scrivere codice. L'autenticazione segue lo schema standard di una chiave API esportata come variabile d'ambiente, che gli SDK leggono automaticamente.

Note sulla gestione dei dati

Tutto ciò che valutate transita dalla piattaforma OpenAI, quindi valgono i consueti controlli sui dati. I dati inviati all'API OpenAI non vengono usati per addestrare o migliorare i modelli salvo consenso esplicito, una policy in vigore dal 1° marzo 2023. I log di monitoraggio degli abusi vengono generati per impostazione predefinita e conservati fino a 30 giorni, e i clienti che ne hanno i requisiti possono richiedere Zero Data Retention o Modified Abuse Monitoring, previa approvazione e requisiti aggiuntivi.

Per i team che valutano la beta, la lettura sensata è che Decisions è una primitiva infrastrutturale più che una funzionalità di prodotto. Conterà di più dove le decisioni sono ad alto volume, sensibili alla latenza e ripetibili, e meno dove la risposta richiede spiegazioni o sfumature. Il limite del modello singolo e l'etichetta beta suggeriscono entrambi di sperimentare su flussi interni prima di spostare su di essa i percorsi rivolti ai clienti.

Come valutare la beta nella pratica

1. Scegliete un flusso interno con un punto decisionale chiaro, come il routing dei ticket o lo screening di immagini, ed esprimete le sue domande come predicate, choice o score.

2. Eseguite casi storici tramite Playground e API, confrontando probabilità e punteggi con le etichette attuali o con le decisioni umane.

3. Definite soglie esplicite per agire sulle probabilità, e registrate i refusal separatamente dalle risposte, per gestirli come caso a sé.

4. Mantenete un percorso di fallback tramite la Responses API con Structured Outputs finché l'API non raggiunge la disponibilità generale e la gamma di modelli non si amplia.

La Decisions API comprime uno schema che molti team hanno costruito a mano: domande vincolate, risposte tipizzate e valutazione rapida. Se si guadagnerà un posto stabile nelle architetture per agenti dipenderà da come si comporterà la beta sotto traffico reale, ma la superficie che espone è facile da capire e semplice da confrontare con quanto già in uso.