What must an audit trail record after an AI agent changes something?

Scope

Use this envelope for agent-initiated changes to data, configuration, access, infrastructure, communications, purchases, or other durable state. Read-only access logging may use a reduced form. The audit store is separate from conversational memory and ordinary application logging.

Why it happens

Agent systems produce many partial records. The chat has the request, the orchestrator has a plan, the gateway has a tool call, identity has a token event, the target has a change, and observability has spans. None alone explains who authorized which exact proposal or whether the intended effect occurred.

Teams often save the model’s final statement as the summary. It may say “deployment succeeded” even though the gateway only accepted a job. Conversely, logging every prompt and argument creates secrets and personal-data exposure without guaranteed audit integrity.

Diagnosis

Select one production change and perform a bidirectional trace. Starting from the user request, reach the exact target version after the change. Starting from the target effect, identify actor, agent version, task, proposal, policy, approval, credential, attempt, and evidence.

Check these failure cases:

• request timed out after target commit;
• a retry used the same or a different idempotency key;
• approval expired before execution;
• target state changed after approval;
• compensation ran partially;
• a log sink was unavailable.

The audit system should represent unknown and audit_degraded, not manufacture a clean story.

Solution

Create an audit event schema and append events at authoritative boundaries: proposal creation, policy decision, approval, credential issuance reference, tool attempt, target receipt, effect verification, compensation, denial, and handoff. Use stable task, action, proposal, target, and effect identities.

Canonicalize and hash sensitive parameters where reviewers need integrity but not routine visibility; retain protected originals only under defined access and retention. Never log bearer tokens or secrets. Send audit events through a protected path with access logging, clock discipline, integrity controls, retention, and outage behavior.

Cross-reference traces for timing and diagnosis. Build human-readable incident views from audit facts rather than storing only prose summaries.

Artifact

The audit-and-effect envelope includes:

request: {id: ..., actor: ..., tenant: ..., purpose: ..., received_at: ...}
agent: {workload: ..., software: ..., model: ..., prompt_policy: ...}
proposal: {id: ..., operation: ..., target: ..., parameters_digest: ..., evidence_refs: [...]}
authorization: {decision: ..., policy: ..., approval: ..., expires_at: ...}
credential_ref: {issuer: ..., audience: ..., scope: ..., token_ref: ...}
attempt: {id: ..., tool: ..., schema: ..., idempotency_key: ..., trace_ref: ...}
target: {canonical_id: ..., version_before: ..., version_after: ...}
effect: {state: committed|failed|unknown, receipt: ..., verified_at: ..., verifier: ...}
recovery: {compensation: ..., residual_effects: ..., handoff: ...}
integrity: {event_ids: [...], sink: ..., retention_class: ..., access_class: ...}

Common mistakes

• Treating the final agent message as effect evidence.
• Logging raw credentials or sensitive payloads into general traces.
• Recording allowed actions but omitting denials and expired approvals.
• Using display names instead of canonical target IDs and versions.
• Storing records without integrity, access, retention, or sink-failure policy.