Replay Record API

Record any agent run from Python with record(), or from YAML with save_replay: true

record() saves everything inside a with block to a local trace file and hands you back its run id and path.

python
from praisonaiagents import Agent
from praisonai.replay import record

with record() as rec:
    Agent(name="writer", instructions="Draft a short blog post").start("AI agents")

print(rec.run_id, rec.path)
Diagram

record()

🎬 with record

âš¡ Agent / tool / LLM events

💾 run-xxx.jsonl

✅ run_id + path

Quick Start

  1. Record a run
    python
    from praisonaiagents import Agent
    from praisonai.replay import record
    
    with record() as rec:
        Agent(name="writer", instructions="Draft a short blog post").start("AI agents")
  2. Watch it while it runs
    python
    from praisonaiagents import Agent
    from praisonai.replay import record
    
    with record(live=True) as rec:
        print(f"praisonai replay view {rec.run_id} --live")
        Agent(name="writer", instructions="Draft a short blog post").start("AI agents")
  3. Or record from YAML
    yaml
    save_replay: true
    roles:
      researcher:
        role: Researcher
        goal: Collect sources
        backstory: You find what matters.
        tasks:
          research:
            description: Research the topic
            expected_output: A summary
    bash
    praisonai agents.yaml

record() Options

ParameterTypeDefaultDescription
run_idstrrun-<12 hex>Trace id and file name
liveboolFalseWrite every event to disk as it happens
metadictNoneExtra data on the session_start event (e.g. {"yaml_path": ...}, which replay rerun uses to find the definition)
full_contentboolFalseKeep tool results and LLM responses untruncated
python
from praisonaiagents import Agent
from praisonai.replay import record

with record("blog-post-v2", meta={"experiment": "shorter prompt"}) as rec:
    Agent(name="writer", instructions="Draft a short blog post").start("AI agents")

Recording Fields

FieldTypeDescription
run_idstrThe run id
pathPathWhere the trace file is written
liveboolWhether events are written immediately
status`str \None`Set to "failed" to mark a run failed when you handle the error yourself
python
from praisonaiagents import Agent
from praisonai.replay import record

with record() as rec:
    try:
        Agent(name="writer", instructions="Draft a short blog post").start("AI agents")
    except Exception:
        rec.status = "failed"

An exception that escapes the block also marks the run failed.


save_replay: true

Set save_replay: true at the top level of a YAML file to record every run — the same as passing --save each time.

CommandRecorded when
praisonai agents.yamlsave_replay: true or --save
praisonai workflow run workflow.yamlsave_replay: true or --save

YAML runs also record their file path, so praisonai replay rerun can find the definition without --file.


Everything Carries the Run Id

record() enters the SDK’s run scope, so every event — hand-offs, tool calls, LLM requests, and nested teams or flows — is tagged with the same run id automatically.

Diagram
ToolAgentAgentTeamrecord()ToolAgentAgentTeamrecord()run scope = run-1a2b3c4d5e6fhand-off (run-1a2b3c4d5e6f)tool call (run-1a2b3c4d5e6f)

Everything recorded is redacted by default.


full_content=True

By default long outputs are kept as previews to keep traces small; full_content=True keeps them whole.

python
from praisonaiagents import Agent
from praisonai.replay import record

with record(full_content=True) as rec:
    Agent(name="writer", instructions="Draft a long blog post").start("AI agents")

Use it when you plan to re-run from any step — a step whose output was only kept as a truncated preview cannot be reused.


Best Practices

Prefer save_replay for YAML

No code change and every run is recorded, ready to view or re-run.

Give experiments a readable run_id

record("blog-post-v2") is easier to find in praisonai replay list than a random id.

Trade disk for completeness deliberately

Turn on full_content=True only for runs you expect to fork.


Related