Design a versioned audit log schema for AI agents

Separate the event envelope from the business payload

The envelope should remain consistent across every producer. Include event ID, event type, schema version, tenant, execution and parent identifiers, actor, source service, environment, region, observed time, emitted time, sequence position, and integrity metadata. Keep business-specific fields inside a typed payload.

An immutable envelope makes mixed event streams searchable and verifiable. It also prevents each model gateway, agent runtime, approval service, and tool adapter from inventing incompatible names for the same concepts.

• Use globally unique event IDs and stable execution IDs rather than database row numbers.
• Record both the logical actor and the credential or service identity used at the boundary.
• Distinguish event time from ingestion time so delayed delivery is visible.
• Include a canonicalization and hash version whenever integrity fields are calculated.

{
  "schema_version": "1.0.0",
  "event_id": "0198f2f2-7a3b-7d64-8e21-b7c9386c1801",
  "event_type": "tool.completed",
  "tenant_id": "tenant_acme",
  "execution_id": "exec_20260823_1042",
  "parent_event_id": "0198f2f2-6e31-7ad4-91ab-c5f93104dd12",
  "actor": {
    "type": "ai_agent",
    "id": "agent:invoice-reviewer",
    "credential_id": "workload:invoice-reviewer"
  },
  "source": {
    "service": "agent-runtime",
    "version": "2026.08.1"
  },
  "environment": "production",
  "region": "us-east-1",
  "event_time": "2026-08-23T10:42:31.184Z",
  "observed_at": "2026-08-23T10:42:31.229Z",
  "sequence": 42,
  "integrity": {
    "canonicalization": "jcs-v1",
    "hash_algorithm": "sha-256",
    "payload_hash": "sha256:77418e964aac33bbf7ad94e7a43b833c08d53dd8156a6ea1ad18d25e6c3c26fe",
    "previous_event_hash": "sha256:b2e95e6a232cebc7a1ee00d8331212c888af5fb4225620f15adf7e5cc9444e46"
  },
  "payload": {
    "tool": {
      "name": "erp.create_credit_note",
      "version": "2.3.1"
    },
    "operation_id": "op_1042",
    "attempt": 1,
    "authorization": {
      "decision": "allow",
      "policy_id": "finance-credit-note-v4"
    },
    "approval_id": "approval_7842",
    "idempotency_key": "credit-note:CN-2026-1042",
    "input_digest": "sha256:8cbb1f38093a5e9af1206feb9fd7f310e5333822f07778c2ede5629c666c9761",
    "outcome": "succeeded",
    "external_reference": {
      "system": "erp",
      "type": "credit_note",
      "id": "CN-2026-1042"
    },
    "result_digest": "sha256:7e17a509ba134cf46597d97909f2a6eac27ce54b6fba1d4e30b816620af808d0"
  }
}

Define event types around decisions and effects

Avoid one oversized event that claims an agent request was authorized, executed, and completed. Emit separate records for request acceptance, policy decision, model invocation, tool proposal, human approval, tool attempt, external acknowledgement, completion, denial, failure, and unknown outcome.

Link attempts with execution, operation, and idempotency identifiers. This lets a reviewer distinguish a retry from a second business decision and trace a target-system transaction back to the exact authority and inputs used.

Version the schema without breaking old evidence

Treat schema changes as a compatibility contract. Add optional fields when possible, publish new event versions for changed meaning, and keep validators for every retained version. Do not reinterpret an old field after evidence has been committed.

Test producers and consumers with representative historical exports. A new deployment should reject malformed events, quarantine unsupported versions, and preserve unknown fields where round-trip export is required.

Make privacy and independent review part of the schema

Classify fields as required, optional, sensitive, hashed, tokenized, or externally referenced. Record the redaction policy and key version used, but never place credentials or unrestricted prompt content in the canonical envelope.

Exports should include schema definitions, event files, checksums, sequence or Merkle information, and a manifest that identifies omitted or protected fields. Reviewers can then validate structure and integrity without receiving unnecessary source data.