Genehmigungsereignisschema für KI-Agenten
Ein Genehmigungsereignis erfasst den Entscheidungszyklus für eine vom Menschen überprüfte Aktion eines gesteuerten KI-Agenten. Diese eigenständige Referenz bewahrt die Genehmigungsdefinition aus dem veröffentlichten Audit-Ereignis und fügt ein adressierbares approval_event_id sowie eine Korrelation für unabhängige Nutzung hinzu.
JSON Schema-Entwurf 2020-12 · Version 1.0.0 · Maker-Checker-Entscheidungsprotokoll
Kurzanleitung
- Definition
- Ein eigenständiger Datensatz des Status einer Genehmigungsanfrage, der erforderlichen Rolle, des menschlichen Prüfers bei decided, der Entscheidung, des Zeitplans und optionaler Begründungsreferenzen.
- Wenn verwendet
- Erstellen Sie es, nachdem ein Richtlinieneffekt eine Aktion zur menschlichen Genehmigung weiterleitet, und erfassen Sie es, wenn die Anfrage decided ist, abläuft oder cancelled ist.
- Entscheidungswerte
- approved, rejected, expired und cancelled beschreiben die endgültige Entscheidung, die durch das Ereignis dargestellt wird.
- Ersteller-Prüfer
- Die aktuellen Genehmigungswege prüfen die Berechtigung approval:decide, die erforderliche Rolle, den ausstehenden Status und die Trennung der Aufgaben, bevor eine Entscheidung aufgezeichnet wird.
01
Schema- und Genehmigungsbeispiele
Das versionierte Schema und zwei Endentscheidungsbeispiele sind eigenständige Artefakte zur Validierung und Referenzimplementierung.
/ai-agent-approval-event/v1/schema.jsonHerunterladen Genehmigtes EreignisbeispielEntschiedene Genehmigung mit einem synthetischen menschlichen Prüfer./ai-agent-approval-event/v1/examples/approved.jsonHerunterladen Abgelehntes EreignisbeispielEntschiedene Ablehnung mit einem Grundcode und Begründungsreferenz./ai-agent-approval-event/v1/examples/rejected.jsonHerunterladen 02
Objekt- und Ausführungsreihenfolge
Ein Genehmigungsereignis befindet sich zwischen einem require_approval-Politikergebnis und jeder approved-Toolwirkung. Abgelaufene und rejected-Pfade bleiben mit abgelehnten oder nicht gestarteten Ergebnissen verknüpfbar.
- 01AnfrageEin Richtlinienergebnis von require_approval erstellt eine Anfrage, die mit der Ausführungskorrelation und einer erforderlichen Rolle verbunden ist.
- 02BewertungEin Prüfer erhält die vorgelegten Nachweise und handelt über einen Genehmigungsweg mit der Berechtigung approval:decide.
- 03ÜberprüfenDie aktuellen Wege prüfen die erforderliche Rolle, den ausstehenden Status und die Trennung von Ersteller und Prüfer. Eine Genehmigung erfordert ebenfalls eine ausdrückliche Bestätigung.
- 04AufzeichnenDie Entscheidung wird gespeichert und eine dauerhafte Prüfpflicht wird geschrieben, bevor der kontrollierte Arbeitsablauf signalisiert wird, wieder fortzufahren.
03
Feldwörterbuch
Das Wörterbuch deckt jedes Genehmigungsmitglied ab, einschließlich Lebenszyklusbedingungen sowie optionaler Neuzuweisung, Überschreibung und Berufungsverweise.
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. |
| approval_event_id | Erforderlich | Adressiert dieses Genehmigungsereignis unabhängig und verknüpft es mit einem Prüfergebnis. Hinzugefügt für eigenständige Veröffentlichung. |
| correlation.correlation_id / execution_id | Erforderlich | Verknüpft die Genehmigung mit der Anforderung, Richtlinie, dem Werkzeug und der Prüfsequenz. Hinzugefügt für 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. |
Lebenszyklus der Genehmigungsanfrage
| Feld | Status | Zweck |
|---|---|---|
| request_id | Erforderlich | Identifiziert die Genehmigungsanfrage, die decided ist. Dies behält die eingebettete Genehmigung.request_id-Bedeutung bei. |
| status | Erforderlich | Gibt an, ob das Ereignis decided, expired oder cancelled ist. |
| requested_at / expires_at | Erforderlich | Speichert die Anforderungs- und Ablaufzeiten als RFC 3339-Datumszeiten. |
| required_role | Erforderlich | Nennt die Rolle, die erforderlich ist, um die Genehmigung zu entscheiden. |
| decided_at | Erforderlich | Erfasst, wann die endgültige Entscheidung, der Ablauf oder die Stornierung aufgezeichnet wurde. |
Entscheidung und unterstützende Referenzen
| Feld | Status | Zweck |
|---|---|---|
| decision | Erforderlich | Trägt approved, rejected, expired oder cancelled und entspricht dem Lebenszyklusstatus. |
| reviewer | Bedingt | Identifiziert den menschlichen Prüfer, wenn der Status decided ist. Der Typ ist immer Benutzer. |
| presented_evidence_digest | Optional | Verknüpft die Entscheidung mit der zur Überprüfung angezeigten Evidenzdarstellung. |
| reason_code / rationale_reference | Optional | Bietet einen stabilen Grund und eine Referenz zu einer umfassenderen Entscheidungsbegründung. |
| reassigned_from | Optional | Erhält die vorherige zugrunde liegende Entscheidung, wenn sich der Bearbeiter einer Genehmigungsanfrage ändert. |
| override.authority_reference / reason_code | Optional | Verweist auf außergewöhnliche Autorität und deren Grund, wenn eine Ausnahme protokolliert wird. |
| appeal.status / reference | Optional | Verknüpft einen späteren Berufungszyklus und dessen stabile Referenz. |
04
Minimales Beispiel
Der approved-Datensatz zeigt die erforderlichen Felder sowie den Prüfer, der für einen decided-Status benötigt wird. Der rejected-Datensatz liefert eine zweite endgültige Entscheidung.
{
"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
Validierung und Prüfwertüberprüfung
JSON Schema prüft den Status und die Entscheidungsform. Der begleitende Prüfer erstellt eine sha256-Überprüfung über den kanonischen Datensatz und kann eine optionale separate Ed25519-Signatur überprüfen.
- 01Lädt das versionierte Schema von der JSON Schema-Download-URL.
- 02Validiert das JSON-Dokument mit einem Entwurf-2020-12-Validator und einem Datums-Uhrzeit-Format-Plugin.
- 03Kanonisiert den vollständigen eigenständigen Datensatz mit rekursiv sortierten Objekt-Schlüsseln, entsprechend dem Ansatz des veröffentlichten Audit-Event-Verifiers.
- 04Berechnet SHA-256 über die kanonischen Bytes und stellt das Ergebnis mit dem Präfix sha256: dar.
- 05Vergleicht die berechnete Prüfsumme mit der von der aufrufenden Beweisprozedur aufbewahrten Prüfsumme.
- 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.
- 07Eine Hash-Abweichung oder ein Signaturfehler ist als fehlgeschlagenes Überprüfungsergebnis zu protokollieren. Bewahren Sie den Entscheidungsnachweis und die dazugehörige Anfrage zur Überprüfung auf.
Beispiele für Terminalentscheidungen
Die approved- und rejected-Beispiele werden gegen den Entwurf 2020-12 validiert und erzeugen reproduzierbare sha256-Digests aus ihrem kanonischen Inhalt.
Manipulationsprüfung
Eine Änderung der Entscheidung verändert sowohl die Bedeutung im Lebenszyklus als auch den kanonischen Digest. Der Prüfer meldetrecord_hash_mismatch.
Der eigenständige Verifizierer akzeptiert eine optionale abgetrennte Ed25519-Signatur. Vertrauen in einen öffentlichen Schlüssel stammt aus dem unabhängig verwalteten Schlüsselregister des Aufrufers.
06
Kompatibilität und Versionierung
Versionieren Sie den Genehmigungsereignisvertrag unabhängig vom Genehmigungsdienst- und Richtlinienvertrag.
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 eine versionierte URL. Verbraucher erklären ihre Unterstützung, bevor sie die neue Version verarbeiten.
Groß
Entfernte oder umbenannte Felder, geänderte Bedeutungen, strengeren Pflichtstatus 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 umsetzt
Der Arbeiter erstellt Prüfprotokolle zur Genehmigung. Die API-Routen erzwingen Entscheidungsbefugnis und bewahren eine dauerhafte Entscheidungsverpflichtung auf.
| Vertragsbereich | Aktuelle Quelle | Kartierung | Status |
|---|---|---|---|
| Genehmigungsanfrage- und Beschlussereignisse | services/execution-worker/src/services/audit-events.ts | Der Mitarbeiter erfasst angeforderte und gelöste Prüfungsvorgänge mit Ausführungs-, Genehmigungs-, Governance-, Entscheidungs-, Begründungs- und Spuren-bezogenen Feldern. Auf dieser Seite werden diese Fakten in die tragbare Genehmigungsereignisform überführt. | Aktueller Produzent mit Normalisierung |
| Maker-Checker Entscheidungsweg | services/execution-api/src/routes/approvals.ts | Der Genehmigungspfad prüft die Berechtigung approval:decide, die erforderliche Rolle, den ausstehenden Status und die Selbstgenehmigung. Die Genehmigung erfordert außerdem eine ausdrückliche Bestätigung; eine Eskalation hält die Anfrage im ausstehenden Zustand. | Aktueller Verbraucher und Produzent |
| Entscheidungsschreibtisch und lokale Genehmigungsroute | services/api/src/routers/approvals.ts | Der Router wendet dieselben Berechtigungs- und Maker-Checker-Zugriffsregeln an, überprüft Richtlinien- und Nachweissatzsets, speichert einen Entscheidungsdatensatz und koordiniert den lokalen oder Ausführungs-API-Genehmigungsstatus. | Aktueller Verbraucher und Produzent |
| Entscheidungsvokabular und Version | services/shared/src/policy/contracts.ts | Der gemeinsame Richtlinienvertrag liefert require_approval als den Pfad, der zu diesem Ereignis führt, und hält die Versionskontrolle der Richtlinie unabhängig vom Genehmigungsereignisschema. | Aktueller gemeinsamer Vertrag |
Absichtliche Abstraktionen und nicht unterstützte Felder
- •Das Schema lässt Mandanten-Datenbank-IDs, Spalten der Genehmigungstabelle, Cerbos-Autorisierungssyntax und rohe Anforderungs- oder Beweisinhalte weg.
- •Das Schema zeichnet required_role und die Identität des Prüfers auf. Es beweist nicht, dass der Prüfer diese Rolle zum Zeitpunkt der Entscheidung innehatte; die Verbraucher führen diese Autoritätsprüfung durch.
- •Das Schema hat die Endstatuswerte decided, expired und cancelled. Die aktuelle Eskalationsaktion API hält die Anfrage ausstehend und hat keinen endgültigen eskalierten Wert in diesem Vertrag.
- •Das Schema enthält optionale Nachweise, Begründungen, Neuzuweisungen, Überschreibungen und Berufungsverweise. Es definiert nicht das Nachweispaket, das Berufungsverfahren oder die Richtlinie zur Überschreibungsbefugnis.
- •Das Schema veröffentlicht keine E-Mail-Adressen der Prüfer, Rollensnapshots, Kommentare oder Entscheidungsbestätigungen. Diese Felder bleiben in den KLA-Entscheidungen und Prüfprotokollen und können durch die Korrelations- und Anfrage-IDs verknüpft werden.
- •Das eigenständige approval_event_id- und Korrelationsobjekt sind Ergänzungen für die eigenständige Veröffentlichung. request_id behält die Genehmigungsanforderungsbedeutung aus dem eingebetteten Genehmigungsobjekt.
08
Verwandte Referenzen
Folgen Sie der Ausführungssequenz vom Aktionsantrag bis zur Richtlinienentscheidung, Genehmigung, wenn erforderlich, und dem vollständigen Audit-Ereignis.
Die Aktion, die die Richtlinienbewertung erreicht hat.
Das require_approval-Ergebnis, das die Aktion zur Überprüfung weiterleitet.
Die vollständige Ereignishülle, die die Anfrage, Entscheidung, Genehmigung, Wirkung und das Ergebnis aufzeichnet.
Den Vertrag anwenden
Die menschliche Entscheidung mit dem Richtlinienzweig verknüpft halten, den sie auflöst.
Verwenden Sie die Korrelations- und Anforderungskennungen, um das Genehmigungsereignis mit der Aktionsanfrage, der Richtlinienentscheidung, dem vollständigen Prüfereignis und späteren Beweisunterlagen zu verbinden.