What to Log When an Agent Makes a Decision

Three months after an agent issued a $4,000 refund, finance asks why. The trace is still there. It has the model, the token count, eleven tool spans, and a success response from the payments API. It does not say which policy the agent applied, which order history it looked at, or whose permission it spent the money under. The question was simple. The log can’t answer it.

AI agent decision logging fills that gap. It is a separate record from the trace: one row per consequential action, written so that a person who was not there can reconstruct what the agent was asked, what it relied on, what it did, under what authority, and what came of it. Observability stops at the trace because a trace describes process. A decision record describes a choice, and choices are what people get asked about later.

Who Reads It

The record is shaped by its reader. A trace is read by an engineer debugging a run this week. A decision record is read by someone else, months later, with a narrower question.

Finance wants to know why money moved. Support wants to know why a customer’s account changed. Security wants to know whether the agent acted inside its permissions. Legal wants to know whether a rule was followed and which version of the rule it was. An engineer evaluating a new model wants a set of past decisions to replay.

None of these readers wants a span tree. They want a sentence with five blanks filled in, and they want to find it by searching for the thing that changed: the order, the account, the ticket.

Five Fields

Every consequential action gets one record with five parts.

The request. Who or what asked, in their words, with a stable identifier. A user message, a scheduled job, an upstream event. If the agent acted on its own initiative inside a longer task, record the task that granted the initiative.

The evidence. What the agent consulted and relied on. Document IDs and versions, the rows it read, the policy text it cited. Record references with versions, not the prompt dump. “Refund policy v14, section 3” can be checked. Forty kilobytes of context cannot be read by anyone.

The action. The exact call that changed the world: tool name, arguments, target record. This is the part teams already log, usually twice.

The authority. The identity it acted as and the permission that allowed it. A user’s delegated token, a service role, an approval from a named person, a spending limit it was under. If a human approved, record who and when. If nobody approved because the action was under a threshold, record the threshold.

The outcome. What the system looked like afterward. The refund ID and amount from the payments service, read back. Later, the downstream signal if one arrives: the customer disputed it, the ticket reopened, the reconciliation matched.

Trace Versus Record

Retention is where the two split hardest. Traces are high volume and get sampled and expired on an observability budget. Decision records are low volume and must survive as long as a refund can be disputed or a contract audited. They belong in a durable store with the business data, keyed by the business object, not in the tracing backend with a 14-day retention.

Write It at the Boundary

The model should not write this record. A model asked to “log your reasoning” produces a plausible account of a decision it may not have made that way. Self-reported rationale is a summary, and summaries drift from what happened.

The tool boundary writes it. The service that executes issue_refund already knows the arguments, the caller’s identity, the permission check it ran, and the result. It can require the agent to pass the request ID and evidence references as parameters, reject the call if they are missing, and write the record in the same transaction as the refund. An action without a record cannot happen. A system prompt reminder to keep good notes can’t promise that.

This is the same argument as Rules Are Not Controls. An instruction to log changes the odds. A tool that refuses to act without the fields decides the matter. It also follows from putting production output in a tool call: once the consequential action has a typed interface, the record is a few more typed parameters.

The model’s rationale still has a place. Capture it as one field among the others, labeled as the agent’s stated reason. It is useful for spotting confusion. It is not evidence of why the system acted.

What Counts as a Decision

Not every tool call needs a record. Reads usually don’t. Drafts a human will review usually don’t, because the human’s approval is the decision and it gets the record.

The rule I’ve had success with: write a record wherever the agent changes something a person outside the run could later ask about. Money, permissions, customer-visible messages, records in a system of record, anything irreversible. When unsure, ask whether you’d want to answer for it in a meeting without the record.

Regulators are converging on the same shape. The EU AI Act’s record-keeping article requires high-risk systems to log events automatically so that risks can be identified and operation can be monitored after deployment.¹ The reasoning applies to anyone running agents against real systems, whatever their exposure to that law.

The Record Pays for Itself

The obvious return is the audit question answered in a minute instead of a week. The less obvious return is evaluation. A table of decisions, each with its request, evidence, action, and later outcome, is a labeled dataset. The decisions that were reversed, disputed, or corrected are the cases to replay against the next model or prompt before it ships. That is the loop We Automate What We Can Verify depends on, and the decision log is where its raw material comes from.

Start with the one action that would hurt most if it went wrong. Give its tool the five fields, write the record in the same transaction, and keep it as long as the action can be questioned. Then do the next one.

Footnotes

1. Regulation (EU) 2024/1689, Article 12: Record-Keeping. ↩