Context Replay

Debug and analyse agent execution by replaying context changes step-by-step

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

AGENT_END carries data["status"]: "completed", "failed" (the agent raised), or "cancelled". An unnamed agent (Agent(instructions=...)) uses node_id="agent:Agent", matching its id in to_graph(agent). Both sync (start/chat) and async (astart/achat) runs record LLM_REQUEST / LLM_RESPONSE.

Traces are stored as JSONL in ~/.praisonai/traces/.

Node IDs & Reused Steps

Every step gets a stable node_id built from its name and position, so one handler reused at two positions shows up as two separate nodes.

from praisonaiagents import AgentFlow

def review(ctx):
    return "ok"

def draft(ctx):
    return "drafted"

flow = AgentFlow(steps=[review, draft, review])
flow.run("go")
# step_start / step_end node_ids:
#   step:review   step:draft   step:review#2

CLI Commands

Interactive navigation

In replay context: Enter/n next, p previous, `g

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

Related