Schema dell’evento di approvazione degli agenti IA
Un evento di approvazione registra il ciclo decisionale di un’azione di un agente IA governato che è stata sottoposta a revisione umana. Questo riferimento indipendente mantiene la definizione di approvazione dell’evento di audit pubblicato e aggiunge un approval_event_id indirizzabile più la correlazione per l’uso autonomo.
JSON Schema draft 2020-12 · Versione 1.0.0 · Record decisionale maker-checker
Riferimento rapido
- Definizione
- Un record indipendente dello stato di una richiesta di approvazione, del ruolo richiesto, del revisore umano quando la decisione è presa, della decisione, delle tempistiche e di riferimenti facoltativi alla motivazione.
- Quando si usa
- Createlo dopo che un risultato di policy instrada un’azione verso l’approvazione umana e registratelo quando la richiesta viene decisa, scade o viene annullata.
- Valori della decisione
- approved, rejected, expired e cancelled descrivono la decisione terminale rappresentata dall’evento.
- Maker-checker
- Gli attuali percorsi di approvazione verificano approval:decide, il ruolo richiesto, lo stato pending e la separazione dei compiti prima di registrare una decisione.
01
Schema ed esempi di approvazione
Lo schema con versione e i due esempi di decisione terminale sono artefatti autosufficienti per validazione e implementazione di riferimento.
/ai-agent-approval-event/v1/schema.jsonScarica Esempio di evento approvatoApprovazione decisa con un revisore umano sintetico./ai-agent-approval-event/v1/examples/approved.jsonScarica Esempio di evento rifiutatoRifiuto deciso con un reason code e un riferimento alla motivazione./ai-agent-approval-event/v1/examples/rejected.jsonScarica 02
Oggetto e ordine di esecuzione
Un evento di approvazione si colloca tra un risultato di policy require_approval e qualsiasi effetto di uno strumento approvato. I percorsi expired e rejected restano collegabili a esiti negati o non avviati.
- 01RichiestaUn risultato di policy require_approval crea una richiesta associata alla correlazione dell’esecuzione e a un ruolo richiesto.
- 02RevisioneUn revisore riceve le evidenze presentate e agisce tramite un percorso di approvazione con il permesso approval:decide.
- 03VerificaI percorsi attuali verificano il ruolo richiesto, lo stato pending e la separazione maker-checker. L’approvazione richiede anche una conferma esplicita.
- 04RegistrazioneLa decisione viene persistita e un obbligo di audit durevole viene scritto prima di segnalare al workflow soggetto a controllo di riprendere.
03
Dizionario dei campi
Il dizionario copre ogni elemento dell’approvazione, incluse le condizioni del ciclo di vita e i riferimenti facoltativi a riassegnazione, override e ricorso.
Identità indipendente e correlazione
| Campo | Stato | Finalità |
|---|---|---|
| schema_version | Obbligatorio | Seleziona il contratto di compatibilità usato per analizzare il record. |
| approval_event_id | Obbligatorio | Indirizza autonomamente questo evento di approvazione e lo collega a un evento di audit. Aggiunto per la pubblicazione indipendente. |
| correlation.correlation_id / execution_id | Obbligatorio | Collega l’approvazione alla sequenza di richiesta, policy, strumento e audit. Aggiunto per la pubblicazione indipendente. |
| correlation.trace_id / span_id / parent_event_id | Facoltativo | Include il contesto di traccia OpenTelemetry e un evento padre facoltativo. Gli identificativi W3C composti interamente da zero non sono validi. |
Ciclo di vita della richiesta di approvazione
| Campo | Stato | Finalità |
|---|---|---|
| request_id | Obbligatorio | Identifica la richiesta di approvazione che viene decisa. Mantiene il significato di approval.request_id incorporato. |
| status | Obbligatorio | Indica se l’evento è decided, expired o cancelled. |
| requested_at / expires_at | Obbligatorio | Registra gli orari della richiesta e della scadenza come date-time RFC 3339. |
| required_role | Obbligatorio | Denomina il ruolo richiesto per decidere l’approvazione. |
| decided_at | Obbligatorio | Registra quando è stata registrata la decisione terminale, la scadenza o l’annullamento. |
Decisione e riferimenti di supporto
| Campo | Stato | Finalità |
|---|---|---|
| decision | Obbligatorio | Contiene approved, rejected, expired o cancelled e corrisponde allo stato del ciclo di vita. |
| reviewer | Condizionale | Identifica il revisore umano quando lo stato è decided. Il type è sempre user. |
| presented_evidence_digest | Facoltativo | Collega la decisione alla rappresentazione delle evidenze mostrata per la revisione. |
| reason_code / rationale_reference | Facoltativo | Fornisce un motivo stabile e il riferimento a una motivazione decisionale più completa. |
| reassigned_from | Facoltativo | Conserva il principale precedente quando una richiesta di approvazione cambia assegnatario. |
| override.authority_reference / reason_code | Facoltativo | Fa riferimento all’autorità eccezionale e al relativo motivo quando viene registrato un override. |
| appeal.status / reference | Facoltativo | Collega un successivo ciclo di vita del ricorso e il suo riferimento stabile. |
04
Esempio minimo
Il record approved mostra i campi richiesti più il revisore necessario per uno stato decided. Il record rejected fornisce una seconda decisione terminale.
{
"schema_version": "1.0.0",
"approval_event_id": "evt_approval_demo_0001",
"correlation": {
"correlation_id": "corr_credit_review_demo_0002",
"execution_id": "exec_credit_review_demo_0002"
},
"request_id": "approval_req_demo_0001",
"status": "decided",
"requested_at": "2026-07-21T11:03:18.240Z",
"expires_at": "2026-07-21T11:33:18.240Z",
"required_role": "kla:senior_approver",
"presented_evidence_digest": "sha256:9999999999999999999999999999999999999999999999999999999999999999",
"reviewer": {
"id": "user_reviewer_demo_0001",
"type": "user",
"display_name": "Synthetic reviewer",
"identity_provider": "demo-idp"
},
"decision": "approved",
"reason_code": "evidence_reviewed",
"rationale_reference": "rationale_demo_0001",
"decided_at": "2026-07-21T11:04:10.240Z"
}05
Validazione e verifica del digest
La validazione dello schema JSON verifica la forma di stato e decisione. Il verificatore complementare riproduce un digest sha256: sul record canonico e può verificare una firma Ed25519 distaccata facoltativa.
- 01Caricate lo schema con versione dall’URL di download dello schema JSON.
- 02Convalidate il documento JSON con un validatore draft 2020-12 e un plugin per il formato date-time.
- 03Canonicalizzate il record indipendente completo con chiavi oggetto ordinate ricorsivamente, in linea con l’approccio del verificatore dell’evento di audit pubblicato.
- 04Calcolate SHA-256 sui byte canonici e rappresentate il risultato con il prefisso sha256:.
- 05Confrontate il digest calcolato con quello conservato dalla procedura di evidenza chiamante.
- 06Quando viene fornita una firma Ed25519 distaccata, risolvete la sua chiave pubblica in modo indipendente e verificate la firma sul digest di 32 byte.
- 07Registrate una mancata corrispondenza dell’hash o un errore della firma come risultato di verifica non superato. Conservate il record decisionale e la richiesta collegata per la revisione.
Esempi di decisione terminale
Gli esempi approved e rejected sono validi rispetto al draft 2020-12 e producono digest sha256: riproducibili a partire dal loro contenuto canonico.
Controllo di manomissione
Modificare la decisione cambia sia il significato del ciclo di vita sia il digest canonico. Il verificatore segnalarecord_hash_mismatch.
Il verificatore indipendente accetta una firma Ed25519 distaccata facoltativa. L’attendibilità di una chiave pubblica deriva dal registro di chiavi gestito in modo indipendente dal chiamante.
06
Compatibilità e versionamento
Versionate il contratto dell’evento di approvazione indipendentemente dal servizio di approvazione e dal contratto di policy.
Patch
Chiarimenti, descrizioni ed esempi possono cambiare mentre il comportamento di validazione resta stabile. Un artefatto immutabile corretto riceve un nuovo URL con versione.
Minor
Nuovi campi facoltativi richiedono un nuovo schema_version e un URL con versione. I consumatori dichiarano il supporto prima di elaborare la nuova versione.
Major
Campi rimossi o rinominati, significati modificati, stato obbligatorio più restrittivo o canonicalizzazione modificata richiedono un nuovo percorso major.
I consumatori conservano le versioni sconosciute per la revisione e interrompono l’elaborazione semantica finché non è dichiarato il supporto. Il percorso v1 usa schema_version 1.0.0.
07
Come KLA implementa questo schema
Il processo di elaborazione crea record di audit delle approvazioni. I percorsi API applicano l’autorità decisionale e persistono un obbligo decisionale durevole.
| Area del contratto | Fonte attuale | Mappatura | Stato |
|---|---|---|---|
| Eventi di richiesta e risoluzione dell’approvazione | services/execution-worker/src/services/audit-events.ts | Il processo di elaborazione registra eventi di audit di richiesta e risoluzione dell’approvazione con campi relativi a esecuzione, approvazione, governance, decisione, motivo e traccia. Questa pagina normalizza tali elementi nella forma portabile dell’evento di approvazione. | Produttore attuale con normalizzazione |
| Percorso decisionale maker-checker | services/execution-api/src/routes/approvals.ts | Il percorso verifica il permesso approval:decide, il ruolo richiesto, lo stato pending e l’auto-approvazione. Approve richiede inoltre una conferma esplicita; un’escalation mantiene la richiesta in pending. | Consumatore e produttore attuale |
| Decision Desk e percorso di approvazione locale | services/api/src/routers/approvals.ts | Il router applica le stesse regole di accesso per permessi e maker-checker, convalida i set di controllo di policy ed evidenze, persiste un record decisionale e coordina lo stato di approvazione locale o di execution-api. | Consumatore e produttore attuale |
| Vocabolario della decisione e versione | services/shared/src/policy/contracts.ts | Il contratto di policy condiviso fornisce require_approval come percorso che conduce a questo evento e mantiene il versionamento della policy indipendente dallo schema dell’evento di approvazione. | Contratto condiviso attuale |
Astrazioni deliberate e campi non supportati
- •Lo schema omette gli ID del database del tenant, le colonne della tabella delle approvazioni, la sintassi di autorizzazione Cerbos e i contenuti grezzi di richieste o evidenze.
- •Lo schema registra required_role e l’identità del revisore. Non dimostra che il revisore detenesse quel ruolo al momento della decisione; i consumatori svolgono tale verifica di autorità.
- •Lo schema ha i valori di stato terminale decided, expired e cancelled. L’azione di escalation dell’API attuale mantiene la richiesta in pending e non ha un valore terminale escalated in questo contratto.
- •Lo schema contiene riferimenti facoltativi a evidenze, motivazione, riassegnazione, override e ricorso. Non definisce il pacchetto di evidenze, la procedura di ricorso o la policy sull’autorità di override.
- •Lo schema non pubblica e-mail del revisore, snapshot del ruolo, commenti o ricevute decisionali. Questi campi restano nei record decisionali e di audit KLA e possono essere collegati tramite gli ID di correlazione e richiesta.
- •approval_event_id e l’oggetto di correlazione indipendenti sono aggiunte per la pubblicazione autonoma. request_id mantiene il significato di richiesta di approvazione dall’oggetto approval incorporato.
08
Riferimenti correlati
Seguite la sequenza di esecuzione dalla richiesta di azione alla decisione di policy, all’approvazione quando richiesta e all’evento di audit completo.
L’azione che ha raggiunto la valutazione della policy.
Il risultato require_approval che instrada l’azione alla revisione.
L’involucro completo dell’evento che registra richiesta, decisione, approvazione, effetto ed esito.
Applica il contratto
Mantenete la decisione umana collegata al ramo di policy che risolve.
Usate gli identificativi di correlazione e richiesta per collegare l’evento di approvazione alla richiesta di azione, alla decisione di policy, all’evento di audit completo e ai record di evidenze successivi.