Audit-Event-Schema für KI-Agenten: Aktionen, Tools, Freigaben und Ergebnisse
Ein Audit-Event für KI-Agenten ist ein dauerhafter Datensatz, der eine angefragte Aktion mit Identität, delegierter Autorität, Policy, menschlicher Prüfung, Tool-Effekten, fachlichem Ergebnis und Integritätsnachweis verbindet. Dieser öffentliche Vertrag ist herstellerneutral; aktuelle KLA-Produzenten erscheinen nur in der Implementierungsabbildung.
JSON Schema draft 2020-12 · Veröffentlicht am 28. Juli 2026 · Normative Feldnamen in englischer Sprache
Kurzreferenz
- Definition
- Ein Audit-Event für KI-Agenten ist ein dauerhafter Datensatz, der eine angefragte Aktion mit Identität, delegierter Autorität, Policy, menschlicher Prüfung, Tool-Effekten, fachlichem Ergebnis und Integritätsnachweis verbindet.
- Anwendungsbereich
- Für folgenreiche Agentenaktionen einschließlich Policy-Ablehnung und fehlgeschlagenem Versuch. Wenden Sie auf die Umsetzung die lokalen rechtlichen, datenschutzrechtlichen, aufbewahrungsbezogenen und branchenspezifischen Anforderungen an.
- Mindestnachweis
- Stabile IDs, Identität von Akteur und Eigentümer, versionierte Komponenten, angefragte Autorität, Policy-Ergebnis, Freigabe sofern erforderlich, Effekte, Ergebnis, Reihenfolge, Datenschutzmaßnahmen und Verifizierungsstatus.
- Praxisbeispiel
- Der vollständige Datensatz verfolgt eine synthetische Kreditentscheidung von der Anfrage über require_approval, die Prüfung durch eine befugte Person, einen Tool-Effekt, ein fachliches Ergebnis bis zu einer gültigen Ed25519-Signatur.
01
Schema und bereinigte Datensätze
Die vier unveränderlichen versionierten URLs unterstützen Umsetzung, Validierung, Audit-Arbeitspapiere und Regressionstests.
/ai-agent-audit-event/v1/schema.jsonHerunterladen Vollständige AusführungGültige freigegebene Aktion mit nachgelagertem Effekt./ai-agent-audit-event/v1/examples/complete-execution.jsonHerunterladen Abgelehnte AktionGültige `block`-Entscheidung ohne Tool-Aufruf./ai-agent-audit-event/v1/examples/denied-action.jsonHerunterladen Erkannte ManipulationStrukturell gültiger Datensatz, dessen signierte Event-Nutzlast verändert wurde./ai-agent-audit-event/v1/examples/tamper-failure.jsonHerunterladen 02
Eine durchgespielte Aktion
Der vollständige Datensatz beschreibt eine synthetische Kreditentscheidung. Die Policy verlangt eine befugte Kreditprüfung, bevor das schreibende Tool läuft.
- 01AnfrageEine Nutzerin delegiert eine im Scope begrenzte Kreditentscheidung an einen Agenten.
- 02PolicyPolicy-Version 4.2.1 liefert require_approval für den erfassten Betrag.
- 03Menschliche EntscheidungEine erfahrene Kreditprüfung sichtet die vorgelegten Nachweise und gibt die gebundene Anfrage frei.
- 04Tool-EffektEin idempotenter Tool-Aufruf aktualisiert das synthetische Ziel und erfasst Digests vor und nach der Änderung.
- 05NachweisDer Hash der kanonischen signierten Nutzlast und die Ed25519-Signatur werden mit dem veröffentlichten Beispielschlüssel verifiziert.
{
"schema_version": "1.0.0",
"event_id": "evt_01JZ8V4R9K2Q7M1W3D5N6P8X0A",
"actors": {
"agent": "agent_credit_review",
"accountable_owner": "role_head_credit_operations"
},
"requested_action": "credit.application.set_disposition",
"policy_decision": "require_approval",
"approval_decision": "approved",
"tool_status": "succeeded",
"business_outcome": "achieved",
"verification": "valid"
}03
Abgrenzung der Datensätze
Jedes Artefakt beantwortet eine andere Prüffrage. Ein produktives Prüfverfahren braucht meist alle vier.
| Artefakt | Frage | Typischer Inhalt | Integritätsgrenze |
|---|---|---|---|
| Betriebsprotokoll | Was hat eine Komponente gemeldet? | Meldungen, Metriken, Fehler, Latenz und lokaler Laufzeitkontext. | Nützlich für den Betrieb. Vollständigkeit, Identität, Autorität und Aufbewahrung können unbestimmt bleiben. |
| Audit-Event | Wer oder was hat eine gesteuerte Aktion unter welcher Autorität angefragt, und was ist passiert? | Identität, Versionen, Zweck, Ressource, Policy, Freigabe, Tool-Effekt, Ergebnis, Datenschutz und Integritätsverweise. | Der Datensatz hat ein stabiles Schema und ein explizites Verifizierungsergebnis. Die Vollständigkeit der Quell-Grundgesamtheit erfordert weiterhin einen Abgleich. |
| Execution Lineage | Wie ist eine Ausführung der Reihe nach verlaufen? | Geordnete Spans oder Events, Eltern-Kind-Beziehungen, Wiederholungen, Tool-Aufrufe und Status. | Lineage liefert Reihenfolge und Kausalität. Sie kann auf mehrere Audit-Events und Quellartefakte verweisen. |
| Nachweispaket | Welche aufbewahrten Artefakte stützen eine Prüfaussage? | Manifest, Audit-Events, Lineage, Policy- und Freigabedatensätze, Quellbelege, Hashes, Signaturen, Auslassungen und Schwärzungen. | Die Paketprüfung testet Artefaktzugehörigkeit, Hashes, Signaturen, Ledger-Nachweise und erklärte Auslassungen. |
04
Feldverzeichnis
Pflichtfelder gelten für jeden Datensatz. Bedingte Felder gelten, wenn die genannte Komponente oder der Lebenszykluspfad vorhanden ist. Optionale Felder bewahren portable Details.
Umschlag und Reihenfolge
| Feld | Status | Zweck |
|---|---|---|
| schema_version | Pflicht | Wählt den Kompatibilitätsvertrag zum Lesen des Datensatzes. |
| audit_event.event_id | Pflicht | Identifiziert dieses Audit-Event eindeutig. |
| audit_event.event_type | Pflicht | Klassifiziert eine abgeschlossene oder abgelehnte Aktion. Der Verifizierungsstatus bleibt in integrity. |
| audit_event.occurred_at / recorded_at / sequence | Pflicht | Trennt Ereigniszeit von Erfassungszeit und erhält eine deterministische Reihenfolge. |
| audit_event.correlation.correlation_id / execution_id | Pflicht | Verknüpft Policy-, Freigabe-, Tool-, Ergebnis- und Nachweisdatensätze ohne Verknüpfung über Zeitstempel. |
| audit_event.correlation.trace_id / span_id / parent_event_id | Optional | Verbindet den Datensatz mit OpenTelemetry oder einem gleichwertigen Trace und mit einem Elternereignis. W3C-Kennungen aus lauter Nullen sind ungültig. |
Scope und Identität
| Feld | Status | Zweck |
|---|---|---|
| audit_event.scope.organization_ref | Pflicht | Trägt einen pseudonymen oder organisationseigenen Scope-Verweis. |
| audit_event.scope.environment / retention_class | Pflicht | Benennt die Betriebsgrenze und die genehmigte Aufbewahrungsbehandlung. |
| audit_event.scope.region / legal_hold | Optional | Erfasst die regionale Ablage und jede Sperre, die die reguläre Löschung aussetzt. |
| audit_event.actors.requester / agent / accountable_owner | Pflicht | Bindet Anfrage, Agenten-Identität und die verantwortliche menschliche oder organisatorische Rolle. |
| audit_event.actors.delegated_user / service_identity | Bedingt | Erfasst Autorität im Auftrag und Workload-Identität, sofern jeweils vorhanden. |
Versionen und angefragte Autorität
| Feld | Status | Zweck |
|---|---|---|
| audit_event.components.agent | Pflicht | Fixiert das Agent-Release und den optionalen Konfigurations-Digest. |
| audit_event.components.model / prompt_template / orchestrator | Bedingt | Fixiert jede Komponente, die die Aktion beeinflusst hat. |
| audit_event.requested_action.action / purpose | Pflicht | Nennt die vorgeschlagene Fähigkeit und den genehmigten fachlichen Zweck. |
| audit_event.requested_action.resource / data_boundary_ref / environment | Pflicht | Definiert Ziel, gesteuerte Datengrenze und Ausführungsumgebung. |
| audit_event.requested_action.amount | Bedingt | Nutzt eine Dezimalzeichenkette und eine ISO-4217-Währung, wenn der Finanzwert die Policy beeinflusst. |
Policy und menschliche Entscheidung
| Feld | Status | Zweck |
|---|---|---|
| audit_event.policy.decision_id / policy_id / policy_version | Pflicht | Bezeichnet die genaue Entscheidung und die maßgebliche Policy-Version. |
| audit_event.policy.policy_digest / inputs_digest | Pflicht | Bindet die Bewertung an geschützte Policy- und Eingabedarstellungen. |
| audit_event.policy.decision | Pflicht | Trägt allow, warn, require_approval oder block. |
| audit_event.policy.matched_rule_ids / reason_codes / evaluated_at | Pflicht | Macht das Ergebnis vor jedem Effekt erklärbar und ordenbar. |
| audit_event.approval | Bedingt | Pflicht, wenn die Policy require_approval liefert. Ausführungseffekte setzen eine entschiedene, freigegebene Anfrage einer menschlichen Prüferin oder eines Prüfers voraus. |
| audit_event.approval.reassigned_from / override / appeal | Optional | Bewahrt außergewöhnliche Fakten des Entscheidungslebenszyklus, sofern das Quellsystem sie unterstützt. |
Ausführung und Ergebnis
| Feld | Status | Zweck |
|---|---|---|
| audit_event.tool_calls[] | Pflicht | Listet jeden versuchten Tool-Aufruf. Blockierte, nicht freigegebene und nicht gestartete Aktionen erfordern ein leeres Array. |
| audit_event.tool_calls[].arguments_digest / result_digest | Pflicht | Bindet geschützte Argumente und Ergebnisse, ohne Geheimnisse in das Event zu legen. |
| audit_event.tool_calls[].downstream_effects[] | Bedingt | Erfasst Belege der Zielsysteme und Zustands-Digests vor und nach der Änderung, sofern Effekte eintreten. |
| audit_event.execution.status / business_outcome | Pflicht | Trennt den technischen Abschluss vom fachlichen Ergebnis und bindet die Semantik abgeschlossener oder abgelehnter Events. |
| audit_event.execution.rollback / incident_ref | Bedingt | Verbindet Wiederherstellung und Untersuchung, sofern einer der Pfade genutzt wird. |
| audit_event.lineage | Pflicht | Verbindet die Aktion mit einem Lineage Record und dessen geordneten Event-IDs. |
Nachweis, Datenschutz und Integrität
| Feld | Status | Zweck |
|---|---|---|
| audit_event.evidence.manifest_ref / artifacts[] | Pflicht | Bezeichnet das Paketmanifest und die Digests der stützenden Artefakte. |
| audit_event.privacy.classification / redaction_status | Pflicht | Nennt den Schutz und die Transformation, die auf den Datensatz angewendet wurden. |
| audit_event.privacy.redactions[] / access_policy_ref | Pflicht | Lokalisiert geschützte Felder und die Policy, die den Zugriff regelt. Die Einträge entsprechen dem erklärten Schwärzungsstatus. |
| integrity.canonicalization / hash_algorithm / record_hash | Pflicht | Definiert und erfasst den Digest der kanonischen signierten Umschlagmetadaten und von audit_event. |
| integrity.previous_event_hash | Optional | Verbindet Datensätze, wenn die Umsetzung eine Hash-verkettete Event-Folge nutzt. Die Signatur schützt diese Verkettung. |
| integrity.signature | Pflicht | Trägt Algorithmus, Schlüssel-ID, Beispiel-Public-Key und die abgetrennte Signatur über den Digest. |
| integrity.verification | Pflicht | Erfasst valid, failed oder not_performed mit Verifiziererversion und Fehlercodes. |
05
Integritätsprüfung
Schemagültigkeit und kryptografische Integrität sind getrennte Prüfungen. Die Vollständigkeit der Grundgesamtheit bleibt ein eigenes Prüfverfahren.
- 01Den Umschlag mit dem versionierten JSON Schema validieren.
- 02Die signierte Nutzlast aus schema_version, audit_event und den integrity-Metadaten außer record_hash und signature.value bilden.
- 03Die signierte Nutzlast mit dem JSON Canonicalization Scheme nach RFC 8785 kanonisieren.
- 04SHA-256 berechnen und mit integrity.record_hash unter Verwendung des Präfixes sha256: vergleichen.
- 05Den vertrauenswürdigen Schlüssel über key_id auflösen. Gültigkeit und Widerrufsstatus zum Zeitpunkt occurred_at prüfen.
- 06Die Ed25519-Signatur über den 32-Byte-Digest verifizieren.
- 07Jeden previous_event_hash gegen den geordneten Nachbarn und einen unabhängig aufbewahrten Anker des ersten Glieds prüfen, bevor die Reihenfolge akzeptiert wird.
- 08Event-IDs und Artefakt-Digests mit Lineage, Effekten im Quellsystem und dem Nachweismanifest abgleichen.
- 09Jeden Fehlercode erfassen. Eine fehlgeschlagene oder nicht verfügbare Prüfung darf nicht valid ergeben.
Beispiele für Freigabe und Ablehnung
Beide validieren, reproduzieren ihre veröffentlichten Hashes und werden mit dem Ed25519-Beispiel-Public-Key verifiziert.
Manipulationsbeispiel
Der Umschlag bleibt schemagültig. Sein fachliches Ergebnis wurde nach der Signatur geändert, daher weicht der neu berechnete Hash ab und die Verifizierung erfasstrecord_hash_mismatch.
Der eingebettete Beispielschlüssel macht die Dateien selbstprüfbar. In der Produktion muss das Vertrauen in Schlüssel über ein separates Register laufen. Ein Schlüssel, der nur aus dem Datensatz stammt, kann die Identität des Ausstellers nicht belegen.
06
OpenTelemetry-Korrelation
Der Trace-Kontext verbindet Telemetrie und Audit-Nachweis. Er trägt nicht die vollständige Prüfaussage.
Weitergeben
W3C-traceparent über Agent, Policy, Freigabe, Tool-Gateway und nachgelagerte Aufrufe propagieren. trace_id und die span_id der Aktion in correlation übernehmen.
Binden
Stabile Attribute execution_id, event_id, decision_id, request_id und call_id ergänzen. Geschützte Eingaben, Token und rohe Modellinhalte außerhalb gewöhnlicher Span-Attribute halten.
Aufbewahren
Die Aufbewahrung von Telemetrie kann kürzer sein als die von Audit-Daten. Audit-Datensatz und auflösbaren Lineage-Verweis über den Ablauf heißer Traces hinaus erhalten.
07
Kompatibilität und Versionierung
Versionieren Sie den Vertrag unabhängig von Produzenten- und Tool-Versionen.
Patch
Klarstellungen, Beschreibungen und Beispiele dürfen sich ändern, ohne das Validierungsverhalten zu ändern. Stabile v1-URLs behalten unveränderliche Dateiinhalte, ein korrigiertes Artefakt erhält daher eine neue Versions-URL.
Minor
Ein neues optionales Feld oder eine Enum-Erweiterung erfordert eine neue schema_version und eine neue versionierte URL. Konsumenten müssen unbekannte Versionen ablehnen, bis sie Unterstützung erklären.
Major
Entfernte oder umbenannte Felder, geänderte Bedeutungen, strengere Pflichtangaben oder geänderte Kanonisierung erfordern einen neuen Major-Pfad. Produzenten können während der Migration doppelt schreiben.
Konsumenten müssen unbekannte Datensätze für die forensische Behandlung aufbewahren und die semantische Verarbeitung stoppen, wenn die Schemaversion nicht unterstützt wird. Sie dürfen ein nicht unterstütztes Policy-Ergebnis oder einen nicht unterstützten Verifizierungsstatus niemals stillschweigend umdeuten.
08
Abbildung auf aktuelle KLA-Produzenten
Der portable Umschlag ist breiter als jeder einzelne KLA-Produzent. Diese Quellen definieren den aktuellen Implementierungsstand.
| Vertragsbereich | Aktuelle Quelle | Abbildung | Status |
|---|---|---|---|
| Identität des Audit-Events und dauerhaftes Anhängen | services/api/src/services/audit-logger.ts | AuditEvent liefert Event, Mandant, Nutzer, Ressource, Aktion, Ergebnis, Korrelation und Sicherheitskontext. Der Logger spiegelt mandantengebundene Events nach ImmuDB. | Aktuelle Quelle |
| Produzenten für Tool-, Policy- und Freigabe-Events | services/execution-worker/src/services/audit-events.ts | Die Worker-Produzenten hashen Tool-Eingaben und -Ergebnisse, erfassen Ausführungs- und Policy-Identität, hängen Freigabeanfrage- und Auflösungsereignisse an und ergänzen die aktive OpenTelemetry-Trace-ID. | Aktuelle Quelle |
| Vier Policy-Ergebnisse | services/shared/src/policy/contracts.ts | GateDecisionValueSchema definiert allow, warn, require_approval und block. Ältere Audit-Hilfsfunktionen im Worker können das blockierte Ergebnis noch als deny schreiben. | Aktuelle Quelle mit Normalisierung |
| Dauerhafte Freigabeentscheidung | services/execution-api/src/services/approval-audit-outbox-worker.ts | Die Freigabe-API nutzt eine geleaste, idempotente Outbox, um einen mandantengebundenen Entscheidungsdatensatz anzuhängen. Der Produzent auf der Anfrageseite bleibt getrennt. | Aktuelle Quelle |
| Execution Lineage und Trace-Korrelation | services/execution-worker/src/services/lineage-trace-publisher.ts | Gesteuerte Läufe veröffentlichen ausführungsbezogene Root- und Schritt-Spans. workflow-observability.ts gibt zusätzlich Policy- und Freigabeattribute über OpenTelemetry aus. | Aktuelle Quelle |
| Sealed Evidence Bundle und Offline-Verifizierung | packages/evidence-contract/src/index.ts | Das Paketmanifest bindet Mandant, Export, Artefakte, Merkle-Root, Manifest-Hash, Signaturmetadaten, Erzeugungsanfrage, Auslassungen und Schwärzungen. packages/evidence-verifier führt die unabhängigen Prüfungen aus. | Aktuelle Quelle |
Bewusste Abstraktionen und nicht abgedeckte Felder
- •KLA gibt diesen öffentlichen Umschlag derzeit nicht als einen nativen Wire-Datensatz aus. Die Referenz normalisiert mehrere maßgebliche Produzenten zu einer Audit-Einheit.
- •Verantwortlicher Eigentümer, vollständige Digests von Modell- und Prompt-Konfiguration, Tool-Versionen, fachliche Ergebnisse, Rollback und Vorfallverweise sind nicht über alle KLA-Laufzeitpfade hinweg einheitlich befüllt.
- •Neuzuweisung, Übersteuerung und Widerspruch bei einer Decision Request sind portable Lebenszyklusfelder. Aktuelle KLA-Produzenten stellen nicht alle drei als einen normalisierten Vertrag auf Aktionsebene bereit.
- •Der Vertrag erfasst die erforderliche Rolle und die Identität der prüfenden Person. Konsumenten in der Produktion müssen prüfen, dass diese Person die erforderliche Rolle zum Entscheidungszeitpunkt innehatte.
- •KLA signiert und verifiziert das Manifest des Sealed Evidence Bundle und validiert Ledger- und Artefaktnachweise. Nicht alle aktuellen KLA-Datensätze tragen die Ed25519-Signatur je Datensatz, die diese portablen Beispiele verwenden.
- •Die Beispiele veröffentlichen einen Beispiel-Public-Key, damit die Dateien selbstprüfbar sind. Produktivsysteme müssen vertrauenswürdige Schlüssel über ein unabhängig verwaltetes Schlüsselregister auflösen und den Widerruf zum Ereigniszeitpunkt prüfen.
Den Vertrag anwenden
Den Datensatz in eine vollständige Prüfmethode einbetten.
Nutzen Sie die Zugriffskontrolle für KI-Agenten, um Umfang und Kontrolltests festzulegen, und den Berechtigungsleitfaden, um Grundgesamtheiten abzugleichen, Aktionen zu ziehen, Nachweise zu bewerten und Ausnahmen zu berichten.