How to create audit trails for AI agents

An audit trail records every action your AI agent takes, every policy decision made, and every outcome observed. In regulated industries, audit trails are a requirement. In every other context, they are the only way to answer "what did the agent do and why?" after something goes wrong.

What gets recorded

Each entry in the audit trail (called a receipt) includes:

• Timestamp: When the action was evaluated
• Tool name: Which tool the agent tried to call
• Arguments: The parameters passed to the tool
• Policy decision: Allow, block, or escalate
• Reason: Why the decision was made (which rule matched)
• Content scan results: Any threats detected by Aegis
• Hash: SHA-256 hash of the receipt contents
• Previous hash: Hash of the preceding receipt, forming a chain

Hash-chained receipts

Every receipt contains the hash of the previous receipt. This creates a chain similar to a blockchain. If someone modifies or deletes a receipt in the middle, the chain breaks and the tampering is detectable.

Receipt 1: hash=sha256(contents_1), prev=null
Receipt 2: hash=sha256(contents_2), prev=hash_1
Receipt 3: hash=sha256(contents_3), prev=hash_2

To verify the chain, walk through the receipts and confirm each hash matches the previous entry.

Generating receipts

The guard function generates receipts automatically:

const decision = guard('file.delete', { path: '/data/report.csv' });

console.log(decision.receipt);
// {
//   id: "rec_7f3a2b",
//   timestamp: "2026-01-15T14:22:00Z",
//   tool: "file.delete",
//   args: { path: "/data/report.csv" },
//   action: "escalate",
//   reason: "Delete operations require approval",
//   hash: "sha256:a1b2c3...",
//   previousHash: "sha256:d4e5f6..."
// }

Storing receipts

By default, receipts are stored in memory. For production, persist them to a durable store:

const guard = createGuard({
  policy,
  receipts: {
    store: 'postgresql',
    connectionString: process.env.DATABASE_URL
  }
});

The control plane handles receipt storage automatically when you connect the SDK to it.

Querying the audit trail

Use the control plane API to query receipts:

# All receipts for a specific session
curl https://your-control-plane/api/receipts?session_id=sess_abc123

# All blocked actions in the last 24 hours
curl https://your-control-plane/api/receipts?action=block&since=24h

# Verify chain integrity
curl https://your-control-plane/api/receipts/verify?session_id=sess_abc123

Retention and compliance

Configure retention policies based on your regulatory requirements. The EU AI Act requires keeping records for the lifetime of the AI system. SOC 2 typically requires 12 months of audit logs. Set your retention policy accordingly and ensure receipts are backed up to immutable storage.