Agent Lifecycle

The agent state machine is defined in vox/agents/lifecycle.py via the AgentState enum. VOX uses nine states with explicitly validated transitions (can_transition_to()).

States

class AgentState(Enum):
    BOOTING = auto()   # Capability initialization
    IDLE = auto()      # Ready but not active
    ACTIVE = auto()    # Operational, processes events
    PAUSING = auto()   # Pause transition
    PAUSED = auto()    # Suspended, events queued
    RESUMING = auto()  # Resume transition
    STOPPING = auto()  # Stop transition
    STOPPED = auto()   # Terminated
    FAILED = auto()    # Irreversible boot error

Allowed transitions

From	To
BOOTING	IDLE, ACTIVE, FAILED, STOPPING
IDLE	BOOTING, STOPPING
ACTIVE	PAUSING, STOPPING
PAUSING	PAUSED, STOPPING
PAUSED	RESUMING, STOPPING
RESUMING	ACTIVE, STOPPING
STOPPING	STOPPED
STOPPED	BOOTING
FAILED	BOOTING

Lifecycle operations

Method	Effect
agent.boot()	IDLE → BOOTING → ACTIVE (or FAILED). Injects vault secrets, initializes store/memory DBs, boots each capability, emits on_boot.
agent.pause()	ACTIVE → PAUSING → PAUSED
agent.resume()	PAUSED → RESUMING → ACTIVE; drains the queued-event buffer
agent.stop()	ACTIVE/PAUSED/IDLE → STOPPING → STOPPED; cancels agent tasks
agent.shutdown()	Full teardown: cancel tasks, cap.shutdown() on every capability, clear roles/capabilities

Paused event buffering

While an agent is PAUSED, emitted events are buffered in a bounded EventQueue (capacity 256). On resume, buffered events are drained and dispatched. If the buffer is full, new events are dropped (counted via dropped).

Boot failure

A capability that fails to boot, a vault access error, or missing required params moves the agent to FAILED. Agents with missing capabilities or SENSITIVE_PARAMS are flagged DEGRADED (see VOXAgent and Capabilities Reference).