---
title: "Agent Lifecycle"
description: "Understanding the full lifecycle of an agent in Nexus OS. From To Trigger created stopped Initial state after naos create stopped running naos run or supervisor start running completed Agent finishes successfully running"
resource: https://www.aiagents.nexus/docs/manual/agents/agent-lifecycle
generated: { by: "process:nexus-agent-assets", at: 2026-09-07T09:13:03Z }
status: stable
---

# 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
```