execution evidence
Build an AI agent tool-call audit trail around the action lifecycle
A useful tool-call audit trail connects the proposed action to policy, approval, dispatch, and outcome records. It should help an operator reconstruct what the system knew, decided, and reported while making the limits of that evidence easy to see.
- For
- Developers, platform operators, and security reviewers designing evidence for governed AI tool execution
- Reviewed
- Jul 14, 2026
- Length
- 1,245 words
Follow the action beyond the conversation
A chat transcript can explain what a user asked and how an agent responded. It cannot establish on its own which structured tool arguments reached an executor, which policy evaluated them, who reviewed them, or what the downstream system reported. Make the proposed action and its lifecycle the unit of investigation. Keep conversational context only when it is relevant and appropriate to store.
Start with a stable action identifier and connect each later record to it. An investigator should be able to answer a practical sequence of questions without hand-matching unrelated logs: What was proposed? Why did policy allow, deny, or pause it? What did the reviewer decide? Which authority reached the executor? What outcome was reported?
The records worth correlating
- The normalized action request, including the tool name, policy-relevant arguments, sourced identity and adapter context, and request hash.
- The policy decision, rule and policy identity, reason, and whether the result was allow, deny, or require approval.
- The approval record, reviewer eligibility, expiry, and the identity of the payload actually approved.
- The original and approved payload identities when an authorized reviewer changes supported input.
- The execution receipt or grant, attempt identity, executor identity, and transition into dispatch.
- The reported terminal result, including succeeded, failed, timed out, cancelled, or unknown.
Correlation is more useful than log volume
Dumping every prompt, response, object, and stack trace into one store creates volume without necessarily creating useful evidence. A smaller set of typed records with stable relationships is easier to investigate. From an approval, an operator should be able to reach the proposal and policy result; from the execution authorization, the corresponding attempt and reported outcome.
Keep identities separate. The person requesting work, the asserted agent label, the authenticated adapter or service account, the reviewer, and the executor can have different responsibilities. When an identity cannot be verified, preserve its provenance and label it as asserted. A single actor field hides exactly the distinctions an incident review is likely to need.
Reconstruct one action in order
- Find the canonical request and confirm the tool, input identity, tenant, requester, adapter, and submission time.
- Read the decision record and identify the policy version, matched rule, outcome, and reason codes that applied to the request.
- If review was required, verify reviewer eligibility, the decision time, expiry, and whether the approved input differs from the original proposal.
- Confirm that execution authority is bound to the same request, decision, policy, approval, attempt, and executor identities.
- Inspect the attempt state and reported outcome without treating a timeout or unknown result as proof that the provider did nothing.
- Compare the chain against a trusted head when local chain verification is relevant, then investigate gaps or changed records rather than assuming the chain proves the underlying event was truthful.
Treat the audit store as sensitive application data
Tool arguments and results can contain customer text, recipients, internal identifiers, or secrets. Record enough to support policy, review, and incident reconstruction, then make a deliberate choice about the rest. Decide which fields need full values, which can use stable hashes or references, who can read exports, and how long each record should remain.
ActionProxy's current minimization, retention, and export-redaction controls are incomplete, and records can retain full action payloads. Protect the underlying JSONL, SQLite, Postgres, volumes, exports, and backups accordingly. Redacting a review screen changes its presentation; it does not remove the underlying value from storage.
Example: investigate an approved email
Suppose a customer reports receiving the wrong attachment. The useful trail starts with the proposed send operation, recipient and attachment reference, and policy decision. It connects the proposed payload identity to the payload identity that was approved, records whether an authorized edit occurred, then follows the bound authority into dispatch and the email runner's reported outcome. A transcript saying “send the updated file” does not supply those links.
Payload identities do not prove the exact card or redacted field values that appeared on a reviewer's screen. ActionProxy's current review hash does not preserve that rendered presentation. If that level of evidence matters, the review-channel integration must record a separate, access-controlled snapshot or equivalent rendering evidence. The trade-off is real: a complete message, attachment, or review snapshot can help an investigation while making the evidence store more sensitive. The AI agent email approval guide covers the review fields for this workflow, while the exact tool-call binding guide follows the approved payload into dispatch.
Common questions
Questions developers ask
Can the audit trail prove exactly what appeared on the review screen?
Not from the current review hash alone. ActionProxy preserves proposed and approved payload identities and the approval binding, but it does not retain a byte-for-byte snapshot of the rendered, possibly redacted review card. Workflows that need that evidence should capture it separately in the review-channel integration and protect it as sensitive data.
Does ActionProxy provide an immutable audit log?
No. It provides a locally verifiable SHA-256 previous-hash chain. The chain is neither keyed nor independently anchored, and a storage administrator can rewrite or truncate the sequence and recompute it. Cross-process append ordering is not claimed.
Does the trail prove that the provider performed the effect?
It records the outcome reported by the executor or runner. A timeout, disconnect, or unknown result cannot establish whether the provider performed the effect, so high-consequence operations may need provider lookup and reconciliation through the runner/operator integration.
How long does ActionProxy retain audit records?
The Community implementation does not provide a complete retention and deletion policy. Operators must choose retention periods, restrict access to the underlying files or database, and cover exports and backups in the same data-handling plan.
