Agent Governance ToolkitAgent Governance Toolkit 4.1.0 · Python 3.10+
Dashboard
0%

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.

python
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.

python
# 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.

ExampleThree decisions recorded to SQLite
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])

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.

ExampleEach row carries the hash of the one before
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"])

Flight recorder vs the kernel list

Flight recorderkernel.get_audit_log()
Stored inA SQLite fileAn in-memory list
Survives a restartYesNo
Tamper-evidentYes, hash chainNo
QueryableYesOnly 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.
Watch out. With 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.
Try it yourself
  • 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.