Agent Lifecycle

Understanding the full lifecycle of an agent in Nexus OS.

States

┌──────────┐
│ created  │ ← naos create
└────┬─────┘
     │
     ▼
┌──────────┐
│ stopped  │ ← initial state / after naos stop
└────┬─────┘
     │ naos run
     ▼
┌──────────┐     ┌──────────────────┐
│ running  │────▶│ budget_exceeded  │ ← cost limit hit
└────┬─────┘     └──────────────────┘
     │
     ├──────────────────┐
     ▼                  ▼
┌──────────┐     ┌──────────┐
│completed │     │  failed  │ ← crash / error
└──────────┘     └────┬─────┘
                      │ supervisor restart
                      ▼
                 ┌──────────┐
                 │ running  │ ← restarted
                 └──────────┘

State Transitions

From	To	Trigger
created	stopped	Initial state after `naos create`
stopped	running	`naos run` or supervisor start
running	completed	Agent finishes successfully
running	failed	Agent crashes or errors
running	budget_exceeded	Cost limit reached
failed	running	Supervisor restart
budget_exceeded	stopped	Budget reset

Events

Each transition generates an audit log entry:

bash

naos audit --agent researcher

# [10:00:01] agent.created     researcher
# [10:00:05] agent.started     researcher
# [10:05:30] agent.failed      researcher  "connection timeout"
# [10:05:31] agent.restarted   researcher  (by supervisor: main)
# [10:10:00] agent.completed   researcher

Stopping Agents

Agent State