Agent Lifecycle

What it is

The sequence of states one running agent instance occupies between creation and disposal — admitted, initialised, executing, waiting on an external event, suspended, finishing, finished, reaped — together with the rules for moving between them and the list of who may force a move. It is per-instance, runtime, and finite: every instance ends, and the system should be able to say which state it ended in and why.

Why it matters

Agent instances are long-lived and expensive compared with request handlers. They hold conversation history, partially consumed budgets, open sandbox sessions, leases on work items, and sometimes a user waiting. Without named states and explicit transitions, instances leak — nothing reaps the ones waiting for an event that will never arrive — resources are released at the wrong moment, and after a crash there is no recorded position to recover to. Retention and deletion obligations also hang off this: you cannot delete a run's data on schedule if you never recorded that the run ended.

Why this is not the artefact's version history

An agent's definition has revisions; an instance has states. A revision is published once and read by many instances; a state belongs to exactly one instance and is overwritten as it advances. Rolling back a definition does not move any instance backwards, and an instance does not change definition revision partway through — or should not, which is itself a lifecycle rule worth stating explicitly.

Key decisions

• Where instance state is held. In process memory it is fast and dies with the worker; in an external store it survives restarts and forces every piece of it to be serialisable.
• Whether an instance may outlive the request that created it, and for how long. Background continuation is the feature that makes long tasks possible and the one that leaks.
• What reaching a terminal state obliges the system to release: sandboxes, tool sessions, leases, reserved budget, and any half-written record the instance was in the middle of.
• Who is permitted to force a transition — the user, an operator, a spend guard, a supervising agent — and whether a forced stop is distinguishable afterwards from a natural one.
• Whether instances survive a process restart, which upgrades every transition from a variable assignment to a durably recorded event.
• How long a finished instance's transcript and state are retained, and what deletes them.

Failure modes

• Instances waiting on a human decision accumulate without limit because no maximum wait was defined; connection pools and memory exhaust before anyone notices the queue.
• Cleanup is attached to the successful path, so a crashed instance leaves behind a running container, a held lease, and a budget that was reserved and never released.
• The coordinator treats an instance as finished while a tool call it issued is still in flight; that call completes afterwards and writes into a run that no longer exists.
• A rolling deploy evicts every in-memory instance mid-task and users watch conversations disappear with no error message.
• Termination is implemented as killing the process, so no final state is written and the transcript stops without a reason; the post-incident question "why did it stop" has no answer.
• An instance that has nothing left to do keeps paying for its full context every turn because its stopping rule depends on a message that stopped arriving.
• After a recovery, an instance identifier is reused while the original is still alive, and two executions write to the same record.
• States are inferred from timestamps rather than recorded, so the dashboard reports whatever the inference rule happens to believe today.

Related capabilities

• Interrupt and Resume — the mechanics behind the suspended and resumed transitions
• Termination Conditions — decides which terminal state an instance reaches
• Shared State Management — holds what must survive the instance that wrote it
• Agent Definition — the revision an instance is created from and pinned to
• Execution Loop — what an instance is doing while it is in the executing state

Applies: Production readiness · Design questions