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

Querying the audit log

query_logs is the flight recorder's filter: it returns the rows that match an agent, a verdict or a time window, and get_statistics summarises the whole log.

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

The flight recorder lesson wrote three decisions. Once a log has thousands, you want the blocked ones, or one agent's actions, not the whole file. That is what querying gives you.

Filtering by agent and by verdict

query_logs takes optional filters and returns the matching rows. With no filter it returns everything up to its limit; with policy_verdict it returns only that verdict.

ExampleFiltering the log by agent and verdict
for_shop = recorder.query_logs(agent_id="shop")
print("all for shop:", len(for_shop))

# the verdict stored for a blocked call is the string "blocked"
blocked = recorder.query_logs(policy_verdict="blocked")
print("only blocked:", len(blocked))
print("blocked tool:", blocked[0]["tool_name"])

Summarising the whole log

get_statistics reads the whole log and returns counts, so you do not have to tally rows yourself. by_verdict is the breakdown, and total_actions is the count.

ExampleA summary of the whole log
stats = recorder.get_statistics()

# the counts are computed across every row in the log
print("by verdict:  ", stats["by_verdict"])
print("total actions:", stats["total_actions"])

query_logs vs get_statistics

query_logsget_statistics
ReturnsThe matching rowsCounts and averages
Use it forReading specific decisionsA dashboard number
Filtersagent, verdict, time, limitNone, it reads all

Where you use querying

  • An alert that fires when the count of blocked calls in the last hour crosses a threshold.
  • A per-agent view, pulling one agent's history out of a shared log.
  • A daily summary, reading by_verdict for the headline numbers.
Watch out. query_logs has a limit that defaults to 100, so a busy log can return a truncated view. Pass a larger limit, or narrow with a time window, when you need every match.
Try it yourself
  • Query with policy_verdict="allowed" and confirm the count is two.
  • Add more calls, then pass limit=1 and see the result truncate.
  • Read every key in get_statistics() and find the average execution time.

Little by little, you're building something great.