Execution Replay
Execution replay lets you debug agent workflows by reviewing the exact sequence of events in a session. Replay every step to understand what happened and why.
Debugging made easy
Sessions capture every API call, event, and result. Use replay to trace failures without adding logging to your code.
Sessions
Every workflow and multi-step operation runs inside a session. Sessions record all events, API calls, and results in a timeline.
typescript
const session = await client.sessions.create({ name: "user-signup-debug",}); // Run your workflowconst workflow = await client.waits.createInboxAndWait({ waitType: "otp", timeoutSeconds: 120, sessionId: session.id,});python
session = client.sessions.create(name="user-signup-debug") # Run your workflowwait = client.waits.create( inbox_id="00000000-0000-4000-8000-000000000001", type="otp", timeout_seconds=120, session_id=session.id,)Timeline
The timeline is a chronological list of every event in the session. Each event includes a timestamp, type, and payload.
typescript
const detail = await client.sessions.get("00000000-0000-4000-8000-000000000004", { include: ["timeline"],}); for (const event of detail.timeline ?? []) { console.log(event.timestamp); console.log(event.type); // "inbox.created", "email.received", etc. console.log(event.payload); // Full event data}python
detail = client.sessions.get("00000000-0000-4000-8000-000000000004", include=["timeline"]) for event in detail["timeline"]: print(event.timestamp) print(event.type) # "inbox.created", "email.received", etc. print(event.payload) # Full event dataTimeline Response
{ "events": [ { "timestamp": "2024-06-12T10:00:00Z", "type": "session.created", "payload": { "sessionId": "sess_789" } }, { "timestamp": "2024-06-12T10:00:01Z", "type": "inbox.created", "payload": { "inboxId": "inb_123", "emailAddress": "..." } }, { "timestamp": "2024-06-12T10:00:05Z", "type": "wait.created", "payload": { "waitId": "wait_456", "type": "otp" } }, { "timestamp": "2024-06-12T10:02:30Z", "type": "email.received", "payload": { "messageId": "msg_789", "subject": "Your code" } }, { "timestamp": "2024-06-12T10:02:31Z", "type": "extraction.completed", "payload": { "type": "otp", "value": "123456", "confidence": 0.98 } }, { "timestamp": "2024-06-12T10:02:31Z", "type": "wait.completed", "payload": { "waitId": "wait_456", "result": "123456" } } ]}Replaying a Session
Replay reconstructs the session step-by-step, allowing you to inspect the state at each point.
typescript
const replay = await client.sessions.get("00000000-0000-4000-8000-000000000004", { include: ["inboxes", "waits", "messages", "extractions", "timeline"],}); console.log(replay.timeline);console.log(replay.inboxes);console.log(replay.waits);python
replay = client.sessions.get( "00000000-0000-4000-8000-000000000004", include=["inboxes", "waits", "messages", "extractions", "timeline"],) print(replay.get("timeline"))print(replay.get("inboxes"))print(replay.get("waits"))Debugging with Replay
- Step durations — Identify slow operations (e.g., long waits)
- Input/output inspection — See exactly what was sent and received
- Error tracing — Find the exact step where a failure occurred
- Confidence analysis — Check extraction confidence scores at each step
Pro tip
Compare successful and failed replays side-by-side to spot differences in inputs, timing, or email content.
Dashboard Replay
You can also view and replay sessions visually in the AgentInbox dashboard.
Go to Sessions in the dashboard, select a session, and click Replay to see a visual timeline with expandable steps.