agentlogsafe

agentlogsafe is a tiny, vendor-neutral event logging and redaction layer for AI agent workflows. It helps teams produce consistent, privacy-safe audit trails for model calls, tool calls, retrieval, policy checks, approvals, decisions, and errors.

Why this exists

Agent applications often log valuable operational evidence alongside prompts, credentials, and personal data. Framework-specific telemetry can also make a simple audit trail unnecessarily difficult to adopt. agentlogsafe provides a small, standard-library-only runtime with a stable event envelope, automatic run context, JSONL output, and conservative redaction enabled by default.

Installation

python -m pip install agentlogsafe

Python 3.10 or newer is required.

Quickstart

from agentlogsafe import AgentLogger

log = AgentLogger(
    agent_name="pricing-agent",
    workflow_name="margin-risk-review",
    sink="agent_events.jsonl",
)

with log.run(input={"request": "Find margin risks"}):
    log.user_message("Find margin risks in this forecast")
    log.model_call(
        provider="azure_openai",
        model="gpt-4.1",
        input_tokens=812,
        output_tokens=132,
        payload={"prompt": "Find margin risks in this forecast"},
    )
    log.tool_call(
        tool_name="snowflake.query",
        args={
            "sql": "select * from margin where email = 'person@example.com'",
            "authorization": "Bearer abc.def.ghi",
        },
    )
    log.decision("Escalated above threshold", requires_human_review=True)

The context manager emits run_start and run_end. If its body raises, it also emits error, marks the run as failed, and re-raises the original exception.

Example JSONL output

Each line is an independent JSON object (formatted here for readability):

{"event_id":"b616cabc-70ee-4970-aad6-16931bdbb554","run_id":"d683f2cd-a784-4b80-b607-5a9e293cc156","event_type":"tool_call","timestamp":"2026-06-23T14:30:00.000000Z","agent_name":"pricing-agent","workflow_name":"margin-risk-review","parent_event_id":null,"provider":null,"model":null,"tool_name":"snowflake.query","status":null,"payload":{"args":{"sql":"select * from margin where email = '[REDACTED]'","authorization":"[REDACTED]"}},"risk":{},"metadata":{}}

Redaction

Redaction handles nested dictionaries and sequences, dataclasses, sets, and objects that expose model_dump() or dict(). Sensitive field names are replaced in full; common PII and credential patterns are replaced wherever they occur in strings.

from agentlogsafe import RedactionConfig, redact

redact({
    "email": "person@example.com",
    "note": "Call 312-555-0199",
    "url": "https://example.com/file?token=secret&format=csv",
})
# {'email': '[REDACTED]', 'note': 'Call [REDACTED]',
#  'url': 'https://example.com/file?token=%5BREDACTED%5D&format=csv'}

config = RedactionConfig(replacement="***", redact_phone_numbers=False)
redact("person@example.com / 312-555-0199", config)
# '*** / 312-555-0199'

Pattern matching is a safety aid, not a substitute for data classification or access controls. Disable default redaction only when the destination and payloads have been reviewed.

Event types

Arbitrary event type names are rejected by default. For a domain-specific type, construct AgentEvent(..., allow_custom_event_types=True) or use the portable custom type with a descriptive payload.

Design principles

• Standard library only at runtime.
• Vendor- and framework-neutral event records.
• Safe defaults with explicit escape hatches.
• Append-only, inspectable JSON Lines.
• Context-local run IDs that work with threads and asynchronous tasks.
• Small APIs and ordinary Python data structures.

Enterprise governance use case

Teams can write a local JSONL audit trail from notebooks, services, and batch jobs, then ship those records through their existing log pipeline. Stable run and event identifiers connect policy decisions, approvals, tool access, and final outcomes without requiring a particular model provider or observability platform. Metadata and risk fields can carry internal classifications while using the same redaction policy as event payloads.

Roadmap

• Additional country-specific, checksum-aware PII detectors.
• Async-native logger run contexts and sink composition.
• Schema migration helpers and compatibility fixtures.
• Batch-oriented OpenTelemetry export and metrics.

License

MIT. See LICENSE.