CORE GUIDE
Interrupt and cancel long-running agents
Long-running agents need explicit interrupt and cancellation semantics so users and operators can stop work safely, distinguish 'stop requested' from 'stopped', and recover without corrupting side effects.
Mental model
Cancellation is a state transition, not a UI button. The runtime must propagate the request to active work, decide which operations are cancellable, wait for or compensate in-flight side effects, persist a terminal or resumable checkpoint, and report the final state.
Why it matters
Agents that run for minutes or hours inevitably outlive user intent, dependencies and deployment windows. Without well-defined cancellation, a 'stop' action may only hide the UI while tools continue executing. Explicit semantics prevent orphaned work, duplicated recovery and uncertainty about whether consequential actions completed.
01
Model cancellation as cooperative runtime control
Represent cancel-requested, cancelling and cancelled states separately. Pass cancellation tokens or equivalent signals to cancellable work, define safe points around irreversible operations, and make non-cancellable side effects idempotent or compensatable. Persist enough state to resume or explain what completed before the stop, and time out cancellation itself when a dependency does not respond.
02
Example: stop request arrives during an external payment call
An agent is waiting on a payment provider when the user cancels. The runtime records cancel-requested but does not assume the payment stopped. It waits for the provider result, reconciles the operation by idempotency key, then either records the payment and ends the workflow or confirms no side effect occurred before entering cancelled state.
Common failure modes
- Treating UI disappearance as proof that background work stopped.
- Cancelling in the middle of an irreversible action without reconciliation.
- Dropping state on cancellation so operators cannot tell what completed.
Engineering heuristics
- Make cancellation state observable and durable.
- Define safe points and reconciliation around irreversible side effects.
- Design cancel and resume semantics together for long-running work.
Takeaways
- 01Cancellation is a protocol between user intent and runtime state.
- 02Stop requested and stopped are different states.
- 03Irreversible work requires reconciliation before cancellation can be declared complete.
Reading evidence
This records actions you actually took; it does not claim mastery, proficiency, or certification.
Used in
This Concept is reused across these canonical learning paths.
Related concepts from the Knowledge Graph
These relationships come from the canonical graph, not a separate Guide taxonomy.