← Back to Blog

AI workflow documentation

AI Agent Decision Log Template: Actions, Approvals and Results

By Claudia · · 6 min read

Keep evidence of what an agent was allowed to do, what it attempted and what happened. Includes a downloadable JSON example and a review checklist.

An AI agent decision log is a record of the actions proposed, authorized, attempted and verified during a run. Link those events to the procedure version and the person or system that requested the work. A transcript saying “done” is not enough to establish that the intended change happened.

Our existing AI workflow documentation guide covers documenting the procedure. This article focuses on the evidence produced when that procedure is used. The template is a suggested operational design, not a certification or a universal legal requirement.

Keep the procedure, permission and result connected

For a useful review, you need to answer three different questions:

  • What was the agent instructed to do? Preserve the approved SOP or skill version and the configuration used for that run.
  • What was it allowed to do? Record the authorization decision and, when required, the approval associated with the specific action.
  • What happened? Record the tool attempt, its response and the subsequent check of the intended result.

OWASP's AI Agent Security Cheat Sheet recommends monitoring decisions, tool activity and outcomes, including authorization and approval metadata for higher-risk actions. That supports the basic structure here; the field names and invoice example below are our suggested implementation.

Capture events in the application or tool gateway that enforces the action. An agent's own description can provide context, but should not be the sole evidence that permission was granted or that a tool executed successfully.

A practical decision-log field set

Fields to adapt to your agent's actual workflow
Field groupSuggested contentsReview question
IdentityRun ID, unique event ID, timestamp, environment and agent ID.Which run and event are we looking at?
InstructionsProcedure version, preserved artifact reference, model configuration reference and policy version.Which instructions and controls applied?
RequestRequester reference and a link to the authorized task.What work was requested?
ActionTool name, target reference and a limited action summary.What change or lookup was proposed?
AuthorizationAllow or deny decision, reason code and approval reference if needed.Was this exact action permitted?
ExecutionWhether a call was attempted, response status and result reference.Did a tool run, fail or time out?
VerificationObserved outcome and evidence reference, or an explicit unknown state.Did the intended result actually occur?
Follow-upException status and the role responsible for resolving it.Who owns the unresolved part?

Use one run ID to connect events and a different event ID for each record. Record retries as additional attempts, rather than overwriting the first failure. Preserve the approved instruction artifact: a file called latest.md is not a stable reference if its contents change.

Example: an invoice draft blocked before execution

Imagine an assistant that may create invoice drafts for approved vendors, but may never send a payment. In this fictional sandbox run, it selects a vendor that has not been approved. The authorization layer rejects the draft creation, so no tool call is attempted.

Download the decision-log example (.json)

{
  "example_only": true,
  "schema_version": "1.0",
  "run_id": "example-run-001",
  "event_id": "example-event-003",
  "event_type": "action_blocked",
  "occurred_at": "2026-11-16T15:04:05Z",
  "environment": "sandbox",
  "agent_id": "invoice-draft-assistant",
  "model_config_ref": "example-model-config-v1",
  "procedure": {
    "id": "invoice-draft",
    "version": "1.2",
    "artifact_ref": "example-approved-skill-v1.2"
  },
  "policy_version": "draft-only-v3",
  "request_ref": "example-ticket-1042",
  "requester_ref": "example-user-17",
  "tool": "accounting.create_invoice_draft",
  "target_ref": "example-vendor-23",
  "action_summary": "Create a draft invoice",
  "authorization": {
    "decision": "deny",
    "reason_code": "VENDOR_NOT_APPROVED",
    "approval_ref": null
  },
  "execution": {
    "attempted": false,
    "status": "not_executed",
    "tool_result_ref": null
  },
  "verification": {
    "status": "not_applicable",
    "evidence_ref": null
  },
  "follow_up": {
    "status": "needs_review",
    "owner_role": "accounts-payable-reviewer"
  }
}

This record represents a blocked action, not a failed payment and not a successfully created draft. The separate execution and verification fields make that distinction explicit. The reviewer can use the request reference to resolve the vendor question without putting invoice contents into the log.

For an allowed action, write an authorization event before execution, an execution event after the call, and a verification event after checking the target system. If the call times out, mark the outcome unknown until it can be reconciled. Retrying immediately can duplicate work when the remote system completed an action but its response was lost.

Record evidence without copying secrets into the log

Start with an allowlist of fields your reviewer needs. Store references to protected source records when copying the full content is unnecessary. Do not log passwords, access tokens or API keys; avoid copying personal and financial information into a general-purpose event stream. OWASP's logging guidance describes data that should be excluded or protected.

For the invoice example, the target reference identifies the vendor record without reproducing its banking details. A reason code such as VENDOR_NOT_APPROVED explains the decision more consistently than an unrestricted paragraph copied from a model response.

Record observable facts and a concise operational explanation. Do not design the system around extracting hidden model reasoning. A statement such as “approval missing for action X” is useful when it comes from an enforced check; an explanation generated after the event is not proof of that check.

Restrict who can read and change logs, and set a retention policy for the system and data involved. An editable spreadsheet may help prototype the fields, but should not be presented as tamper-evident evidence. There is no single retention period that this template can prescribe for every organization.

Test the log with failures as well as successes

Before relying on the record, exercise a small set of sandbox cases and have someone reconstruct each run using only the saved evidence:

  1. Allowed action: the request, permission, execution and verified result can all be found.
  2. Blocked action: the reason is recorded and no execution is falsely claimed.
  3. Missing approval: execution stops until the required authorization is present.
  4. Timeout: the record distinguishes an unknown outcome from a definite failure.
  5. Retry: attempts remain linked without concealing the original event.
  6. Changed procedure: an old run still points to its original approved instructions.
  7. Logging failure: an unavailable log destination is detected and handled according to the action's risk.

For the invoice assistant, define in advance that a missing mandatory authorization record prevents a write. A read-only helper may need a different failure policy. The important part is to test and document the choice instead of discovering it during an incident.

Where Claudia fits in this workflow

Use Claudia to capture the human procedure and export the reviewed SKILL.md with its supporting screenshots. Preserve that version in your documentation or source repository, then reference it from the agent's run record.

The recording documents the intended workflow. It does not supply an automatic audit trail of a separate AI agent's later tool calls. Your runtime, application or monitoring system must produce those events and enforce permissions. Review the skill before use with our SKILL.md audit checklist.

Start with one bounded task and one reviewer. If that reviewer can identify the requested change, the governing procedure, the authorization and the verified outcome, you have a useful foundation for expanding the logging design.