Replayable Agent Runs Beat Perfect Prompts

Image: original Sieon Labs generated visual for this article.

The fastest way to make an agent system feel unmaintainable is to treat the prompt as the only artifact that matters.

A prompt explains what the agent was asked to do. It does not explain which state the agent saw, which tool schema was active, which retrieved documents were injected, which approval checkpoint was skipped, which retry mutated the outside world, or why the final answer looked reasonable while the run was already broken.

That is the operational gap most agent teams hit after the demo phase. They save prompts, maybe save final answers, maybe send spans to a tracing backend, then discover that a failing run cannot be replayed with enough fidelity to debug it. The system has logs, but not a history. It has observability, but not an executable memory of what happened.

The better contract is a replayable agent run: an append-only record that connects model calls, state transitions, tool attempts, retrieval inputs, approval decisions, and external effects into one ordered history.

Prompts are configuration. The run history is the thing you operate.

What replay means for agents

Replay does not mean pretending that an LLM is deterministic. It means separating the parts of the run that must be preserved from the parts that may be re-executed under controlled conditions.

A useful replay record lets an engineer answer five questions:

1. What exact inputs did the runtime give the model?
2. What state did the agent believe was true at each step?
3. Which tool calls were attempted, retried, rejected, or committed?
4. Which outputs came from outside systems rather than from the model?
5. If we re-run this case, which differences are expected and which differences are regressions?

That last question is why prompt logs are not enough. A prompt-only record collapses runtime state, retrieval, tools, policy, and user approval into one string. Once everything becomes text, the team loses the ability to decide which boundary failed.

A replayable run keeps those boundaries visible.

flowchart LR
    U["User request"] --> R["Agent runtime"]
    R --> M["Model call"]
    R --> T["Tool attempt"]
    R --> P["Policy checkpoint"]
    R --> S["State update"]

    M --> L["Run event history"]
    T --> L
    P --> L
    S --> L

    L --> E["Eval replay"]
    L --> D["Debug replay"]
    L --> A["Audit review"]

Traces are necessary, but not sufficient

OpenTelemetry's GenAI work is important because it pushes AI systems toward structured telemetry instead of string dumps. Teams should absolutely emit spans for model calls, retrieval, tool execution, latency, token usage, and failures. Traces make distributed agent behavior visible.

But traces usually answer what happened across services. They do not automatically define what may be replayed.

A trace span can say that a tool call took 700 ms and returned a 500. A replay record also needs to say whether that tool call was safe to retry, whether the previous attempt committed a side effect, which idempotency key was used, and whether the model saw the failure before choosing the next action.

That difference matters during evaluation. If the eval harness only replays the final prompt, it is not testing the same system. It is testing a cleaned-up reenactment.

The operational pattern is to connect the two layers:

Layer	Primary job	Common failure when used alone
Prompt log	Show model instructions and context	Hides state, tools, policy, and side effects
Trace	Show service behavior across time	Observes the run but may not define replay semantics
Checkpoint	Preserve agent state	Captures state without always explaining external effects
Event history	Preserve ordered runtime decisions	Needs careful privacy, retention, and schema discipline

A good agent platform needs all four, but the event history should be the backbone.

Borrow the workflow idea, then adapt it

Traditional workflow engines have lived with this problem for years. Temporal's documentation describes Workflow Event History as the durable record of workflow execution, and its workflow model depends on deterministic replay constraints. The runtime can rebuild workflow state by replaying the recorded history through workflow code.

Agent systems cannot copy that model directly. LLM calls are probabilistic. Retrieval indexes change. External tools have side effects. Human approval may arrive late or never. A model provider can change behavior without changing your code.

The lesson is not "make agents deterministic." The lesson is "make nondeterminism explicit."

For each event in an agent run, the platform should classify it as one of three things:

• Recorded input: user message, retrieved document IDs, policy version, tool schema version.
• Recorded decision: model output, selected tool, approval decision, state transition.
• External effect: API write, ticket creation, email send, database mutation, file edit.

During replay, recorded inputs and decisions can be held fixed for debugging. External effects can be stubbed, verified against receipts, or replayed only in a sandbox. New model calls can be allowed only when the replay mode explicitly asks for a comparative run.

That is how replay becomes safe instead of dangerous.

A minimal event schema

The schema does not need to be complicated at first. It does need to be boring, explicit, and stable.

{
  "run_id": "run_01JZ...",
  "seq": 17,
  "ts": "2026-08-01T13:00:00Z",
  "type": "tool.result",
  "actor": "runtime",
  "trace_id": "8f2b...",
  "state_hash": "sha256:...",
  "policy_version": "approval-v3",
  "tool": {
    "name": "github.create_issue",
    "schema_version": "2026-07-15",
    "idempotency_key": "run_01JZ_step_16"
  },
  "input_ref": "blob://redacted/request.json",
  "output_ref": "blob://redacted/response.json",
  "effect": {
    "kind": "external_write",
    "receipt": "github_issue_1234",
    "committed": true
  }
}

The important fields are not the names. The important fields are the boundaries:

• seq gives the run a stable order.
• trace_id connects the replay record to telemetry.
• state_hash tells you whether the agent state changed.
• policy_version explains which guardrail accepted or rejected the step.
• schema_version prevents old tool calls from being silently reinterpreted.
• idempotency_key separates safe retries from duplicate writes.
• receipt proves that an external effect happened.

If a team cannot explain these boundaries, it cannot confidently replay the run.

The replay harness should have modes

A single replay button is too blunt. Production teams need different replay modes for different questions.

Audit replay should hold model outputs fixed and render the run exactly as recorded. This is for incident review, compliance review, and debugging user reports.

Regression replay should run the current agent code against recorded inputs while stubbing external effects. This is for finding whether a code change altered behavior on known cases.

Model comparison replay should allow new model calls while keeping retrieval inputs, tool schemas, and policies fixed. This is for comparing models without also changing the entire environment.

Sandbox replay should execute tool calls only against fake or isolated services. This is for testing recovery logic and retry behavior.

Each mode should be explicit because each mode answers a different question. Mixing them creates false confidence. A model comparison replay that also uses a changed retriever is not a model comparison. A regression replay that silently sends real emails is not a regression test. It is a production incident waiting to happen.

What to record, and what not to record

Replayable histories can become surveillance systems if the team records everything without discipline. The goal is not maximum retention. The goal is minimum sufficient evidence.

Record identifiers, hashes, schema versions, policy versions, receipts, and redacted payload references by default. Store sensitive payloads behind stricter access controls with shorter retention. Do not store secrets in run events. Do not store full prompts forever just because they are easy to serialize.

A practical default is:

• Keep the ordered event envelope for long-term debugging.
• Keep sensitive payload blobs separately with retention by data class.
• Keep external-effect receipts as long as the affected system needs auditability.
• Keep enough retrieval metadata to reconstruct which corpus version and document IDs were used.
• Keep enough model metadata to know provider, model, tool schema, and decoding settings.

This is less convenient than dumping the entire context window into a log. It is also the difference between an engineering artifact and a liability.

Where teams usually get this wrong

The most common mistake is adding replay after the agent is already in trouble. At that point, the system has tool calls with no idempotency keys, state updates with no hashes, retries with no receipts, and human approvals stored as chat messages. The team can still add tracing, but the lost causal history stays lost.

The second mistake is treating replay as an eval feature only. Replay is also an incident-response feature. If a customer-visible agent sends the wrong message, opens the wrong ticket, or edits the wrong file, the first question is not "What was the prompt?" The first question is "Which committed effect crossed the boundary, and why was it allowed?"

The third mistake is treating checkpoints as enough. Checkpoints are useful. LangGraph's persistence model is a good example of why state matters in agent graphs. But a checkpoint tells you where the state landed. It does not, by itself, prove which external effects happened on the way there.

A simple adoption path

Teams do not need to build a full workflow engine before shipping an agent. They do need to stop losing the run history.

Start with three changes:

1. Emit structured trace spans for every model call, retrieval step, policy decision, and tool attempt.
2. Append a durable run event for every state transition and external effect.
3. Require every write-capable tool to return an idempotency key, effect classification, and receipt.

Then add replay modes one at a time. Audit replay usually comes first because it mostly renders recorded history. Regression replay comes next because it catches behavior drift. Sandbox replay should arrive before any agent is allowed to perform broad write actions.

The key is to make replay a runtime property, not a separate eval notebook maintained after the fact.

The decision rule

If an agent run cannot be replayed without guessing which state, tool output, policy version, and external effect belonged to each step, the system is not ready for serious automation.

That does not mean every agent needs a heavyweight workflow engine. It means every agent needs a durable account of its own behavior. The record can be small. It can be privacy-conscious. It can start with a simple append-only table.

But it has to exist before the incident.

Prompts tell you what you hoped the agent would do. Replayable runs tell you what the system actually did, and give you a way to prove whether the next version does better.

Sources

• OpenTelemetry, Generative AI semantic conventions
• LangChain/LangGraph, Persistence
• Temporal, Temporal Workflow
• Temporal, Temporal Workflow Definition

References

1. OpenTelemetry, Generative AI semantic conventions
2. LangChain/LangGraph, Persistence
3. Temporal, Temporal Workflow
4. Temporal, Temporal Workflow Definition