Schema für Richtlinienentscheidungen von KI-Agenten
Eine Antwort auf eine Richtlinienentscheidung zeichnet die Richtlinienidentität, geschützte Eingaben, das kanonische Ergebnis, zugeordnete Regeln, Begründungscodes und den Bewertungszeitpunkt auf. Diese eigenständige Referenz bewahrt das Richtlinien-Subobjekt aus dem veröffentlichten Audit-Ereignis und fügt eine adressierbare policy_decision_event_id sowie Korrelation für die unabhängige Nutzung hinzu.
JSON Schema-Entwurf 2020-12 · Version 1.0.0 · Vier kanonische Entscheidungswerte
Schnellreferenz
- Definition
- Eine eigenständige Antwort aus der Richtlinienbewertung mit Richtlinienidentität, Eingaben und Richtlinien-Hashes, einer kanonischen Entscheidung, übereinstimmenden Regeln und Begründungscodes.
- Wann verwendet
- Erstellen Sie es nach der Auswertung einer Aktionsanforderung und bevor die Ausführungsroute fortgesetzt, für die Genehmigung pausiert oder gestoppt wird.
- Entscheidungswerte
- allow, warn, require_approval und block sind die kanonischen Werte im gemeinsamen Richtlinienvertrag.
- Abgelehnte Aktion
- Das block-Beispiel zeichnet destination_outside_declared_boundary in reason_codes auf und enthält keine Ausführungsfelder, da diese Seite das Entscheidungsobjekt beschreibt.
01
Schema- und Entscheidungsbeispiele
Das Schema und vier Entscheidungsbeispiele sind als unveränderliche versionierte Artefakte verfügbar. Jeder Entscheidungswert hat einen konkreten Datensatz.
/ai-agent-policy-decision/v1/schema.jsonHerunterladen Beispiel erlaubenEntscheidung für eine Aktion innerhalb des deklarierten Umfangs./ai-agent-policy-decision/v1/examples/allow.jsonHerunterladen Beispiel warnenEntscheidung, die den aktuellen Arbeitsweg mit einem Warnhinweis fortsetzt./ai-agent-policy-decision/v1/examples/warn.jsonHerunterladen Genehmigung erforderlich BeispielEntscheidung, die die Aktion an eine menschliche Genehmigungsanforderung weiterleitet./ai-agent-policy-decision/v1/examples/require-approval.jsonHerunterladen Beispiel blockierenAbgelehnte-Aktion-Entscheidung mit einem Grenzgrundleistungs-Code./ai-agent-policy-decision/v1/examples/block.jsonHerunterladen 02
Objekt- und Ausführungsreihenfolge
Die Antwort folgt der Aktionsanforderung. Ihre Entscheidung bestimmt den Pfad vor einem Tool-Aufruf oder Geschäftseffekt.
- 01AnforderungDie Agentenaktionsanforderung liefert die Aktion, den Zweck, die Ressource, die Datenbegrenzung und die Umgebung.
- 02BewertenDer Auswerter bindet das Ergebnis an policy_id, policy_version, policy_digest, inputs_digest, übereinstimmende Regeln und Grundcodes.
- 03Pfadallow setzt die Aktion fort. warn setzt die aktuelle Arbeiterroute fort und gibt einen Warnhinweis aus. require_approval erstellt einen Pfad zur menschlichen Genehmigung. block stoppt die Aktion.
- 04AufzeichnungDie Entscheidung bleibt durch Korrelation mit späteren Genehmigungs-, Werkzeug- und Prüfungsaufzeichnungen verknüpfbar.
03
Feldwörterbuch
Das Wörterbuch deckt jedes erforderliche und optionale Mitglied ab, einschließlich der eigenständigen Identitäts- und Korrelationshinzufügungen.
Eigenständige Identität und Korrelation
| Feld | Status | Zweck |
|---|---|---|
| schema_version | Erforderlich | Wählt den Kompatibilitätsvertrag aus, der zum Parsen des Datensatzes verwendet wird. |
| policy_decision_event_id | Erforderlich | Adressiert unabhängig diesen Entscheidungsdatensatz und verknüpft ihn mit einem Audit-Ereignis. Hinzugefügt für eine eigenständige Veröffentlichung. |
| correlation.correlation_id / execution_id | Erforderlich | Verknüpft das Richtlinienergebnis mit der Anfrage, Genehmigung, dem Werkzeug und der Audit-Sequenz. Hinzugefügt für eine eigenständige Veröffentlichung. |
| correlation.trace_id / span_id / parent_event_id | Optional | Trägt OpenTelemetry-Trace-Kontext und ein optionales übergeordnetes Ereignis. Alle W3C-Identifikatoren mit Nullwerten sind ungültig. |
Richtlinienidentität und geschützte Eingaben
| Feld | Status | Zweck |
|---|---|---|
| decision_id | Erforderlich | Identifiziert die Richtlinienbewertungsentscheidung innerhalb des Quell-Governance-Systems. |
| policy_id / policy_version | Erforderlich | Nennt die Richtlinie und die genaue Richtlinienversion, die für die Bewertung verwendet wurde. |
| policy_digest / inputs_digest | Erforderlich | Bindet das Ergebnis an geschützte Richtlinien- und Eingabedarstellungen. |
Entscheidungserklärung
| Feld | Status | Zweck |
|---|---|---|
| decision | Erforderlich | Trägt allow, warn, require_approval oder block. |
| evaluated_at | Erforderlich | Zeichnet auf, wann die Richtlinienbewertung als ein RFC 3339-Datum-Uhrzeit abgeschlossen wurde. |
| matched_rule_ids | Erforderlich | Listet eindeutige Regelkennungen auf, die während der Bewertung übereinstimmten. |
| reason_codes | Erforderlich | Listet mindestens eine eindeutige Kennung auf, die das ausgewählte Ergebnis erklärt. |
04
Minimales Beispiel
Der allow-Datensatz zeigt das kleinste vollständige Entscheidungsobjekt. Die Downloads fügen die Fälle warn, require_approval und block hinzu.
{
"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
Validierung und Digest-Überprüfung
Die JSON Schema-Validierung überprüft die Form. Der begleitende Verifizierer reproduziert 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 Datums-Uhrzeit-Format-Plugin.
- 03Kanonalisiere den vollständigen eigenständigen Datensatz mit rekursiv sortierten Objekt-Schlüsseln, entsprechend dem veröffentlichten Audit-Event-Überprüfer-Ansatz.
- 04Berechne SHA-256 über die kanonischen Bytes und stelle das Ergebnis mit dem sha256:-Präfix dar.
- 05Vergleichen Sie die berechnete Prüfsumme mit der vom aufrufenden Beweisverfahren gespeicherten Prüfsumme.
- 06Wenn eine separate Ed25519-Signatur bereitgestellt wird, lösen Sie den öffentlichen Schlüssel unabhängig auf und überprüfen Sie die Signatur über den 32-Byte-Digest.
- 07Erfassen Sie eine Hash-Diskrepanz oder Signaturfehlfunktion als fehlgeschlagenes Verifikationsergebnis. Allein eine gültige Form stellt keinen unveränderten Datensatz dar.
Vier schemagültige Ergebnisse
Die Beispiele allow, warn, require_approval und block validieren gegen den Entwurf 2020-12 und erzeugen reproduzierbare sha256-Digests aus ihrem kanonischen Inhalt.
Manipulationsprüfung
Die Änderung von reason_codes hält das Dokument strukturell lesbar, während sich der kanonische Digest ändert. Der Prüfer meldetrecord_hash_mismatch.
Der eigenständige Prüfer akzeptiert eine optionale separate Ed25519-Signatur. Vertrauen in einen öffentlichen Schlüssel stammt aus dem vom Aufrufer unabhängig verwalteten Schlüsselregister.
06
Kompatibilität und Versionierung
Versionieren Sie den Antwortvertrag unabhängig von Richtlinienpaketen und Evaluator-Versionen.
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.
Geringfügig
Neue optionale Felder erfordern ein neues schema_version und eine 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 die Unterstützung erklärt wird. Der v1-Pfad verwendet schema_version 1.0.0.
07
Wie KLA dies umsetzt
Der gemeinsame Richtlinienvertrag definiert das Entscheidungs-Vokabular. Worker- und Ausführungsrouten protokollieren die Bewertung und den anschließenden Governance-Pfad.
| Vertragsbereich | Aktuelle Quelle | Abbildung | Status |
|---|---|---|---|
| Kanonischer Entscheidungswortschatz | services/shared/src/policy/contracts.ts | GateDecisionValueSchema und POLICY_SCHEMA_VERSION definieren allow, warn, require_approval, block und die Richtlinienschema-Version 1.0.0. | Aktueller gemeinsamer Vertrag |
| Entscheidungsaufzeichnung | services/execution-worker/src/services/audit-events.ts | recordPolicyDecisionAuditEvent zeichnet Richtlinienidentität, Entscheidung, Grund, Regel, Workflow und Ausführungsdetails auf. Sein Legacy-Helfer akzeptiert "deny" für das blockierte Ergebnis, daher verwendet diese Seite den gemeinsamen kanonischen block-Wert. | Aktueller Produzent mit Normalisierung |
| Vom Entscheid ausgewählter Pfad | services/execution-worker/src/workflows/workflow-spec-runner.ts | Der Workflow-Pfad setzt allow und warn fort, markiert warn als Warnung, fordert Genehmigung für require_approval an und stoppt block. | Aktueller Ausführungsverbraucher |
| Audit-Verknüpfung | services/execution-worker/src/services/audit-events.ts | Richtlinien- und Genehmigungs-Audit-Produzenten behalten Ausführungskennungen und aktiven Trace-Kontext, sodass eine Entscheidung mit dem umgebenden Ausführungsdatensatz verknüpft werden kann. | Derzeitiger verwandter Produzent |
Gezielte Abstraktionen und nicht unterstützte Felder
- •Das Schema lässt Cerbos-Richtliniendokumente, JSON-Logikregelkörper, Berechtigungs-Payloads und Evaluator-Konfigurationen aus.
- •Das Schema erfasst Prüfsummen für Richtlinien und Eingaben. Es veröffentlicht nicht den geschützten Richtlinientext, Anforderungsargumente, Prompts, Modelausgaben oder rohe personenbezogene Daten.
- •Das Schema zeichnet eine kanonische Entscheidung auf. Es kodiert nicht jedes interne Steuersignal, jede Klassifizierung, Abhilfe oder Richterspur, die vom weiteren gemeinsamen GateDecision-Vertrag getragen wird.
- •Das Schema zeichnet die übereinstimmenden Regel-IDs und Begründungscodes auf. Es behauptet nicht, dass ein Begründungscode die Autorisierung, die Mandantenisolation oder die Vollständigkeit der Quellpopulation beweist.
- •Das eigenständige policy_decision_event_id- und Korrelationsobjekt sind Ergänzungen für die eigenständige Veröffentlichung. Das eingebettete Richtlinienobjekt hat kein Feld.
- •Die Beispiele sind synthetische Aufzeichnungen. Ihre Digest-Werte zeigen Feldbeschränkungen und enthalten keine Kunden- oder Produktionskennungen.
08
Verwandte Referenzen
Folgen Sie der Anforderung, der Richtlinienentscheidung, der Genehmigung, wenn erforderlich, und dem vollständigen Audit-Ereignis in der Ausführungsreihenfolge.
Die angeforderte Aktion wird durch diese Richtlinienantwort bewertet.
Der Maker-Checker-Datensatz wird verwendet, wenn das Ergebnis require_approval ist.
Der vollständige Ereignisumschlag für die Anfrage, Richtlinie, Genehmigung, das Tool, das Ergebnis und den Integritätsdatensatz.
Wenden Sie den Vertrag an
Behalten Sie das Richtlinienergebnis neben der Anfrage, die es bewertet hat.
Verwenden Sie die Aktionsanforderungs- und Genehmigungsreferenzen mit dieser Antwort und verwenden Sie dann das Audit-Protokoll-Schema, um die vollständige geregelte Ausführungssequenz beizubehalten.