CORE GUIDE
Asynchronous long-running work
Tasks that outlive one request need explicit job identity, durable state, cancellation and result retrieval; keeping an HTTP or model call open is not a long-running architecture.
Mental model
Long-running work is a state machine around a durable job, not an unusually long synchronous request. The caller submits work, observes progress, may cancel or retry safely, and later retrieves a verified result.
Why it matters
Agent tasks increasingly involve minutes or hours of research, tool execution, approvals and retries. If the system ties that lifetime to one connection, deployments, network failures and user navigation turn into lost state or duplicate work. An asynchronous contract makes ownership, progress and recovery observable.
01
Separate submission, execution and observation
Create a durable job ID at submission, persist the requested operation and idempotency key, and enqueue or schedule execution independently from the client connection. Workers checkpoint progress, publish coarse status and honor cancellation at defined boundaries. Result retrieval should distinguish terminal success, terminal failure, cancellation and still-running state.
02
Example: repository migration runs for forty minutes
A coding agent is asked to migrate a large monorepo. The UI receives a job ID immediately rather than holding one streaming request forever. Workers update checkpoints after dependency groups, a deploy does not erase progress, and the user can cancel before the final write phase. Reconnecting later reads the same durable job instead of creating another migration.
Common failure modes
- Treating a long timeout as a substitute for durable job state.
- Starting a duplicate job whenever the client reconnects.
- Offering cancellation in the UI without defining safe cancellation points in the worker.
Engineering heuristics
- Give every long-running operation a durable job identity.
- Make retry, resume and cancel semantics explicit at the protocol boundary.
- Expose progress as evidence-backed state, not speculative model narration.
Takeaways
- 01Long duration requires a job protocol.
- 02Connection lifetime and task lifetime should be independent.
- 03Durable state makes recovery, cancellation and deduplication possible.
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.