Agent Governance ToolkitAgent Governance Toolkit 4.1.0 · Python 3.10+
Dashboard
0%
1
Curious builder0 XP earned · 300 to level 2
0 daysFinish a lesson to begin
Badge collection0 of 6 unlocked
47 small wins to finish your pathNext lesson →

The audit log as JSONL

GovernanceAuditLogger writes the audit trail as JSONL: one JSON object per line in a text file, the shape a log collector expects.

Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0

The flight recorder is a database. Many systems instead ship plain log files to a collector. The JSONL logger writes that format: each decision is one line, so tools like a SIEM can read it without a database driver.

Building the logger

Syntax: the logger starts empty and you attach a backend. The JSONL backend takes the path of the file to append each line to.

python
import tempfile, os
from agent_os.audit_logger import GovernanceAuditLogger, JsonlFileBackend, AuditEntry

path = os.path.join(tempfile.mkdtemp(), "audit.jsonl")
logger = GovernanceAuditLogger()
logger.add_backend(JsonlFileBackend(path))

Writing a decision

A decision is an AuditEntry. The fields name the agent, the action, the verdict and the reason. log records it and flush writes it out.

python
entry = AuditEntry(event_type="tool_call", agent_id="shop",
                   action="refund", decision="deny", reason="over limit")
logger.log(entry)
logger.flush()

Reading the line back

The file now holds one line of JSON. Reading it as text shows the exact shape; parsing it shows the fields a collector would index. The timestamp is set when the entry is made, so it differs every run.

ExampleOne decision as a line of JSON
import json

# the file holds one JSON object per line
line = open(path).read().strip()
record = json.loads(line)

# read the fields a collector would index (timestamp is left out, it changes each run)
for field in ["event_type", "agent_id", "action", "decision", "reason"]:
    print(field, "=", record[field])

JSONL vs the flight recorder

JSONL loggerFlight recorder
FileA text file, one line eachA SQLite database
Read byAny log collectorA SQLite query
Tamper-evidentNo, it is plain textYes, a hash chain
Use it forShipping to a SIEMA durable local record

Where you use JSONL

  • A log pipeline that tails files and forwards lines to a collector.
  • A container that writes decisions to stdout or a file for the platform to pick up.
  • A quick grep, when you want to search decisions with text tools.
Watch out. JSONL is plain text with no hash chain, so it is readable but not tamper-evident on its own. When you need to prove a line was not changed, pair it with the flight recorder or ship it to a store you trust.
Try it yourself
  • Log a second decision and confirm the file now has two lines.
  • Print the raw line including its timestamp and note it changes each run.
  • Add a metadata dictionary to the entry and read it back from the line.
PreviousProving the audit log's integrity

Slow is fine. Stopping is the only problem.