What to Log When an AI Agent Makes a Decision: Fields and Format

The table below is the working schema. Treat the first six rows as mandatory for any decision that crosses a boundary into a side effect.

Three of these deserve emphasis.

The prompt_hash is the field teams skip and then regret. Hashing the full template plus resolved variables means a silent template edit changes the hash, so you can prove which instructions were in force at decision time even if someone later edited the prompt in production. Hashing per-request also lets you group identical prompts to measure cost and latency without storing the text.

The reviewer field must distinguish a named human from an automated gate. This matters because oversight requirements are graded, not binary. For compliance purposes, human authorization (no AI action without explicit approval, logged before execution) is the strongest form, human review of outputs is intermediate, and population-level monitoring is the weakest form that still counts as oversight (human in the loop and AI compliance). A log that says "reviewer": "policy-engine" for a decision that legally required human authorization is evidence of a gap, not a defense.

The reason field should contain policy reason codes and a short operator-facing sentence, not a fabricated summary of what the model was thinking. Design your policy engine to emit codes like refund_below_limit or data_sensitivity_high so the reason is safe to show reviewers, and add a free-text reason_note for what the human decided and why. Human-in-the-loop research is clear that the value arrives when feedback is captured, governed, and reused, rather than left inside a disconnected review screen (HITL at Databricks).

Write each record as a single JSON object on one line. JSON lines append cleanly, stream well, and are trivially ingestible by columnar stores and log pipelines. Several emerging proposals converge on this shape. An IETF draft for an agent audit trail specifies a JSON record structure linked by tamper-evident SHA-256 hash chaining, transport-agnostic and exportable to JSONL, Syslog, and CSV (agent audit trail draft). A separate community specification for agent decision records uses structured JSON serialization with required frontmatter validation (Agent Decision Records).

Here is a complete record for a support agent that changes a renewal status:

{
  "decision_id": "01JQ8Z4T7K9M2",
  "correlation_id": "run_7f3a91",
  "timestamp": "2026-03-04T14:22:07.418Z",
  "tenant_id": "acme-eu",
  "actor": {"type": "human", "id": "user_1192", "auth": "session"},
  "task": {"type": "renewal_status_change", "request_ref": "ticket:88412"},
  "inputs": [
    {"kind": "user_message", "sha256": "9c1f...", "ref": "ticket:88412/msg:3"},
    {"kind": "retrieval", "sha256": "4ab0...", "ref": "kb:renewal-policy#v4"},
    {"kind": "tool_result", "tool": "get_account", "sha256": "77de...", "ref": "crm:acct:4411@v27"}
  ],
  "model": {
    "provider": "example",
    "name": "frontier-small",
    "version": "snapshot-2026-02-11",
    "temperature": 0.0,
    "max_tokens": 800
  },
  "prompt": {
    "template_id": "renewal_agent",
    "prompt_hash": "b3e1c8...",
    "token_count": 1840
  },
  "output": {
    "raw": "{\"action\":\"update_renewal\",\"status\":\"paused\"}",
    "ref": "blob:decisions/01JQ8Z4T7K9M2/output.txt"
  },
  "policy": {"name": "renewal-policy", "version": "v4", "verdict": "allow", "reasons": ["account_owner_verified", "below_risk_threshold"]},
  "reviewer": {"type": "automated_rule", "id": "policy-engine", "version": "v4"},
  "reason": "Account owner requested pause; amount below threshold; no exceptions matched.",
  "action": {"tool": "billing.updateRenewal", "target_ref": "crm:acct:4411", "idempotency_key": "01JQ8Z4T7K9M2-act"},
  "outcome": {"state": "verified", "result_ref": "billing-event:ee91c2", "version_after": 28}
}

Two format decisions are worth copying. First, store references and hashes for large or sensitive inputs and outputs rather than copying content; the pointer respects the retention rules of the system that owns the data. Second, split the record into a planned phase and an outcome phase. Write the decision before the side effect so a timeout or crash is itself recorded, then append the verified result. That pattern turns ambiguity into an explicit unknown state instead of silently implying success, and the idempotency key from the planned record prevents duplicate retries (decision logs, evidence without chain of thought).

Hash chaining is optional at small scale and worth the effort at audit scale. Including the previous record's digest in each new record makes tampering detectable, which is exactly what general log management guidance recommends: centralized collection plus integrity protection such as tamper-evident or write-once storage for records used in investigations (policy decision log format and retention).

Log at decision boundaries, not on every model turn. Good boundaries are selecting a workflow or external tool, classifying a request into a risk tier, changing a record or moving money, denying an action because policy blocked it, escalating to a human, and declaring a long-running task complete (decision boundaries). Retrieval chunks, retries, and draft sentences belong in traces, linked by a stable ID when they matter.

A minimal Python wrapper that emits one JSON line per decision:

import hashlib, json, uuid
from datetime import datetime, timezone

def emit(store, record):
    store.append(json.dumps(record, separators=(",", ":")) + "\n")

def sha(text: str) -> str:
    return hashlib.sha256(text.encode("utf-8")).hexdigest()

def log_decision(store, run_id, prompt_template, variables, model, output, verdict, reviewer):
    rendered = prompt_template.format(**variables)
    record = {
        "decision_id": uuid.uuid4().hex,
        "correlation_id": run_id,
        "timestamp": datetime.now(timezone.utc).isoformat(timespec="milliseconds"),
        "model": model,
        "prompt": {"template_id": model["prompt_id"], "prompt_hash": sha(rendered)},
        "output": {"raw": output},
        "policy": verdict,
        "reviewer": reviewer,
        "reason": verdict["reasons"],
    }
    emit(store, record)
    return record["decision_id"]

store.append should target a file or object store opened in append-only mode, or a queue that writes once. Never update a record in place; corrections are new records that reference the original decision_id.

For team-level operations, a few habits keep the log usable. Set a retention baseline from the strictest regime you operate under: PCI DSS requires at least 12 months of audit log retention with 3 months immediately available; HIPAA requires audit controls without a fixed period; GDPR Article 30 requires records of processing where personal data is involved. Enterprises under multiple regimes should retain for the longest applicable minimum rather than picking one number (retention baselines). Also flag the review tier in each record so an auditor can filter for decisions that required human authorization, which is the distinction regulators care about most (oversight levels).

If your agents run across several providers, Quanta Inference gives you one OpenAI-compatible endpoint for text, image, video, audio, and embedding models, which keeps model metadata and request IDs consistent across the log (Quanta Inference).

Not every agent step deserves the same treatment. Use this routing rule, and encode it in the agent harness so it is not left to developer memory.

The middle row is where policy documents and logs meet. Workplace AI policies consistently require human review of AI output before reliance, disclosure when AI was used to perform work, and reporting paths for concerns about outputs (LexisNexis policy template). A decision log is what makes those clauses auditable. If the policy says a human verified the output, the log should carry a reviewer identity and a timestamp, and the reviewer should have had the information, authority, and time to actually influence the outcome (meaningful oversight). That last condition is why the review screen must show safe evidence links, policy reasons, and the expected change on one page.

Log enforcement also needs to be technical. Many policies prohibit inputting confidential data into unapproved tools and require approval before integrating AI with internal systems (sample acceptable use policy). A decision log that records which tool and data reference each agent touched turns those prohibitions into monitorable events. Pair it with a disclosure requirement: Taylor & Francis, for example, asks authors to state the full name of the tool used, how it was used, and the reason (publishing AI policy). Your model and reason fields store exactly those three facts.

A support agent handles 40,000 decisions a day. Assume 20 percent are consequential (side effects, denials, escalations) and get full records at roughly 2 KB of JSON each, and 80 percent get light events at roughly 400 bytes.

That is under 11 GB a year before compression; JSON lines of this shape typically compress well. At those volumes, storing a pre-action record and an outcome append costs almost nothing relative to the model calls themselves, so the real constraint is governance, not storage. The expensive mistake is the reverse: storing full prompts and outputs for every turn, which multiplies volume by an order of magnitude and drags your log into the scope of every privacy review. Sampling prompts at 1 to 5 percent while keeping hashes and token counts for all calls keeps cost predictable (sampling guidance).

The strongest argument for the reviewer and reason fields is that oversight claims get tested after the fact. When a workflow claims human-in-the-loop compliance, that claim should mean a named person authorized each action in the execution log, not that a human was available if they chose to look (HITL versus HOTL). Logs that record a delegation chain, in which every agent action maps to a human authorizer in a tamper-evident record, are what distinguish real oversight from a label (delegation chain).

Two governance habits close the loop. First, review a sample of records weekly against the reason codes, looking for decisions where the verdict was allow but the outcome was unknown or rejected downstream. That pattern usually means the policy engine lacks a check, and it is invisible in dashboards that only count successes. Second, feed reviewer corrections back into the policy and prompt as versioned changes, so the policy.version and prompt_hash in future records show the fix took effect.

If your team would rather not build the review queue and record store from scratch, an AI expert engagement can produce the schema, the retention policy, and the reviewer interface as a finished deliverable (Quanta Experts). Either way, start with the six mandatory fields, one JSON line per decision, and the boundary rule. Everything else is an extension.