Build Forensic Audit Logs for AI Agents

A forensic agent log should let an investigator answer who requested an action, what data and authority the agent used, which policy allowed it, what tool was invoked, whether a human approved it, and what external effect actually occurred. Capture those facts as structured, correlated events at trusted enforcement points. Protect the record from alteration, restrict sensitive fields, and verify that logging failures cannot silently erase evidence or break the production service.

Ordinary application logs are not automatically an audit trail. OWASP distinguishes security and audit uses, recommends recording the “when, where, who, and what” of each event, and calls for protection against unauthorized access and tampering (OWASP Logging Cheat Sheet). NIST SP 800-92 provides broader guidance on building log-management infrastructure and processes, though its final publication dates to 2006 and should be combined with current platform practices (NIST SP 800-92).

Begin with investigation questions

Design the event model by writing the questions an incident responder must answer:

• Which authenticated human, service, or remote agent initiated the task?
• Which tenant, session, role, and delegated authority were active?
• Which model, prompt template, policy, tool schema, and application release ran?
• Which untrusted documents, messages, memories, or tool results influenced the step?
• Which capability and exact arguments reached a tool gateway?
• What authorization and risk decision was made, by which policy version?
• What did an approver see and authorize?
• Did the downstream system accept the operation, reject it, or leave an uncertain outcome?
• What data crossed organizational or tenant boundaries?
• Could the action be undone, and was cleanup attempted?

These questions reveal missing instrumentation. If the only record is a transcript saying “I sent the email,” you cannot establish the authenticated actor, the final recipients, or whether the email provider accepted it.

Trace identity and authority end to end

Assign one task identifier at the user-facing entry point and propagate trace and span context through the agent runtime, policy service, approval service, tool gateway, and asynchronous jobs. Add an operation or attempt identifier for each side effect and preserve the downstream provider's receipt.

Record an explicit actor chain rather than one overloaded user_id:

{
  "initiator": {"type": "human", "id": "user_123"},
  "client": {"type": "application", "id": "support_console"},
  "agent": {"id": "triage_agent", "instance_id": "run_..."},
  "delegation": {"subject": "user_123", "actor": "agent_runtime"},
  "tool_principal": {"id": "mail_sender", "credential_ref": "cred_version_..."}
}

The values are illustrative. In production, use stable internal identifiers, log the tenant independently, and record the authorization mechanism and scope without recording the access token. For delegated agents, include the caller, callee, delegation depth, and attenuation applied at each hop.

Define a small, versioned event vocabulary

Prefer several factual events to one giant mutable run document. A useful baseline is:

Version the envelope and each payload. Event consumers must tolerate additive fields and reject or quarantine unsupported breaking versions. Publish a data dictionary: type, meaning, owner, sensitivity, cardinality, retention, and example for every field.

OpenTelemetry's generative-AI semantic conventions offer common names for model and agent telemetry, but the specification itself marks the conventions' maturity and compatibility per signal. Check their current status before binding a long-lived audit schema to them (OpenTelemetry Generative AI semantic conventions). Observability spans can feed an investigation, but security audit requirements such as retention, access, and integrity usually warrant a separately governed record.

Record decisions, not private chain of thought

Do not depend on hidden model reasoning as forensic evidence. It may be unavailable, unstable, sensitive, misleading, or inappropriate to retain. Record observable inputs and outputs plus system decisions:

• the user's explicit objective or a protected reference to it;
• model and prompt-template identifiers;
• hashes and provenance for attached context;
• structured plan or action proposal shown by the product, if any;
• policy rule and machine-readable reason code;
• validated tool arguments or their protected reference;
• approval preview and digest; and
• downstream result and receipt.

If the product asks a model for a rationale, label it as model-generated explanation rather than authoritative reasoning. It can support debugging but does not prove why a stochastic system produced an output.

Capture provenance without copying everything

Full prompts, documents, and tool responses may contain personal data, credentials, contractual material, or attacker-controlled payloads. Logging all content increases breach impact and may violate retention requirements.

For each input, store a durable source identifier, version or retrieval time, cryptographic digest, trust label, tenant, and data classification. Put content required for an investigation in a separately encrypted evidence store with stricter access, shorter retention where appropriate, and an audit trail of reads. In the main event stream, use a protected reference.

Hashes establish that later content matches the recorded bytes; they do not prove the content was truthful or who created it. Use keyed digests if low-entropy sensitive values could otherwise be guessed from their hashes. Canonicalize structured data using one documented serialization before hashing.

Never log passwords, access tokens, API keys, private keys, session identifiers that grant access, or raw authorization headers. OWASP's secrets guidance explicitly calls for auditability while keeping secret values out of logs (OWASP Secrets Management Cheat Sheet). Record a non-secret credential identifier, version, issuer, audience, and scopes instead.

Prove the external effect

Agent output is an intention, not an effect. Instrument the adapter closest to the downstream system. For a message, retain the provider message identifier and final recipients; for a deployment, the environment and artifact digest; for a permission change, the affected principal, resource, old state, and new state.

Use three outcome states rather than forcing every timeout into success or failure:

succeeded   downstream supplied authoritative confirmation
failed      downstream supplied authoritative rejection or no effect occurred
unknown     connection failed after submission; reconciliation required

An unknown result must trigger reconciliation using the same idempotency key, not a blind repeat. Record the later resolution as another event linked to the original attempt. This preserves history instead of rewriting it.

For critical effects, emit an intent event durably before invoking the downstream system, then a result event afterward. If the application and event store cannot share a transaction, use a transactional outbox or equivalent durable handoff. Document the failure window rather than claiming impossible exactly-once delivery.

Protect integrity and availability

Send audit events to a centralized system outside the agent runtime's administrative boundary. Use authenticated, encrypted transport; tightly controlled writer identities; append-oriented storage; restricted administrator roles; and monitored, read-only replicas or archives. Audit access to the audit data.

Tamper evidence can include immutable object retention, signed batches, hash-linked records, trusted timestamps, and independent replication. A hash chain can reveal some deletion or modification when anchors and verification are independently protected; it does not by itself provide complete nonrepudiation, prevent truncation, or establish that the producer told the truth. Test verification and restoration regularly.

Synchronize clocks and retain both event time and ingestion time. Include monotonic sequence numbers within a run where feasible, but do not assume clocks across distributed systems are perfectly ordered.

Logging must fail visibly. Buffer briefly during collector outages, enforce storage quotas and backpressure, alert on drops, and expose a metric for accepted versus exported critical events. Do not let an attacker fill the log pipeline with high-cardinality model text. At the same time, avoid letting a noncritical analytics sink outage crash every agent task. Define which high-risk actions fail closed when their audit intent cannot be durably recorded.

Set access and retention deliberately

Separate operations, security, compliance, and product-analytics access. Give each the minimum fields needed. Require reasoned, logged access for sensitive evidence and support legal hold without silently extending all telemetry forever.

Base retention on investigation windows, contractual and regulatory duties, data sensitivity, storage cost, and the lifetime of the external effect. Delete expired data from primary stores, replicas, exports, and test fixtures through a verifiable process. Document jurisdictions and tenant data-residency constraints.

Build a portable incident package

An authorized export should contain:

• the filtered event timeline in a documented format;
• schema and policy versions;
• integrity-verification results and anchors;
• referenced evidence manifests and hashes;
• relevant deployment, model, tool, and prompt-template identifiers;
• clock and known-gap notes; and
• a chain-of-custody record for the export.

Keep the raw evidence unchanged. Investigators can add annotations in a separate layer. Generate timelines by correlation identifiers and causal links, not only timestamp order.

Test before an incident

Run exercises that:

• reconstruct one normal and one malicious task without database-side guesswork;
• trace a delegated action through every actor and credential boundary;
• distinguish an approved preview from the committed effect;
• detect a missing, duplicated, reordered, or altered event;
• reconcile an unknown downstream outcome;
• verify redaction with canary secrets and personal data;
• simulate collector, network, and storage failure;
• restore archived evidence and validate integrity;
• enforce audit-reader authorization and record access; and
• expire evidence across all replicas according to policy.

Measure field completeness at the enforcement points. A dashboard with many spans is not success if the one irreversible action lacks its actor or receipt.

Production checklist

• Start from incident questions and explicit audit objectives.
• Propagate task, trace, operation, attempt, actor, and tenant identifiers.
• Emit versioned events at policy, approval, tool, and effect boundaries.
• Preserve source provenance and digests; isolate sensitive content.
• Record model identifiers and observable decisions, not hidden chain of thought.
• Never log credentials or access-granting session material.
• Treat uncertain downstream outcomes explicitly and reconcile idempotently.
• Centralize append-oriented records outside the agent's control plane.
• Protect integrity, availability, reader access, retention, and deletion.
• Alert on event loss and define fail-closed actions.
• Regularly verify archives and rehearse a complete reconstruction.