Building Agents
MDX
Designing Long-Running Agents
Patterns for durable tasks that span minutes, hours, approvals, retries, and changing external state.
Editorial review: clarity, operational relevance, safety boundaries, and source quality.
Persist outside the process
Long-running work needs a durable task record containing state, inputs, outputs, limits, and ownership. An in-memory loop cannot survive a restart or deployment.
Durability requires separating the task record from any one worker. Persist the objective, owner, current state, plan version, artifacts, attempts, budgets, and next wake-up time. Workers should claim tasks with leases so a crash does not leave permanent ownership or allow two processes to act concurrently.
Resume from checkpoints
Record completed steps and make actions idempotent so the task can continue without repeating side effects. Refresh time-sensitive observations when resuming after a delay.
A checkpoint must say what is complete and what external effects occurred. On resume, revalidate credentials, approvals, deadlines, and time-sensitive observations. Use idempotency keys for writes and a reconciliation step when the previous attempt's outcome is unknown.
Keep users informed
Expose meaningful progress, pending approvals, and a way to cancel. A background agent should never become invisible merely because it no longer fits in one request.
Progress should reflect user-relevant milestones rather than model activity. Notify users when input is needed, estimates change materially, or work terminates. Cancellation must revoke queued work and prevent later callbacks from continuing with stale authority. Retain enough trace data to explain the outcome after hours or days.
Practical example
A multi-hour vendor review
The task gathers documents, waits for an external registry, asks an analyst to resolve one identity match, and resumes after approval. Each stage writes artifacts to durable storage and queues the next transition. When the registry callback arrives, the runtime checks that the task is still active and the request is current. Cancellation invalidates its lease and all pending approval tokens.
Field checklist
Apply it in practice
- Persist task state independently of workers.
- Use leases, idempotency keys, and reconciliation.
- Refresh stale inputs and authority on resume.
- Expose progress, input requests, cancellation, and terminal status.
Decision framework
Questions to answer before you build
Long-running agents are durable workflows, not long model conversations. They need persisted state, leased work, resumable checkpoints, refreshed authority, and visible user control.
What survives a worker restart?
Persist objective, owner, state, artifacts, attempts, budgets, approvals, and the next scheduled action outside the executing process.
What must be refreshed on resume?
Recheck credentials, approval expiry, deadlines, external facts, and whether the user has changed or cancelled the task.
How will uncertain effects be reconciled?
Store idempotency keys and external references, then read actual state before deciding whether to retry or continue.
Common failure signals
Watch for these warning signs
- Keeping essential progress only in a context window or process memory.
- Allowing two workers to act because task ownership has no lease.
- Continuing after cancellation because queued callbacks retain stale authority.
Selected primary references
Continue with the source material
These sources inform the wider editorial perspective for this topic. They are not presented as line-by-line citations for every statement.