Schema della risposta di decisione di policy per agenti IA
Una risposta di decisione di policy registra identità della policy, input protetti, esito canonico, regole corrispondenti, codici motivazione e tempo di valutazione. Questo riferimento autonomo conserva il sotto-oggetto policy dell’evento di audit pubblicato e aggiunge un policy_decision_event_id indirizzabile e la correlazione per l’uso indipendente.
JSON Schema draft 2020-12 · Versione 1.0.0 · Quattro valori canonici di decisione
Riferimento rapido
- Definizione
- Una risposta autonoma della valutazione di policy con identità della policy, digest degli input e della policy, una decisione canonica, regole corrispondenti e codici motivazione.
- Quando si usa
- Creala dopo la valutazione di una richiesta di azione e prima che il percorso di esecuzione prosegua, si metta in pausa per l’approvazione o si arresti.
- Valori di decisione
- allow, warn, require_approval e block sono i valori canonici del contratto di policy condiviso.
- Azione negata
- L’esempio block registra destination_outside_declared_boundary in reason_codes e non contiene campi di esecuzione perché questa pagina descrive l’oggetto decisione.
01
Schema ed esempi di decisione
Lo schema e i quattro esempi di decisione sono disponibili come artefatti immutabili e versionati. Ogni valore di decisione ha un record concreto.
/ai-agent-policy-decision/v1/schema.jsonScarica Esempio allowDecisione per un’azione all’interno dell’ambito dichiarato./ai-agent-policy-decision/v1/examples/allow.jsonScarica Esempio warnDecisione che mantiene il percorso del worker corrente con un indicatore di avviso./ai-agent-policy-decision/v1/examples/warn.jsonScarica Esempio require_approvalDecisione che indirizza l’azione verso una richiesta di approvazione umana./ai-agent-policy-decision/v1/examples/require-approval.jsonScarica Esempio blockDecisione di azione negata con un codice motivazione relativo al confine./ai-agent-policy-decision/v1/examples/block.jsonScarica 02
Oggetto e ordine di esecuzione
La risposta segue la richiesta di azione. La sua decisione seleziona il percorso prima di una chiamata a uno strumento o di un effetto operativo.
- 01RichiestaLa richiesta di azione dell’agente fornisce azione, finalità, risorsa, confine dei dati e ambiente.
- 02ValutaIl valutatore associa il risultato a policy_id, policy_version, policy_digest, inputs_digest, regole corrispondenti e codici motivazione.
- 03Instradaallow continua l’azione. warn continua il percorso worker corrente ed emette un indicatore di avviso. require_approval crea un percorso di approvazione umana. block interrompe l’azione.
- 04RegistraLa decisione resta collegabile ai successivi record di approvazione, strumenti e audit tramite la correlazione.
03
Dizionario dei campi
Il dizionario copre ogni membro obbligatorio e facoltativo, incluse le aggiunte di identità e correlazione autonome.
Identità autonoma e correlazione
| Campo | Stato | Scopo |
|---|---|---|
| schema_version | Obbligatorio | Seleziona il contratto di compatibilità usato per analizzare il record. |
| policy_decision_event_id | Obbligatorio | Indirizza autonomamente questo record di decisione e lo collega a un evento di audit. Aggiunto per la pubblicazione autonoma. |
| correlation.correlation_id / execution_id | Obbligatorio | Collega il risultato della policy alla sequenza di richiesta, approvazione, strumento e audit. Aggiunto per la pubblicazione autonoma. |
| correlation.trace_id / span_id / parent_event_id | Facoltativo | Trasporta il contesto di traccia OpenTelemetry e un evento padre facoltativo. Gli identificativi W3C composti solo da zeri non sono validi. |
Identità della policy e input protetti
| Campo | Stato | Scopo |
|---|---|---|
| decision_id | Obbligatorio | Identifica la decisione di valutazione della policy nel sistema di governance sorgente. |
| policy_id / policy_version | Obbligatorio | Nomina la policy e l’esatta versione della policy usata per la valutazione. |
| policy_digest / inputs_digest | Obbligatorio | Vincola il risultato alle rappresentazioni protette della policy e degli input. |
Spiegazione della decisione
| Campo | Stato | Scopo |
|---|---|---|
| decision | Obbligatorio | Contiene allow, warn, require_approval o block. |
| evaluated_at | Obbligatorio | Registra quando la valutazione della policy è stata completata come data-ora RFC 3339. |
| matched_rule_ids | Obbligatorio | Elenca gli identificativi univoci delle regole corrispondenti durante la valutazione. |
| reason_codes | Obbligatorio | Elenca almeno un identificativo univoco che spiega l’esito selezionato. |
04
Esempio minimo
Il record allow mostra il più piccolo oggetto decisione completo. I download aggiungono i casi warn, require_approval e block.
{
"schema_version": "1.0.0",
"policy_decision_event_id": "evt_policy_decision_demo_0001",
"correlation": {
"correlation_id": "corr_credit_review_demo_0001",
"execution_id": "exec_credit_review_demo_0001"
},
"decision_id": "dec_demo_0001",
"policy_id": "policy_credit_case_access",
"policy_version": "4.2.1",
"policy_digest": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"inputs_digest": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
"decision": "allow",
"evaluated_at": "2026-07-21T09:14:29.180Z",
"matched_rule_ids": [
"rule_case_summary_read"
],
"reason_codes": [
"within_declared_scope"
]
}05
Validazione e verifica del digest
La validazione JSON Schema controlla la forma. Il verificatore complementare riproduce un digest sha256: sul record canonico e può verificare una firma Ed25519 separata facoltativa.
- 01Carica lo schema versionato dall’URL del download JSON Schema.
- 02Valida il documento JSON con un validatore draft 2020-12 e un plugin per il formato date-time.
- 03Canonizza il record autonomo completo con chiavi degli oggetti ordinate ricorsivamente, in linea con l’approccio del verificatore dell’evento di audit pubblicato.
- 04Calcola SHA-256 sui byte canonici e rappresenta il risultato con il prefisso sha256:.
- 05Confronta il digest calcolato con quello conservato dalla procedura di evidenza chiamante.
- 06Quando viene fornita una firma Ed25519 separata, risolvi la chiave pubblica in modo indipendente e verifica la firma sul digest di 32 byte.
- 07Registra un mismatch dell’hash o un errore di firma come risultato di verifica fallito. Una forma valida da sola non dimostra che il record sia invariato.
Quattro esiti validi per lo schema
Gli esempi allow, warn, require_approval e block sono validi rispetto a draft 2020-12 e producono digest sha256: riproducibili dal loro contenuto canonico.
Controllo della manomissione
La modifica di reason_codes mantiene il documento strutturalmente leggibile ma cambia il digest canonico. Il verificatore restituiscerecord_hash_mismatch.
Il verificatore autonomo accetta una firma Ed25519 separata facoltativa. La fiducia in una chiave pubblica proviene dal registro delle chiavi governato indipendentemente dal chiamante.
06
Compatibilità e versionamento
Versiona il contratto della risposta indipendentemente dai policy pack e dai rilasci del valutatore.
Patch
Chiarimenti, descrizioni ed esempi possono cambiare mentre il comportamento di validazione resta stabile. Un artefatto immutabile corretto riceve un nuovo URL versionato.
Minor
Nuovi campi facoltativi richiedono una nuova schema_version e un URL versionato. I consumatori dichiarano il supporto prima di elaborare la nuova versione.
Major
Campi rimossi o rinominati, significati modificati, stato obbligatorio più restrittivo o canonizzazione modificata richiedono un nuovo percorso major.
I consumatori conservano le versioni sconosciute per la revisione e interrompono l’elaborazione semantica finché il supporto non viene dichiarato. Il percorso v1 usa schema_version 1.0.0.
07
Come lo implementa KLA
Il contratto di policy condiviso definisce il vocabolario delle decisioni. I percorsi worker ed execution registrano la valutazione e il successivo percorso di governance.
| Area del contratto | Sorgente attuale | Mappatura | Stato |
|---|---|---|---|
| Vocabolario canonico delle decisioni | services/shared/src/policy/contracts.ts | GateDecisionValueSchema e POLICY_SCHEMA_VERSION definiscono allow, warn, require_approval, block e la versione 1.0.0 dello schema di policy. | Contratto condiviso attuale |
| Registrazione della decisione | services/execution-worker/src/services/audit-events.ts | recordPolicyDecisionAuditEvent registra identità della policy, decisione, motivazione, regola, workflow e dettagli di esecuzione. Il suo helper legacy accetta deny per l’esito bloccato, quindi questa pagina usa il valore canonico condiviso block. | Produttore attuale con normalizzazione |
| Percorso selezionato dalla decisione | services/execution-worker/src/workflows/workflow-spec-runner.ts | Il flusso di lavoro continua con allow e warn, marca warn come avviso, richiede approvazione per require_approval e interrompe con block. | Consumatore attuale dell’esecuzione |
| Collegamento all’audit | services/execution-worker/src/services/audit-events.ts | I produttori degli audit di policy e approvazione conservano identificativi di esecuzione e contesto di traccia attivo, così una decisione può essere collegata al record di esecuzione circostante. | Produttore correlato attuale |
Astrazioni deliberate e campi non supportati
- •Lo schema omette documenti di policy Cerbos, corpi di regole JSON Logic, payload di entitlements e configurazione del valutatore.
- •Lo schema registra digest per policy e input. Non pubblica il testo della policy protetta, gli argomenti della richiesta, i prompt, l’output del modello o dati personali grezzi.
- •Lo schema registra una decisione canonica. Non codifica ogni segnale di controllo interno, classificazione, remediation o traccia del giudice contenuto nel più ampio contratto GateDecision condiviso.
- •Lo schema registra ID delle regole corrispondenti e codici motivazione. Non afferma che un codice motivazione dimostri autorizzazione, isolamento del tenant o completezza della popolazione sorgente.
- •policy_decision_event_id autonomo e oggetto correlation sono aggiunte per la pubblicazione autonoma. L’oggetto policy incorporato non contiene nessuno dei due campi.
- •Gli esempi sono record sintetici. I loro valori digest dimostrano i vincoli dei campi e non contengono identificativi di clienti o produzione.
08
Riferimenti correlati
Segui richiesta, decisione di policy, approvazione quando richiesta e evento di audit completo nell’ordine di esecuzione.
L’azione richiesta valutata da questa risposta di policy.
Il record maker-checker usato quando il risultato è require_approval.
L’involucro completo dell’evento per richiesta, policy, approvazione, strumento, esito e record di integrità.
Applica il contratto
Conserva il risultato della policy accanto alla richiesta che ha valutato.
Usa la richiesta di azione e i riferimenti all’approvazione con questa risposta, poi usa lo schema del registro di audit per conservare la sequenza completa di esecuzione governata.