Audit logs for AI agent tool calls: what to record, and what to leave out

What to record for every tool call an agent makes, what to leave out, and how to tie each call to the approval that allowed it, with a logging wrapper and a hash chain in TypeScript.

· 9 min read

An audit log for an AI agent records every tool call as an event: which credential made it, for whom, with which arguments, what came back, and which approval allowed it if the call needed one. The model’s reasoning is useful for debugging, but it is not the audit log. The calls are what changed something.

A log is good when it answers questions in minutes: every refund one agent made last Tuesday, who allowed the one that went wrong, and whether anything ran that should have asked first. This page lists the fields that make those answers possible, the ones to leave out, and the code to write them.

What to record for every call

Call and run ids
A unique id per call, and the id of the run or session it belongs to, so one task can be followed from start to end.
The credential
The id of the key or token the agent used. The name an agent gives itself proves nothing, since the model writes it.
On whose behalf
The person or customer whose task this is, by id. An agent acting for many users needs this or every call looks the same.
The tool
Its full name, with the server or service it lives on, such as billing/refund or mcp__shop__orders_refund.
Arguments
A copy with secrets and personal data replaced, plus a SHA-256 hash of the full arguments, so a later dispute can prove which exact call this was.
The approval
For a call that needs a person's yes: the approval request's id. For one that did not: that it was not gated, so a missing approval is visible.
The result
ok, refused or error, a hash or a short summary of what came back, and how long it took.
Time and order
A UTC timestamp, and a sequence number per writer, since clocks on two machines disagree.

One finished call, as the event inside one line of the log (the writer further down wraps it with the hashes):

{
  "event": "tool.finished",
  "at": "2026-11-20T09:14:03.512Z",
  "call": "c7f1d0e2-5b0a-4e8f-9d43-6a1f0f2b9c11",
  "run": "run_8812",
  "agent_key_id": "key_support_prod",
  "on_behalf_of": "user_4471",
  "tool": "billing/refund",
  "args": { "order": "A-1009", "amount": "40.00", "currency": "EUR", "card": "[redacted]" },
  "args_sha256": "9b0c…e41a",
  "gated": true,
  "approval": "0193f6a2-…",
  "status": "ok",
  "result_sha256": "51d7…08cc",
  "ms": 842,
  "outcome_reported": true,
  "seq": 7
}

What to leave out

An audit log is read by more people, and kept for longer, than almost any other data you hold. What goes into it should be safe to show an auditor:

  • Secrets. API keys, tokens, passwords andAuthorization headers, including ones a tool echoes back in an error message. Mark the fields that hold them per tool and replace them before anything is written.
  • Full bodies with personal data. An email’s text or a customer’s record does not need to sit in the log. Keep an id and a hash, and mark those fields for redaction too; the original stays in the system it belongs to.
  • Whole model transcripts. Keep them elsewhere for debugging, for a shorter time, if at all. They hold everything the user typed and everything every tool returned.

A hash of the arguments proves which call this was without keeping the arguments. Hash a canonical form, with keys sorted (RFC 8785 describes one), or the same arguments in a different order give a different hash.

One wrapper around every tool

Logging belongs in the one function every tool call goes through, not in each tool, and not in the prompt. The wrapper below writes an event when a call starts and one when it ends, whatever happened. For tools marked as gated, it asks a person first through VariantGate and records the approval’s id with the call:

import { randomUUID } from "node:crypto";
import { ApprovalClient } from "@variantgate/agent";
import { ChangedApprovalError, NotApprovedError } from "@variantgate/agent/errors";
import type { Decision } from "@variantgate/agent/types";
import { audit, sha256 } from "./audit-log";
// Run, Tool, redact (replaces secret and personal fields), canonical (RFC 8785 JSON)
// and alert are yours.

const approvals = new ApprovalClient({
  agent: "support-bot",
  apiUrl: "https://api.variantgate.com",
  key: process.env.VG_KEY!,
});
const kindOf = (error: unknown) => (error instanceof Error ? error.name : typeof error);

export async function callTool(run: Run, tool: Tool, args: Record<string, unknown>) {
  const call = { call: randomUUID(), run: run.id, agent_key_id: run.keyId,
    on_behalf_of: run.userId, tool: `${tool.server}/${tool.name}`,
    args: redact(args, tool.redactFields), args_sha256: sha256(canonical(args)),
    gated: tool.gated };
  // Writing the log must never change what the caller sees.
  const log = (fields: Record<string, unknown>, result?: unknown) => {
    try {
      const result_sha256 = result === undefined ? undefined : sha256(canonical(result));
      audit({ ...call, ...fields, result_sha256 });
    } catch (error) {
      alert("audit log write failed", call.call, error);
    }
  };
  const finished = (fields: Record<string, unknown>, result?: unknown) =>
    log({ event: "tool.finished", ...fields }, result);
  log({ event: "tool.started" });

  let approval: Decision | undefined;
  if (tool.gated) {
    let asked: Decision | undefined;
    try {
      // Described from the redacted copy: the request is kept in a sealed record.
      asked = await approvals.ask({ action: tool.action, summary: tool.describe(call.args),
        amount: tool.amountOf?.(args), currency: tool.currency, details: call.args }, 30);
      approval = await approvals.waitForDecision(asked);
    } catch (error) {
      // Asking failed, so nobody said yes. Withdraw it, so nobody approves it later.
      if (asked) await approvals.withdraw(asked.id).catch(() => {});
      finished({ status: "approval_error", approval: asked?.id, error: kindOf(error) });
      throw error;
    }
    if (!approval.allowed) {
      // Denied, expired, withdrawn, or approved while paused.
      finished({ status: "not_approved", approval: approval.id, decision: approval.status });
      throw new NotApprovedError(approval);
    }
    if (approval.changed) {
      // Approved only with changes: this code can only do what it asked, so it does nothing.
      await approvals.reportOutcome(approval.id, "failed", "not done: the approval changed the request")
        .catch(() => {});
      finished({ status: "not_approved", approval: approval.id, decision: "changed" });
      throw new ChangedApprovalError(approval);
    }
  }

  const started = Date.now();
  let result: unknown;
  try {
    result = await tool.run(args);
  } catch (error) {
    // The error's class only, in the outcome and the log: tools echo tokens in messages.
    if (approval) await approvals.reportOutcome(approval.id, "failed", kindOf(error)).catch(() => {});
    finished({ status: "error", approval: approval?.id, error: kindOf(error) });
    throw error;
  }

  // The call ran. Nothing below throws, so the agent has no reason to retry it.
  const reported = approval
    ? await approvals.reportOutcome(approval.id, "succeeded").then(() => true, () => false)
    : undefined;
  finished({ status: "ok", approval: approval?.id, ms: Date.now() - started,
    outcome_reported: reported }, result);
  return result;
}
  • The started event comes first. A call that crashes the process half way still leaves a trace, and a started event without a finished one is worth a look.
  • A no is logged too. A denied, expired or withdrawn approval, or one approved only with changes, is written as not_approved with the approval’s id and its status, so the log shows the agent did not act, and why.
  • A call that ran is never logged as failed. If the tool ran but reporting its outcome to VariantGate failed, or the log line itself could not be written, the call still returns its result and nothing invites a retry; the first case is logged as ok with outcome_reported: false. An error is logged, and reported, by its class only, since tools echo tokens and arguments in their messages and the approval record is sealed.
  • Which tools are gated is decided in code, and a tool that moves money passes its amount, so an owner’s rule such as “refunds up to €50 run on their own” can answer it. If you are not sure which tools should ask, paste your tool list into the tool risk checker.

Make changes visible

A log the agent’s own process can rewrite is weak evidence. Two things make it stronger. First, ship each line off the machine as soon as it is written, to storage the agent’s credentials cannot delete from, such as a log service or a bucket with write-once retention. Second, chain the lines: each one carries a hash of the one before it.

// audit-log.ts
import { createHash } from "node:crypto";
import { appendFileSync, mkdirSync } from "node:fs";

export const sha256 = (text: string) => createHash("sha256").update(text).digest("hex");

// One file, and one chain, per process: a restart or a second worker starts its own.
// Each line holds the event, the previous hash and its own, so a changed, removed
// or reordered line breaks every hash after it.
mkdirSync("audit", { recursive: true });
const LOG_PATH = `audit/${new Date().toISOString().replaceAll(":", "-")}-${process.pid}.jsonl`;
let prev = "0".repeat(64);
let seq = 0;

export function audit(event: Record<string, unknown>) {
  const payload = JSON.stringify({ ...event, at: new Date().toISOString(), seq });
  const hash = sha256(prev + payload);
  appendFileSync(LOG_PATH, JSON.stringify({ seq, payload, prev_hash: prev, hash }) + "\n");
  prev = hash;
  seq += 1;
}

Changing, removing or reordering a line now breaks every hash after it. Note the latest hash somewhere else from time to time, such as a ticket or a separate system. If the chain still checks out later and that hash is still in it, nothing before it changed. This is the same scheme VariantGate uses for its sealed record, so the short check script in the record docs verifies each of these files unchanged. Each process writes its own file, so a restart or a second worker starts a new chain instead of breaking the old one.

The questions it must answer

Test a log by asking it the questions an incident or an audit will ask. With one JSON event per line, jq is enough:

# Gated calls that ran with no approval behind them. There must be none.
jq -c '.payload | fromjson
  | select(.event == "tool.finished" and .gated and .status == "ok" and .approval == null)' \
  audit/*.jsonl

# Every refund one agent key made on one day, with the approval for each.
jq -r '.payload | fromjson
  | select(.event == "tool.finished" and .tool == "billing/refund")
  | select(.agent_key_id == "key_support_prod" and (.at | startswith("2026-11-20")))
  | [.at, .status, .args.order, .args.amount, .approval] | @tsv' audit/*.jsonl

The first query checks the wrapper itself: its answer must be empty, and you can run it every night. It cannot see a call that never went through the wrapper, such as a script that calls the payment API directly. To show that nothing got around the check, compare the log with a second source, such as the payment provider’s list of refunds, the way an auditor would; how auditors test completeness covers that.

Two records, one question each

The tool-call log answers “what ran?”. It belongs to you, lives next to the agent and covers every call. The approval record answers “who allowed it?”: who asked, the exact words the person saw, who decided, why, and when. It belongs to a system the agent can only add questions to.

The approval id joins them. Every gated call in the log names one, and every approval in the record says whether the agent reported the action as done or failed. Together they show a call that ran without asking, and an approval that was never used. What the approval record should hold is covered in what an audit trail for AI agents should record; what an auditor will ask for is in evidence for AI agent access.

How long to keep it

As long as the longest reason you have. A SOC 2 Type 2 report covers an observation period, often six to twelve months, and the auditor samples from all of it. The EU AI Act asks deployers of high-risk systems to keep the system’s automatic logs for at least six months; Article 12 and its retention rules are covered separately. Data protection law pushes the other way, which is one more reason to keep personal data out of the log in the first place.

Sources

  1. RFC 8785: JSON Canonicalization Scheme (JCS)
  2. OWASP Logging Cheat Sheet: data to exclude from logs
  3. jq manual