The idea
When something goes wrong, or an auditor asks, you need to answer: which user asked for this, what did the agent do, with what arguments, what was the result, and who approved it? Audit logs are append-only, structured records of security-relevant events.
Log: authenticated user and tenant, request ID, model and prompt version, every tool call with arguments and result status, approvals and rejections, guardrail blocks and data accessed. Redact PII and secrets, and protect the logs from modification.
Keep audit logs separate from debug traces, with stricter access and longer retention as your compliance needs require.
Without it you cannot investigate incidents, prove compliance or detect abuse patterns.
Words to know
- Append-onlyRecords can be added but not changed or deleted.
Try it without code
Answer an incident question
- Pretend a customer says the agent emailed the wrong person yesterday.
- Write what you would need to know.
- Check whether your logs today could answer it.
Use it in code
Structured audit events as JSON lines.
import json, datetime, uuid
def audit(event, *, user_id, tenant_id, request_id, **fields):
record = {"ts": datetime.datetime.utcnow().isoformat() + "Z", "id": uuid.uuid4().hex,
"event": event, "user_id": user_id, "tenant_id": tenant_id,
"request_id": request_id, **fields}
with open("audit.log", "a") as f: # ship to append-only storage in production
f.write(json.dumps(record) + "\n")
audit("tool_call", user_id="u7", tenant_id="t1", request_id="r42",
tool="send_email", args={"to": "anna@example.ie", "subject": "Invoice"},
approved_by="u7", result="sent")Emit audit events for every tool call, approval and guardrail block in your agent, then answer the incident question from the log.
Common mistakes
- Mixing audit events into noisy debug logs.
- Logging full PII and secrets.