Skip to main content
from praisonaiagents import Agent

agent = Agent(name="replay-agent", instructions="Replay recorded agent sessions for debugging.")
agent.start("Replay the session from yesterday to reproduce the bug.")
The user saves a trace during a run, then steps through recorded context events to debug handoffs and tools. Record agent context events during a run, then step through them interactively to debug handoffs, tool calls, and token growth. 
praisonai recipe run my-recipe --save
praisonai replay list
praisonai replay context <session_id>

​
Quick Start

1

Simple Usage

Save a trace during a recipe or workflow run:
# Recipe run with trace saving
praisonai recipe run my-recipe --save

# agents.yaml or workflow
praisonai agents.yaml --save
praisonai workflow run my-workflow --save

# List and replay
praisonai replay list
praisonai replay context <session_id>
2

With Configuration

Emit traces from Python and persist to disk:
from praisonai.replay import ContextTraceWriter
from praisonaiagents import ContextTraceEmitter

writer = ContextTraceWriter(session_id="my-session")
emitter = ContextTraceEmitter(sink=writer, session_id="my-session", redact=True)

emitter.session_start()
emitter.agent_start("researcher")
emitter.message_added("researcher", "user", "Find info about AI", 1, 100)
emitter.agent_end("researcher")
emitter.session_end()
writer.close()

​
How It Works

Event typeDescription
SESSION_START / SESSION_ENDSession boundaries
AGENT_START / AGENT_ENDAgent lifecycle
AGENT_HANDOFFHandoff to another agent
MESSAGE_ADDEDContext message appended
TOOL_CALL_START / TOOL_CALL_ENDTool execution
LLM_REQUEST / LLM_RESPONSELLM API calls
CONTEXT_SNAPSHOTFull context state captured
Traces are stored as JSONL in ~/.praisonai/traces/.

​
CLI Commands

CommandPurpose
praisonai replay listList available traces
praisonai replay context <id>Interactive step-through
praisonai replay flow <id>Agent flow visualisation
praisonai replay show <id>Dump events (non-interactive)
praisonai replay delete <id>Delete a trace
praisonai replay cleanupRemove old traces

​
Interactive navigation

In replay context: Enter/n next, p previous, g <N> go to event, q quit.

​
Filters

praisonai replay show my-session --agent researcher
praisonai replay show my-session --type agent_start
praisonai replay show my-session --json

​
Common Patterns

​
In-memory trace during tests

from praisonaiagents import ContextTraceEmitter, ContextListSink

sink = ContextListSink()
emitter = ContextTraceEmitter(sink=sink, session_id="test-session")

emitter.session_start()
# ... agent execution ...
emitter.session_end()

for event in sink.get_events():
    print(f"{event.event_type}: {event.agent_name}")

​
Read traces programmatically

from praisonai.replay import ContextTraceReader, ReplayPlayer

reader = ContextTraceReader("my-session")
if reader.exists:
    player = ReplayPlayer(reader, use_rich=True)
    player.run()

​
Cleanup old traces

praisonai replay cleanup --max-age 7
praisonai replay cleanup --max-size 200 --dry-run

​
Best Practices

Include a timestamp or task identifier so traces are easy to find in replay list.
redact=True (default) strips sensitive data from persisted traces.
Full CONTEXT_SNAPSHOT events can be large — prefer message and tool events for routine debugging.
Use replay cleanup --max-age 7 so trace storage does not grow unbounded on developer machines.

Run History

Inspect past agent runs and session metadata

Observability Hooks

Emit structured events for external observability tools