Replay Rerun

Re-run a recorded run from any step — earlier steps reuse their recorded output

praisonai replay rerun re-runs a recorded run from the step you choose: steps before it reuse their recorded output, so you only pay for the part you changed.

python
from praisonaiagents import Agent, AgentFlow
from praisonai.replay import record
from praisonai.replay.rerun import rerun

research = Agent(name="research", instructions="List three facts about the topic")
draft = Agent(name="draft", instructions="Write a short post from the facts")

with record(full_content=True) as first:
    AgentFlow(steps=[research, draft]).start("AI agents")

rec, result = rerun(AgentFlow(steps=[research, draft]), first.run_id, "step:draft", input="AI agents")
print(rec.run_id, result)
Diagram

Rerun run-bbb

Original run-aaa

recorded output

forked_from

research

draft

edit

research ♻️ reused

draft 🔁 fresh

edit 🔁 fresh

Quick Start

  1. Record a run
    bash
    praisonai agents.yaml --save
  2. Find the node to re-run from
    bash
    praisonai replay list
    praisonai replay flow run-1a2b3c4d5e6f --format mermaid
  3. Re-run from that node
    bash
    praisonai replay rerun run-1a2b3c4d5e6f --from step:draft
    Re-running run-1a2b3c4d5e6f from step:draft as run-9f8e7d6c5b4a (reusing: step:research)

How It Works

AgentFlow

Diagram
LLMTraceStepCacheAgentFlowreplay rerunLLMTraceStepCacheAgentFlowreplay rerunseed with recorded step outputsresearch?cache hit (recorded output)draft?missrun draft fresh

Earlier steps go through the flow’s normal cache-hit path, so variables and {{previous_output}} behave exactly as on a real cache hit — the same path the Step-Result Cache uses.

AgentTeam

Diagram
LLMAgentTeamreplay rerunLLMAgentTeamreplay rerunrestore earlier tasks as completedreset NODE and later tasksskip completed tasksrun NODE fresh

Earlier tasks come back completed with their recorded output; the task you chose and everything after it start again.


Node Ids

Node idMeans
task:writeThe write task of an AgentTeam
step:draftThe draft step of an AgentFlow
step:draft#2The second run of a repeated draft step

Only nodes that finished as completed or cached before your node started are reused.

Options

OptionDefaultDescription
RUN—Run id or path to the recorded trace
--fromrequiredNode id to re-run from
--filethe YAML recorded with the runYAML definition to run instead

Fork Tracking

The new run records where it came from on its first workflow_start event:

json
{"forked_from": {"run_id": "run-1a2b3c4d5e6f", "node_id": "step:draft"}}

See it with praisonai replay show <new-run> --type workflow_start or in an HTML export.


When It Fails

Diagram

No

Yes

Truncated

Yes

Yes

No

Step inserted

Yes

🔁 replay rerun –from NODE

Schema 1.1?

❌ No node ids: re-record

Earlier outputs full?

❌ Use full_content=True

Recorded variable redacted?

❌ Re-run from that node

Flow order matches recording?

❌ Did not run in recording

✅ Reuse earlier steps, run NODE onward

Variables are preserved

Variables a step’s handler sets with StepResult(variables={...}) are recorded and restored, so a later step reads the recorded value — not a fresh one.

python
from praisonaiagents import AgentFlow
from praisonaiagents.workflows import StepResult
from praisonai.replay import record
from praisonai.replay.rerun import rerun

def research(ctx):
    return StepResult(output="notes", variables={"customer_id": 42})

def draft(ctx):
    return StepResult(output=f"draft for customer {ctx.variables.get('customer_id')}")

with record(full_content=True) as rec:
    AgentFlow(steps=[research, draft]).start("topic")

# research is reused from the recording, and its customer_id=42 is restored
rerun(AgentFlow(steps=[research, draft]), rec.path, "step:draft", input="topic")
Diagram
draftrun-xxx.jsonlAgentFlowdraftrun-xxx.jsonlAgentFlowRecordingRerun from step:draftstep_end research (variables: customer_id=42)research reused + customer_id=42ctx.variables[“customer_id”] == 42

A step that was skipped in the recording is checked again against the restored variables, so the same condition skips it again.

Secrets block rerun

If a step set a secret-looking variable (such as api_key, token, password or secret), the recording redacted it — so rerun refuses to restore it.

python
from praisonaiagents import AgentFlow
from praisonaiagents.workflows import StepResult
from praisonai.replay import record
from praisonai.replay.rerun import RerunError, rerun

def auth(ctx):
    return StepResult(output="ok", variables={"api_key": "sk-abcdefghijklmnop"})

def call(ctx):
    return StepResult(output="done")

with record(full_content=True) as rec:
    AgentFlow(steps=[auth, call]).start("x")

try:
    rerun(AgentFlow(steps=[auth, call]), rec.path, "step:call", input="x")
except RerunError as e:
    print(e)

# Re-run from the step that sets the secret, so it runs fresh
rerun(AgentFlow(steps=[auth, call]), rec.path, "step:auth", input="x")

The full list of redacted key names is REDACT_KEYS in praisonaiagents/trace/redact.py.

Rerun validates the current flow

A step added before your node that never ran in the recording would run fresh and change the input your node gets, so rerun stops instead.

Step inserted before the target

The recording ran research → draft; the current flow is research → extra → draft.

python
from praisonaiagents import AgentFlow
from praisonaiagents.workflows import StepResult
from praisonai.replay import record
from praisonai.replay.rerun import RerunError, rerun

def research(ctx): return StepResult(output="r")
def extra(ctx):    return StepResult(output="e")
def draft(ctx):    return StepResult(output="d")

with record(full_content=True) as rec:
    AgentFlow(steps=[research, draft]).start("topic")

try:
    rerun(AgentFlow(steps=[research, extra, draft]), rec.path, "step:draft", input="topic")
except RerunError as e:
    print(e)
Unnamed patterns are caught too

Steps are matched by graph node id, so an inserted If, When or Loop with no name raises the same error.

Nested target

When your node lives inside a pattern (for example research → If[draft] → polish), the check runs up to that pattern — a step inserted before it is still rejected.


Python

python
from praisonaiagents import Agent, AgentFlow
from praisonai.replay.rerun import rerun

research = Agent(name="research", instructions="List three facts about the topic")
draft = Agent(name="draft", instructions="Write a short post from the facts")
flow = AgentFlow(steps=[research, draft])

rec, result = rerun(flow, "run-1a2b3c4d5e6f", "step:draft", input="AI agents")
print(rec.run_id, rec.path)
ParameterTypeDefaultDescription
targetAgentFlow \AgentTeam—What to run (must match the recorded kind)
sourcestr \list—Run id, trace path, or loaded events
node_idstr—Node to re-run from
inputAnyNonePassed to target.start()
run_idstrautoId for the new run
liveboolFalseFlush every event as it happens
metadictNoneExtra session_start data

Returns (recording, result).


Best Practices

Record with full_content=True

Long step outputs are otherwise only kept as previews; full_content=True lets you re-run from any node.

Change one thing per rerun

Edit the step you’re tuning, rerun from it, and compare the two runs side by side in replay view.


Related