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.
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)Quick Start
- Record a run
bash praisonai agents.yaml --save - Find the node to re-run from
bash praisonai replay list praisonai replay flow run-1a2b3c4d5e6f --format mermaid - Re-run from that node
bash praisonai replay rerun run-1a2b3c4d5e6f --from step:draftRe-running run-1a2b3c4d5e6f from step:draft as run-9f8e7d6c5b4a (reusing: step:research)
How It Works
AgentFlow
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
Earlier tasks come back completed with their recorded output; the task you chose and everything after it start again.
Node Ids
| Node id | Means |
|---|---|
task:write | The write task of an AgentTeam |
step:draft | The draft step of an AgentFlow |
step:draft#2 | The second run of a repeated draft step |
Only nodes that finished as completed or cached before your node started are reused.
Options
| Option | Default | Description |
|---|---|---|
RUN | — | Run id or path to the recorded trace |
--from | required | Node id to re-run from |
--file | the YAML recorded with the run | YAML definition to run instead |
Fork Tracking
The new run records where it came from on its first workflow_start event:
{"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
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.
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")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.
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.
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
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)| Parameter | Type | Default | Description | |
|---|---|---|---|---|
target | AgentFlow \ | AgentTeam | — | What to run (must match the recorded kind) |
source | str \ | list | — | Run id, trace path, or loaded events |
node_id | str | — | Node to re-run from | |
input | Any | None | Passed to target.start() | |
run_id | str | auto | Id for the new run | |
live | bool | False | Flush every event as it happens | |
meta | dict | None | Extra 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.