Evidence Room | Developer Docs

L'Evidence Room (/evidence-room) è il luogo in cui l'attività degli agenti governati si trasforma in prove pronte per l'audit. Compila record firmati, lineage di esecuzione e stato delle policy in artefatti portabili e a prova di manomissione, che puoi consegnare a un revisore esterno e che il revisore può verificare sul proprio portatile, offline, senza dover mai riporre fiducia in KLA. Questa pagina è destinata ai responsabili di compliance, rischio e audit che stanno costruendo un fascicolo di prove, e agli operatori della piattaforma che lo esportano e lo condividono.

L'Evidence Room consuma l'output della pipeline Evidence-by-Default: gli span OpenTelemetry confluiscono nel KLA Collector (che redige le informazioni di identificazione personale, o PII), poi nel registro crittografico ImmuDB che produce le Merkle proof: impronte matematiche che rendono rilevabile qualsiasi manomissione successiva.

Sealed Evidence Bundle

Un Sealed Evidence Bundle è l'oggetto di esportazione centrale: un file .zip autosufficiente che racchiude tutto il necessario per ricostruire e dimostrare una porzione di storia degli agenti.

Contenuto	Cosa dimostra
Record JSON firmati	Le esatte azioni dell'agente, le chiamate agli strumenti e i costi che si sono verificati
Lineage Record	La traccia completa, passo dopo passo, di ogni esecuzione governata
Stato delle policy	Quale policy pack era attivo e la decisione restituita: `allow`, `warn`, `require_approval` o `block`
Esiti del Decision Desk	Qualsiasi approvazione umana o Escalation che ha risolto una decisione `require_approval`
Merkle proof	Ancoraggio crittografico fino a un hash radice del registro pubblicato

🛡️ Important

Un **Lineage Record** è il nome che KLA assegna a una singola traccia end-to-end dell'esecuzione di un agente. Raggruppare un Lineage Record con la relativa decisione di policy e l'esito del Decision Desk produce una narrazione completa e difendibile per una singola esecuzione, in un unico file.

Verifica indipendente

Questo è il senso dell'Evidence Room: la verifica non dipende dalla fiducia in KLA. Un revisore ricalcola le Merkle proof contenute in un bundle confrontandole con l'hash radice pubblicato e conferma, interamente in autonomia, che le prove sono autentiche e non modificate. Tutti i controlli vengono eseguiti offline, senza necessità di accesso alla rete.

kla evidence verify \
  --bundle evidence-room_acme-prod_exp_9f2c_v1.zip \
  --out ./report

Il verificatore conferma le firme, ricalcola la Merkle root e convalida l'ancoraggio al registro, poi scrive un file verification-report.json e un report HTML leggibile da una persona. Il codice di uscita 0 significa che il bundle è Sealed e affidabile.

flowchart LR
  A["Attività dell'agente"] --> B["KLA Collector<br/>redazione PII"]
  B --> C["Registro ImmuDB<br/>Merkle proof"]
  C --> D["Sealed Evidence Bundle"]
  D --> E["Il revisore verifica offline"]

Job di esportazione e link di condivisione sicuri

Gli insiemi di prove possono coprire mesi di attività, perciò le esportazioni vengono eseguite come job asincroni. Definisci l'ambito (un intervallo di date, un agente o un singolo Lineage Record), metti in coda l'esportazione e ne monitori il completamento senza mantenere aperta una sessione.

curl -X POST https://api.kla.digital/v1/evidence.export \
  -H "Authorization: Bearer $KLA_ACCESS_TOKEN" \
  -H "x-tenant-id: acme-prod" \
  -d '{"agent":"refund-approver","from":"2026-01-01","to":"2026-03-31"}'

Quando il bundle è pronto, genera un link di condivisione sicuro: un URL di download a tempo limitato e con accesso circoscritto, che puoi inviare a un regolatore o revisore esterno senza dovergli predisporre un account KLA. Il destinatario scarica il bundle e lo verifica con i passaggi descritti sopra.

💡 Tip

I link di condivisione hanno un ambito definito e una scadenza. Imposta la finestra più breve compatibile con il calendario di revisione del revisore: il link si revoca automaticamente alla scadenza.

Control Mapping e Control Pack

Le prove grezze rispondono alla domanda cosa è successo. I revisori hanno bisogno di sapere anche quale requisito viene soddisfatto. Il Control Mapping collega i singoli segnali di governance (una decisione di policy, un'approvazione, un evento di redazione) a clausole specifiche di un framework di compliance.

Un Control Pack è un'esportazione orientata alla compliance: un Sealed Evidence Bundle organizzato attorno a un framework anziché a un intervallo temporale. KLA fornisce mapping per i regimi più comuni:

EU AI Act, Allegato IV: i requisiti di documentazione tecnica per i sistemi di IA ad alto rischio, mappati sulle istruzioni dei tuoi agenti, sui controlli di policy e sull'audit trail.
SOC 2: i criteri di change management, controllo degli accessi e monitoraggio, comprovati da Release, record del Decision Desk e Lineage continuo.

Un Control Pack ti consente di rispondere a una richiesta di documentazione tecnica ai sensi dell'EU AI Act o a una revisione SOC 2 Type II con un unico file verificabile, anziché con una cartella di screenshot. Usa il Lineage Explorer per indagare su una specifica esecuzione, quindi esportala direttamente nell'Evidence Room come parte del pack.