Skip to main content
Every tool call can be recorded to an append-only JSONL audit log — thread-safe for concurrent multi-agent writes. 
from praisonaiagents import Agent

agent = Agent(name="audited", instructions="Log every tool call for compliance.")
agent.start("List recent deployments.")
The user enables audit logging; each tool invocation is appended to JSONL safely even when many agents run in parallel.

​
How It Works

Each tool call the agent makes is appended to the audit log before the result returns to the user.

​
Quick Start

1

Enable audit logging

from praisonaiagents import Agent
from praisonai.security import enable_audit_log

enable_audit_log()  # default: ~/.praisonai/audit.jsonl

agent = Agent(
    name="AuditedAgent",
    instructions="Every tool call is logged.",
)
agent.start("Summarise today's PRs")
2

Close on shutdown

from praisonai.security import get_audit_log

get_audit_log().close()  # flush and release handle

​
What’s Logged

Each JSONL line records:
  • timestamp, session_id, agent_name
  • tool_name, tool_input, execution_time_ms
  • Optional tool_output (when include_output=True)
The hook registers on after_tool automatically when you call enable_audit_log().

​
Configuration

OptionTypeDefaultDescription
log_pathstr~/.praisonai/audit.jsonlAppend-only JSONL path
include_outputboolFalseInclude truncated tool output
max_output_charsint500Max output chars when include_output=True
enable_audit_log(
    log_path="./my-audit.jsonl",
    include_output=True,
    max_output_chars=1000,
)

​
Thread Safety (PR #2062)

  • Uses threading.Lock for concurrent multi-agent writes
  • Keeps a long-lived file handle (reopened lazily if rotated)
  • Each write calls fsync for crash durability
  • Call get_audit_log().close() on shutdown to flush and release the handle

​
Best Practices

Call enable_audit_log() before creating agents so every tool invocation is captured from the first turn — retrofitting mid-session misses earlier calls.
Call get_audit_log().close() in your shutdown handler to flush the file handle. Long-running daemons that skip this may lose the last buffered line on crash.
Leave include_output=False unless you need forensic replay. When enabled, tune max_output_chars to avoid bloating the JSONL with large tool payloads.
Store logs outside web-served directories. The audit path is protected by default — do not disable Protected Paths on production hosts.

Security Overview

Enable audit log with other security features

Protected Paths

Audit log file is itself protected