How to Pause, Resume, and Cancel an Agent Run

Quick answer
Pause is a checkpoint: finish the current step, persist state, and stop before the next one.
Resume replays from the checkpoint, skipping completed steps by idempotency key.
Cancel stops future steps but cannot undo completed side effects, so define what it means for the task.
Without checkpoints, pause is a kill and resume is a restart, which duplicates work.
Test all three on a staging run before you need them in an incident.

What is the difference between pause and cancel?

Pause is cooperative: the worker reaches a safe boundary, saves state, and exits. Resume picks up from that state. Cancel is terminal: no further steps run, and the run’s completed side effects are left as they are.

That last part is the one people miss. Cancelling after a step that created a ticket or sent a message does not undo it. The run’s record needs to say what it did before it stopped, or the next person will repeat it.

How do you make a run resumable?

Persist a checkpoint before and after each step: the step identifier, its inputs, whether it completed, and the result. On resume, load the last checkpoint and continue from the next unfinished step. The state belongs in a store, not in the model’s context.

Give each side-effecting step an idempotency key derived from the run and the step. If the step already ran, the tool should return the existing result rather than create a second one. That is what makes a retry safe.

checkpoint: { run_id, step: "create_pr", status: "done", result_ref: "pr#412" }
next step:  { run_id, step: "comment_review", status: "pending" }
idempotency key: sha256(run_id + step)  -> reuse on retry
cancel: stop after current step; record completed side effects

Where should the boundary be?

Between steps, never inside one. Interrupting a shell command or a file write leaves a partial state that neither resume nor cancel can reason about. Let the current step finish or fail, then honour the control request.

For steps that take a long time, split them. A migration that runs for ten minutes should be its own step with a checkpoint around it, so a pause does not wait for the whole job.

How do you verify the controls work?

Run a task on staging, pause it mid-way, resume it, and confirm no side effect happened twice. Then cancel a run after a side effect and confirm the record shows what completed. Both tests find bugs that only appear during an incident.

Also test the timeout path. A run that ignores pause because it is stuck should still be killed by the supervisor, and the kill should leave a resumable checkpoint rather than a corrupted state.

Where this bites vibecoders
The first version rarely has pause at all: the run either finishes or the process dies. Add checkpoints and idempotency keys before giving the agent any side-effecting tool, because those two are also what make retries safe.

Where AI coding assistants get this wrong

Treating pause as a process kill with no saved state.
Resuming by restarting the task and duplicating side effects.
Interrupting a step midway and leaving a partial write.
Assuming cancel rolls back completed actions.
Storing checkpoints only in the model context.
Never testing pause and resume before an incident.

Checklist

Persist a checkpoint before and after each step.
Derive an idempotency key per step.
Honour pause and cancel between steps only.
Record completed side effects on cancel.
Split long steps so checkpoints are frequent.
Test pause, resume, cancel, and timeout on staging.

FAQ

Can an agent resume with full context?

It resumes with the persisted state, which is usually a summary rather than the full conversation. Design the checkpoint to contain what the next step needs: the task, the completed steps, the decisions, and the artefacts. That is more reliable than replaying a transcript.

Should cancel attempt a rollback?

Only for steps that were designed to be reversible. A rollback that runs automatically after a partial run can create a worse state than leaving it. Record what happened and let a human decide, unless the task has a clean compensating action.

How long can a paused run stay paused?

As long as the state store retains it and the world has not changed underneath. A paused deployment from yesterday may be invalid today. Resume should re-check preconditions — the branch still exists, the target is still the intended one — before continuing.

Does pausing save cost?

It stops future model calls, which is where most of the cost is. The tokens already spent are not recovered. A paused run also frees the concurrency slot, which matters when a queue is backing up.