Schema für Aktionsanforderungen von KI-Agenten
Eine Aktionsanforderung zeichnet die Autorisierung auf, die ein KI-Agent vor der Richtlinienbewertung und jeder Tool-Wirkung anfordert. Diese eigenständige Referenz bewahrt die requested_action-Struktur aus dem veröffentlichten Audit-Ereignis und fügt eine adressierbare action_request_id sowie Korrelation für die unabhängige Nutzung hinzu.
JSON Schema-Entwurf 2020-12 · Version 1.0.0 · Normative Feldnamen auf Englisch
Schnellreferenz
- Definition
- Ein eigenständiger Datensatz einer angeforderten Agentenaktion: Fähigkeit, Zweck, Ressource, Datenbereich, Umgebung und Anforderungszeit.
- Wann verwendet
- Erstellen Sie ihn, wenn ein Agent eine geregelte Aktion vorschlägt. Verknüpfen Sie ihn mit Richtlinien-, Genehmigungs-, Werkzeug- und Prüfungsaufzeichnungen mithilfe von Korrelation.
- Erforderliche Felder
- Die Anforderungs-ID, Schema-Version, Korrelations-IDs, Aktion, Zweck, Ressource, Datenbereich, Umgebung und requested_at.
- Optionale Details
- Geben Sie den Betrag für finanzielle Aktionen an und fügen Sie den Spurenkontext hinzu, wenn die Ausführung OpenTelemetry-Identifikatoren trägt.
01
Schema und Beispiele
Die versionierten Artefakte sind eigenständig. Verbraucher können die Anfrage validieren, ohne das Audit-Event-Schema zu laden.
/ai-agent-action-request/v1/schema.jsonHerunterladen Ein einfaches Lese-BeispielMinimale synthetische Anfrage ohne finanziellen Betrag./ai-agent-action-request/v1/examples/basic-read.jsonHerunterladen Beispiel für KreditverfügungSynthetische Finanzaktion mit Betrag und Spurkorrelation./ai-agent-action-request/v1/examples/credit-disposition.jsonHerunterladen 02
Objekt- und Ausführungsreihenfolge
Die Anfrage ist der erste dauerhafte Vertrag in der Referenzsequenz. Die Richtlinie bewertet sie, bevor eine Genehmigung oder ein Werkzeug-Effekt aufgezeichnet wird.
- 01AnfrageDer Agent schlägt eine Aktion gegen eine benannte Ressource innerhalb einer deklarierten Daten-Grenze und Umgebung vor.
- 02KorrelierenDer action_request_id identifiziert diesen eigenständigen Datensatz. correlation_id und execution_id verbinden ihn mit dem Ausführungsgraphen.
- 03BewertenDie Richtlinienentscheidung zeichnet allow, warn, require_approval oder block für die gleiche Ausführungs-Korrelation auf.
- 04FortsetzenEin Werkzeugaufruf folgt einem zulässigen oder warnenden Pfad. Ein require_approval-Pfad zeichnet ein Genehmigungsereignis vor einer Wirkung auf.
03
Feldwörterbuch
Das Wörterbuch deckt jedes Top-Level-Feld, jedes geschachtelte Ressourcenmitglied, jedes Korrelationsmitglied und jedes bedingte Finanzmitglied ab.
Eigenständige Identität und Korrelation
| Feld | Status | Zweck |
|---|---|---|
| schema_version | Erforderlich | Wählt den Kompatibilitätsvertrag aus, der zur Analyse des Datensatzes verwendet wird. |
| action_request_id | Erforderlich | Adressiert diese Anfrage unabhängig und verknüpft sie mit einem Audit-Ereignis. Hinzugefügt für die eigenständige Veröffentlichung. |
| correlation.correlation_id / execution_id | Erforderlich | Verbindet die Anfrage mit Richtlinie, Genehmigung, Werkzeug- und Audit-Datensätzen ohne Zeitstempel-Verknüpfung. Hinzugefügt für eigenständige Veröffentlichung. |
| correlation.trace_id / span_id / parent_event_id | Optional | Trägt den OpenTelemetry-Trace-Kontext und ein optionales übergeordnetes Ereignis. Alle W3C-Identifikatoren mit Nullwerten sind ungültig. |
Angeforderte Berechtigung
| Feld | Status | Zweck |
|---|---|---|
| action | Erforderlich | Nennt die Fähigkeit, die der Agent zu verwenden vorschlägt. |
| purpose | Erforderlich | Gibt den geschäftlichen Zweck an, der der Richtlinienbewertung zugeführt wurde. |
| resource.type / resource.id | Erforderlich | Identifiziert die Zielressource und deren Ressourcentyp. |
| data_boundary_ref | Erforderlich | Nennt die verwaltete Datenbegrenzung, die mit der Anfrage verbunden ist. |
| environment | Erforderlich | Identifiziert die Ausführungsumgebung, die der Anfrage übermittelt wurde. |
| requested_at | Erforderlich | Zeichnet auf, wann die Aktion als RFC 3339-Datum-Uhrzeit angefordert wurde. |
| amount.value / amount.currency | Bedingt | Trägt eine Dezimalzeichenfolge und einen Währungscode aus drei Großbuchstaben, wenn der finanzielle Wert die Richtlinie beeinflusst. |
04
Minimales Beispiel
Dieses Beispiel enthält die erforderlichen Felder für eine synthetische Leseaktion. Das zweite herunterladbare Beispiel fügt Betrag und Trace-Kontext hinzu.
{
"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
Validierung und Digest-Überprüfung
JSON Schema Validierung überprüft die Form. Der begleitende Verifizierer erzeugt einen sha256-Digest über den kanonischen Datensatz und kann eine optionale abgetrennte Ed25519-Signatur überprüfen.
- 01Laden Sie das versionierte Schema von der JSON Schema-Download-URL.
- 02Validieren Sie das JSON-Dokument mit einem Entwurf-2020-12-Validator und einem Datum-Uhrzeit-Format-Plugin.
- 03Kanonisieren Sie den vollständigen eigenständigen Datensatz mit rekursiv sortierten Objektschlüsseln, die dem veröffentlichten Audit-Ereignis-Verifizierer-Ansatz entsprechen.
- 04Berechnen Sie SHA-256 über die kanonischen Bytes und stellen Sie das Ergebnis mit dem Präfix sha256: dar.
- 05Vergleichen Sie den berechneten Digest mit dem Digest, der vom aufrufenden Nachweisverfahren aufbewahrt wird.
- 06Wenn eine getrennte Ed25519-Signatur bereitgestellt wird, lösen Sie deren öffentlichen Schlüssel unabhängig auf und überprüfen Sie die Signatur über den 32-Byte-Digest.
- 07Ein Hash-Mismatch oder ein Signaturfehler wird als fehlgeschlagenes Verifizierungsergebnis aufgezeichnet und der ursprüngliche Datensatz zur Untersuchung aufbewahrt.
Schema-validierte Anfrage
Die herunterladbaren Beispiele validieren gegen Entwurf 2020-12 und erzeugen einen reproduzierbaren sha256-Digest aus ihrem kanonischen Inhalt.
Manipulationsprüfung
Das Ändern eines Feldes wie action macht das Dokument strukturell lesbar, während sich der kanonische Digest ändert. Der Prüfer meldetrecord_hash_mismatch.
Der eigenständige Verifizierer akzeptiert eine optionale abgetrennte Ed25519-Signatur. Das Vertrauen in einen öffentlichen Schlüssel ergibt sich aus dem unabhängig verwalteten Schlüsselregister des Aufrufers.
06
Kompatibilität und Versionierung
Versionieren Sie den eigenständigen Vertrag unabhängig von Agenten-, Richtlinien- und Tool-Releases.
Korrekturversion
Klarstellungen, Beschreibungen und Beispiele können sich ändern, während das Validierungsverhalten stabil bleibt. Ein korrigiertes unveränderliches Artefakt erhält eine neue versionierte URL.
Klein
Neue optionale Felder erfordern eine neue schema_version und versionierte URL. Verbraucher erklären die Unterstützung, bevor sie die neue Version verarbeiten.
Groß
Entfernte oder umbenannte Felder, geänderte Bedeutungen, strengere Pflichtfelder oder geänderte Kanonisierung erfordern einen neuen Hauptversionspfad.
Verbraucher bewahren unbekannte Versionen zur Überprüfung auf und stoppen die semantische Verarbeitung, bis Unterstützung erklärt wird. Der v1-Pfad verwendet schema_version 1.0.0.
07
Wie KLA dies implementiert
Das eingebettete Audit-Schema ist die maßgebliche Feldquelle. Laufzeitproduzenten stellen zugehörige Felder bereit, die sich mit der öffentlichen eigenständigen Form verknüpfen und normalisieren lassen.
| Vertragsbereich | Aktuelle Quelle | Zuordnung | Status |
|---|---|---|---|
| Eingebettete angeforderte Aktionsform | apps/platform/src/lib/ai-agent-audit-event/v1/schema.json | Das Audit-Ereignis-Schema definiert requested_action.action, Zweck, Ressource, data_boundary_ref, Umgebung, Menge und requested_at. Diese Seite veröffentlicht diese Felder auf oberster Ebene. | Gelieferte Referenzquelle |
| Laufzeit-Tool-Anforderungsfakten | services/execution-worker/src/services/audit-events.ts | recordToolAuditEvent zeichnet executionId, toolName, toolAction, Datenbereiche und Hashes für Tool-Parameter und Ergebnisse auf. Die Funktion gibt dieses normalisierte eigenständige Anfrageobjekt nicht aus. | Aktueller verwandter Produzent |
| Ausführungs-Korrelation | services/execution-worker/src/services/audit-events.ts | Tool-Audit-Aufzeichnungen enthalten executionId und die aktive OpenTelemetry Trace-ID. Verbraucher verwenden das eigenständige Korrelationsobjekt, um diese Laufzeitinformationen zu verbinden. | Aktueller verwandter Produzent |
| Verknüpfung von Richtlinien und Audit | services/shared/src/policy/contracts.ts | GateContext- und GateDecision-Verträge stellen die ausführungsseitigen Richtlinien-IDs und kanonischen Entscheidungswerte bereit, die nach der Auswertung dieser Anfrage verwendet werden. | Aktueller Verbraucher-Vertrag |
Bewusste Abstraktionen und nicht unterstützte Felder
- •Das Schema lässt Mandanten-Datenbank-IDs, interne Zeilen-IDs und Cerbos-Richtliniensyntax aus.
- •Das Schema enthält Ressourcenreferenzen und data_boundary_ref. Es enthält keine Rohinhalte der Ressourcen, Aufforderungen, Modellausgaben, Werkzeugargumente oder Werkzeugergebnisse.
- •Das Schema behauptet nicht, dass der Anforderer autorisiert ist. Die politische Entscheidung und der verbrauchende Autorisierungspfad legen das anwendbare Kontrollresultat fest.
- •Das Schema schreibt nicht vor, wie eine Implementierung eine Datengrenzenreferenz auflöst oder die referenzierten Daten beibehält.
- •Das eigenständige action_request_id- und Korrelationsobjekt sind Ergänzungen für die eigenständige Veröffentlichung. Das eingebettete requested_action-Objekt hat keines der Felder.
- •Die öffentlichen Beispiele enthalten synthetische IDs und Zeitstempel. Sie enthalten keine Kundendaten oder Zugangsdaten.
08
Verwandte Referenzen
Folgen Sie der gesteuerten Ausführungssequenz von der Anfrage über die Richtlinie, Genehmigung bis zum vollständigen Prüfungsvorgang.
Das für diese angeforderte Aktion bewertete Richtlinienergebnis.
Der Maker-Checker-Eintrag, der verwendet wird, wenn die Richtlinie eine menschliche Genehmigung erfordert.
Der vollständige Ereignisrahmen, der Anfrage, Richtlinie, Genehmigung, Werkzeuge und Ergebnis verbindet.
Vertrag anwenden
Verknüpfen Sie die Anfrage mit dem Rest des gesteuerten Ausführungsprotokolls.
Verwenden Sie das Audit-Log-Schema für den vollständigen Ereignishülle, und folgen Sie dann den verknüpften Richtlinien- und Genehmigungsverweisen durch die Ausführungssequenz.