Building an Audit Trail for AI Agents: What to Log, How to Structure It, and Why Tool Calls Alone Aren't Enough

An AI agent did something it shouldn't have. It opened a private repository, summarized the contents, and pushed them into a public pull request. Your tool-call log shows the sequence cleanly: read_file, read_file, create_pull_request. Every call succeeded. Every parameter looks valid. And the log tells you exactly nothing about the only question that matters during an incident: why did the agent decide to do that?

That gap is the central problem of agent auditing. A traditional application produces deterministic actions you can trace to code paths. An AI agent produces actions from a probabilistic decision made over a context window you didn't fully control, often stuffed with content from untrusted sources. The action layer alone cannot tell you whether the agent followed a user's instruction or an attacker's injected one. To govern agents, your audit trail has to record both the intent and the action, and it has to prove neither was altered after the fact.

This guide covers what to log, how to structure it against the emerging OpenTelemetry standard, how to make it immutable and privacy-safe, and the concrete controls a security team puts in place. It assumes you already have agents and Model Context Protocol (MCP) servers running across your fleet. If you don't yet know where they all are, start with building an AI agent inventory, because you cannot audit what you haven't discovered.

What an AI agent audit trail actually is

An audit trail is not the same thing as a log. A log is a stream of events written for debugging and operations; nobody promises it wasn't edited. An audit trail is a record built to be evidence: structured, attributed, retained, and tamper-evident. The working definition to keep in mind is blunt: a log proves nothing; an audit trail must prove that nothing changed since it was written.

For AI agents specifically, the audit trail spans more layers than a conventional system. An agent's behavior emerges from a loop: it receives a goal, reasons over context, decides to call a tool, observes the result, and reasons again. A faithful record has to capture every stage of that loop, not just the side effects.

OWASP makes the governance case directly. The MCP Top 10 lists lack of audit and telemetry as a first-class risk: without logging, agent actions have no traceability, root-cause analysis becomes impossible, breach dwell time grows, and prompt injection or model drift go undetected in real time. The recommended baseline fields are timestamp, agent ID, session ID, tool invoked, parameters used, response summary, and user identity, captured as tamper-evident structured logging.

The two layers tool-call logging misses

Most agent observability tooling logs two things well and one thing poorly. It captures the LLM call and the tool call, but treats them as separate streams rather than a linked record of a single decision. The result is that you can see an action and the model output that triggered it, but you can't always answer the forensic question. Here are the layers a complete trail needs.

Layer 1 - The LLM request (intent)

This is the layer that explains why. It records the system prompt, the conversation messages (or their hashes), the request model, the response model, the finish reason, and token usage. When an agent decides to call a tool, the intent layer holds the context that produced that decision, including any untrusted content that may have entered it. Without this, you cannot tell whether an exfiltration was a user request or the product of an injected instruction.

Layer 2 - The tool invocation (action)

This is the layer that explains what. It records the tool name, the arguments passed, the result returned, latency, the MCP method and session, and crucially the bound identity under which the action executed. Tool-call-only logging stops here, which is exactly why it's insufficient: the action is visible but unmotivated.

The layers most teams forget

Two more layers matter and are routinely skipped. The memory and retrieval layer logs memory reads and writes and RAG lookups. The MINJA research (arXiv:2503.03704) demonstrated query-only injection into an agent's memory bank with no direct access to it, reporting a 98.2% injection success rate and a 76.8% attack success rate in the study. If you log only LLM and tool spans, a memory-poisoning attack leaves no trace. The identity and attribution layer binds each event to a specific credential or token so you can distinguish delegated user authority from autonomous agent action. See why memory poisoning is so hard to detect for the threat model behind this requirement.

Why intent logging is non-negotiable

Simon Willison's lethal trifecta names the conditions under which agentic data theft becomes near-inevitable: access to private data, exposure to untrusted content, and the ability to communicate externally. When all three are present, a single injected instruction can turn an agent against its own operator. A tool-call log captures the exfiltration step but not the injected instruction sitting in the model's context that caused it. Only the intent layer lets you attribute the action to attacker-controlled content versus legitimate user intent. We unpack the mechanics in the lethal trifecta and agent data exfiltration and indirect prompt injection explained.

This isn't theoretical. EchoLeak (CVE-2025-32711, CVSS 9.3) was a zero-click prompt-injection flaw in Microsoft 365 Copilot, disclosed by Aim Security (Aim Labs) in June 2025 and patched server-side by Microsoft, in which a crafted email could drive data exfiltration with no user interaction. Separately, Invariant Labs in May 2025 documented a GitHub MCP attack pattern in which malicious instructions planted in a public-repository issue caused an agent to pull private-repo data into context and leak it through an autonomously created pull request. In both cases, the forensically interesting event is the injected instruction crossing a trust boundary, which lives in the intent layer, not in the final tool call.

This also maps cleanly to the OWASP LLM Top 10 (2025). LLM06 Excessive Agency is the argument for rigorous action-layer logging, while LLM01 Prompt Injection and LLM02 Sensitive Information Disclosure are the argument for intent-layer logging. For the full taxonomy, see the OWASP Top 10 for LLM applications guide and the controls-focused OWASP agentic Top 10 checklist.

How the schema works: OpenTelemetry GenAI

The de-facto schema for agent telemetry is the OpenTelemetry GenAI Semantic Conventions. They are still marked Development status (the semantic conventions sit around the v1.37-v1.41 range, with most GenAI attributes still experimental), so treat exact attribute names as subject to change and verify them against the live spec before shipping code. But the structure is stable enough to design around, and it models the agent loop with span types including:

• invoke_agent - the orchestration or routing span that wraps an agent turn.
• chat - the LLM intent call: the request and response that constitute reasoning.
• execute_tool - the action: a single tool invocation and its result.

That span tree is the spine of a good audit record. One agent turn produces an invoke_agent span, which contains one or more chat spans and the execute_tool spans they trigger. Correlation comes for free through the trace, and across multi-turn conversations through a conversation identifier.

The key attributes (names to re-verify against the current spec) include the operation name (chat, execute_tool, invoke_agent, and so on), the provider name, the request and response models, token usage split into input and output (with cache-read and reasoning tokens broken out for reasoning models), the finish reasons, the tool name with its call arguments and result, the agent ID and name, and a conversation ID for multi-turn correlation.

How to handle prompt and completion content

By default the conventions capture no message content - spans carry only metadata such as model names, token counts, and durations. Capturing content is opt-in, and the choice is a privacy decision as much as an engineering one. In practice teams use one of three approaches:

1. Not recorded (the default) - spans carry metadata but no message text. Safest, least useful for forensics.
2. Inline - full input and output messages stored as span attributes. Richest, but spreads raw prompt content (and any PII inside it) across your telemetry pipeline.
3. External reference - content stored in a database or object store, with only a reference on the span. This is the better fit for production systems with sensitive or high-volume data.

The external-reference approach is the foundation of the privacy-separable design later in this guide. It lets you keep lean, queryable spans for operations while routing sensitive content into a controlled store with its own retention and access rules.

Capturing the MCP boundary

Most agent actions now flow through MCP servers, and the protocol boundary is where attribution gets hard, because the tool often runs in a separate process or service. OpenTelemetry added MCP-specific attributes precisely for this. Capture mcp.method.name (for example tools/call), mcp.session.id, mcp.protocol.version, and the transport (for example stdio versus an HTTP-based transport).

Because MCP client and server spans are linked through W3C Trace Context, a single trace can cross the protocol boundary: you can follow a tool call from the agent, through the MCP client, into the MCP server, and back. That end-to-end trace is what makes MCP forensics tractable. For the broader MCP threat surface, see the MCP server security complete guide, and for the identity side, OAuth for MCP servers explained.

On identity: the MCP authorization specification expects internet-facing servers to implement OAuth 2.1 with PKCE, with the MCP server acting as an OAuth Resource Server. Your audit trail should record token issuance and bind every tool call to a specific credential, recording whether the action was user-delegated or agent-autonomous. Blended authority is the single hardest forensic problem in agentic systems, and the only fix is to attribute every action to a concrete token. This connects directly to non-human identity governance and least privilege for AI agents.

The immutable audit schema

Once you've decided what to capture, you need a concrete, append-only record format. A practical JSONL/JSON audit schema captures the following mandatory fields per event:

• eventId - a sortable ULID, not a random UUID, so records order naturally.
• actorId - a pseudonymized reference (an HMAC-derived value), never a raw email.
• action - a namespace:verb string such as repo:read or order:update.
• resource + resourceId - what was acted on.
• timestamp - ISO 8601 UTC with a trailing Z.
• context - masked IP (first three octets + .x), user agent, sessionId, requestId.
• diff - before/after or an RFC 6902 JSON Patch of what changed.
• prevHash + eventHash - SHA-256 values that chain the record to its predecessor.

{
  "eventId": "01JZ8K2P7Q9R3T4V5W6X7Y8Z9A",
  "actorId": "hmac:9f2b...c41",
  "action": "repo:create_pull_request",
  "resource": "github.repo",
  "resourceId": "acme/internal-billing",
  "timestamp": "2026-06-21T14:03:51Z",
  "context": { "ip": "203.0.113.x", "sessionId": "sess_8842", "traceId": "4bf92f..." },
  "intentRef": "s3://audit-content/turns/01JZ8K2P.json",
  "identity": { "token": "tok_agent_ci", "authority": "autonomous" },
  "prevHash": "a1c9...0f",
  "eventHash": "7d3e...b2"
}

Note intentRef: rather than inlining the prompt, the action record points to the externally stored intent content (the external-reference approach above). Sensitive fields are masked as [MASKED] before capture, and the hash chain ties the lightweight action record to the heavier content store.

Making it tamper-evident

Immutability is what turns logging into an audit trail, and for tamper-evidence (SOC 2 and similar) you layer it rather than relying on any single mechanism:

• Database layer - make the table append-only: an INSERT-only role plus triggers that reject UPDATE and DELETE.
• Cryptographic layer - chain records with SHA-256 so each eventHash covers the prevHash. Any edit breaks the chain forward from that point. The genesis record uses 64 zeros as its prevHash.
• Storage layer - write to WORM media. AWS S3 Object Lock in Compliance mode prevents deletion even by an administrator; Azure Immutable Blob Storage is the equivalent.
• Verification layer - re-check the chain on a schedule (daily is typical), store the latest verified hash in a locked table, and optionally publish the chain root to an external ledger for independent attestation.

One more discipline that auditors increasingly expect: meta-auditing. Log who reads the audit log itself (the Postgres pgaudit extension can do this), so the act of inspecting evidence is itself evidence.

Privacy: keeping the trail GDPR-safe

Immutability and the right to erasure look contradictory: GDPR says you must be able to delete a person's data, but the whole point of a hash chain is that you can't. The resolution is a two-table separation that decouples identity from events:

• audit_events - immutable and hash-chained. Holds only an opaque actorId, derived as a truncated HMAC-SHA256(secret, user_id). No emails, no names.
• actor_identity - mutable. Maps each opaque actorId to the real email and name, with an erased_at column.

To honor a right-to-erasure request, you redact the identity row, not the immutable event. The link to a real person is severed while the audit chain stays intact and verifiable. This maps to GDPR Article 5 (data minimization, storage limitation, integrity) and Article 32, which names pseudonymization and encryption as technical measures. Hashing prompts adds another layer: you can prove a prompt's content later by re-hashing it, without ever storing the raw, possibly PII-laden text. For the wider obligations, see GDPR for AI agents, and for outbound data risk, why traditional DLP fails for agents.

Retention and storage tiers

Retention is driven by your compliance regime, and the practical answer is tiered storage with automated expiration, never manual deletion.

A common pattern moves data through three tiers: a hot database for 0-90 days (queryable for live investigation), a warm analytics store such as ClickHouse for 90 days to a year, and cold object storage (S3 Glacier) for 1-7 years. Expiration runs through partition drops and storage lifecycle rules so deletion is policy-driven and itself auditable.

What a security team does, in order

Pulling the pieces together, here is the sequence a platform or security team follows to stand up an agent audit trail:

1. Inventory first. Discover every agent and MCP server. You cannot instrument what you don't know exists. Start from building an AI agent inventory and building an MCP server registry.
2. Emit OTel GenAI spans as the live telemetry layer: invoke_agent, chat, execute_tool, plus MCP attributes. Route content through external references rather than inlining it.
3. Bind every action to an identity. Require OAuth 2.1 for internet-facing MCP servers and record token issuance and authority type (delegated vs autonomous) on each tool call.
4. Sink an immutable audit copy. Write hash-chained JSONL to WORM storage, separate from operational telemetry, with the two-table PII design.
5. Log memory and retrieval events so memory-poisoning and retrieval-injection are reconstructable.
6. Correlate everything by conversation ID, session ID, and trace ID, so an investigator can pivot from one suspicious tool call to the full decision that produced it.
7. Verify and integrate. Re-check the hash chain on a schedule, stream to your SIEM/XDR, and build behavioral baselines so anomalies surface in near real time.
8. Meta-audit reads of the audit store itself.

For coding-agent fleets specifically, this builds on the patterns in auditing Claude Code across a fleet and governing AI coding assistants across your fleet. When something does go wrong, the audit trail is the substrate your AI agent incident response playbook runs on.

Where continuous visibility fits

The hardest part of this whole effort isn't the schema; it's coverage. An audit trail is only as trustworthy as the population of agents and MCP servers it covers, and in most organizations that population is changing weekly, often without security's knowledge. Agents spin up in CI, MCP servers get added to a developer's editor, a new assistant gets a token. Each one that escapes inventory is a gap in the trail, an action with no recorded intent and no bound identity.

This is the same blind spot we describe in AI agents are the new shadow IT: you can't govern what you can't see, and you can't audit what you haven't discovered. Continuous discovery and behavioral monitoring of the agent and MCP layer is the category Anomity works in, and it's the prerequisite that makes everything above real rather than aspirational. The two-layer audit record, the immutability, the GDPR separation: all of it depends on first knowing the complete, current set of things that need to be logged. You can read how we approach the discovery side in inside Anomity discovery.

Build the trail to capture intent and action, make it provable, keep it private, and cover every agent. Do that, and the next time an agent opens a private repo and pushes it to a public PR, you won't be staring at three successful tool calls. You'll be able to read the injected instruction that caused them.