Come creare un contratto degli input per un workflow AI

Il file arriva alle 07:02. Si chiama clienti_finale_v4_OK.xlsx. La colonna che ieri conteneva l'email oggi contiene una nota libera.

Il workflow lo apre lo stesso. Il modello prova a capire. Da quel momento ogni controllo sull'output parte già in ritardo.

Per creare un contratto degli input per un workflow AI devi dichiarare quali fonti sono ammesse, quale versione e formato accetti, quali campi servono, quanto può essere vecchio il dato, quali trasformazioni sono consentite e cosa succede quando una regola non passa. Il risultato è una funzione operativa che sa accettare, mettere in quarantena o rifiutare ogni ingresso, non un documento decorativo.

Il contratto agisce prima del modello

Un prompt può chiedere di ignorare righe incomplete. Non può provare da dove arriva il file, quale versione dello schema usa o se una trasformazione precedente ha tagliato una colonna.

Il NIST AI 600-1 propone di documentare origine e lineage, valutare i flussi di dati e contenuti, registrare le dipendenze upstream e rivedere l'idoneità dei dati nelle fasi del ciclo di vita AI. Sono azioni di gestione del rischio per sistemi generativi. Non sono uno schema pronto per il tuo processo.

Qui il contratto trasforma quelle domande in controlli eseguibili.

Il dataset di test per un workflow AI serve a verificare il comportamento su casi congelati. La checklist per verificare un output AI controlla ciò che esce. Il contratto degli input decide se il caso può entrare.

Inizia dall'inventario delle fonti

Elenca le fonti reali. Non scrivere documenti aziendali.

source_id	Origine	Trasporto	Owner	Frequenza
CRM-CONTACTS	vista contatti approvata	API	sales operations	su evento
BRIEF-UPLOAD	form brief	file upload	account team	su richiesta
CATALOG-DAILY	export catalogo	object storage	product operations	giornaliera

La tabella usa nomi fittizi. Il punto è assegnare un ID stabile a ogni origine. Un file caricato a mano e un export automatico possono avere lo stesso formato, ma non la stessa provenienza o affidabilità.

Collega l'elenco all'inventario dei workflow AI in azienda. Il workflow dichiara da quali source_id dipende. La fonte dichiara quali workflow consumano i suoi dati. Così una modifica non resta invisibile.

Scrivi lo schema minimo

Il contratto non deve descrivere ogni colonna disponibile. Descrive quelle necessarie alla decisione.

Per ciascun campo indica:

• nome canonico
• tipo
• obbligatorietà
• valori ammessi o formato
• regola per il valore nullo
• eventuale classificazione
• owner della definizione

Un esempio:

contract_id: INPUT-BRIEF-03
source_id: BRIEF-UPLOAD
schema_version: 3
accepted_formats:
  - application/pdf
  - text/markdown
required_metadata:
  request_id: string
  submitted_at: datetime_with_timezone
  language: enum[it,en]
  consent_state: enum[confirmed,not_required]
max_age: P7D
on_invalid: quarantine

P7D è un esempio ISO 8601 per una durata di sette giorni. Non è una freschezza giusta per tutti. Un catalogo può cambiare ogni ora. Una policy approvata può restare valida per mesi.

Separa presenza, forma e significato

Tre controlli diversi vengono spesso chiamati validazione.

La presenza chiede se il campo esiste. La forma controlla se rispetta tipo e formato. Il significato verifica se il valore è ammissibile nel processo.

event_date: 2026-13-44 fallisce la forma. event_date: 2025-04-02 può essere formalmente valida, ma non ammissibile per un nuovo evento nel 2026. budget: 0 può essere valido per una voce gratuita oppure indicare un dato mancante mascherato.

Il contratto assegna un codice a ogni fallimento:

Codice	Livello	Azione
FIELD_MISSING	presenza	rifiuta o chiedi integrazione
FORMAT_INVALID	forma	rifiuta
VALUE_OUTSIDE_POLICY	significato	metti in quarantena
SOURCE_NOT_ALLOWED	provenienza	rifiuta e registra

Il testo leggibile serve alla persona. Il codice serve al workflow e alle metriche.

Registra provenienza e trasformazioni

La provenienza non è soltanto l'URL da cui hai scaricato un file.

Registra almeno source_id, timestamp di acquisizione, versione, hash dell'oggetto e trasformazioni applicate. Se il dato passa da CSV a JSON, se un campo viene rinominato o se due fonti vengono unite, il passaggio entra nel lineage.

input_id: IN-20260818-771
source_id: CATALOG-DAILY
acquired_at: 2026-08-18T07:02:11+02:00
source_version: export-184
source_hash: sha256:example
transformations:
  - normalize_currency:v2
  - map_category:v5
contract_version: 4

Hash e ID sono fittizi. In produzione, l'hash non prova che il contenuto è vero. Prova soltanto quale contenuto hai elaborato.

Il NIST AI 600-1 distingue origine, flusso, trasformazioni e dipendenze upstream. Questa distinzione torna utile quando un output cambia e devi capire se è cambiato il modello, il prompt o ciò che è entrato.

Definisci la freschezza per decisione

Dato recente non è un controllo.

Scrivi la data di riferimento e l'età massima per l'uso specifico. Una scheda venue aggiornata sei mesi fa può bastare per una prima lista. Non basta per confermare disponibilità, capienza o accessibilità oggi.

Il contratto può avere più stati:

• fresh_for_draft
• fresh_for_review
• fresh_for_action
• expired

Così un input vecchio può ancora aiutare a preparare domande, ma non autorizza un'azione esterna.

Evita un valore di default unico. La freschezza viene dal processo e dalla fonte, non dal modello.

Classifica prima di inviare al modello

Il contratto decide quali campi possono entrare nel contesto. Non copiare tutto perché potrebbe servire.

Per ogni campo usa una classe semplice:

Classe	Uso nel workflow
public	può entrare nel contesto previsto
internal	entra solo nell'ambiente approvato
restricted	richiede un percorso specifico
prohibited	non entra nel workflow

I nomi delle classi sono esempi. Le categorie reali devono combaciare con policy, contratti e requisiti applicabili.

Il filtro avviene prima della chiamata al modello. Chiedere al modello di non leggere una colonna dopo avergliela inviata non è un filtro.

Usa la quarantena per i casi correggibili

Rifiuto e quarantena non sono sinonimi.

Rifiuta una fonte non ammessa, un formato pericoloso o un requisito essenziale assente. Metti in quarantena un caso che una persona autorizzata può correggere senza cambiare la regola.

La quarantena conserva:

• input_id
• codice motivo
• riferimento alla fonte
• versione del contratto
• correzioni consentite
• owner
• scadenza

Non conserva una copia incontrollata in una chat. La persona apre il dato nel sistema previsto.

Quando corregge, nasce una nuova versione dell'input. Il record originale resta collegato. Nessuna sovrascrittura silenziosa.

Controlla le trasformazioni

Una trasformazione può sembrare innocua e cambiare il significato.

Tagliare spazi è diverso dal sostituire valori mancanti. Convertire una data è diverso dal dedurre il fuso. Tradurre un'etichetta è diverso dal riclassificare una categoria.

Per ogni trasformazione dichiara input, output, versione, assunzioni e test. Se usa un LLM, trattala come un passaggio probabilistico. Salva il testo di origine e il risultato per i casi sottoposti a verifica, entro i limiti applicabili.

Un contratto utile permette soltanto trasformazioni elencate. Se compare una funzione nuova, il workflow si ferma finché la versione del contratto non viene aggiornata.

Versiona il contratto

Il produttore di dati non può cambiare una colonna il venerdì e sperare che tutti i consumer si adattino lunedì.

Ogni versione dichiara:

• differenza dalla precedente
• compatibilità
• data di entrata in vigore
• consumer coinvolti
• finestra di test
• percorso di ritorno

Una modifica compatibile aggiunge un campo facoltativo che i consumer vecchi ignorano. Rinominare un campo obbligatorio è una rottura. Cambiare il significato senza cambiare il nome è peggio, perché passa i controlli di forma.

Prima del rilascio, esegui i casi congelati del dataset di test contro entrambe le versioni. Il contratto controlla l'ingresso. Il dataset mostra come cambia il comportamento a valle.

Un esempio dall'inizio alla fine

Un workflow prepara una bozza di scheda prodotto partendo da un export giornaliero.

Il contratto accetta soltanto CATALOG-DAILY, schema versione 4, valuta ISO, descrizione sorgente e timestamp. Il prezzo è obbligatorio per il confronto interno, ma il workflow non lo pubblica. La categoria deve provenire dalla tassonomia approvata.

Alle 07:02 arriva un export con una nuova categoria e senza timestamp. La presenza fallisce su exported_at. Il significato fallisce su category_code. L'input entra in quarantena. Il modello non viene chiamato.

Product operations corregge la fonte, genera export-185 e conserva il collegamento a export-184. Il nuovo input passa il contratto. Il workflow produce la bozza e la manda alla verifica dell'output.

Due errori bloccati prima di consumare token o creare una scheda ambigua. Il risultato è un confine osservabile, non una promessa di risparmio.

Misura il contratto

Conta gli esiti per contract_id, versione, fonte e codice motivo.

Le metriche operative utili sono:

• input accettati
• input in quarantena
• input rifiutati
• tempo medio di correzione per codice
• fonti che producono più rotture
• esecuzioni avviate con contratto sconosciuto, che devono restare a zero

Non trasformare il tasso di rifiuto in un obiettivo isolato. Un calo può indicare dati migliori oppure controlli allentati. Leggi il numero insieme alle versioni e ai difetti a valle.

Il KPI di conversione della pagina resta l'invio form aggregato con source_page e source_form. Per giudicare l'impatto SEO servono almeno 28 giorni comparabili dopo un eventuale rilascio.

Dove si rompe di solito

Il primo errore è validare solo il tipo. Una stringa può avere il formato giusto e il significato sbagliato.

Il secondo è accettare qualsiasi origine purché il file si apra. Formato e provenienza sono controlli diversi.

Il terzo è trasformare senza versione. Quando cambia un output, nessuno sa quale passaggio ha modificato il dato.

Il quarto è inviare tutto al modello e filtrare dopo. Il filtro tardivo non riduce ciò che il modello ha già ricevuto.

Il quinto è correggere l'input originale. Senza una nuova versione perdi la causa del difetto e la prova della correzione.

Think, Build, Enable applicato agli input

Think: scegli una decisione del workflow e identifica i dati minimi necessari. Elimina ciò che non serve.

Build: implementa schema, provenienza, freschezza, classificazione, trasformazioni e percorsi di rifiuto o quarantena.

Enable: consegna a source owner e operations codici motivo, runbook e casi di prova. Il team deve correggere un ingresso senza chiedere al costruttore quale colonna intendeva.

Un contratto degli input funziona quando il rifiuto è leggibile quanto l'accettazione.