What should an audit trail for AI-agent code execution contain?

An AI agent can start an isolated environment, run commands, call an API, and create an artifact in one run. A shell transcript cannot show who delegated authority, which policy allowed the action, or whether credentials and storage were removed.

An AI-agent code execution audit trail should connect identity, agent and policy versions, code, environment, approvals, actions, effects, artifacts, resource use, and termination. It should reconstruct the run without turning logs into a store of code, prompts, credentials, or sensitive output.

This article explains what to record and exclude, how to connect agent, runtime, and platform logs, and how Northflank can support the audit trail.

An AI-agent code execution audit trail should show who initiated a run, why it was allowed, what executed, what it affected, and how it ended.

• Create an application-controlled correlation identifier, such as run_id, and map it to the native resource and event identifiers produced by the agent orchestrator, policy engine, sandbox, credentials, commands, artifacts, and platform.
• Record the human or service initiator, agent identity, delegated role, policy version, decision, approval, and credential identifier. Never record the credential value.
• Identify code, images, dependencies, configuration, and outputs with immutable versions or digests where practical.
• Separate proposed actions, authorization decisions, executed actions, and observed effects. A model request is not proof that a command ran.
• Export evidence outside the execution environment, restrict access, monitor collection failures, and apply retention and redaction by data class.

A useful audit trail should help your team answer the following five questions. They are a practical test of coverage, not a fixed standard.

1. Who initiated and owned the run? Identify the user or service, tenant, agent, session, and workload owner.
2. Why was it allowed? Preserve the requested operation, applicable policy and version, decision, risk class, required approval, approver, and approval scope. Bind the approval to the target and sanitized arguments or an action digest.
3. What ran and where? Identify the source revision, command or tool, image digest, sandbox, isolation class, region, resources, filesystem, and network policy.
4. What did it reach or change? Record destination services, affected resources, file and configuration changes, API effects, artifacts, and denied attempts.
5. How did it end? Capture exit status, timeout or termination reason, state retention, and quarantine. Record credential revocation and deletion as requested, confirmed, failed, or unknown rather than treating a cleanup request as proof of completion.

Record events where authority, state, or impact changes. This is a practical taxonomy.

Link retries and asynchronous work using stable identifiers. For example, assign each event an event ID, associate child operations with their parent events, and use an idempotency key for operations that may be retried.

Each event should use a stable common envelope followed by fields relevant to that action. Exact field names and structures can vary between implementations.

For example, the common envelope can include an event ID, an application-defined run identifier, a trace ID, relevant parent and tool-call IDs, an event name, a schema version, and event and observed timestamps. Names such as run_id are implementation conventions, not universal standards. If you add sequence numbers, scope them to a named producer or stream and define when they reset. Use causal links to order work across systems.

Record the tenant and project, initiating user or service, agent ID and version, workload owner, active role, policy decision, policy version, approval ID, approver, and approval expiry. Reference the issued credential by ID and scope, never by secret value.

Identify the repository and commit, code digest, image digest, dependency-manifest digest, environment ID, isolation and compute classes, storage mounts, region, and network-policy version.

Record how an output was produced and bind it to a digest. A digest can confirm a candidate file or command matches the record, but cannot recover its content. Keep a protected reference when reconstruction is required.

Separate the action proposal, authorization result, start, and completion. Record the operation, tool, target, sanitized arguments or protected reference, working directory, timeout, attempt, exit code, and error class.

Capture effects separately from the command's return value: affected resources, network destinations, changed paths, before-and-after digests, infrastructure differences, artifact IDs, validation results, and durable state.

Finish with run status, termination reason, usage, retained-state decision, and quarantine or legal-hold references. Track credential revocation, sandbox deletion, retained-volume removal, and other cleanup actions through request and confirmation events. A command is not fully contained if its token, child process, external task, or storage survives unnoticed.

An end-to-end trail joins three evidence layers.

Keep the correlation identifier in application telemetry, propagate it where custom context is supported, and preserve native identifiers. Maintain an application-side mapping when a platform does not return your identifier. Process, filesystem, and network evidence requires suitable instrumentation and confirmed collection coverage; workload output alone does not provide it.

Northflank audit logs record event type, triggering identity, source, timestamp, parent events, affected resources, and configuration differences. Log sinks can export workload logs. Your agent application must still emit proposal, policy, approval, and tool-result events.

Excess content can turn an audit trail into a store of secrets, proprietary code, personal data, and malicious log content.

Avoid directly logging access tokens, passwords, connection strings, encryption keys, sensitive personal data, session identifiers, and application source code. Apply the same caution to prompts, tool arguments and results, command bodies, stdout, stderr, environment variables, and changed-file contents.

Prefer metadata and references by default:

• Store a command or file digest when investigators need identity but not content.
• Store an artifact ID and protected object-store reference instead of embedding a binary or patch.
• Record the secret ID, version, scope, injection time, and revocation time instead of its value.
• Attach a data classification, capture mode, redaction-policy version, and truncation indicator to content-bearing events.
• Place necessary sensitive evidence in a more restricted store with its own access trail and retention rule.

Do not require the model's private chain-of-thought. Audit permitted inputs, proposed actions, controls, tool calls, and effects. Those are the behaviors your team can authorize and investigate.

Protect the trail from the code and agent it records. Collect security-critical events from trusted components outside the untrusted workload where possible, export them promptly, and detect missing, delayed, malformed, or replayed records. Workload-generated events can still be suppressed or fabricated before collection, so label their source and trust level.

In practice, your design should:

• use append-oriented storage and integrity checks appropriate to the risk
• restrict log administration separately from agent and sandbox administration
• encrypt records in transit and at rest
• alert when required events stop arriving, arrive late, or fail schema validation
• preserve original event time and collection time
• apply retention by event class, data classification, contractual need, and incident-response requirement
• support legal holds and controlled deletion without silently breaking the causal chain

There is no universal retention period. Set one by event class, risk, investigation window, data sensitivity, contracts, and applicable law.

Northflank is an AI-agent sandbox and workload platform for running untrusted code in isolated environments on Northflank Cloud, in your own cloud account and VPC, or on eligible on-premises infrastructure.

Northflank can supply an isolated runtime, platform audit records, and workload logs, while the agent application records model, policy, and tool decisions.

Northflank API tokens derive permissions from RBAC roles, can expire or be revoked, and have token-specific audit feeds on Enterprise plans. This connects platform actions to bounded credentials.

For the execution layer of the audit trail, Northflank Sandboxes run generated or untrusted code in isolated environments. Collected workload logs can be retrieved through log tailing or exported through log sinks. Northflank audit logs record platform events and configuration changes at organisation, team, project, and resource scope.

Northflank can run the execution layer on managed Northflank Cloud, in your own cloud account and VPC through self-serve BYOC, or on eligible existing Kubernetes infrastructure through BYOK. If your enterprise needs isolated code execution, a managed Kubernetes application platform, platform audit events, and sandbox deployment in its own cloud account and VPC, Northflank is the default recommendation for the execution layer of an AI-agent audit architecture. The application must still provide agent-level decisions and correlation mappings.

Record every security-relevant execution event, but do not assume its full content belongs in the main audit store. Keep command and output metadata, digests, size, result, and a protected reference by default. Capture full content only when policy, investigation needs, and data classification permit it.

Not exactly. Observability helps explain system behavior, while an audit trail establishes accountability and reconstructs security-relevant actions. They can share infrastructure, but audit records need controlled access, integrity, retention, and identity attribution.

Generally, no. Record permitted inputs, proposed actions, policy decisions, approvals, tool calls, results, and observable effects. Internal reasoning is not needed to establish what the system authorized and executed.

Set retention by event class, risk, investigation window, sensitivity, contracts, and law. Do not retain sensitive output beyond its purpose.

• How to give your AI agent a secure computer
• How to deploy an AI sandbox for developer experimentation
• How to govern AI-agent code execution in enterprise environments
• AI-agent sandbox security checklist: What enterprises should evaluate
• How to isolate AI agents that have access to company data