AI Agent Audit Logs: What to Capture and Why

What should an AI agent audit log capture?

A complete audit record describes a single agent action from intent to outcome. Drop any one of these fields and you lose the ability to reconstruct the event later, exactly when you need it most. At minimum, each record should capture:

• Intent - the goal the agent was pursuing and the user request or trigger that initiated it, so a reviewer understands why the action happened.
• Action and arguments - the exact tool or API call invoked and the parameters passed (for example, update_deal with the deal ID and the new stage), so the action is reproducible and reviewable.
• Actor and identity - which agent ran, on whose behalf, and under which scoped credentials, so the action ties back to a real principal and a least-privilege role.
• Approver and decision - if the action was gated by a human-in-the-loop approval, who reviewed it, whether they approved or rejected it, and any note they left.
• Timestamp - a precise, time-zoned record of when the action was requested and when it completed.
• Result - the outcome returned by the target system: success or failure, the response payload or error, and the ID of any record created or changed.
• Correlation IDs - the conversation, session, and request identifiers that let you trace one action back to the full sequence it belonged to.

The single most overlooked field is intent. A log that shows an agent updated 40 records but not why is hard to defend in an audit. Pairing intent with the concrete action and arguments turns a raw event stream into an explainable record a reviewer can actually read.

The second most overlooked is identity at the right granularity. "The agent did it" is not an answer an auditor accepts. The record needs the principal the action ran on behalf of and the scoped role it used, so a privileged read of customer PII is attributable and a write is tied to a least-privilege credential rather than a shared god-mode key.

What a single audit record looks like in practice

Abstract field lists are easy to nod along to and hard to act on, so here is a concrete one. Imagine a support AI agent that has just escalated a refund on a customer ticket. A complete record for that one action reads, in plain terms, like this:

Intent: "Customer reported a duplicate charge on order #44812 and qualifies for a refund under the 30-day policy." Action: issue_refund with order_id 44812, amount 129.00, currency USD. Actor: support-agent running on behalf of user j.rivera@acme.com under the role support-write-refunds (capped at refunds under 250 USD). Approver: m.chen@acme.com approved at 2026-06-02T14:03:11-04:00 with the note "verified duplicate in Stripe." Result: success, Stripe refund re_1P9x... created, ticket #88120 moved to Resolved. Correlation IDs: conversation c_7741, session s_2210, request r_55190.

Read that record a year later and you can answer every question an auditor or a customer might raise without opening a single other system. You know why the refund happened, exactly what ran, who the agent acted for, which human signed off and why, and what changed downstream. That is the bar. If your logging cannot produce a line like this for an arbitrary past action, it is a metrics feed, not an audit trail.

How AI agent audit logging works, step by step

Logging is not a feature you bolt on at the end. It is a sequence that runs inside every agent turn, capturing each stage so the record is complete before the next action begins. Here is the flow for a single gated action.

The order matters. Intent and identity are captured before execution, which means even a failed or rejected action leaves a record. That is the opposite of logging only successes, which is how teams end up unable to explain the action that caused the incident: it errored, so nothing was written.

Why do AI agent audit logs need to be immutable?

Audit logs are evidence, and evidence only holds up if no one can quietly rewrite it after the fact. Immutability means records are append-only: once written, an entry cannot be edited or deleted, only superseded by a new entry that references the original. This is what lets you prove to an auditor, or to yourself during an incident, that the log reflects what actually happened and was not altered to hide a mistake or a breach.

Immutability also protects the people operating the agent. If a customer disputes that an agent changed their data, or a regulator asks how a decision was made, an append-only trail is the difference between a clear answer and an unprovable claim. In practice this means storing logs in a write-once store, restricting who can touch the log pipeline, and ideally hash-chaining or signing entries so any tampering is detectable rather than silent.

There is a subtle trap worth naming: the agent must not be able to write to its own audit log. If a compromised or prompt-injected agent can author or alter the very record meant to catch it, the log proves nothing. The pipeline that records actions has to sit outside the agent's reach, which is why audit logging belongs to the platform, not to the prompt.

How to log approvals and human-in-the-loop decisions

Approvals deserve their own record, not just a flag on the action. When an agent proposes a risky action, such as sending a refund, deleting a record, or emailing a customer, a human-in-the-loop gate pauses execution until a person decides. That decision is itself an auditable event with its own who, when, and why.

A good approval record links the proposed action to its reviewer and captures:

• The proposed action and arguments, exactly as the agent intended to run them.
• The approver's identity and role, so the sign-off ties to a real, authorized person.
• The decision - approved, rejected, or modified - and the time it was made.
• Any reviewer note or reason, which matters most for rejections and modifications.
• The link between the approval and the resulting action record, so you can trace proposal to outcome in one hop.

Capturing approvals this way lets you later prove that a sensitive action was not autonomous: a named person signed off on it. It also surfaces patterns worth acting on, such as a tool that gets rejected often and whose permissions should be tightened so the agent stops proposing it in the first place.

Modifications are the case people forget. When a reviewer approves an action but changes its arguments first (lowering a refund amount, swapping a recipient), the log has to show both the agent's original proposal and the human's edited version. Recording only the final action hides the fact that a person intervened, which is precisely the signal an auditor is looking for.

How long should AI agent audit logs be retained?

How long you keep audit logs depends on your regulatory and contractual obligations, but for most teams the practical floor is at least one year, so the records cover a full annual audit cycle. Frameworks like SOC 2 expect you to retain evidence of controls operating across the audit period, and some industries (finance, healthcare) require considerably longer. Set retention by policy, document that policy, and apply it consistently rather than letting logs age out by default.

Retention is only half the equation; access control is the other half. Audit logs reference sensitive operations and the records they touched, so they should be readable by the right reviewers (security, compliance, ops) and protected from everyone else, including the agent itself. Pair that with least-privilege RBAC on the agent's own credentials and you get a system where the agent can only do what it is scoped to do, and every time it does, the record is preserved and reviewable.

Different frameworks pull the number in different directions, which is why a single hardcoded default rarely survives a real audit. The table below maps common obligations to the retention you should plan for.

A worked example: using the log when an agent goes wrong

Say a RevOps team wakes up to a Slack alert: a batch of Salesforce opportunities got pushed to Closed Lost overnight, and nobody remembers approving that. Without an audit log this is a forensics nightmare across Salesforce history, login records, and guesswork. With a complete log it is a 20-minute investigation. Here is how the records carry the response:

• Scope - filter the log to the time window and the update_opportunity action: 137 records touched between 02:11 and 02:14, all by the pipeline-hygiene agent.
• Authorization - check the approver field: every one ran autonomously, no human-in-the-loop gate fired, which immediately tells you the gate was misconfigured for this tool.
• Root cause - read the intent: a scheduled cleanup was told to close opportunities with no activity in 90 days, but the date filter was inverted, so it caught active deals instead of stale ones.
• Blast radius - pull the result IDs: you now have the exact 137 opportunity IDs and their prior stage values from the recorded arguments, so a corrective batch can restore them precisely.
• Containment - trace the actor and identity: revoke the scoped credential the cleanup ran under and add a human-in-the-loop gate on update_opportunity before re-enabling it.

Notice what made this fast. The records were immutable, so the timeline was trustworthy rather than something that could have been edited to hide the bug. Each record carried correlation IDs, so the team could pivot from one bad write to the scheduled run and the prompt that produced it. And the arguments were stored, so the prior values needed to reverse the damage were sitting in the log itself. That is the difference between a contained incident and a guessing game.

Pitfalls that quietly gut an audit trail

Most failed audits are not the result of having no logs. They come from logs that look fine until someone actually needs them. These are the failure modes worth checking for before you trust a setup:

• Logging only successes - the action that caused the incident often errored, so if you skip failures and rejections, the most important record is the one that does not exist.
• Mutable storage - if logs live in a regular table an admin or the agent can update or delete, they are operational telemetry, not evidence, and an auditor will treat them that way.
• Missing intent - an event stream of tool calls with no reason attached is unreadable a month later and indefensible in an audit; you can see what but never why.
• Coarse identity - "the agent did it" with no principal or scoped role means you cannot attribute a privileged read or tie a write to a least-privilege credential.
• Logging secrets in plain text - capturing full arguments is good, but tokens, passwords, and raw PII in the log create a new breach surface; sensitive values should be masked or referenced, not stored raw.
• No correlation IDs - records you cannot stitch back into a conversation turn an investigation into manual cross-referencing across systems, exactly when speed matters most.
• Channel gaps - an agent that runs on web, Slack, Teams, WhatsApp, and an API but only logs one channel leaves blind spots an attacker or a bug can hide in.

The common thread is that each of these looks acceptable in a demo and fails under a real audit or incident. The test is not "do we have logs." It is "can we answer who-did-what-why-when-who-approved for an arbitrary action from six months ago, including one that failed."

How to evaluate audit logging when choosing a platform

When you compare AI agent platforms, audit logging tends to get a single checkbox on the feature grid, which hides enormous variation. Use this framework to score what is actually there rather than what the marketing page claims. Walk each platform through these questions and weight them by your own risk tolerance:

• Completeness - does every action get a record, including privileged reads, failures, and rejected approvals, or only successful writes?
• Immutability - are entries append-only and tamper-evident (hash-chained or signed), and is the agent itself locked out of the log pipeline?
• Approval capture - are human-in-the-loop decisions their own linked records that show the original proposal and any reviewer modification?
• Identity depth - does each record carry the principal and the scoped, least-privilege role, or just a generic agent name?
• Coverage - is logging uniform across every channel and integration, so there are no blind spots between Slack, Teams, the API, and the CRM?
• Retention and access - can you set retention by policy, govern deletion, and restrict who can read the log, including excluding the agent?

Score each platform out of those six and you will usually find that platforms which treat governance as core (RBAC, approvals, and audit designed together) clear the bar, while those that treat logging as an afterthought pass the demo and fail the audit. The chart below shows how that gap tends to look in practice.

How does Onpilot log every AI agent action?

Onpilot writes an immutable audit record for every action an AI agent takes and every approval decision a human makes. You don't wire this up yourself; it is part of how agents run. Each record captures the intent, the tool call and its arguments, the scoped identity the action ran under, the approver and decision when a human-in-the-loop gate is required, the timestamp, and the result returned by the target system.

Those records work alongside the rest of Onpilot's governance model. Least-privilege RBAC limits what each agent can touch in your CRM, support, and data tools; human-in-the-loop approvals gate risky actions before they execute; and the audit log preserves the whole sequence across every channel the agent runs on - web, Slack, Teams, WhatsApp, and the API. Because the same record is written no matter where the agent runs, there are no channel blind spots to reconstruct later.

The result is governed cross-system action you can prove after the fact, whether the reviewer is an auditor, a security team, or you. The agent can only do what it is scoped to do, a named person signs off on the risky parts, and every step leaves a record that the agent cannot rewrite.