Schema della richiesta di azione dell’agente IA
Una richiesta di azione registra l’autorità che un agente IA chiede di usare prima della valutazione della policy e di qualsiasi effetto dello strumento. Questo riferimento autonomo conserva la forma requested_action dell’evento di audit pubblicato e aggiunge un action_request_id indirizzabile più la correlazione per un uso indipendente.
JSON Schema draft 2020-12 · Versione 1.0.0 · Nomi normativi dei campi in inglese
Riferimento rapido
- Definizione
- Un record autonomo di una singola azione richiesta da un agente: capacità, finalità, risorsa, perimetro dei dati, ambiente e momento della richiesta.
- Quando si usa
- Crearlo quando un agente propone un’azione governata. Collegarlo ai record di policy, approvazione, strumento e audit tramite la correlazione.
- Campi obbligatori
- ID della richiesta, versione dello schema, ID di correlazione, azione, finalità, risorsa, perimetro dei dati, ambiente e requested_at.
- Dettagli facoltativi
- Includere amount per le azioni finanziarie e il contesto di traccia quando l’esecuzione contiene identificatori OpenTelemetry.
01
Schema ed esempi
Gli artefatti con versione sono autonomi. I consumatori possono convalidare la richiesta senza caricare lo schema dell’evento di audit.
/ai-agent-action-request/v1/schema.jsonScarica Esempio di lettura di baseRichiesta sintetica minima senza importo finanziario./ai-agent-action-request/v1/examples/basic-read.jsonScarica Esempio di decisione creditiziaAzione finanziaria sintetica con importo e correlazione di traccia./ai-agent-action-request/v1/examples/credit-disposition.jsonScarica 02
Oggetto e ordine di esecuzione
La richiesta è il primo contratto durevole nella sequenza di riferimento. La policy la valuta prima che siano registrati un’approvazione o un effetto dello strumento.
- 01RichiestaL’agente propone un’azione su una risorsa denominata entro un perimetro dei dati e un ambiente dichiarati.
- 02Correlazioneaction_request_id identifica questo record autonomo. correlation_id ed execution_id lo collegano al grafo di esecuzione.
- 03ValutazioneLa decisione di policy registra allow, warn, require_approval oppure block per la stessa correlazione di esecuzione.
- 04ProseguimentoUna chiamata allo strumento segue un percorso allow o warn. Un percorso require_approval registra un evento di approvazione prima dell’effetto.
03
Dizionario dei campi
Il dizionario copre ogni campo di primo livello, ogni membro della risorsa annidata, ogni membro della correlazione e il membro finanziario condizionale.
Identità e correlazione autonome
| Campo | Stato | Finalità |
|---|---|---|
| schema_version | Obbligatorio | Seleziona il contratto di compatibilità usato per analizzare il record. |
| action_request_id | Obbligatorio | Indirizza in modo indipendente questa richiesta e la collega a un evento di audit. Aggiunto per la pubblicazione autonoma. |
| correlation.correlation_id / execution_id | Obbligatorio | Collega la richiesta ai record di policy, approvazione, strumento e audit senza un join temporale. 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 identificatori W3C composti solo da zeri non sono validi. |
Autorità richiesta
| Campo | Stato | Finalità |
|---|---|---|
| action | Obbligatorio | Denomina la capacità che l’agente propone di utilizzare. |
| purpose | Obbligatorio | Indica la finalità aziendale fornita alla valutazione della policy. |
| resource.type / resource.id | Obbligatorio | Identifica la risorsa di destinazione e il relativo tipo di risorsa. |
| data_boundary_ref | Obbligatorio | Denomina il perimetro dei dati governato associato alla richiesta. |
| environment | Obbligatorio | Identifica l’ambiente di esecuzione fornito nella richiesta. |
| requested_at | Obbligatorio | Registra quando è stata richiesta l’azione come data e ora RFC 3339. |
| amount.value / amount.currency | Condizionale | Trasporta una stringa decimale e una valuta maiuscola di tre lettere quando il valore finanziario influenza la policy. |
04
Esempio minimo
Questo esempio contiene i campi obbligatori per un’azione di lettura sintetica. Il secondo esempio scaricabile aggiunge l’importo e il contesto di traccia.
{
"schema_version": "1.0.0",
"action_request_id": "req_action_demo_0001",
"correlation": {
"correlation_id": "corr_credit_review_demo_0001",
"execution_id": "exec_credit_review_demo_0001"
},
"action": "read_case_summary",
"purpose": "review_credit_case",
"resource": {
"type": "credit_case",
"id": "case_demo_0001"
},
"data_boundary_ref": "boundary_credit_case_minimum",
"environment": "staging",
"requested_at": "2026-07-21T09:14:29.100Z"
}05
Convalida e verifica del digest
La convalida JSON Schema controlla la forma. Il verificatore complementare riproduce un digest sha256: sul record canonico e può controllare una firma Ed25519 opzionale e separata.
- 01Caricare lo schema con versione dall’URL di download del JSON Schema.
- 02Convalidare il documento JSON con un validatore draft 2020-12 e un plugin di formato date-time.
- 03Canonicalizzare il record autonomo completo con chiavi degli oggetti ordinate ricorsivamente, secondo l’approccio del verificatore dell’evento di audit pubblicato.
- 04Calcolare SHA-256 sui byte canonici e rappresentare il risultato con il prefisso sha256:.
- 05Confrontare il digest calcolato con quello conservato dalla procedura di evidenza chiamante.
- 06Quando è fornita una firma Ed25519 separata, risolvere in modo indipendente la relativa chiave pubblica e verificare la firma sul digest di 32 byte.
- 07Registrare una mancata corrispondenza dell’hash o un errore di firma come risultato di verifica non riuscito e conservare il record originale per l’indagine.
Richiesta valida rispetto allo schema
Gli esempi scaricabili sono validi rispetto al draft 2020-12 e producono un digest sha256: riproducibile dal loro contenuto canonico.
Controllo di manomissione
Modificare un campo come action mantiene il documento leggibile dal punto di vista strutturale, ma modifica il digest canonico. Il verificatore riportarecord_hash_mismatch.
Il verificatore autonomo accetta una firma Ed25519 opzionale e separata. La fiducia in una chiave pubblica deriva dal registro delle chiavi governato indipendentemente dal chiamante.
06
Compatibilità e versionamento
Versionare il contratto autonomo indipendentemente dalle release dell’agente, della policy e dello strumento.
Patch
Chiarimenti, descrizioni ed esempi possono cambiare mentre il comportamento di convalida rimane 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ù rigoroso o canonicalizzazione modificata richiedono un nuovo percorso major.
I consumatori conservano le versioni sconosciute per la revisione e interrompono l’elaborazione semantica finché il supporto non è dichiarato. Il percorso v1 usa schema_version 1.0.0.
07
Come KLA implementa questo schema
Lo schema di audit incorporato è la fonte normativa dei campi. I produttori in fase di esecuzione espongono campi correlati che la forma pubblica autonoma può collegare e normalizzare.
| Area del contratto | Fonte attuale | Associazione | Stato |
|---|---|---|---|
| Forma dell’azione richiesta incorporata | apps/platform/src/lib/ai-agent-audit-event/v1/schema.json | Lo schema dell’evento di audit definisce requested_action.action, purpose, resource, data_boundary_ref, environment, amount e requested_at. Questa pagina pubblica tali campi al livello superiore. | Fonte di riferimento rilasciata |
| Dati di richiesta dello strumento a runtime | services/execution-worker/src/services/audit-events.ts | recordToolAuditEvent registra executionId, toolName, toolAction, ambiti dei dati e hash per parametri e risultati dello strumento. La funzione non emette questo oggetto di richiesta autonomo normalizzato. | Produttore correlato attuale |
| Correlazione dell’esecuzione | services/execution-worker/src/services/audit-events.ts | I record di audit dello strumento contengono executionId e l’ID di traccia OpenTelemetry attivo. I consumatori usano l’oggetto di correlazione autonomo per collegare questi dati in fase di esecuzione. | Produttore correlato attuale |
| Collegamento tra policy e audit | services/shared/src/policy/contracts.ts | I contratti GateContext e GateDecision forniscono gli identificatori di esecuzione lato policy e i valori canonici della decisione usati dopo la valutazione di questa richiesta. | Contratto del consumatore attuale |
Astrazioni deliberate e campi non supportati
- •Lo schema omette ID di database del tenant, ID di riga interni e sintassi della policy Cerbos.
- •Lo schema contiene riferimenti alla risorsa e data_boundary_ref. Non contiene il contenuto non elaborato della risorsa, prompt, output del modello, argomenti dello strumento o risultati dello strumento.
- •Lo schema non afferma che il richiedente sia autorizzato. La decisione di policy e il percorso di autorizzazione che la utilizza stabiliscono il risultato di controllo applicabile.
- •Lo schema non prescrive come un’implementazione risolva un riferimento al perimetro dei dati o conservi i dati a cui si riferisce.
- •action_request_id autonomo e l’oggetto di correlazione sono aggiunte per la pubblicazione autonoma. L’oggetto requested_action incorporato non ha nessuno dei due campi.
- •Gli esempi pubblici contengono ID e timestamp sintetici. Non contengono dati dei clienti né materiale di credenziali.
08
Riferimenti correlati
Seguire la sequenza di esecuzione governata dalla richiesta, attraverso policy e approvazione, fino all’evento di audit completo.
Il risultato di policy valutato per questa azione richiesta.
Il record maker-checker usato quando la policy richiede un’approvazione umana.
L’involucro completo dell’evento che collega richiesta, policy, approvazione, strumenti e risultato.
Applica il contratto
Collega la richiesta al resto del record di esecuzione governata.
Usare lo schema del log di audit per l’involucro completo dell’evento, quindi seguire i riferimenti collegati di policy e approvazione nella sequenza di esecuzione.