Schéma d’événement d’approbation d’un agent IA
Un événement d’approbation consigne le cycle de décision d’une action d’agent IA gouvernée qui a atteint la revue humaine. Cette référence autonome conserve la définition d’approbation de l’événement d’audit publié et ajoute approval_event_id ainsi qu’une corrélation pour un usage indépendant.
JSON Schema draft 2020-12 · Version 1.0.0 · Enregistrement de décision maker-checker
Repères essentiels
- Définition
- Enregistrement autonome du statut d’une demande d’approbation, du rôle requis, du réviseur humain lorsqu’elle est décidée, de la décision, des échéances et des références de justification facultatives.
- Quand l’utiliser
- Créez-le lorsqu’un résultat de politique achemine une action vers une approbation humaine, puis consignez-le lorsque la demande est décidée, expire ou est annulée.
- Valeurs de décision
- approved, rejected, expired et cancelled décrivent la décision terminale représentée par l’événement.
- Maker-checker
- Les routes d’approbation vérifient approval:decide, le rôle requis, l’état pending et la séparation des tâches avant d’enregistrer une décision.
01
Schéma et exemples d’approbation
Le schéma versionné et les deux exemples de décisions terminales sont des artefacts autonomes pour la validation et l’implémentation.
/ai-agent-approval-event/v1/schema.jsonTélécharger Exemple d’événement approuvéApprobation décidée avec un réviseur humain synthétique./ai-agent-approval-event/v1/examples/approved.jsonTélécharger Exemple d’événement refuséRefus décidé avec code de motif et référence de justification./ai-agent-approval-event/v1/examples/rejected.jsonTélécharger 02
Objet et ordre d’exécution
L’événement d’approbation se situe entre un résultat de politique require_approval et tout effet d’outil approuvé. Les chemins expiré et refusé restent des résultats refusés ou non démarrés traçables.
- 01DemanderUn résultat de politique require_approval crée une demande associée à la corrélation d’exécution et à un rôle requis.
- 02RevoirUn réviseur examine les preuves présentées et agit via une route d’approbation avec la permission approval:decide.
- 03VérifierLes routes vérifient le rôle requis, l’état pending et la séparation maker-checker. L’approbation exige aussi une reconnaissance explicite.
- 04EnregistrerLa décision est persistée et une obligation d’audit durable est écrite avant que le workflow gouverné soit signalé pour reprendre.
03
Dictionnaire des champs
Le dictionnaire couvre chaque membre d’approbation, y compris les champs conditionnels du cycle de vie et les références facultatives de réaffectation, d’annulation et d’appel.
Identité autonome et corrélation
| Champ | Statut | Finalité |
|---|---|---|
| schema_version | Obligatoire | Sélectionne le contrat de compatibilité utilisé pour analyser l’enregistrement. |
| approval_event_id | Obligatoire | Adresse cet événement d’approbation et le relie à un événement d’audit. Ajouté pour la publication autonome. |
| correlation.correlation_id / execution_id | Obligatoire | Relie l’approbation à la demande, à la politique, à 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. |
Cycle de vie de la demande d’approbation
| Champ | Statut | Finalité |
|---|---|---|
| request_id | Obligatoire | Identifie la demande d’approbation décidée et conserve le sens de approval.request_id intégré. |
| status | Obligatoire | Indique si l’événement est decided, expired ou cancelled. |
| requested_at / expires_at | Obligatoire | Enregistre la demande et son expiration au format date-heure RFC 3339. |
| required_role | Obligatoire | Nomme le rôle requis pour décider l’approbation. |
| decided_at | Obligatoire | Enregistre l’heure de la décision terminale, de l’expiration ou de l’annulation. |
Décision et références associées
| Champ | Statut | Finalité |
|---|---|---|
| decision | Obligatoire | Porte approved, rejected, expired ou cancelled et correspond au statut du cycle de vie. |
| reviewer | Conditionnel | Identifie le réviseur humain lorsque le statut est decided. Le type est toujours user. |
| presented_evidence_digest | Facultatif | Lie la décision à la représentation des preuves présentée pendant la revue. |
| reason_code / rationale_reference | Facultatif | Fournit un motif stable et une référence vers une justification plus complète. |
| reassigned_from | Facultatif | Conserve le principal initial lorsqu’une demande d’approbation est réassignée. |
| override.authority_reference / reason_code | Facultatif | Référence l’autorité d’exception et son motif lorsqu’un override est enregistré. |
| appeal.status / reference | Facultatif | Lie un cycle d’appel ultérieur à sa référence stable. |
04
Exemple minimal
L’enregistrement approuvé montre les champs obligatoires et le réviseur requis pour un statut decided. L’enregistrement refusé fournit une seconde décision 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
Validation et vérification de l’empreinte
La validation JSON Schema vérifie le statut et la forme de la décision. 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 et conservez la décision et sa demande liée.
Exemples de décision terminale
Les exemples approuvé et refusé sont valides selon le draft 2020-12 et produisent des empreintes sha256: reproductibles à partir de leur contenu canonique.
Contrôle d’altération
Modifier la décision change le sens du cycle de vie et 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 le contrat d’événement d’approbation indépendamment du service d’approbation et du contrat de politique.
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 worker crée les enregistrements d’audit d’approbation. Les routes API appliquent l’autorité de décision et persistent une obligation de décision durable.
| Contrat source | Source actuelle | Correspondance | Statut |
|---|---|---|---|
| Demande et résolution d’approbation | services/execution-worker/src/services/audit-events.ts | Le worker enregistre les événements d’audit de demande et de résolution avec exécution, approbation, gouvernance, décision, motif et contexte de trace. Cette page normalise ces faits dans la forme publique de l’événement d’approbation. | Producteur actuel avec normalisation |
| API de décision maker-checker | services/execution-api/src/routes/approvals.ts | L’API vérifie la permission approval:decide, le rôle requis, l’état pending et l’auto-approbation. Approuver exige aussi une reconnaissance explicite ; une escalade conserve la demande en attente. | Consommateur et producteur actuels |
| Decision Desk et route d’approbation locale | services/api/src/routers/approvals.ts | Le routeur applique les mêmes règles de permission et d’accès maker-checker, valide les contrôles de politique et de preuve, persiste un enregistrement de décision et coordonne l’état local ou execution-api. | Consommateur et producteur actuels |
| Vocabulaire de décision et version | services/shared/src/policy/contracts.ts | Le contrat de politique partagé fournit require_approval comme voie vers cet événement et conserve le versionnement de la politique indépendant du schéma d’approbation. | Contrat partagé actuel |
Abstractions délibérées et champs non pris en charge
- •Le schéma omet les ID de base de données du tenant, les colonnes de la table d’approbation, la syntaxe d’autorisation Cerbos et le contenu brut des demandes ou des preuves.
- •Le schéma consigne required_role et l’identité du réviseur. Il ne prouve pas que le réviseur possédait ce rôle au moment de la décision ; les consommateurs vérifient cette autorité.
- •Le schéma porte les statuts terminaux decided, expired et cancelled. L’action d’escalade actuelle de l’API conserve la demande pending et n’ajoute pas escalated à ce contrat.
- •Le schéma transporte des références facultatives de preuve, justification, réaffectation, override et appel. Il ne définit ni le paquet de preuves, ni la procédure d’appel, ni la politique d’autorité d’override.
- •Le schéma ne publie pas l’adresse e-mail du réviseur, les instantanés de rôles, les commentaires ou les reçus de décision. Ces champs restent dans les enregistrements de décision et d’audit de KLA.
- •approval_event_id et l’objet correlation autonomes sont ajoutés pour la publication indépendante. request_id conserve le sens de la demande d’approbation intégrée.
08
Références associées
Suivez la séquence de la demande d’action à la décision de politique, à l’approbation si nécessaire, puis à l’événement d’audit complet.
L’action qui a atteint l’évaluation de politique.
Le résultat require_approval qui achemine l’action vers la revue.
L’enveloppe complète qui enregistre demande, décision, approbation, effet et résultat.
Appliquer le contrat
Reliez la décision humaine à la branche de politique qui l’a résolue.
Utilisez les identifiants de corrélation et de demande pour relier l’événement d’approbation à la demande d’action, à la décision de politique, à l’événement d’audit complet et aux preuves ultérieures.