What Must an Audit Trail for AI Agents Capture?
An audit trail for AI agents needs six fields: actor, authority, change, prior state, triggering instruction, and human approval, not just a timestamp.
Most AI agent audit trails answer one question well: which action ran, and when. That is enough to reconstruct a human's clickstream. It is not enough to answer the question a compliance lead actually asks the moment an agent's action gets disputed: who authorized this, under what instruction, and did a human sign off before it counted as done?
The direct answer: a complete audit trail for AI agents needs six fields, not two. Who acted (a named agent identity, not an anonymous API key), on whose authority (the human and the token scope that granted the access), what changed, the prior state before the change, the instruction or task that triggered the action, and whether a human approved the result. Most logging tools capture the first two and stop. The fifth field, the triggering instruction, is the one that gets skipped most often, because it lives a layer above the action itself and nobody wired the reference back to it.
TL;DR: The six fields
- Actor: which named agent acted
- Authority: whose access and which token scope
- Change: exactly what was modified
- Prior state: what it was before
- Instruction: the task or prompt that caused it
- Approval: whether a human signed off
The diagram below lines up what a thin trail captures against what a complete one needs. Most vendor logs stop at the left column.
The Six Fields a Complete Audit Trail for AI Agents Needs
Each field answers a distinct question an investigator asks, in a predictable order, once an agent's action gets disputed.
| Field | Question it answers | Common gap |
|---|---|---|
| Actor | Which agent acted? | Logged as a shared API key, not a named identity |
| Authority | Whose access, under what scope? | Scope not recorded, only that "an agent" acted |
| Change | What exactly was modified? | Logged as an event name with no field-level detail |
| Prior state | What was it before? | Only the new value is stored, the before value is gone |
| Instruction | What task or prompt caused it? | The action layer has no reference back to the trigger |
| Approval | Did a human sign off? | No review step exists; the action is final the moment it runs |
Actor and authority come from the same place a human's log entry would: the identity making the call and the credential it is using. Change and prior state are a database diff, tedious to wire up but conceptually simple. Approval is a workflow question: did this land as a draft a human reviewed, or did it commit directly. The field that breaks most systems is instruction.
Why the Triggering Instruction Is the Field Most Tools Skip
An agent does not act spontaneously. Something caused it: a task assignment, a scheduled sweep, a prompt a person typed. That cause lives one layer above the action itself, in whatever system routed the request to the agent in the first place. Most audit logging is built at the action layer, where a database write happens, and that layer often has no reference back to the task or instruction that produced it.
The gap matters because "the agent updated the budget field" and "the agent updated the budget field because it was asked to reconcile Q3 actuals against the approved baseline" are different facts for an auditor. The first is an event. The second is evidence. Without the instruction attached, every disputed agent action turns into a reconstruction exercise: pulling Slack history, guessing at what task was open, asking the team what they remember asking for. With it attached, the log answers the question directly.
How Long to Keep Agent Audit Logs
Retention should be one policy that covers every actor, not a separate rule for agents. The regimes that set the floor are the same ones that already govern human activity: HIPAA and FINRA commonly require multi-year retention with no deletion for the audit trail itself, GDPR pushes toward shorter, purpose-limited windows, and an org running under more than one regime at once should apply whichever one is strictest across the board rather than picking per record.
Two failure modes show up here. The first is treating agent logs as lower stakes than human logs and purging them faster, which leaves a gap in exactly the record most likely to get questioned. The second is applying no policy at all and letting logs grow unbounded, which is a cost problem more than a compliance one, but a real one once agent action volume climbs past what a handful of humans would ever generate in the same period.
What Append-Only Actually Buys You
A retention policy decides when a row eventually gets purged on a schedule. Append-only decides that nothing can alter a row before that. The distinction matters for an audit trail specifically, because an editable log is not evidence, it is a claim: anyone with database access could, in principle, have changed it after the fact, and there would be no record that they did. An audit trail that only allows new rows and never permits an update or delete on an existing one is the mechanism that turns "we believe this happened" into "here is the row proving it happened," for a human's action and an agent's action alike.
What This Looks Like in Practice
Onplana's audit log applies the same standard to agent activity that it applies to human activity, not a separate, thinner one. Every agent tool call lands in the same audit trail as human activity rather than a client-side log a vendor can't see, and log rows are append-only at the application layer, so nothing can rewrite a row once it is written. Agent work connects over MCP through personal access tokens scoped to specific projects, which is the "authority" field: the log shows which token, at what scope, not just "an agent did something." Work an agent completes through Run with Onplana Agent lands in a review inbox as a draft a human approves before it becomes final, which is the "approval" field answered structurally rather than by policy alone. Retention follows the same six built-in presets (STANDARD, GDPR, HIPAA, FINRA, SOC 2, CUSTOM) that govern every other actor in the org, with the strictest applicable policy enforced by a daily worker, and full audit export to CSV or JSON is available on the ENTERPRISE plan and above for anyone handing this record to an external auditor.
Security questions for AI agent access covers the buyer-side evaluation this feeds into, and building audit-ready project plans for regulated industries covers the same discipline applied to schedules rather than agent actions. The full control inventory, encryption, retention, and identity included, lives on Onplana's security page, and enterprise project governance covers where this audit trail sits inside the broader governance feature set. The rest of the Onplana blog covers the agent-governance patterns this checklist assumes: scoping, escalation, and review.
Frequently asked questions
What must an audit trail capture for AI agent work?
Six fields: which agent acted, on whose authority (the connecting user and token scope), what changed, the prior state before the change, the instruction or task that triggered it, and whether a human approved the result. A log with only the first two answers a much smaller question than compliance actually asks.
Why do most AI agent audit trails miss the triggering instruction?
Because it is the hardest field to wire up. Actor and action come from the API call itself; prior state comes from a database diff. The instruction lives one layer up, in whatever task or prompt caused the agent to act, and most logging is bolted onto the action layer without a reference back to that context.
How long should AI agent audit logs be retained?
The same retention policy that governs human activity, not a separate one. Compliance regimes set the floor: HIPAA and FINRA commonly require multi-year retention, GDPR pushes toward shorter windows, and an org operating under several regimes at once should apply the strictest one across every actor, human or agent.
Is an activity feed the same as an audit trail?
No. An activity feed is for humans skimming what happened recently and is allowed to summarize, reorder, or drop low-signal events. An audit trail exists for someone reconstructing a disputed change months later, which means it has to be complete, ordered, and immutable in a way a feed was never designed to be.
Can audit trail entries be edited or deleted after the fact?
They shouldn't be able to be, for either humans or agents. An append-only log, one that only allows new rows and never permits an update or delete on an existing one, is what makes an audit trail evidence instead of a claim. A retention policy can eventually purge old rows on a schedule; nothing should be able to alter one early.
Ready to make the switch?
Start your free Onplana account and import your existing projects in minutes.