The Agent Run Timeline: Building a Replay UI

A timeline you can scrub. The web component, the data model, and the keyboard shortcuts that turn an opaque run into something a junior SRE can debug.

The UI shape

A horizontal timeline showing each step as a rectangle, sized by duration, colored by type (model call, tool call, decision).

Click a step: see the full payload. Right-arrow: jump to the next step. Slash key: search across steps.

Persisted state in URL: the run_id and the focused step. Sharing a link shares a specific moment in the run.

Data model

Steps are stored as a flat array, each with start_ms, duration_ms, type, payload. The flat array sorts and renders trivially.

Decisions are first-class steps. "Decided to call tool X with args Y" is a step the operator can scrub to.

Errors are highlighted with a red bar. Tool failures, hallucination flags, refusals; all surfaced visually.

Performance considerations

Long runs (hundreds of steps) need virtualisation. Render only the visible region; the rest is computed on demand.

Payload bodies can be large. Lazy-load them; the timeline lists are fast even when individual payloads are heavy.

Cache aggressively. Replay is read-only on a finished run; cache the entire timeline structure.

Keyboard shortcuts

Right/left: next/previous step. Shift+arrow: jump 10 steps. Home/end: first/last step.

Slash: focus search. Enter on result: jump to that step.

Esc: close detail panel. Question mark: show shortcut reference. Treat the UI like a developer tool, not a dashboard.

Export and share

Export as JSON: the whole run as a downloadable file. Useful for offline analysis and bug reports.

Export as Markdown: a narrative version with each step's key info. Useful for postmortem writeups.

Direct link: a URL that opens the timeline at a specific step. Useful for chat conversations about specific moments.