how to log agent tool calls for security review

TL;DR

Log every tool call the agent makes with who, what, when, and with what arguments, into append-only storage the agent cannot rewrite. "What did the agent do?" should be answerable in minutes, not a forensic project. If the agent can edit its own history, you have a diary, not an audit trail.

The query

how to log agent tool calls for security review

Use this when

• Agents take actions: file writes, API calls, database changes, messages sent
• You need to answer "what did the agent do on Tuesday" for security or compliance
• An incident involves agent behavior and you need the timeline
• Reviewers must approve or audit agent actions after the fact

Not for

• General app logging strategy
• Logging prompts for model quality evals (related, different schema)
• Choosing or deploying a SIEM product

Steps

1. Define the event schema before you log anything: timestamp, agent identity, session id, tool name, full arguments (redacted where sensitive), result summary, and the human or policy that authorized it. One schema, every tool.

Expected output: a documented schema with an example event per tool category.

1. Emit the log at the tool-dispatch layer, not inside each tool. One choke point means no tool can forget to log, and no tool can skip it.

Expected output: adding a new tool requires zero logging code; it is logged automatically.

1. Write to append-only storage the agent cannot modify: a separate service, a write-once bucket, or a log pipeline with no delete path from the agent's credentials. Include a sequence number or hash chain so gaps are detectable.

Expected output: a test deletion or edit attempt from the agent's identity fails.

1. Redact at write time: secrets, tokens, and PII in arguments get replaced with markers before storage. Decide the redaction list up front; "we will redact later" means plaintext secrets in logs.

Expected output: sample log lines show markers like [redacted secret] where values were.

1. Build the review view: filter by agent, session, tool, and time; expand any event to full arguments; export a session timeline in one click. Reviewers will not use a system that makes them grep raw files.

Expected output: a reviewer can reconstruct a full session in under five minutes.

1. Set retention and alerting: keep logs as long as compliance requires, and alert on patterns like privilege escalation attempts, repeated denied actions, or tools used outside their normal scope.

Expected output: a simulated abuse pattern fires an alert; retention policy is documented.

Variant phrasings

"audit trail for AI agent actions"

Same skill. Emphasize immutability and the authorization field: who or what approved each action.

"what should I log when an agent calls tools"

Step 1 is the checklist: identity, session, tool, arguments, result, authorization, timestamp. Add input/output sizes for exfiltration spotting.

"tamper-proof agent logs"

Step 3: hash-chained, append-only, written by a service the agent cannot reach with write credentials. Test the tamper resistance, do not assume it.

Why this happens

Agents act fast and opaquely; without a trail, a bad action is discovered by its consequences, days later, with no record of how it happened. Teams discover this during their first incident and then build logging under pressure. Building it first makes incidents boring.

Edge cases and pitfalls

• Argument payloads can be huge; log a truncated copy plus a hash of the full payload so you can verify later.
• Streaming tool results: log the final result, not every chunk, but note that it was streamed.
• Multi-agent sessions: the session id must follow the work across agents, or the trail fragments.
• The agent's own read access to logs is fine and useful; write access is what you must withhold.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_2BplsPyA8nZAYD4eDSF2EA