Building Audit Trails for AI Agents in Python

When an AI agent executes an action — placing a trade, scaling infrastructure, accessing patient records — someone will eventually ask: who authorized this, and can you prove it?

A log file is not proof. Log files can be edited, truncated, or silently modified after the fact. For regulated industries and high-stakes automation, you need a tamper-evident audit trail — one where any modification to any record is cryptographically detectable.

The problem with traditional logging

Most agent frameworks write decisions to a log file or database. This is fine for debugging, but it fails the audit test. A compliance officer cannot prove that a log entry was not modified after the fact. There is no cryptographic link between records. There is no chain of custody.

The fix is hash chaining: each record includes the hash of the previous record. Modify any record in the chain and every subsequent hash becomes invalid. An auditor can verify the entire chain without access to the system that produced it.

Hash-chained audit trail in Python

Here is a minimal implementation:

import hashlib, json, time

def make_record(action, agent_id, prev_hash=""):
    record = {
        "agent_id": agent_id,
        "action": action,
        "timestamp": time.time(),
        "hash_prev": prev_hash,
    }
    canonical = json.dumps(record, sort_keys=True, separators=(",", ":"))
    record["hash_curr"] = hashlib.sha256(canonical.encode()).hexdigest()
    return record

# Build a chain
chain = []
prev = ""
for action in ["verify:trade_AAPL", "attest:deploy_v2", "bind:scale_api"]:
    record = make_record(action, "my-agent", prev)
    chain.append(record)
    prev = record["hash_curr"]

# Verify the chain
for i, rec in enumerate(chain):
    expected_prev = chain[i-1]["hash_curr"] if i > 0 else ""
    assert rec["hash_prev"] == expected_prev, f"Chain broken at {i}"
print("Chain intact:", len(chain), "records")

Each record includes hash_prev (the hash of the previous record) and hash_curr (its own hash). Modify any record and the chain breaks forward. This is the same principle behind blockchain ledgers, applied to agent decision logs.

From DIY to production

The code above works for prototyping. For production agent deployments, you need additional guarantees:

• Signed records — HMAC or digital signatures so records cannot be forged
• Post-quantum signatures — ML-DSA-87 (FIPS 204) for long-term evidence integrity
• Independent verification — auditors can verify the chain without access to the issuing system
• Intent binding — link declared intent to actual command before execution
• Outcome verification — prove the agent did what it said it would do

This is what the Kevros governance gateway provides as a service. Every decision gets a signed release token. Every action gets a hash-chained provenance record. Every intent gets a cryptographic binding to its command.

Try it

The Kevros API is free to try — 1,000 calls per month, no credit card. Get a hash-chained audit trail for your agent in three lines:

from kevros_governance import GovernanceClient

client = GovernanceClient(api_key="kvrs_...")
result = client.verify(
    action_type="trade",
    action_payload={"symbol": "AAPL", "quantity": 100},
    agent_id="my-trading-agent",
)
print(result.decision)        # ALLOW, CLAMP, or DENY
print(result.release_token)   # Cryptographic proof
print(result.provenance_hash) # Hash-chained evidence