Schema del registro di audit degli agenti IA: azioni, strumenti, approvazioni e risultati
Un evento di audit di un agente IA è un record durevole che collega un'azione richiesta a identità, autorità delegata, policy, revisione umana, effetti degli strumenti, risultato aziendale e prova di integrità. Questo contratto pubblico è indipendente dal fornitore e usa gli attuali produttori KLA solo nella mappatura dell'implementazione.
Bozza di JSON Schema 2020-12 · Pubblicato il 28 luglio 2026 · Nomi dei campi normativi in inglese
Riferimento rapido
- Definizione
- Un evento di audit di un agente IA è un record durevole che collega un'azione richiesta a identità, autorità delegata, policy, revisione umana, effetti degli strumenti, risultato aziendale e prova di integrità.
- Applicabilità
- Usalo per azioni dell'agente con conseguenze rilevanti, compreso un rifiuto della policy o un tentativo non riuscito. Applica all'implementazione i requisiti locali giuridici, di privacy, conservazione e settore.
- Prove minime
- ID stabili, identità dell'attore e del responsabile, componenti versionati, autorità richiesta, esito della policy, approvazione quando necessaria, effetti, risultato, ordinamento, controlli della privacy e stato di verifica.
- Esempio svolto
- Il record completo segue una disposizione di credito sintetica dalla richiesta, attraverso require_approval, la revisione autorizzata, un effetto dello strumento, un risultato aziendale e una firma Ed25519 valida.
01
Schema e record sanitizzati
I quattro URL immutabili e versionati supportano implementazione, validazione, carte di lavoro di audit e test di regressione.
/ai-agent-audit-event/v1/schema.jsonScarica Esecuzione completaAzione approvata valida con un effetto a valle./ai-agent-audit-event/v1/examples/complete-execution.jsonScarica Azione negataDecisione di blocco valida senza chiamata allo strumento./ai-agent-audit-event/v1/examples/denied-action.jsonScarica Manomissione rilevataRecord strutturalmente valido il cui payload dell'evento firmato è stato modificato./ai-agent-audit-event/v1/examples/tamper-failure.jsonScarica 02
Un’azione svolta
Il campione completo registra una disposizione di credito sintetica. La policy richiede un sottoscrittore autorizzato prima dell'esecuzione dello strumento con capacità di scrittura.
- 01RichiestaUn utente delega a un agente un'azione di disposizione del credito con ambito definito.
- 02Valutazione della policyLa policy versione 4.2.1 restituisce require_approval per l’importo registrato.
- 03Decisione umanaUn sottoscrittore senior esamina le prove presentate e approva la richiesta vincolata.
- 04Effetto dello strumentoUna chiamata idempotente allo strumento aggiorna la destinazione sintetica e registra i digest prima/dopo.
- 05ProvaL’hash del payload firmato canonico e la firma Ed25519 vengono verificati con la chiave campione pubblicata.
{
"schema_version": "1.0.0",
"event_id": "evt_01JZ8V4R9K2Q7M1W3D5N6P8X0A",
"actors": {
"agent": "agent_credit_review",
"accountable_owner": "role_head_credit_operations"
},
"requested_action": "credit.application.set_disposition",
"policy_decision": "require_approval",
"approval_decision": "approved",
"tool_status": "succeeded",
"business_outcome": "achieved",
"verification": "valid"
}03
Confini dei record
Ogni artefatto risponde a una domanda di audit diversa. Una procedura di assurance di produzione richiede in genere tutti e quattro.
| Artefatto | Domanda | Contenuti tipici | Confine dell'integrità |
|---|---|---|---|
| Log operativo | Che cosa ha segnalato un componente? | Messaggi, metriche, errori, latenza e contesto locale di runtime. | Utile per le operazioni. Completezza, identità, autorità e conservazione possono restare non specificate. |
| Evento di audit | Chi o che cosa ha richiesto un'azione governata, con quale autorità e cosa è accaduto? | Identità, versioni, scopo, risorsa, policy, approvazione, effetto dello strumento, risultato, privacy e riferimenti di integrità. | Il record ha uno schema stabile e un risultato di verifica esplicito. La completezza della popolazione di origine richiede comunque riconciliazione. |
| Lineage di esecuzione | Come è progredita un'esecuzione nell'ordine? | Span o eventi ordinati, relazioni genitore-figlio, tentativi, chiamate di strumenti e stato. | Il lineage fornisce sequenza e causalità. Può collegarsi a più eventi di audit e artefatti di origine. |
| Pacchetto di prove | Quali artefatti conservati supportano un'asserzione di audit? | Manifest, eventi di audit, lineage, record di policy e approvazione, ricevute di origine, hash, firme, omissioni e redazioni. | La verifica del pacchetto controlla appartenenza degli artefatti, hash, firme, prove del registro mastro e omissioni dichiarate. |
04
Dizionario dei campi
I campi obbligatori si applicano a ogni record. I campi condizionali si applicano quando esiste il componente o il percorso del ciclo di vita indicato. I campi facoltativi conservano dettagli portabili.
Involucro e ordinamento
| Campo | Stato | Scopo |
|---|---|---|
| schema_version | Obbligatorio | Seleziona il contratto di compatibilità usato per analizzare il record. |
| audit_event.event_id | Obbligatorio | Identifica in modo univoco questo evento di audit. |
| audit_event.event_type | Obbligatorio | Classifica un'azione completata o negata. Lo stato di verifica resta nell'integrità. |
| audit_event.occurred_at / recorded_at / sequence | Obbligatorio | Separa l'ora dell'evento dall'ora di raccolta e conserva un ordinamento deterministico. |
| audit_event.correlation.correlation_id / execution_id | Obbligatorio | Collega record di policy, approvazione, strumento, risultato e prove senza una correlazione basata sul timestamp. |
| audit_event.correlation.trace_id / span_id / parent_event_id | Facoltativo | Collega il record a OpenTelemetry o a una traccia equivalente e a un evento padre. Gli identificatori W3C composti solo da zero non sono validi. |
Ambito e identità
| Campo | Stato | Scopo |
|---|---|---|
| audit_event.scope.organization_ref | Obbligatorio | Contiene un riferimento all'ambito pseudonimo o controllato dall'organizzazione. |
| audit_event.scope.environment / retention_class | Obbligatorio | Indica il confine operativo e il trattamento di conservazione approvato. |
| audit_event.scope.region / legal_hold | Facoltativo | Registra la collocazione regionale e qualsiasi sospensione che interrompa l'eliminazione ordinaria. |
| audit_event.actors.requester / agent / accountable_owner | Obbligatorio | Vincola la richiesta, l'identità dell'agente e il ruolo umano o organizzativo responsabile. |
| audit_event.actors.delegated_user / service_identity | Condizionale | Registra l'autorità per conto di altri e l'identità del carico di lavoro quando esiste. |
Versioni e autorità richiesta
| Campo | Stato | Scopo |
|---|---|---|
| audit_event.components.agent | Obbligatorio | Fissa la release dell'agente e il digest facoltativo della configurazione. |
| audit_event.components.model / prompt_template / orchestrator | Condizionale | Fissa ogni componente che ha influenzato l'azione. |
| audit_event.requested_action.action / purpose | Obbligatorio | Indica la capacità proposta e lo scopo aziendale approvato. |
| audit_event.requested_action.resource / data_boundary_ref / environment | Obbligatorio | Definisce il target, il confine dei dati governati e l'ambiente di esecuzione. |
| audit_event.requested_action.amount | Condizionale | Usa una stringa decimale più la valuta ISO 4217 quando il valore finanziario influenza la policy. |
Policy e decisione umana
| Campo | Stato | Scopo |
|---|---|---|
| audit_event.policy.decision_id / policy_id / policy_version | Obbligatorio | Identifica la decisione esatta e la versione della policy applicabile. |
| audit_event.policy.policy_digest / inputs_digest | Obbligatorio | Vincola la valutazione alle rappresentazioni protette della policy e degli input. |
| audit_event.policy.decision | Obbligatorio | Contiene allow, warn, require_approval o block. |
| audit_event.policy.matched_rule_ids / reason_codes / evaluated_at | Obbligatorio | Rende il risultato spiegabile e ordinabile prima di qualsiasi effetto. |
| audit_event.approval | Condizionale | Obbligatorio quando la policy restituisce require_approval. Gli effetti di esecuzione richiedono una richiesta decisa e approvata da un revisore umano. |
| audit_event.approval.reassigned_from / override / appeal | Facoltativo | Conserva fatti eccezionali sul ciclo di vita della decisione quando il sistema di origine li supporta. |
Esecuzione e risultato
| Campo | Stato | Scopo |
|---|---|---|
| audit_event.tool_calls[] | Obbligatorio | Elenca ogni chiamata allo strumento tentata. Le azioni bloccate, non approvate e non avviate richiedono un array vuoto. |
| audit_event.tool_calls[].arguments_digest / result_digest | Obbligatorio | Vincola argomenti e risultati protetti senza inserire segreti nell’evento. |
| audit_event.tool_calls[].downstream_effects[] | Condizionale | Registra ricevute del sistema di destinazione e digest dello stato prima/dopo quando si verificano effetti. |
| audit_event.execution.status / business_outcome | Obbligatorio | Separa il completamento tecnico dal risultato aziendale e vincola la semantica dell'evento completato o negato. |
| audit_event.execution.rollback / incident_ref | Condizionale | Collega recupero e indagine quando viene usato uno dei due percorsi. |
| audit_event.lineage | Obbligatorio | Collega l’azione a un record di lineage e ai relativi ID evento ordinati. |
Prove, privacy e integrità
| Campo | Stato | Scopo |
|---|---|---|
| audit_event.evidence.manifest_ref / artifacts[] | Obbligatorio | Identifica il manifest del pacchetto e i digest degli artefatti di supporto. |
| audit_event.privacy.classification / redaction_status | Obbligatorio | Indica la protezione e la trasformazione applicate al record. |
| audit_event.privacy.redactions[] / access_policy_ref | Obbligatorio | Individua i campi protetti e la policy che governa l'accesso. Le voci corrispondono allo stato di redazione dichiarato. |
| integrity.canonicalization / hash_algorithm / record_hash | Obbligatorio | Definisce e registra il digest dei metadati dell'involucro firmato canonico e di audit_event. |
| integrity.previous_event_hash | Facoltativo | Collega i record quando l'implementazione usa una sequenza di eventi collegata tramite hash. La firma protegge questo collegamento. |
| integrity.signature | Obbligatorio | Contiene algoritmo, ID chiave, chiave pubblica campione e firma del digest separata. |
| integrity.verification | Obbligatorio | Registra valid, failed o not_performed con versione del verificatore e codici di errore. |
05
Verifica dell'integrità
La validità dello schema e l'integrità crittografica sono controlli separati. La completezza della popolazione resta una procedura di audit distinta.
- 01Convalida l'involucro con il JSON Schema versionato.
- 02Crea il payload firmato da schema_version, audit_event e metadati di integrità diversi da record_hash e signature.value.
- 03Canonizza il payload firmato con RFC 8785 JSON Canonicalization Scheme.
- 04Calcola SHA-256 e confrontalo con integrity.record_hash usando il prefisso sha256:.
- 05Risolvi la chiave attendibile tramite key_id. Verificane validità e stato di revoca a occurred_at.
- 06Verifica la firma Ed25519 sul digest di 32 byte.
- 07Verifica ciascun previous_event_hash rispetto al vicino ordinato e a un ancoraggio del primo collegamento conservato indipendentemente prima di accettare l’ordine della sequenza.
- 08Riconcilia gli ID evento e i digest degli artefatti con lineage, effetti del sistema di origine e manifest delle prove.
- 09Registra ogni codice di errore. Un controllo non riuscito o non disponibile non può produrre valid.
Esempi positivi e negati
Entrambi sono validati, riproducono i rispettivi hash pubblicati e sono verificati con la chiave pubblica Ed25519 campione.
Esempio di manomissione
L'involucro resta valido rispetto allo schema. Il suo risultato aziendale è cambiato dopo la firma, quindi l'hash ricalcolato differisce e la verifica registrarecord_hash_mismatch.
La chiave campione incorporata rende i file auto-verificabili. La verifica di produzione deve considerare attendibili le chiavi tramite un registro separato. Una chiave fornita solo dal record non può stabilire l’identità dell’emittente.
06
Correlazione OpenTelemetry
Il contesto di traccia unisce telemetria e prove di audit. Non contiene l'intera asserzione di audit.
Propaga
Propaga W3C traceparent tra agente, policy, approvazione, gateway dello strumento e chiamate a valle. Copia trace_id e span_id dell’azione nella correlazione.
Vincola
Aggiungi attributi stabili execution_id, event_id, decision_id, request_id e call_id. Mantieni input protetti, token e contenuto grezzo del modello fuori dagli attributi ordinari degli span.
Conserva
La conservazione della telemetria può essere più breve di quella di audit. Conserva il record di audit e il riferimento di lineage risolvibile dopo la scadenza delle tracce attive.
07
Compatibilità e versionamento
Versiona il contratto indipendentemente dalle versioni del produttore e dello strumento.
Patch
Chiarimenti, descrizioni ed esempi possono cambiare senza modificare il comportamento di validazione. Gli URL stabili v1 mantengono contenuti di file immutabili, quindi un artefatto corretto riceve un nuovo URL di versione.
Minor
Un nuovo campo facoltativo o un’estensione dell’enum richiedono un nuovo schema_version e un URL versionato. I consumer devono rifiutare le versioni sconosciute finché non dichiarano supporto.
Major
Campi rimossi o rinominati, significati modificati, stato obbligatorio più rigoroso o canonizzazione modificata richiedono un nuovo percorso major. I produttori possono eseguire la doppia scrittura durante la migrazione.
I consumer devono conservare i record sconosciuti per la gestione forense e interrompere l’elaborazione semantica quando la versione dello schema non è supportata. Non devono mai convertire silenziosamente un esito di policy o uno stato di verifica non supportato.
08
Mappatura degli attuali produttori KLA
L'involucro portabile è più ampio di qualsiasi singolo produttore KLA. Queste fonti definiscono la verità attuale dell'implementazione.
| Area contrattuale | Fonte attuale | Mappatura | Stato |
|---|---|---|---|
| Identità dell'evento di audit e append durevole | services/api/src/services/audit-logger.ts | AuditEvent fornisce evento, tenant, utente, risorsa, azione, risultato, correlazione e contesto di sicurezza. Il logger rispecchia gli eventi con ambito tenant in ImmuDB. | Fonte attuale |
| Produttori di eventi di strumenti, policy e approvazione | services/execution-worker/src/services/audit-events.ts | I produttori del worker eseguono l'hash degli input e dei risultati degli strumenti, acquisiscono l'identità di esecuzione e della policy, aggiungono eventi di richiesta e risoluzione dell'approvazione e collegano l'ID di traccia OpenTelemetry attivo. | Fonte attuale |
| Quattro esiti della policy | services/shared/src/policy/contracts.ts | GateDecisionValueSchema definisce allow, warn, require_approval e block. Gli helper di audit del worker meno recenti possono ancora indicare l’esito bloccato come deny. | Fonte attuale con normalizzazione |
| Decisione di approvazione durevole | services/execution-api/src/services/approval-audit-outbox-worker.ts | L'API di approvazione usa un outbox con lease e idempotente per aggiungere un record decisionale vincolato al tenant. Il produttore sul lato della richiesta resta separato. | Fonte attuale |
| Lineage di esecuzione e correlazione delle tracce | services/execution-worker/src/services/lineage-trace-publisher.ts | Le esecuzioni governate pubblicano span radice e di passaggio con ambito di esecuzione. workflow-observability.ts emette anche attributi di policy e approvazione tramite OpenTelemetry. | Fonte attuale |
| Sealed Evidence Bundle e verifica offline | packages/evidence-contract/src/index.ts | Il manifest del pacchetto vincola tenant, esportazione, artefatti, radice Merkle, hash del manifest, metadati della firma, richiesta del factory, omissioni e redazioni. packages/evidence-verifier esegue i controlli indipendenti. | Fonte attuale |
Astrazioni deliberate e campi non supportati
- •KLA al momento non emette questo involucro pubblico come un unico record wire nativo. Il riferimento normalizza diversi produttori autorevoli in un'unità di audit.
- •Il responsabile, i digest completi della configurazione di modello e prompt, le versioni degli strumenti, i risultati aziendali, il rollback e i riferimenti agli incidenti non sono popolati uniformemente in ogni percorso di runtime KLA.
- •Riassegnazione, override e appello della Decision Request sono campi portabili del ciclo di vita. Gli attuali produttori KLA non espongono tutti e tre come un unico contratto normalizzato a livello di azione.
- •Il contratto registra il ruolo richiesto e l’identità del revisore umano. I consumer di produzione devono verificare che il revisore detenesse il ruolo richiesto quando è avvenuta la decisione.
- •KLA firma e verifica il manifest del Sealed Evidence Bundle e convalida prove del registro mastro e degli artefatti. Gli attuali record KLA non presentano tutti la forma di firma Ed25519 per record usata da questi esempi portabili.
- •Gli esempi pubblicano una chiave pubblica campione affinché i file siano auto-verificabili. I sistemi di produzione devono risolvere le chiavi attendibili tramite un registro di chiavi governato indipendentemente e verificare la revoca al momento dell’evento.
Applica il contratto
Inserisci il record in un metodo di audit completo.
Usa il quadro aziendale per definire ambito e test dei controlli. Usa il programma di audit per riconciliare le popolazioni, campionare le azioni, valutare le prove e riportare le eccezioni.