Schéma de réponse de décision de politique d’un agent IA
Une réponse de décision de politique consigne l’identité de la politique, les entrées protégées, le résultat canonique, les règles correspondantes, les codes de motif et l’heure d’évaluation. Cette référence autonome conserve le sous-objet policy de l’événement d’audit publié et ajoute policy_decision_event_id ainsi qu’une corrélation pour un usage indépendant.
JSON Schema draft 2020-12 · Version 1.0.0 · Quatre valeurs de décision canoniques
Repères essentiels
- Définition
- Réponse autonome de l’évaluation de politique avec identité de politique, empreintes des entrées et de la politique, une décision canonique, les règles correspondantes et les codes de motif.
- Quand l’utiliser
- Créez-la après l’évaluation d’une demande d’action et avant que l’exécution ne poursuive sa route, soit mise en pause pour approbation ou soit arrêtée.
- Valeurs de décision
- allow, warn, require_approval et block sont les valeurs canoniques du contrat de politique partagé.
- Action refusée
- L’exemple block consigne destination_outside_declared_boundary dans reason_codes et ne contient aucun champ d’exécution, car cette page décrit l’objet de décision.
01
Schéma et exemples de décision
Le schéma et les quatre exemples de décision sont disponibles comme artefacts versionnés immuables. Chaque valeur de décision possède un enregistrement concret.
/ai-agent-policy-decision/v1/schema.jsonTélécharger Exemple allowDécision pour une action dans le périmètre déclaré./ai-agent-policy-decision/v1/examples/allow.jsonTélécharger Exemple warnDécision qui poursuit la route du worker avec un marqueur d’avertissement./ai-agent-policy-decision/v1/examples/warn.jsonTélécharger Exemple require_approvalDécision qui achemine l’action vers une demande d’approbation humaine./ai-agent-policy-decision/v1/examples/require-approval.jsonTélécharger Exemple blockDécision d’action refusée avec un code de motif de périmètre./ai-agent-policy-decision/v1/examples/block.jsonTélécharger 02
Objet et ordre d’exécution
La réponse suit la demande d’action. Sa décision sélectionne la route avant un appel d’outil ou un effet métier.
- 01DemanderLa demande d’action de l’agent fournit l’action, la finalité, la ressource, le périmètre de données et l’environnement.
- 02ÉvaluerL’évaluateur lie le résultat à policy_id, policy_version, policy_digest, inputs_digest, aux règles correspondantes et aux codes de motif.
- 03Acheminerallow poursuit l’action. warn poursuit la route du worker et émet un avertissement. require_approval crée une voie d’approbation humaine. block arrête l’action.
- 04EnregistrerLa décision reste reliée aux enregistrements ultérieurs d’approbation, d’outil et d’audit grâce à la corrélation.
03
Dictionnaire des champs
Le dictionnaire couvre chaque membre obligatoire et facultatif, y compris les ajouts d’identité autonome et de corrélation.
Identité autonome et corrélation
| Champ | Statut | Finalité |
|---|---|---|
| schema_version | Obligatoire | Sélectionne le contrat de compatibilité utilisé pour analyser l’enregistrement. |
| policy_decision_event_id | Obligatoire | Adresse cette décision et la relie à un événement d’audit. Ajouté pour la publication autonome. |
| correlation.correlation_id / execution_id | Obligatoire | Relie le résultat de politique à la demande, à l’approbation, à l’outil et à l’audit. Ajouté pour la publication autonome. |
| correlation.trace_id / span_id / parent_event_id | Facultatif | Transporte le contexte de trace OpenTelemetry et un événement parent facultatif. Les identifiants W3C composés uniquement de zéros sont invalides. |
Identité de la politique et entrées protégées
| Champ | Statut | Finalité |
|---|---|---|
| decision_id | Obligatoire | Identifie la décision d’évaluation de politique dans le système de gouvernance source. |
| policy_id / policy_version | Obligatoire | Nomme la politique et la version exacte utilisées pour l’évaluation. |
| policy_digest / inputs_digest | Obligatoire | Lie le résultat aux représentations protégées de la politique et des entrées. |
Explication de la décision
| Champ | Statut | Finalité |
|---|---|---|
| decision | Obligatoire | Porte allow, warn, require_approval ou block. |
| evaluated_at | Obligatoire | Enregistre la fin de l’évaluation de politique comme date-heure RFC 3339. |
| matched_rule_ids | Obligatoire | Liste les identifiants uniques des règles correspondantes pendant l’évaluation. |
| reason_codes | Obligatoire | Liste au moins un identifiant unique expliquant le résultat sélectionné. |
04
Exemple minimal
L’enregistrement allow montre l’objet de décision complet le plus court. Les téléchargements ajoutent les cas warn, require_approval et 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
Validation et vérification de l’empreinte
La validation JSON Schema vérifie la structure. Le vérificateur compagnon reproduit une empreinte sha256: et peut vérifier une signature Ed25519 détachée facultative.
- 01Chargez le schéma versionné depuis l’URL de téléchargement du JSON Schema.
- 02Validez le document JSON avec un validateur draft 2020-12 et un module de format date-heure.
- 03Canonisez l’enregistrement autonome en triant récursivement les clés des objets, conformément au vérificateur d’événements d’audit publié.
- 04Calculez SHA-256 sur les octets canoniques et utilisez le préfixe sha256:.
- 05Comparez l’empreinte calculée à celle conservée par la procédure de preuve appelante.
- 06Avec une signature Ed25519 détachée, résolvez la clé publique indépendamment et vérifiez la signature sur l’empreinte de 32 octets.
- 07Consignez toute divergence d’empreinte ou tout échec de signature comme une vérification échouée. Une structure valide seule ne prouve pas qu’un enregistrement est inchangé.
Exemples conformes aux quatre décisions
Les exemples allow, warn, require_approval et block sont valides selon le draft 2020-12 et produisent des empreintes sha256: reproductibles à partir de leur contenu canonique.
Contrôle d’altération
Modifier reason_codes conserve un document lisible par le schéma, mais change l’empreinte canonique. Le vérificateur signalerecord_hash_mismatch.
Le vérificateur autonome accepte une signature Ed25519 détachée facultative. La confiance dans la clé publique provient d’un registre de clés gouverné indépendant de l’appelant.
06
Compatibilité et versionnement
Versionnez la réponse indépendamment des policy packs et des versions de l’évaluateur.
Correctif
Les clarifications, descriptions et exemples peuvent évoluer tant que le comportement de validation reste stable. Un artefact immuable corrigé reçoit une nouvelle URL versionnée.
Version mineure
De nouveaux champs facultatifs exigent une nouvelle schema_version et une URL versionnée. Les consommateurs doivent déclarer leur prise en charge avant de traiter la nouvelle version.
Version majeure
La suppression ou le renommage de champs, la modification de sens, le renforcement d’un statut obligatoire ou la modification de la canonisation exigent une nouvelle version majeure.
Conservez les versions inconnues pour revue et traitez-les comme non prises en charge jusqu’à déclaration explicite. Le chemin v1 utilise schema_version 1.0.0.
07
Implémentation par KLA
Le contrat de politique partagé définit le vocabulaire de décision. Les routes worker et d’exécution enregistrent l’évaluation et la voie de gouvernance qui suit.
| Contrat source | Source actuelle | Correspondance | Statut |
|---|---|---|---|
| Vocabulaire canonique de décision | services/shared/src/policy/contracts.ts | Les valeurs du schéma GateDecision et POLICY_SCHEMA_VERSION définissent allow, warn, require_approval, block et la version 1.0.0 du schéma de politique. | Contrat partagé actuel |
| Enregistrement de décision | services/execution-worker/src/services/audit-events.ts | recordPolicyDecisionAuditEvent enregistre identité de politique, décision, motifs, règles, workflow et détails d’exécution. L’ancien helper accepte deny pour la voie bloquée ; cette page utilise la valeur canonique block. | Producteur actuel avec normalisation |
| Route choisie par la décision | services/execution-worker/src/workflows/workflow-spec-runner.ts | Le workflow poursuit allow et warn, marque warn comme avertissement, demande une approbation pour require_approval et arrête block. | Consommateur d’exécution actuel |
| Lien avec l’audit | services/execution-worker/src/services/audit-events.ts | Les producteurs d’audit de politique et d’approbation conservent les identifiants d’exécution et le contexte de trace actif afin de relier une décision à l’enregistrement d’exécution qui l’entoure. | Producteur associé actuel |
Abstractions délibérées et champs non pris en charge
- •Le schéma omet les documents de politique Cerbos, les corps de règles JSON Logic, les charges d’entitlements et la configuration de l’évaluateur.
- •Le schéma enregistre les empreintes de la politique et des entrées. Il ne publie pas le texte protégé de la politique, les arguments de la demande, les invites, la sortie du modèle ni les données personnelles brutes.
- •Le schéma enregistre une décision canonique. Il ne code pas chaque signal de contrôle interne, classification, remédiation ou trace du juge transporté par le contrat GateDecision partagé plus large.
- •Le schéma enregistre les ID des règles correspondantes et les codes de motif. Il n’affirme pas qu’un code prouve l’autorisation, l’isolation des tenants ou l’exhaustivité de la population source.
- •policy_decision_event_id et l’objet correlation autonomes sont ajoutés pour la publication indépendante. L’objet policy imbriqué ne comporte aucun de ces champs.
- •Les exemples sont des enregistrements synthétiques. Leurs empreintes illustrent les contraintes de champs et ne contiennent aucun identifiant client ou de production.
08
Références associées
Suivez la demande, la décision de politique, l’approbation si nécessaire et l’événement d’audit complet dans l’ordre d’exécution.
L’action demandée que cette réponse évalue.
L’enregistrement maker-checker utilisé lorsque le résultat est require_approval.
L’enveloppe complète de la demande, de la politique, de l’approbation, de l’outil, du résultat et de l’intégrité.
Appliquer le contrat
Conservez le résultat de politique avec la demande qu’il a évaluée.
Utilisez les références de demande d’action et d’approbation avec cette réponse, puis le schéma de journal d’audit pour conserver la séquence complète de l’exécution gouvernée.