AI Agent Audit Trails: A Logging Design Guide

Q: What should an AI agent audit trail include?

Five categories. Identity (which user, which tenant, which agent version). Inputs (the user request and any tool result that influenced a decision). Decisions (each tool call with arguments and the model output that proposed it). Outcomes (the result returned by each tool and the final answer to the user). Approvals (who approved any human-in-the-loop step). The NIST AI Risk Management Framework (2023) and SOC 2 trust services criteria both require equivalents.

Q: How long should I keep AI agent audit logs?

Driven by the highest applicable obligation. SOC 2 typically expects 12 months. HIPAA requires 6 years. GDPR has no fixed retention but requires the ability to produce records for subject access requests. Financial-services rules can require 7 years or more. Default for a B2B SaaS agent is 13 months active plus 12 months cold storage; longer for regulated industries.

Q: How do I make AI agent logs tamper-evident?

Append-only storage plus a hash chain. Each log entry includes the hash of the previous entry. A daily summary hash is signed and published to a separate system (or to a customer-controlled bucket). Any modification to a log entry breaks the chain and is detectable. AWS CloudTrail file integrity validation and the SLSA framework both use this pattern.

Q: Should AI agents log every model call?

Yes, with redaction for PII. Each call should log prompt hash, model identifier, token counts, latency, and a redacted excerpt. Full prompt and response can be stored separately with tighter access controls. The OpenAI logs object and Anthropic Workbench both surface equivalent data for debugging; the audit trail uses similar fields with retention and access policies suited to compliance use.

Q: What is the most common mistake in AI agent audit logging?

Logging the inputs but not the agent's decisions. If the audit trail records 'user asked to refund $500' and 'agent issued refund' without the intermediate reasoning and tool selection, the trail cannot answer 'why did the agent do this'. Always log the model's tool-call output that drove the action, not just the action.

An AI agent's audit trail is the difference between "the agent took an action" and "we know why the agent took that action." It is what enables incident response, compliance audits, and the kind of post-hoc analysis that turns a one-off bug into a fixed system. This guide is the logging design for production agents: what to log, how to structure it, how long to keep it, and how to make it credible to auditors.

For the operational view of what to do when the audit trail tells you the agent misbehaved, see how to debug an agent that did the wrong thing. For broader monitoring concerns, see AI agent monitoring and observability.

What to log

Five categories cover the audit-trail requirements of SOC 2, HIPAA, GDPR, and the NIST AI Risk Management Framework (2023). Capture each on every run.

Identity. Which user initiated the run, which tenant they belong to, which agent version is running, which prompt hash. Without identity, no other field is interpretable in audit.

Inputs. The user request that started the run. Every tool result that the agent read. The system prompt hash (not the full prompt; the hash lets you reconstruct from the prompt store).

Decisions. Each tool call with arguments. The model output that proposed the tool call (or a hash of it, with the full output in a separate higher-retention store). The reasoning trace if your provider exposes one.

Outcomes. The result the tool returned. Errors and retries. The final answer the agent gave the user.

Approvals. Every human-in-the-loop checkpoint: who approved, at what timestamp, with what comment. For approval design, see how to add a human approval step to an agent.

Log schema

One row per event. Multiple events per run. A working schema looks like this.

Field	Type	Notes
event_id	uuid	Unique per event
run_id	uuid	Groups events into a single agent run
timestamp	iso8601 with tz	Server-side, not client
tenant_id	string	Tenant scope, indexed
user_id	string	Initiating user
agent_id	string	Logical agent name
agent_version	string	Deployed version or git hash
prompt_hash	string	SHA-256 of the system prompt
event_type	enum	input, tool_call, tool_result, model_call, approval, error, output
payload	jsonb	Type-specific data (redacted)
prev_hash	string	Hash of prior event for chain validation

This schema works with Postgres + jsonb up to several million events per day. For higher volumes, append to S3 or equivalent with daily compaction; keep an index in a queryable store for the working window.

Retention

Retention is set by the most demanding obligation that applies. Common rules.

SOC 2. No fixed minimum in the standard. Auditors typically expect 12 months and inspect a sample.

HIPAA. 6 years for records related to PHI access (HHS HIPAA Security Rule).

GDPR. No fixed retention but requires producing records for subject access requests; in practice 13 to 24 months is common.

PCI DSS. 1 year minimum with at least 3 months immediately available, per requirement 10.5 (PCI Security Standards Council).

SOX. 7 years for records related to financial reporting.

Pick the strictest rule that applies; default to 13 months active plus 12 months in cold storage if no specific rule applies. The cold tier costs 10 to 30x less per GB and meets discovery requirements.

Tamper-evident design

Auditors and incident responders need confidence that logs were not modified after the fact. Tamper-evident design uses append-only storage plus a hash chain.

Append-only storage. The log table has no UPDATE or DELETE permissions for the agent service account. Modifications require a separate, audited role. AWS S3 Object Lock provides this at the storage layer; Postgres with revoked UPDATE/DELETE permissions at the application role provides it at the database layer.

Hash chain. Each log entry includes prev_hash, the SHA-256 of the previous entry. A separate daily job computes the chain hash for the day and signs it with a key the agent service cannot access. The signed digest is published to a customer-controlled bucket or a separate audit system.

Detection. Periodically verify the chain. Any modification breaks subsequent prev_hash links and is detectable in O(n) time. AWS CloudTrail file integrity validation uses an equivalent design.

Redaction and PII

Log destinations often have broader access than the source system. A support engineer who can read agent logs but not customer email is a common access topology. Redact before storage.

Common redactions. Email bodies down to subject + sender + recipients. Customer record contents down to record ID + operation. Free-text user messages with PII patterns (email addresses, phone numbers, SSNs, credit-card numbers) masked. Tool results that contain PII stored separately with stricter access.

Provide a "full-fidelity" log tier behind heavier access control for incident response, where redaction would block investigation. Two tiers (redacted, full-fidelity) plus an access audit on the full-fidelity tier is the production standard.

Access controls

Three access roles for the audit trail.

Agent service account. Append-only. Cannot read its own historical entries, cannot delete, cannot modify.

Support / engineering. Read on redacted tier only. Reads are themselves logged.

Audit / security. Read on full-fidelity tier. Reads are logged to a separate system.

The "reads are logged" property prevents the audit-of-the-audit problem: a malicious actor with logs access cannot examine specific data without leaving a trail.

Common mistakes

Logging actions but not decisions. The audit shows "agent refunded $500" but not the model output that proposed the refund. The trail cannot answer "why."

Same access for service and humans. The agent service has DELETE on the log table. One bug deletes evidence at the moment you need it.

No retention policy. The team builds the logger and never specifies how long to keep entries. Storage costs accumulate; auditors find no retention SLA.

Logs in the same database as the data they describe. A database compromise that affects production data also affects the audit trail. Separate the audit store, even if the rest of the architecture is monolithic.

Reading the trail during incident response

An audit trail is most valuable when something has gone wrong. Three patterns make trail reading effective under pressure.

Run-scoped views. The first action in any investigation is "show me everything from run X." This requires run_id to be indexed and the UI to filter on it in one click. Trails that need a SQL query to assemble a run view slow incident response by minutes that count.

Decision diff. When two runs of the same task produced different outcomes, the question is "what did the model decide differently." A side-by-side view of the tool calls in two runs is the single highest-leverage piece of tooling on top of the trail. Build it once; use it every incident.

Replay-on-trace. Some agent frameworks let you re-execute an agent against a recorded prompt and tool-result trace. The replay produces a new model output for comparison. This is the deepest investigation tool and the one that depends most on capturing the inputs in the trail. Without recorded tool results, replay is impossible.

Mapping the trail to compliance controls

Auditors are most efficient when the trail maps directly to the control language they care about. SOC 2 CC6 (logical access) maps to identity + tool calls per user. CC7 (system operations) maps to errors and recoveries. CC8 (change management) maps to the prompt_hash field tying runs to deployed versions. The mapping does not need to be a formal document; it needs to be a one-page table the auditor can use to navigate the trail. Build the table once during the first audit; reuse it every cycle.

Frequently asked questions

What should an AI agent audit trail include?

Five categories: identity, inputs, decisions, outcomes, approvals.

How long should I keep AI agent audit logs?

Driven by strictest applicable rule. Default 13 months active plus 12 months cold storage if no specific rule applies.

How do I make AI agent logs tamper-evident?

Append-only storage plus a hash chain. Daily signed digest published to a separate system.

Should AI agents log every model call?

Yes, with PII redacted. Prompt hash, model id, token counts, latency, and a redacted excerpt.

What is the most common mistake in AI agent audit logging?

Logging the action but not the model decision that drove it. Always log the tool-call output that proposed the action.

Three things to ship this week

Lock down write permissions. The agent service account writes; nothing reads or modifies historical entries.
Add prev_hash to every event. Build the daily digest job.
Set retention SLA and put cold-storage move policy in code.

Sources

NIST, "AI Risk Management Framework", 2023, nist.gov
AWS, "CloudTrail log file integrity validation", docs.aws.amazon.com
US HHS, "HIPAA Security Rule", hhs.gov
PCI Security Standards Council, "PCI DSS v4.0", pcisecuritystandards.org
AICPA, "Trust Services Criteria (SOC 2)", aicpa-cima.com