Come creare un audit trail per un workflow AI
Alle 08:42 un workflow apre un task. Alle 08:43 il task compare due volte. Il log dell'automazione dice success.
Manca la parte che serve: quale input ha avviato il run, quale versione ha deciso, quale scrittura è stata tentata e quale ricevuta prova l'effetto.
Per creare un audit trail di un workflow AI devi legare ogni esecuzione a un'identità unica e conservare riferimenti verificabili lungo tutta la catena. Input. Versioni. Decisioni. Output. Side effect. Stato finale. Il risultato è un execution evidence pack, una scheda che permette di ricostruire il run senza copiare dentro ogni dato elaborato.
L'audit trail ricostruisce un run
Quattro oggetti vicini fanno lavori diversi.
L'inventario dei workflow AI dice quali workflow esistono, chi li possiede e in quale stato si trovano. Il monitoraggio di un workflow AI in produzione osserva errori, latenza, volumi e segnali nel tempo. Il registro degli incidenti AI conserva un evento anomalo, la risposta e il seguito.
L'audit trail risponde a una domanda più stretta: cosa è successo in questa esecuzione?
Un log tecnico può contenere migliaia di righe senza dare la risposta. L'audit trail collega le righe utili a identità, versione, regola applicata e prova dell'effetto. Il NIST AI RMF Playbook cita proprio tracciabilità, provenienza e logging di processi, risultati e impatti tra i meccanismi che aiutano l'auditabilità.
Parti da sette domande
Un pack completo deve permettere a una persona autorizzata di rispondere a sette domande senza indovinare:
- Cosa ha avviato il run?
- Quale versione del workflow ha girato?
- Quali fonti e tool ha usato?
- Quale regola ha permesso o fermato l'azione?
- Cosa ha prodotto?
- Quale effetto esterno è stato tentato o completato?
- Come e perché il run è finito in quello stato?
Non servono sette database. Serve una chiave comune.
Dai un'identità stabile all'esecuzione
Il primo campo è run_id. Deve essere unico, immutabile e presente in ogni passaggio che produce evidenza.
Una scheda minima può partire così:
run_id: wf-support--2026-08-19T08:42:17Z--01J5...
workflow_id: wf-support-draft
workflow_version: 3.4.2
trigger_type: form_submitted
trigger_ref: form-event:8f17...
started_at: 2026-08-19T08:42:17Z
finished_at: 2026-08-19T08:43:06Z
status: completed_with_hold
Il riferimento al trigger non deve contenere il testo del form. Punta al record corretto, nel sistema autorizzato. Se qualcuno esporta l'audit trail, non si porta dietro una copia inattesa di email, telefono o note libere.
Usa lo stesso run_id nei log applicativi, nelle chiamate ai tool, nelle ricevute e nell'eventuale escalation. Senza questa continuità puoi cercare per orario. È un ripiego fragile.
Registra riferimenti agli input, non copie indiscriminate
Per ogni input conserva tipo, provenienza, versione e digest quando serve verificare che il contenuto non sia cambiato.
| Campo | Esempio | Perché serve |
|---|---|---|
input_ref | kb:policy-support:v12 | apre la fonte autorizzata |
input_sha256 | 6cf2... | verifica il contenuto usato |
received_at | 08:42:17Z | ordina gli eventi |
classification | internal | applica accessi e retention |
validation_result | green | prova il gate di ingresso |
Il digest non rende innocuo un dato. Dimostra soltanto che due contenuti coincidono. La policy deve ancora stabilire chi può accedere alla fonte, per quanto tempo resta disponibile e cosa va escluso.
Qui NIST SP 800-92 offre un confine utile: il log management copre generazione, trasmissione, conservazione, accesso, analisi e dismissione dei log. Registrare è solo l'inizio.
Congela le versioni che hanno preso la decisione
Scrivere modello: LLM serve a poco. La catena deve distinguere almeno workflow, prompt o istruzione gestita, modello, tool e policy.
execution_stack:
workflow_version: 3.4.2
instruction_ref: prompt:support-router:v7
model_ref: provider/model-version
tool_schema_ref: ticket-create:v4
policy_ref: support-write-policy:v3
Se un componente non espone una versione stabile, registra l'identificatore disponibile e il limite. Non inventare precisione. Modello corrente al 19/08 è meno elegante di un ID, ma è più onesto di una versione falsa.
La versione risolve anche un equivoco frequente. Due run con lo stesso input possono produrre risultati diversi perché nel mezzo è cambiata una regola, un tool o una knowledge base. Senza la catena delle versioni il confronto resta una supposizione.
Separa proposta, decisione e azione
Un workflow AI spesso produce una proposta prima di agire. L'audit trail deve mostrare il passaggio.
| Passaggio | Campo chiave | Esempio |
|---|---|---|
| Proposta | candidate_action | create_ticket |
| Valutazione | policy_result | allowed_with_hold |
| Decisione | decision_actor | rule:support-write-v3 |
| Azione | tool_call_id | call:01J5... |
| Esito | receipt_ref | ticket:TK-2048 |
Conserva anche i codici motivo. Bloccato non spiega nulla. MISSING_ACCOUNT_ID permette di contare il problema, correggere l'input e verificare se ricompare.
Il NIST AI RMF chiede che test, metriche, metodi e risultati siano documentati e che i rischi possano essere seguiti nel tempo. Un codice stabile collega il singolo run a quella vista aggregata. La descrizione libera resta utile per la persona, ma non sostituisce il codice.
Tratta ogni side effect come una consegna con ricevuta
La parte più delicata arriva quando il workflow scrive fuori dal proprio stato. Crea un ticket. Invia un messaggio. Aggiorna un record.
Per ogni side effect registra tre momenti: intenzione, avvio e conferma. Se la conferma manca, lo stato corretto è delivery_unknown, non failed.
side_effect:
action: create_ticket
idempotency_key: wf-support:case-884:v1
started_at: 08:42:51Z
provider_request_id: req_7c91
receipt_ref: ticket:TK-2048
result: confirmed
Un timeout dopo started_at lascia un dubbio. Ripetere alla cieca può creare il doppione visto alle 08:43. Prima riconcilia l'identificatore remoto o la chiave idempotente. Solo dopo decidi se riprovare.
Zero ricevuta, zero certezza.
Riduci ciò che conservi
Un audit trail utile non è una discarica di payload. Conserva ciò che serve per provare la catena e punta al dato originale quando l'accesso è autorizzato.
Tre scelte riducono il rischio. Usa identificatori opachi al posto dei dati personali. Salva digest al posto di copie quando basta verificare l'integrità. Separa il pack operativo dai contenuti con accesso ristretto.
Anche il prompt completo merita cautela. Può contenere istruzioni interne, dati inseriti dall'utente o materiale protetto. Registra una versione gestita e, se serve, l'hash del testo effettivo. Aprire il contenuto resta un'azione autorizzata.
La durata di conservazione non si decide copiando un numero da un altro progetto. Dipende da rischio, uso, contratto e regole applicabili. Scrivi chi la decide e quale evento avvia la cancellazione o l'archiviazione prevista dalla tua policy.
Verifica che il pack sia davvero ricostruibile
Un file pieno di campi può essere ancora inutilizzabile. Provalo con un esercizio semplice: dai il solo run_id a una persona che conosce il processo ma non ha seguito il caso.
Chiedile di trovare input, versione, decisione, side effect e stato finale. Poi falle indicare un campo mancante o incoerente. Se deve cercare a mano per intervalli di tempo, il legame è rotto.
Controlla anche l'integrità. Hash del pack, ordinamento temporale, riferimenti risolvibili e schema versionato. Se aggiorni lo schema, conserva la versione che permette di leggere i run vecchi.
Un esempio completo
Un workflow prepara un ticket da una richiesta interna. Il trigger arriva alle 08:42:17. Il validatore trova l'account ma non il reparto. La policy consente di creare il ticket in stato needs_routing, senza inviare comunicazioni.
Il pack registra run_id, riferimento al form, hash dell'input normalizzato, workflow 3.4.2, prompt v7, regola support-write-v3 e codice MISSING_DEPARTMENT. La chiamata usa la chiave wf-support:case-884:v1. Il provider restituisce TK-2048.
Alle 08:43 un worker riceve di nuovo lo stesso evento. Trova la chiave già confermata e collega il secondo tentativo alla ricevuta esistente. Nessun nuovo ticket.
Il caso resta misurabile. Il contenuto personale resta nel sistema che già lo governa.
Misura la capacità di ricostruire
Conta pack completi sul totale dei run, non il numero di righe di log. Aggiungi il tempo necessario per ricostruire un campione e la quota di side effect con ricevuta conclusiva.
Un set minimo può includere:
- run con identità e versioni complete
- decisioni con codice motivo
- side effect con stato e ricevuta
- riferimenti non risolvibili
- accessi al pack fuori dal ruolo previsto
Il KPI di conversione della pagina resta l'invio form aggregato con source_page e source_form. L'impatto organico richiede almeno 28 giorni comparabili dopo un eventuale rilascio.
Gli errori che rendono inutile l'audit trail
Il primo è copiare tutto. Più dati non significano più prova. Spesso significano più accessi da governare.
Il secondo è registrare solo il risultato del modello. Senza input, versione e regola non puoi spiegare perché quell'output è entrato nel processo.
Il terzo è usare l'orario come chiave. Due worker possono agire nello stesso secondo. Un run_id esiste proprio per evitare questa ambiguità.
Il quarto è marcare failed quando la scrittura ha esito sconosciuto. Quello stato invita al retry e prepara il doppione.
Il quinto è rendere modificabile la ricevuta. Una correzione va aggiunta come nuovo evento collegato. Riscrivere la prova cancella la storia che volevi conservare.
Think, Build, Enable applicato all'audit trail
Think: scegli un workflow che può creare, inviare o modificare qualcosa. Elenca le sette domande e i dati che non devono entrare nel pack.
Build: assegna run_id, versiona lo schema, collega input, decisioni e ricevute. Prova un successo, un blocco e un esito sconosciuto.
Enable: consegna una vista leggibile a operations e risk owner. Fai ricostruire tre run senza il team che ha costruito il workflow.
L'audit trail funziona quando una persona trova la prova. Non quando chi ha scritto l'automazione ricorda dove cercarla.
Domande frequenti
Audit trail e log sono la stessa cosa?
No. I log registrano eventi tecnici. L'audit trail lega gli eventi utili a identità, versioni, decisioni e ricevute di una singola esecuzione.
Devo conservare tutto il prompt?
Di solito basta una versione gestita e, quando serve, il digest del testo effettivo. Il prompt completo può contenere dati o istruzioni che richiedono accessi più stretti.
Un hash anonimizza il contenuto?
No. Un hash aiuta a verificare l'integrità. Non trasforma automaticamente un dato personale o riservato in informazione innocua.
Chi può modificare un audit trail?
La regola sicura è appendere correzioni collegate, non riscrivere gli eventi conclusi. Accessi e ruoli dipendono dalla governance del processo.
Da quale workflow partire?
Scegli quello con un side effect reale e almeno un caso ambiguo. La consulenza roadmap e governance AI di MAIKER HUB parte da una singola esecuzione e costruisce il controllo attorno alla prova necessaria.