Causal Audit

What question it answers

A tool call shows that an agent asked for information. It does not show that the information affected the final outcome. Causal Audit asks the narrower, useful question: if this approved piece of evidence were different, would the measured outcome also be different?

It is an execution-level diagnostic in Agents Runtime. It is designed for evidence review, not for reading an agent's hidden reasoning.

Where it fits

Causal Audit joins four parts of the platform. Each has a deliberately narrow job, which keeps a sensitive test explainable and prevents the control plane from becoming an agent runtime.

Example

Imagine a fraud-review agent calls a transaction database and receives a risk confidence of 0.90. The agent recommends REVIEW. A governed policy may permit a safe test in which the confidence is reduced to0.40. The original runtime replays the same source in isolation, using that approved alternate evidence.

If the measured outcome changes substantially, the tool evidence appears to have mattered. If it does not, the evidence may have been ignored by the evaluated path. The original claim, original evidence, and original execution remain untouched.

Controlled Replay Framework

A controlled replay is a new, isolated execution—not a retry of a failed production request and not an edit of history. It starts from a frozen reference to the completed source, changes only the evidence permitted by the active policy, and asks the runtime's registered replay adapter to run that safe variant.

This page explains how Causal Audit uses the framework. For the complete model of ownership, lifecycle, worker hand-off, recovery, and retained lineage, read Controlled Replay Framework.

Completed execution
  → choose auditable tool evidence
  → apply an approved intervention policy
  → run an isolated controlled replay in the original runtime
  → compare the original and replay outcomes
  → store the immutable result and its lineage

An intervention policy is a versioned permission for one kind of change to one tool-result schema. It can use a neutral value (NULLIFY), an authorized alternate reference (REPLACE), or a bounded field change (PERTURB). A policy can be previewed and validated before it is activated. Previewing does not run an agent or create an audit.

What must be ready

Causal Audit is intentionally not available for every observed execution. Before an operator can request one, the integration needs these building blocks:

• Completed evidence: a succeeded execution with ordered tool-call records, a bounded outcome score, and durable evidence references.
• Evidence contract: a tool name plus schema identity and version, so the platform can verify that an alternate value has the right shape.
• Replay capability: an explicit adapter name, version, frozen source reference, and supported intervention strategies declared by the runtime.
• Active policy: one unambiguous, versioned Intervention Policy matching that tool and schema.
• Durable workers: the API and replay worker must share the same durable stores so queued audit and replay work survives a restart.

The local deterministic adapter is a safe reference implementation for learning and validation. A production integration supplies its own registered adapter; the control plane does not attempt to replay an arbitrary agent by itself.

When a check is allowed

The platform fails closed: it refuses an audit when it cannot run a safe and meaningful comparison. An eligible execution needs all of the following:

• A completed, successful execution with a bounded outcome score.
• Tool evidence with an approved durable reference and schema identity.
• An active, unambiguous intervention policy for that tool evidence.
• A runtime-declared replay capability that can run without production side effects.
• A compatible controlled-replay adapter and complete tenant/project scope.

How workers complete it

Submitting an audit is quick because the API only validates the request, preserves its inputs, and queues durable work. The longer work happens in the worker system, so a browser refresh or API restart cannot lose the request.

API: validate eligibility → save QUEUED audit → submit CAUSAL_AUDIT job
  ↓
Audit worker: freeze inputs → create controlled Replay job(s)
  ↓
Replay worker: call the runtime adapter → save counterfactual execution + outcome artifact
  ↓
Audit worker: score every result → calculate influence → save immutable audit

More than one controlled replay may be created when the audit requests multiple samples. The audit worker waits for every required sample before it calculates an aggregate counterfactual score. A missing or failed sample fails the audit; it never turns a partial set of replays into a confident-looking answer.

Controlled replays use the normal durable Replay framework, but they do not enter its generic evaluation, baseline-comparison, or drift workflow. Their adapter already produces the bounded outcome artifact that Causal Audit scores. This distinction prevents an unrelated scorecard comparison from rejecting a valid isolated causal test. See Replay Management and Job Executionfor the shared framework.

How to read a result

The audit compares the original outcome score with the aggregate score from the controlled replays. Its classifications describe that measured comparison:

In simple terms, evidence influence is the original score minus the aggregate controlled-replay score. A configured threshold decides whether that difference is large enough to be material. The default threshold is a methodology setting, not a universal scientific constant.

Every completed audit keeps the policy version, intervention digest, controlled replay IDs, produced execution IDs, and evaluator scores. That lineage lets a reviewer understand the result without exposing the temporary raw evidence used during replay.

An audit moves from QUEUED to RUNNING while workers do this work, then ends as SUCCEEDED or FAILED. A failed audit retains safe diagnostics, but it has no classification or partial influence score. A completed audit is immutable: requesting a different policy, strategy, sample count, or seed creates a different audit rather than rewriting the original answer.

Safety controls

• The source execution and historical evidence are never changed.
• The original runtime, not the control plane, performs the isolated replay.
• Production side effects are not permitted in controlled replays.
• Policy selection, evidence resolution, and replay run under the approved tenant and project scope.
• Partial replay failures fail the whole audit instead of producing a best-effort score.

What it cannot prove

Causal Audit measures sensitivity of a defined outcome under one controlled evidence change. It does not prove universal causation, reveal private model reasoning, or prove why an agent made a decision. It gives a reviewable answer to one specific, bounded question.

Next steps

Follow the Run Causal Audit tutorial for a guided policy-and-review workflow. If your runtime is not yet sending execution evidence, start with Observe Agent Runtime. Read Intervention Policies before approving a new evidence change, and Agents Runtime Operations before enabling audits in production.