AI Agent Audit Log Schema: Actions, Tools, Approvals, and Outcomes
An AI agent audit event is one durable record that connects a requested action to identity, delegated authority, policy, human review, tool effects, business outcome, and integrity proof. This public contract is vendor-neutral and uses current KLA producers only in the implementation mapping.
JSON Schema draft 2020-12 · Published 2026-07-28 · English canonical
Quick reference
- Definition
- An AI agent audit event is one durable record that connects a requested action to identity, delegated authority, policy, human review, tool effects, business outcome, and integrity proof.
- Applicability
- Use it for consequential agent actions, including a policy denial or a failed attempt. Apply local legal, privacy, retention, and sector requirements to the implementation.
- Minimum evidence
- Stable IDs, actor and owner identity, versioned components, requested authority, policy result, approval when required, effects, outcome, ordering, privacy controls, and verification state.
- Worked example
- The complete record follows a synthetic credit disposition from request through require_approval, authorized review, one tool effect, a business outcome, and a valid Ed25519 signature.
01
Schema and sanitized records
The four immutable versioned URLs support implementation, validation, audit workpapers, and regression tests.
/ai-agent-audit-event/v1/schema.jsonDownload Complete executionValid approved action with a downstream effect./ai-agent-audit-event/v1/examples/complete-execution.jsonDownload Denied actionValid block decision with no tool call./ai-agent-audit-event/v1/examples/denied-action.jsonDownload Tamper failureStructurally valid record whose signed event payload was changed./ai-agent-audit-event/v1/examples/tamper-failure.jsonDownload 02
One worked action
The complete sample records a synthetic credit disposition. Policy requires an authorized underwriter before the write-capable tool runs.
- 01RequestA user delegates a scoped credit-disposition action to an agent.
- 02PolicyPolicy version 4.2.1 returns require_approval for the recorded amount.
- 03Human decisionA senior underwriter reviews the presented evidence and approves the bound request.
- 04Tool effectOne idempotent tool call updates the synthetic target and records before/after digests.
- 05ProofThe canonical signed payload hash and Ed25519 signature verify with the published sample key.
{
"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
Record boundaries
Each artifact answers a different audit question. A production assurance procedure usually needs all four.
| Artifact | Question | Typical contents | Integrity boundary |
|---|---|---|---|
| Operational log | What did a component report? | Messages, metrics, errors, latency, and local runtime context. | Useful for operations. Completeness, identity, authority, and retention may remain unspecified. |
| Audit event | Who or what requested a governed action, under which authority, and what happened? | Identity, versions, purpose, resource, policy, approval, tool effect, outcome, privacy, and integrity references. | The record has a stable schema and an explicit verification result. Source-population completeness still requires reconciliation. |
| Execution lineage | How did one execution progress in order? | Ordered spans or events, parent-child relationships, retries, tool calls, and status. | Lineage supplies sequence and causality. It can link to several audit events and source artifacts. |
| Evidence bundle | Which retained artifacts support an audit assertion? | Manifest, audit events, lineage, policy and approval records, source receipts, hashes, signatures, omissions, and redactions. | Bundle verification tests artifact membership, hashes, signatures, ledger proofs, and declared omissions. |
04
Field dictionary
Required fields apply to every record. Conditional fields apply when the named component or lifecycle path exists. Optional fields preserve portable detail.
Envelope and ordering
| Field | Status | Purpose |
|---|---|---|
| schema_version | Required | Selects the compatibility contract used to parse the record. |
| audit_event.event_id | Required | Uniquely identifies this audit event. |
| audit_event.event_type | Required | Classifies a completed or denied action. Verification state stays in integrity. |
| audit_event.occurred_at / recorded_at / sequence | Required | Separates event time from collection time and preserves deterministic ordering. |
| audit_event.correlation.correlation_id / execution_id | Required | Joins policy, approval, tool, outcome, and evidence records without a timestamp join. |
| audit_event.correlation.trace_id / span_id / parent_event_id | Optional | Links the record to OpenTelemetry or an equivalent trace and to a parent event. W3C all-zero identifiers are invalid. |
Scope and identity
| Field | Status | Purpose |
|---|---|---|
| audit_event.scope.organization_ref | Required | Carries a pseudonymous or organization-controlled scope reference. |
| audit_event.scope.environment / retention_class | Required | Names the operating boundary and approved retention treatment. |
| audit_event.scope.region / legal_hold | Optional | Records regional placement and any hold that suspends ordinary disposal. |
| audit_event.actors.requester / agent / accountable_owner | Required | Binds the request, agent identity, and accountable human or organizational role. |
| audit_event.actors.delegated_user / service_identity | Conditional | Records on-behalf-of authority and workload identity when either exists. |
Versions and requested authority
| Field | Status | Purpose |
|---|---|---|
| audit_event.components.agent | Required | Pins the agent Release and optional configuration digest. |
| audit_event.components.model / prompt_template / orchestrator | Conditional | Pins each component that influenced the action. |
| audit_event.requested_action.action / purpose | Required | States the proposed capability and approved business purpose. |
| audit_event.requested_action.resource / data_boundary_ref / environment | Required | Defines the target, governed data boundary, and execution environment. |
| audit_event.requested_action.amount | Conditional | Uses a decimal string plus ISO 4217 currency when financial value affects policy. |
Policy and human decision
| Field | Status | Purpose |
|---|---|---|
| audit_event.policy.decision_id / policy_id / policy_version | Required | Identifies the exact decision and governing policy version. |
| audit_event.policy.policy_digest / inputs_digest | Required | Binds the evaluation to protected policy and input representations. |
| audit_event.policy.decision | Required | Carries allow, warn, require_approval, or block. |
| audit_event.policy.matched_rule_ids / reason_codes / evaluated_at | Required | Makes the result explainable and orderable before any effect. |
| audit_event.approval | Conditional | Required when policy returns require_approval. Execution effects require a decided, approved request from a human reviewer. |
| audit_event.approval.reassigned_from / override / appeal | Optional | Preserves exceptional decision lifecycle facts when the source system supports them. |
Execution and outcome
| Field | Status | Purpose |
|---|---|---|
| audit_event.tool_calls[] | Required | Lists every attempted tool call. Blocked, non-approved, and unstarted actions require an empty array. |
| audit_event.tool_calls[].arguments_digest / result_digest | Required | Binds protected arguments and results without placing secrets in the event. |
| audit_event.tool_calls[].downstream_effects[] | Conditional | Records target-system receipts and before/after state digests when effects occur. |
| audit_event.execution.status / business_outcome | Required | Separates technical completion from the business result and binds completed or denied event semantics. |
| audit_event.execution.rollback / incident_ref | Conditional | Connects recovery and investigation when either path is used. |
| audit_event.lineage | Required | Links the action to one Lineage Record and its ordered event IDs. |
Evidence, privacy, and integrity
| Field | Status | Purpose |
|---|---|---|
| audit_event.evidence.manifest_ref / artifacts[] | Required | Identifies the bundle manifest and supporting artifact digests. |
| audit_event.privacy.classification / redaction_status | Required | States the protection and transformation applied to the record. |
| audit_event.privacy.redactions[] / access_policy_ref | Required | Locates protected fields and the policy that governs access. Entries match the declared redaction status. |
| integrity.canonicalization / hash_algorithm / record_hash | Required | Defines and records the digest of the canonical signed envelope metadata and audit_event. |
| integrity.previous_event_hash | Optional | Connects records when the implementation uses a hash-linked event sequence. The signature protects this link. |
| integrity.signature | Required | Carries the algorithm, key ID, sample public key, and detached digest signature. |
| integrity.verification | Required | Records valid, failed, or not_performed with verifier version and failure codes. |
05
Integrity verification
Schema validity and cryptographic integrity are separate checks. Population completeness remains a separate audit procedure.
- 01Validate the envelope with the versioned JSON Schema.
- 02Build the signed payload from schema_version, audit_event, and integrity metadata other than record_hash and signature.value.
- 03Canonicalize the signed payload with RFC 8785 JSON Canonicalization Scheme.
- 04Compute SHA-256 and compare it with integrity.record_hash using the sha256: prefix.
- 05Resolve the trusted key by key_id. Verify its validity and revocation state at occurred_at.
- 06Verify the Ed25519 signature over the 32-byte digest.
- 07Verify each previous_event_hash against its ordered neighbor and an independently retained first-link anchor before accepting sequence order.
- 08Reconcile event IDs and artifact digests to lineage, source-system effects, and the evidence manifest.
- 09Record every failure code. A failed or unavailable check cannot produce valid.
Positive and denied examples
Both validate, reproduce their published hashes, and verify with the sample Ed25519 public key.
Tamper example
The envelope remains schema-valid. Its business outcome changed after signing, so the recomputed hash differs and verification recordsrecord_hash_mismatch.
The embedded sample key makes the files self-verifying. Production verification must trust keys through a separate registry. A key supplied only by the record cannot establish issuer identity.
06
OpenTelemetry correlation
Trace context joins telemetry and audit evidence. It does not carry the full audit assertion.
Carry
Propagate W3C traceparent across agent, policy, approval, tool gateway, and downstream calls. Copy trace_id and the action span_id into correlation.
Bind
Add stable execution_id, event_id, decision_id, request_id, and call_id attributes. Keep protected inputs, tokens, and raw model content outside ordinary span attributes.
Retain
Telemetry retention can be shorter than audit retention. Preserve the audit record and resolvable lineage reference after hot traces expire.
07
Compatibility and versioning
Version the contract independently from producer and tool versions.
Patch
Clarifications, descriptions, and examples may change without changing validation behavior. Stable v1 URLs keep immutable file contents, so a corrected artifact receives a new version URL.
Minor
A new optional field or enum extension requires a new schema_version and versioned URL. Consumers must reject unknown versions until they declare support.
Major
Removed or renamed fields, changed meanings, tighter required status, or changed canonicalization require a new major path. Producers can dual-write during migration.
Consumers must preserve unknown records for forensic handling and stop semantic processing when the schema version is unsupported. They must never silently coerce an unsupported policy outcome or verification status.
08
Current KLA producer mapping
The portable envelope is broader than any one KLA producer. These sources define current implementation truth.
| Contract area | Current source | Mapping | Status |
|---|---|---|---|
| Audit event identity and durable append | services/api/src/services/audit-logger.ts | AuditEvent supplies event, tenant, user, resource, action, result, correlation, and security context. The logger mirrors tenant-scoped events into ImmuDB. | Current source |
| Tool, policy, and approval event producers | services/execution-worker/src/services/audit-events.ts | Worker producers hash tool inputs and results, capture execution and policy identity, append approval request and resolution events, and attach the active OpenTelemetry trace ID. | Current source |
| Four policy outcomes | services/shared/src/policy/contracts.ts | GateDecisionValueSchema defines allow, warn, require_approval, and block. Older worker audit helpers can still spell the blocked outcome as deny. | Current source with normalization |
| Durable approval decision | services/execution-api/src/services/approval-audit-outbox-worker.ts | The approval API uses a leased, idempotent outbox to append a tenant-bound decision record. The request-side producer remains separate. | Current source |
| Execution lineage and trace correlation | services/execution-worker/src/services/lineage-trace-publisher.ts | Governed runs publish execution-scoped root and step spans. workflow-observability.ts also emits policy and approval attributes through OpenTelemetry. | Current source |
| Sealed Evidence Bundle and offline verification | packages/evidence-contract/src/index.ts | The bundle manifest binds tenant, export, artifacts, Merkle root, manifest hash, signature metadata, factory request, omissions, and redactions. packages/evidence-verifier performs the independent checks. | Current source |
Deliberate abstractions and unsupported fields
- •KLA does not currently emit this public envelope as one native wire record. The reference normalizes several authoritative producers into one audit unit.
- •Accountable owner, complete model and prompt configuration digests, tool versions, business outcomes, rollback, and incident references are not uniformly populated across every KLA runtime path.
- •Decision Request reassignment, override, and appeal are portable lifecycle fields. Current KLA producers do not expose all three as one normalized action-level contract.
- •The contract records the required role and human reviewer identity. Production consumers must verify that the reviewer held the required role when the decision occurred.
- •KLA signs and verifies the Sealed Evidence Bundle manifest and validates ledger and artifact proofs. Current KLA records do not all carry the per-record Ed25519 signature shape used by these portable examples.
- •The examples publish a sample public key so the files are self-verifying. Production systems must resolve trusted keys through an independently governed key registry and test revocation at the event time.
Apply the contract
Place the record inside a complete audit method.
Use the enterprise framework to define scope and control tests. Use the audit program to reconcile populations, sample actions, evaluate evidence, and report exceptions.