Agent Audit Logging: What to Record and What to Redact

An agent audit log answers a specific question after the fact: what did this thing actually do, on whose behalf, and with what authority? Most agent logging answers a different question — was the request successful — and is therefore useless at exactly the moment it is needed.

The distinction matters because agents fail in ways that look fine from the outside. A run that completed successfully and modified the wrong records produces clean metrics and a serious problem.

The unit of record is the action, not the request

Logging one entry per agent run is too coarse. A single run may issue two hundred tool calls, and the interesting one is somewhere in the middle.

Log every tool call as its own record. Tool name, full arguments, result status, duration, turn number, and the run and session identifiers that let you reassemble the sequence.

The full arguments matter more than they appear to. Executed a write is not an audit record; wrote 4kB to config/production.yaml is. When the question arrives it will be about the specific target, and a summarised argument list cannot answer it. Agent observability and tracing covers the surrounding instrumentation.

Record the authority, not just the action

Every entry should carry the identity the action ran under and the permission decision that let it through.

That means the service identity of the agent, the human who initiated the run, whether a gate fired and what the decision was, and which rule permitted the call. Without these the log tells you what happened but not why it was allowed, which is the half that matters for changing anything.

Denials belong in the log alongside successes, with the same detail. A denied call is often the most informative record in the file, because it marks the point where the agent tried to leave its lane. Agent permission models covers producing those decisions in a loggable form.

Capture the inputs that caused the action

Agent behaviour is a function of the conversation, so an audit trail that omits the conversation cannot explain the behaviour.

Store the messages that preceded each tool call, or at minimum a reference to a stored transcript keyed by run identifier. Transcripts are large, which argues for keeping them in object storage with the audit entries holding pointers rather than inlining them.

Record the model identifier and the exact version, along with the sampling parameters. When behaviour changes without a code change, the model version is the first thing you will want and the thing nobody logged. Pinning model versions covers why it moves underneath you.

Where content was retrieved from outside — a fetched page, a file from a shared drive, an issue body — record its source. Injection investigations are impossible without knowing what text entered the context and from where.

Redaction has to happen before the write

Agent logs accumulate secrets faster than ordinary application logs, because tool arguments and outputs are unstructured and often contain whatever the environment held.

Redact at capture rather than at read. A filter applied to arguments and outputs before they are written keeps secrets out of the store entirely, whereas redacting at query time means the store is already the liability.

Pattern matching on known key formats catches most of it — provider key prefixes, bearer tokens, private key headers. Complement it by denying entire fields known to be sensitive rather than trying to match their contents, since a value with no fixed shape will not be caught by a pattern.

Accept that redaction is lossy and that some incidents will need the unredacted form. The answer is a separate, tightly restricted store with a short retention window, not a relaxed default.

Retention and immutability

Audit records are only evidence if they cannot be quietly changed. Write them to an append-only destination that the agent identity cannot write to directly and cannot delete from at all.

Set retention from the questions you expect to ask. Debugging questions arrive within days. Security and compliance questions arrive months later, and are the reason to keep a reduced record — action, identity, target, decision — long after the full transcripts have expired.

Tiering costs little: keep everything briefly, keep the structured entries for a long time, keep transcripts only as long as they are plausibly useful.

Make it queryable or it will not be used

An audit log nobody can search is a compliance artefact rather than an operational one.

Index on the fields real questions use: identity, tool name, target resource, decision, time range. The recurring questions are narrow — what did this agent touch, who ran it, what was denied last week — and they should be a single query each.

Reading a run in sequence should be equally easy, because the way you understand an incident is by replaying the ordered sequence of calls rather than by reading individual entries. Replaying agent traces covers reconstructing a run from stored records.

A minimum viable record

Per tool call: timestamp, run and session identifiers, turn number, agent identity, initiating human, tool name, full arguments after redaction, result status, duration, permission decision and the rule that produced it, model identifier and version.

Per run: the start and end, the initiating request, the final outcome, total cost, and a pointer to the stored transcript.

That fits in a modest schema, costs almost nothing to write, and is the difference between explaining an incident in ten minutes and guessing about it for a week. Agent cost attribution covers reusing the same records for spend.