Log the evidence needed to distinguish who requested an action, what authority the executor used, which decision applied to which proposal, and what result was actually observed. An AI agent audit trail connects those records with their sources and limitations. A conversation history or session identifier alone does not establish that connection.
AI agent governance defines the authority and responsibilities involved. The audit trail makes that authority reviewable after a decision or action. Specify the information needed across the trail, rather than requiring every field on every event or assuming that each integration can supply it. Agent observability describes the telemetry available for understanding the workflow; an audit trail organizes evidence for a review question.
Start with the question the investigator needs to answer
Use the hypothetical example from the architecture guide: an employee requests viewer access for an on-call contractor to an incident-response workspace. The proposed workflow requires applicable workspace-owner approval. Suppose a dispatched request loses its response, and a later read shows the contractor as a member. These are illustrative conditions, not collected telemetry or a KonaSense integration.
The later read establishes an observed membership state. It does not identify which attempt produced that state, whether the approved role was the one sent, or whether another actor changed the membership. Those questions require records with a causal relationship to the operation, not merely nearby timestamps.
| Investigation question | Records needed in the hypothetical workflow | Limit of the conclusion |
|---|---|---|
| Who requested access, and for whom? | Initiating identity, task reference, resolved contractor account | A name in generated text is not a verified account or delegation |
| Did approval cover the attempted change? | Approval scope, proposal version, actual workspace, account, role, and executor | A shared session does not make different proposals equivalent |
| Which attempt reached the destination? | Executor dispatch and a destination record tied to that attempt | A timeout does not establish that dispatch or processing failed |
| Which attempt produced the membership change? | Destination evidence linking the change to a specific request and acting identity | A later state read alone cannot attribute the change |
| Can the available trail support the finding? | Source, collection and transformation history, access and verification evidence | Protected records can still be incomplete or describe an incorrect source observation |
The field groups below describe an evidence specification for answering those questions. They are not a product export schema.
Identify the actors and the work they belong to
Actor / user: record the initiating person or system reference and how that identity was established. The source might be authenticated request context or an approved task system. Distinguish a verified requester from a name supplied in a prompt. In the example, the employee asking for access and the contractor receiving it have different roles.
Agent identity: identify the agent or runtime instance involved, with an implementation or configuration reference where relevant. Obtain it from the execution environment, not solely from the agent's self-description. Separately identify the account or service identity used to execute the operation, including the relevant permission scope without copying its credential. The agent label is not the identity the destination necessarily authorizes.
Session ID: use the runtime's session reference to group related work, preserving its source or namespace. Associate it with task, proposal, decision, and attempt records as appropriate. A session can contain several actions, retries, or concurrent operations; its identifier cannot distinguish all of them. Resumed work also needs a way to identify which configuration and authorization conditions applied.
Preserve the proposal and the context actually evaluated
Model: when a model participates, record the identifier and version or deployment reference available from the invocation or runtime configuration. Preserve whether it is a reported alias or a resolved revision. If the precise version is unavailable, record that limitation. The model field helps investigate the proposal's origin; it does not establish the executor's authority or reproduce the outcome by itself.
Prompt or input reference: identify the task input and version used for the relevant step, preferably through a controlled reference when full content is unnecessary. The initiating system or runtime should establish the association. Define what the reference resolves to, who may resolve it, and what happens when the referenced content expires. An ID with no available or trustworthy referent cannot explain what the agent received.
Context: preserve the decision-relevant facts and their origins. For the workspace example, that includes the resolved contractor account, incident assignment, workspace, proposed role, and applicable approval. Associate facts with the version or observation time used in the evaluation. A later directory lookup may show current state rather than the facts the evaluator relied on.
Tool selected: record the tool identity supplied by the runtime and the server or implementation that resolves it. Include a version or configuration reference when a tool name can map to different behavior. The investigator needs to distinguish the interface proposed by the agent from the component that actually executed an operation.
Tool parameters when appropriate: preserve the material arguments of the proposed operation and, when observable, the arguments actually dispatched. Use selected fields or protected references where the parameters contain sensitive data. A change from viewer to administrator is material to the example's authorization; a generic “membership tool called” record cannot expose that difference. Record transformations without silently replacing the earlier proposal.
Record the policy decision and its applicable approval
Policy evaluated: identify the policy, rule set, and version actually used by the evaluator, together with the context reference. Take this from the evaluation path when available. A snapshot of the policy configured later cannot establish which version produced an earlier decision. If the version was not captured, preserve the gap rather than filling it with the current policy.
Decision: retain the evaluator's result and its relationship to the evaluated proposal. Keep a response constructed for the executor separate from an observation that the executor applied it. Denied and pending requests may have decision records without any attempted action. An Allow decision authorizes an attempt within its conditions; it does not report success at the destination.
Approval state: record whether approval was required, pending, rejected, granted, expired, or not applicable according to the mechanism in use. When approval is granted, associate its source, authorized reviewer, scope, and applicable proposal version. A claim in agent-generated text is not the approval record. If the workspace, role, account, or executor changes, the trail must let a reviewer assess whether the earlier approval still applied.
Risk signals: retain the observations or assessments that influenced a decision, with their source and interpretation. Distinguish an observed condition, such as an unresolved account, from a classifier's assessment or an agent's assertion. If a score is used, document its meaning and relevant version. A severity label does not prove malicious intent, and a later signal should not be presented as if it informed an earlier decision.
The runtime governance pillar explains how decision validity changes with context. The audit specification should preserve enough of that context to review validity without claiming that the record itself enforced it.
Distinguish an attempted action from an observed result
Action attempted: identify the particular dispatch or execution attempt, its actual target, acting identity, and relationship to the authorized proposal. The source must be a component positioned to observe that attempt. Use separate attempt references for retries while preserving their common operation or task relationship. Do not create an attempted-action event merely because the evaluator returned Allow.
Action result: preserve what the tool, executor, or destination actually reported, identifying the source and stage. Request acceptance, completed processing, and a later state observation are different evidence. Keep failure, partial success, and unknown outcomes when they apply. An error receiving a response may leave the destination result unknown rather than proving the action failed.
For the hypothetical membership change, a destination audit record that reliably associates the change with the specific dispatched request could support attribution to that attempt. Its usefulness depends on how the association was produced and verified. A repeated session ID, a matching role, or a later membership read is insufficient on its own. If that association is unavailable, the investigator can report the observed state while leaving the cause unresolved.
The controlled agent action field note compares deliberate local replay conditions in which unavailable caller confirmation accompanies different observed file states, with references to the collected records and their limits.
Keep event time separate from collection time
Timestamp: record when the source says the event occurred and, where available, when the collection system observed or received it. Identify the clock source, relevant uncertainty, and any conversion. Delayed collection can make an older event appear later in the receiving system; different clocks can disagree even when delivery is immediate.
OpenTelemetry's Logs Data Model explicitly separates Timestamp, measured at the source, from ObservedTimestamp, measured when the collection system observes the event. It also provides optional TraceId and SpanId fields for request correlation. These are general telemetry semantics, not a complete AI agent audit model or proof that an integration produces those fields. OpenTelemetry Logs Data Model.
Preserve causal relationships through identified requests, decisions, dispatches, and destination observations. Sorting events from different components by timestamp cannot repair an absent relationship. If a timestamp was generated during ingestion because the source time was unknown, do not present it as the execution time.
Describe the integrity protection actually applied
Evidence integrity metadata: identify the event source, collector and transformation versions, relevant access protections, and any integrity mechanism actually used. Record what was verified, by which verifier, and against which trusted reference. The evidence system should distinguish a supplied protection claim from a successful check.
A cryptographic hash can help detect a change in the bytes it covers when compared with a trusted digest. NIST's Secure Hash Standard describes this change-detection purpose. For an audit record, specify the algorithm, covered representation, and how the comparison value is protected. A digest stored beside editable content is not, by itself, independent assurance of that content's history. NIST FIPS 180-4.
A digital signature addresses a different question: NIST's Digital Signature Standard describes detecting unauthorized changes and authenticating the signatory. Record whose signing identity was verified and what data the signature covers. Even a valid signature does not establish that the signer observed the action correctly or emitted every required event. NIST FIPS 186-5.
If storage is described as immutable, document the retention and access configuration supporting that claim and the evidence that it was applied. Storage protection, a verified signature, and a matching digest establish different properties. None can recover an event that was never produced. These are requirements to assess, not claims about KonaSense storage or signing capabilities.
Minimize sensitive content across the trail
Choose the investigation purpose before deciding what content to retain. The workspace example needs the relevant account, role, task, and approval relationship; it does not automatically require every conversation or unrelated directory attribute. Where a bounded record can answer the question, avoid creating another full copy of sensitive input.
OWASP's logging guidance recommends excluding sensitive values such as tokens and passwords, and treating identifiers and other contextual data according to their sensitivity. It also calls for access controls and verification of the logging mechanism. Use those principles when specifying the trail and the systems that resolve its references. OWASP Logging Cheat Sheet.
A reference is not automatically harmless. It may identify a person, reveal an internal resource, or permit access to sensitive content. Apply authorization when resolving it, and keep routine operational access separate from access needed for a specific investigation. Removing content from the visible log does not protect an unrestricted linked store.
Define retention by purpose for records and their referenced content, including extracts created during investigations. Make expiration coherent: a retained record should disclose when supporting content is no longer available rather than silently resolving to a different version. No universal retention period fits every investigation or organization, and retaining all prompts indefinitely is not a substitute for a defined evidence requirement.
Make pipeline gaps visible to the investigator
Specify how the trail represents an event that was not emitted, not collected, lost, duplicated, delayed, transformed, or inaccessible to the reviewer. Those states are not interchangeable. The absence of a collected dispatch event might indicate no dispatch, but it might also indicate a gap in collection. Use observations about the producer and collection path to narrow that uncertainty.
Preserve source-event identity through forwarding and transformation where it is available. A duplicate delivery should not silently become a second action, and a normalized “success” should not replace a more limited source meaning such as request acceptance. If a mapping removes information needed for the investigation, record that loss and retain an appropriately controlled route to the source evidence when justified.
An inaccessible record is also an operational condition. Identify who can authorize access or confirm expiration, without weakening the evidence store's controls. The investigator should be able to state why a conclusion remains incomplete rather than interpreting every missing field as “not applicable.”
Validate the specification with synthetic questions and records
Use a controlled environment and synthetic identities to test whether the specified relationships answer the investigation questions. For the workspace example, plan a viewer proposal with applicable approval, an altered proposal, a retry after a lost response, and a later state read with no causal record. Also include a duplicated delivery and an expired input reference. These are proposed validation cases, not tests executed for this guide.
Ask a reviewer to distinguish what each case establishes and what remains unknown. Can they identify the exact approved proposal, separate concurrent attempts, distinguish collection time from event time, and recognize a result whose cause is unresolved? Record any missing field or relationship that prevented the answer, and revise the specification for that purpose. Do not fill the gap with a guessed value.
The coding agent rollout guide explains how to assign owners, run a bounded pilot, and hand evidence to operational teams. Use this audit model to define the records that those teams must be able to interpret.
Assess KonaSense records by their source and meaning
In the reviewed Claude Code PreToolUse path for Kona for Agents, the adapter can send a report containing the hook response it constructed. That is evidence about the adapter's response when the report is available. It is not an acknowledgment that the host applied the response or that the destination completed an action.
Evaluate each available record against its source, transformation, and collection path before using it in an audit conclusion. Neither an adapter report nor received OTLP activity, by itself, establishes a complete or immutable trail. Confirm the fields and relationships present in the installed integration, and keep unavailable decision, execution, and outcome evidence explicit.