I tried to forge my own AI agent's audit log
A new framework introduces passports, mandates, gates, and immutable logs to track AI agent actions. The system prevents unauthorized behavior, enables rollback, and ensures that only humans can approve irreversible steps.
AI agents are increasingly deployed across enterprises, but many lack clear oversight. Recent studies show that half of the organisations running agents have already exceeded their intended permissions, and nearly half of production agents have no monitoring at all. This gap leaves organisations unable to answer the question: what did the agent do and why?
Building an Accountability Layer
The solution begins with a passport—a machine‑readable card that defines an agent’s identity, purpose, and limits. A sample passport looks like this:
{"agent_id":"kepil.leads.v1","purpose":"Handle inbound requests and hand qualified ones to a person","does_not":["never promises prices or deadlines on the company's behalf","never sends invoices or contracts","never exports the customer base outside the perimeter"],"risk_class":"medium","autonomy_class":"medium","risk_review":{"last":"2026-09-14","next_due":"2027-09-14"}}Each new version of an agent receives a fresh passport, while the old one remains archived so that historical permissions can be audited. Passports also carry the operator, the model list, rationale for each class, an incident log, and a cryptographic hash of the card itself.
Defining What an Agent Can Do
Beyond the passport, a mandate specifies the exact actions an agent may perform. It lists allowed actions, forbidden actions, systems the agent can access, and limits such as message quotas or cost caps. For example:
{"mandate_id":"mnd-0001","allowed_actions":["read:inbox","read:crm","generate:reply","send:message","write:crm","generate:summary","send:handoff"],"allowed_systems":["crm.local","whatsapp.local"],"forbidden_actions":["sign:*","pay:*","export:database","send:bulk"],"human_confirmation_required":["send:*","write:crm","publish:*"],"limits":{"messages":300,"llm_cost_kzt":4000},"valid_until":"2026-09-21T10:09:45"}Anything not explicitly allowed is automatically refused. This strict approach is essential because many agents are wired with a single shared API key and unrestricted network access.
The Gatekeeper
All external calls pass through a gate that checks the passport, mandate, action, system, limits, and whether the action is irreversible. The gate runs checks in a fixed order and refuses any request that fails a check. A false refusal triggers a retry, while a false pass triggers a breach notification.
Immutable Logging
Every decision is recorded in an append‑only JSONL log. Each entry contains a hash of the previous record, creating a tamper‑evident chain:
{"seq":10241,"ts":"2026-09-12T11:42:07+05:00","agent_id":"kepil.leads.v1","action":{"type":"send:message","target":"whatsapp.local"},"decision":"await_human","cost_kzt":0,"prev_hash":"sha256:c61d8b…","hash":"sha256:d5ade5…"}Personal data never enters the log; only types, counts, and hashes are stored. The log’s integrity is verified by a separate verifier written in TypeScript, ensuring that the writer (Python) and the verifier cannot collude to hide tampering.
Testing for Forgery
To validate the system, a test script altered a log entry from a refusal to an approval. The verifier detected the change because the hash chain was broken, proving that the log is tamper‑evident. Additionally, a bug in number canonicalisation—Python serialising 0.0 as "0.0" and JavaScript as "0"—was caught because the verifier expected consistent formatting.
Human‑in‑the‑Loop Confirmation
Only humans can approve irreversible actions. The confirmation card is presented via a panel or a Telegram bot with two buttons. The system explicitly blocks any tool that could call a confirm function, preventing agents from approving their own irreversible actions.
Undo and Rollback Capabilities
Every action has a compensating action defined in a rollback table. When a user requests an undo, the system walks backwards through the log, applying compensating actions until it reaches an irreversible step. The rollback itself is recorded as an operator decision, ensuring that only authorised personnel can trigger it.
For example, if the last hour’s actions include a message sent and a CRM record created, the system can undo both. If it encounters an irreversible action—such as a tailored requirement search—it stops and reports what could not be undone.
Deployment and Integration
The core library is written in pure Python 3.11+ with no external dependencies, making it suitable for air‑gapped environments. It stores state in JSON files, eliminating the need for a database and simplifying dispute resolution. The package can be installed via pip and integrates with an MCP server, a JSON API, and an n8n node.
For organisations running AI agents in production, this framework answers the critical question: what did agent X do on a given date, and who authorised it? If you cannot currently answer that, this tool fills the gap.
Why it matters
Without a tamper‑evident audit trail, AI agents can act beyond their intended scope, exposing organisations to legal and operational risks. This framework provides the transparency needed for compliance and trust.
Key points
- Half of AI‑agent‑running organisations have already exceeded permissions
- Passports and mandates enforce strict action limits
- A gate checks every external call before it reaches the model
- Immutable JSONL logs provide tamper‑evident audit trails
- Only humans can approve irreversible actions
- Rollback logic walks backwards through the log to undo actions
Frequently asked questions
What is an AI agent passport?
A passport is a machine‑readable card that defines an agent’s identity, purpose, and limits, including what it cannot do.
How does the system prevent unauthorized actions?
All external calls pass through a gate that validates the passport, mandate, and limits before allowing the action.
Can the log be edited after the fact?
No. The log is append‑only and each entry hashes the previous one, making tampering detectable.
Who can approve irreversible actions?
Only humans via a panel or a Telegram bot; the system blocks any tool that could call a confirm function.
