Schéma de demande d’action d’un agent IA
Une demande d’action consigne l’autorité qu’un agent IA souhaite utiliser avant l’évaluation de la politique et tout effet d’outil. Cette référence autonome conserve la structure requested_action de l’événement d’audit publié et ajoute un action_request_id adressable ainsi qu’une corrélation pour un usage indépendant.
JSON Schema draft 2020-12 · Version 1.0.0 · Noms de champs normatifs en anglais
Repères essentiels
- Définition
- Enregistrement autonome d’une action d’agent demandée : capacité, finalité, ressource, périmètre de données, environnement et heure de la demande.
- Quand l’utiliser
- Créez-le lorsqu’un agent propose une action gouvernée. Reliez-le aux enregistrements de politique, d’approbation, d’outil et d’audit grâce à la corrélation.
- Champs obligatoires
- ID de la demande, version du schéma, identifiants de corrélation, action, finalité, ressource, périmètre de données, environnement et requested_at.
- Détail facultatif
- Ajoutez le montant pour les actions financières et le contexte de trace lorsque l’exécution porte des identifiants OpenTelemetry.
01
Schéma et exemples
Les artefacts versionnés sont autonomes. Les consommateurs peuvent valider la demande sans charger le schéma de l’événement d’audit.
/ai-agent-action-request/v1/schema.jsonTélécharger Exemple de lecture simpleDemande synthétique minimale, sans montant financier./ai-agent-action-request/v1/examples/basic-read.jsonTélécharger Exemple de décision de créditAction financière synthétique avec montant et corrélation de trace./ai-agent-action-request/v1/examples/credit-disposition.jsonTélécharger 02
Objet et ordre d’exécution
La demande est le premier contrat durable de la séquence de référence. La politique l’évalue avant l’enregistrement d’une approbation ou d’un effet d’outil.
- 01DemanderL’agent propose une action sur une ressource nommée, dans un périmètre de données et un environnement déclarés.
- 02Corréleraction_request_id identifie cet enregistrement autonome. correlation_id et execution_id le relient au graphe d’exécution.
- 03ÉvaluerLa décision de politique enregistre allow, warn, require_approval ou block pour la même corrélation d’exécution.
- 04PoursuivreUn appel d’outil suit une voie autorisée ou avertie. Une voie require_approval enregistre un événement d’approbation avant tout effet.
03
Dictionnaire des champs
Le dictionnaire couvre chaque champ de premier niveau, membre de ressource imbriqué, membre de corrélation et membre financier conditionnel.
Identité autonome et corrélation
| Champ | Statut | Finalité |
|---|---|---|
| schema_version | Obligatoire | Sélectionne le contrat de compatibilité utilisé pour analyser l’enregistrement. |
| action_request_id | Obligatoire | Adresse cette demande indépendamment et la relie à un événement d’audit. Ajouté pour la publication autonome. |
| correlation.correlation_id / execution_id | Obligatoire | Relie la demande aux enregistrements de politique, d’approbation, d’outil et d’audit sans jointure par horodatage. 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. |
Autorité demandée
| Champ | Statut | Finalité |
|---|---|---|
| action | Obligatoire | Nomme la capacité que l’agent propose d’utiliser. |
| purpose | Obligatoire | Indique la finalité métier fournie à l’évaluation de politique. |
| resource.type / resource.id | Obligatoire | Identifie la ressource cible et son type. |
| data_boundary_ref | Obligatoire | Nomme le périmètre de données gouverné associé à la demande. |
| environment | Obligatoire | Identifie l’environnement d’exécution fourni avec la demande. |
| requested_at | Obligatoire | Enregistre l’heure de la demande au format date-heure RFC 3339. |
| amount.value / amount.currency | Conditionnel | Transporte une chaîne décimale et une devise majuscule à trois lettres lorsque la valeur financière influence la politique. |
04
Exemple minimal
Cet exemple contient les champs obligatoires d’une action de lecture synthétique. Le second exemple téléchargeable ajoute un montant et le contexte de trace.
{
"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
Validation et vérification de l’empreinte
La validation JSON Schema vérifie la structure. Le vérificateur compagnon reproduit une empreinte sha256: sur l’enregistrement canonique 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 complet en triant récursivement les clés des objets, conformément à l’approche du vérificateur d’événements d’audit publié.
- 04Calculez SHA-256 sur les octets canoniques et représentez le résultat avec le préfixe sha256:.
- 05Comparez l’empreinte calculée à celle conservée par la procédure de preuve appelante.
- 06Lorsqu’une signature Ed25519 détachée est fournie, résolvez sa clé publique indépendamment et vérifiez la signature sur l’empreinte de 32 octets.
- 07Consignez une divergence d’empreinte ou un échec de signature comme une vérification échouée et conservez l’enregistrement original pour enquête.
Demande conforme au schéma
Les exemples téléchargeables sont valides selon le draft 2020-12 et produisent une empreinte sha256: reproductible à partir de leur contenu canonique.
Contrôle d’altération
Modifier un champ tel que action 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 une clé publique provient du registre de clés gouverné et indépendant de l’appelant.
06
Compatibilité et versionnement
Versionnez le contrat autonome indépendamment des versions de l’agent, de la politique et de l’outil.
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.
Les consommateurs doivent conserver les versions inconnues pour revue et les traiter comme non prises en charge jusqu’à déclaration explicite. Le chemin v1 utilise schema_version 1.0.0.
07
Implémentation par KLA
Le schéma d’audit intégré fournit les champs normatifs. Les producteurs d’exécution exposent des champs associés que la forme autonome publique peut relier et normaliser.
| Contrat source | Source actuelle | Correspondance | Statut |
|---|---|---|---|
| Structure requested_action intégrée | apps/platform/src/lib/ai-agent-audit-event/v1/schema.json | Le schéma d’événement d’audit définit requested_action.action, purpose, resource, data_boundary_ref, environment, amount et requested_at. Cette page publie ces champs au niveau supérieur. | Source de référence publiée |
| Demande d’outil d’exécution | services/execution-worker/src/services/audit-events.ts | recordToolAuditEvent enregistre executionId, toolName, toolAction, les périmètres de données et les hachages des paramètres et résultats de l’outil. La fonction n’émet pas cet objet de demande autonome normalisé. | Producteur associé actuel |
| Corrélation d’exécution | services/execution-worker/src/services/audit-events.ts | Les enregistrements d’audit d’outil portent executionId et l’ID de trace OpenTelemetry actif. Les consommateurs utilisent l’objet correlation autonome pour relier ces faits d’exécution. | Producteur associé actuel |
| Lien entre politique et audit | services/shared/src/policy/contracts.ts | Les contrats GateContext et GateDecision fournissent les identifiants d’exécution côté politique et les valeurs de décision canoniques utilisées après l’évaluation de cette demande. | Contrat consommateur 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 ID internes de lignes et la syntaxe de politique Cerbos.
- •Le schéma porte des références de ressources et data_boundary_ref. Il ne porte pas les contenus bruts des ressources, les invites, la sortie du modèle, les arguments d’outil ni les résultats d’outil.
- •Le schéma n’affirme pas que le demandeur est autorisé. La décision de politique et la voie d’autorisation consommatrice établissent le résultat de contrôle applicable.
- •Le schéma ne prescrit pas la résolution d’une référence de périmètre de données ni la conservation des données référencées.
- •action_request_id et l’objet correlation autonomes sont ajoutés pour la publication indépendante. L’objet requested_action imbriqué ne comporte aucun de ces champs.
- •Les exemples publics contiennent des ID et horodatages synthétiques. Ils ne contiennent ni données client ni éléments d’identification.
08
Références associées
Suivez la séquence d’exécution gouvernée, de la demande à la politique, à l’approbation et à l’événement d’audit complet.
Le résultat de politique évalué pour cette demande d’action.
L’enregistrement maker-checker utilisé lorsque la politique exige une approbation humaine.
L’enveloppe complète qui relie demande, politique, approbation, outils et résultat.
Appliquer le contrat
Reliez la demande au reste de l’enregistrement d’exécution gouvernée.
Utilisez le schéma de journal d’audit pour l’enveloppe complète de l’événement, puis suivez les références de politique et d’approbation liées dans la séquence d’exécution.