Come definire il contratto di output di un workflow AI

Il workflow restituisce success. Nel campo totale c'è n.d.. Il gestionale accetta il record e manda avanti un ordine senza importo.

La chiamata ha funzionato. La consegna no.

Un contratto di output definisce cosa deve produrre un workflow AI, in quale struttura, con quali prove e in quali casi il risultato va rifiutato. Serve a chi riceve l'output: una persona, un altro software o un passaggio operativo.

Lo schema chiude la forma. Non chiude la verità. Un JSON valido può contenere una data inventata, una fonte assente o una decisione che il workflow non era autorizzato a prendere.

Parti dal consumer

Prima di scegliere i campi, scrivi chi usa il risultato e quale azione farà dopo.

Un riepilogo letto da un operatore può tollerare una frase incompleta e chiedere una correzione. Un record che aggiorna un ordine richiede tipi rigidi, controlli e uno stop path. Stesso modello. Conseguenze diverse.

La scheda iniziale può contenere:

Il contratto di input del workflow AI governa ciò che entra. Il contratto di output governa il passaggio opposto. Tenere i due confini separati evita di trattare un input ben formato come garanzia di un risultato buono.

Dai un'identità a ogni consegna

!Passaggio controllato di un output AI verso il processo aziendale che lo utilizza

*Il contratto collega la consegna al consumer, alle evidenze e alla verifica. — Visual originale MAIKER HUB*

Un output senza identità diventa difficile da correggere. Non sai quale corsa l'ha prodotto, quale versione del prompt era attiva o se un retry ha creato due risultati.

Campi utili:

contract_version: output-order-v3
result_id: res-20260822-00418
run_id: run-20260822-00418
producer_version: workflow-17
status: needs_review
generated_at: 2026-08-22T09:14:32+02:00

I valori sono fittizi. Il punto è il legame. result_id identifica la consegna, run_id identifica l'esecuzione e contract_version dice come leggerla.

Separa involucro e payload

L'involucro contiene ciò che serve a governare il risultato. Il payload contiene il dato di business.

{
  "contract_version": "output-order-v3",
  "result_id": "res-20260822-00418",
  "status": "needs_review",
  "payload": {
    "supplier": "Example Srl",
    "currency": "EUR",
    "total": null
  },
  "evidence": [
    {"field": "supplier", "source_ref": "doc-7#page=1"}
  ],
  "warnings": ["total_missing"],
  "next_action": "route_to_accounts_payable"
}

Questa divisione permette di validare il payload senza perdere stato, prove e percorso di recovery.

Usa lo schema per ciò che sa controllare

La specifica JSON Schema distingue la base del formato dalle regole di validazione. Puoi descrivere tipi, campi richiesti, valori ammessi e vincoli tra dati.

Esempio ridotto:

{
  "type": "object",
  "required": ["currency", "total"],
  "properties": {
    "currency": {"enum": ["EUR", "USD", "GBP"]},
    "total": {"type": "number", "minimum": 0}
  },
  "additionalProperties": false
}

Lo schema può respingere totale: molto. Non può stabilire se 1430.00 corrisponde al documento. Per quello servono una fonte, un confronto e una regola di decisione.

Si chiama doppio gate: prima struttura, poi significato.

Collega i campi alle prove

Una citazione generica in fondo all'output aiuta poco. Collega la prova al campo o al claim che sostiene.

Il localizzatore può essere una pagina, una riga, un record o un timestamp. Deve permettere a chi revisiona di ritrovare la prova senza rifare tutto il lavoro.

Il NIST Generative AI Profile include ground truth, supervisione umana, review degli input e più metodi tra le pratiche di valutazione degli output. Tradotto nel contratto: un solo segnale non basta per i campi che muovono soldi, diritti o comunicazioni esterne.

Definisci stati che cambiano il flusso

!Tre stati di controllo qualità per accettare, rivedere o fermare un output AI

*Stati leggibili trasformano la qualità in una decisione operativa. — Visual originale MAIKER HUB*

Success e error sono troppo poveri. Usa stati collegati a un comportamento.

• accepted: struttura e controlli previsti sono verdi

• partial: una parte utile esiste, ma non basta per chiudere il task

• needs_review: serve una decisione umana prima del passaggio successivo

• rejected: il risultato non rispetta il contratto

• abstained: il workflow dichiara di non avere evidenza sufficiente

Un risultato partial non deve entrare per caso nel percorso di accepted. Il consumer decide esplicitamente quali stati può leggere e cosa fare con ciascuno.

Scrivi il rifiuto prima del caso buono

Il percorso felice arriva facile. I difetti costosi stanno nei bordi.

Definisci prima almeno questi casi:

Il rifiuto deve essere machine-readable e comprensibile a chi lavora. ERR_42 senza spiegazione crea solo un altro ticket.

Versiona senza rompere chi riceve

Aggiungere un campo facoltativo non ha lo stesso impatto di rinominare total in amount. Il primo cambiamento può essere compatibile. Il secondo può spezzare il consumer.

Per ogni nuova versione registra:

• cosa cambia

• quali consumer sono coinvolti

• esempio prima e dopo

• test di compatibilità

• data di uscita

• percorso di ritorno

Conserva i vecchi contratti finché esistono output storici o consumer che li usano. Cancellarli rende il passato illeggibile.

Costruisci i test dal contratto

Il dataset di test per un workflow AI deve includere casi buoni e casi da fermare.

Un set minimo può contenere:

1. record completo e sostenuto da prove

2. tipo errato in un campo obbligatorio

3. valore plausibile senza fonte

4. fonti in conflitto

5. campo nuovo ignorato da un consumer precedente

6. retry della stessa esecuzione

7. output corretto destinato al consumer sbagliato

Ogni caso dichiara l'esito atteso. Se il workflow passa un test perché il valutatore ha chiuso un occhio, il contratto non sta funzionando.

Lascia alla review un pacchetto completo

La review umana non deve ricevere solo il testo generato. Servono input rilevante, output, fonti, differenze, warning e azioni ammesse.

La checklist per verificare un output AI aiuta sul singolo risultato. Il contratto fa un lavoro diverso: decide cosa il reviewer deve trovare già pronto e quale disposizione può assegnare.

Un pulsante Approva non basta. Le disposizioni utili sono più precise: accetta, correggi, richiedi fonte, rimanda al producer, blocca il consumer.

Misura le rotture del confine

Non contare soltanto quanti output sono stati prodotti. Guarda dove il contratto si rompe.

Misure operative:

• output rifiutati per campo

• claim senza prova

• review aperte oltre la finestra prevista

• consumer che ricevono una versione non supportata

• retry duplicati

• correzioni umane per categoria

• risultati accettati poi riaperti

Una quota alta di rifiuti non è sempre un male. Può mostrare che il gate sta fermando casi che prima passavano in silenzio.

Un esempio fittizio

Un workflow legge richieste di acquisto e prepara un record per il gestionale. Il contratto richiede fornitore, valuta, totale, centro di costo e localizzatore della prova.

Nel caso A i cinque campi sono presenti, lo schema è valido e ogni valore punta al documento. Stato: accepted.

Nel caso B il totale non è leggibile. Il modello propone 1.430, ma non trova una riga che lo sostenga. Il contratto vieta di trasformare l'ipotesi in numero. Stato: needs_review. Il gestionale non riceve nulla.

Nel caso C il consumer è offline dopo che il record è stato preparato. Stato: partial. Il retry riusa lo stesso result_id e prima riconcilia la destinazione. Niente doppio ordine.

Tre casi. Tre azioni diverse. La parola success non li avrebbe distinti.

Gli errori che svuotano il contratto

Il primo è descrivere solo il JSON. Manca la decisione.

Il secondo è rendere facoltativi tutti i campi per evitare errori. Così il contratto accetta qualunque cosa.

Il terzo è usare una confidence del modello come prova. Il numero può aiutare il routing, ma non sostituisce una fonte o un test.

Il quarto è inviare null e stringa vuota come se fossero la stessa assenza. Il consumer perde il motivo.

Il quinto è correggere manualmente l'output senza conservare la versione originale e la disposizione. Non sai più cosa ha prodotto il workflow.

Think, Build, Enable applicato all'output

Think: identifica consumer, decisione successiva, danno possibile e campi che devono essere provati.

Build: crea involucro, schema, stati, evidenze, rifiuti, versioni e test. Collega ogni difetto a un'azione.

Enable: assegna owner del contratto, reviewer e percorso di recovery. Mostra le rotture con misure leggibili.

Porta il contratto del tuo workflow alla consulenza roadmap e governance AI di MAIKER HUB. Il punto di partenza è un output reale che oggi passa, anche quando non dovrebbe.

Fonti e riferimenti

• NIST AI Risk Management Framework

• NIST AI 600-1: Generative AI Profile

• Commissione europea: quadro normativo sull'intelligenza artificiale