Recording every decision: the flight recorder
The flight recorder is the toolkit's SQLite audit store: it writes one row per decision to a database file, chained by hashes so a later edit can be caught.
Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0
The map lesson named three stores. This one builds the durable default. A decision is recorded as a trace: you open it before the tool runs and close it with the outcome.
Opening the recorder
Syntax: the recorder takes a database path. Batching is off here so every write lands immediately, which is what you want while learning.
import tempfile, os, sqlite3
from agent_control_plane.flight_recorder import FlightRecorder
db = os.path.join(tempfile.mkdtemp(), "shop.db")
recorder = FlightRecorder(db_path=db, enable_batching=False)Recording a trace per call
start_trace opens a trace before the tool runs and returns an id. log_success closes it with a result; log_violation closes it with the reason the gate refused.
# one trace per call: log_success for an allowed call, log_violation for a blocked one
for tool, allowed in [("order_status", True), ("refund", True), ("delete_account", False)]:
trace = recorder.start_trace(agent_id="shop", tool_name=tool, tool_args={})
if allowed:
recorder.log_success(trace, result="ok")
else:
recorder.log_violation(trace, violation_reason="not in allow list")
recorder.flush()Reading the recorded decisions
get_log returns the rows. Each carries the agent, the tool, and the verdict the gate reached: allowed or blocked.
log = recorder.get_log()
print("entries:", len(log))
# each row keeps the agent, the tool and the verdict
for e in log:
print(e["agent_id"], e["tool_name"], e["policy_verdict"])
# the file is a real sqlite database in WAL mode
con = sqlite3.connect(db)
print("journal mode:", con.execute("PRAGMA journal_mode").fetchone()[0])entries: 3 shop order_status allowed shop refund allowed shop delete_account blocked journal mode: wal
How the rows are chained
Each row stores an entry_hash of its own contents and the previous_hash of the row before it. That link is what lets the recorder notice later if a row was changed, which the integrity lesson uses.
log = recorder.get_log()
# every row links to the one before by hash, forming a chain
chained = (log[1]["previous_hash"] == log[0]["entry_hash"]
and log[2]["previous_hash"] == log[1]["entry_hash"])
print("rows chained by hash:", chained)
print("first row previous_hash:", log[0]["previous_hash"])rows chained by hash: True first row previous_hash: None
Flight recorder vs the kernel list
| Flight recorder | kernel.get_audit_log() | |
|---|---|---|
| Stored in | A SQLite file | An in-memory list |
| Survives a restart | Yes | No |
| Tamper-evident | Yes, hash chain | No |
| Queryable | Yes | Only by hand |
Where you use the recorder
- A production gate that must keep a lasting record of what it allowed and blocked.
- An incident review, reading back exactly which tools an agent called and when.
- A compliance report, where the record has to be queryable and provably unedited.
enable_batching=True (the default) writes are buffered and a row may not be on disk until flush() or the flush interval. Call flush() before you read, or set enable_batching=False as these lessons do.Related
- Previous: Where the audit trail is written
- Next: Querying the audit log
- Add a fourth call and read the new row from
get_log(). - Open the recorder with
enable_batching=True, read before flushing, and see the row missing. - Print one full row and read every field the recorder stores.
Every expert started right here.