Supervisors

Supervisors monitor agents and automatically restart them on failure. Inspired by Erlang/OTP supervision trees, they provide fault tolerance for your agent systems.

Strategies

Strategy Behavior
one-for-one Restart only the failed agent
one-for-all Restart all children if one fails
rest-for-one Restart failed agent and all agents started after it

Creating a Supervisor

# Create supervisor with strategy
naos supervisor create main --strategy one-for-one --max-restarts 3

# Add child agents
naos supervisor add main researcher
naos supervisor add main analyzer

# Start the supervisor (starts all children)
naos supervisor start main

Supervisor Tree

View the supervision tree:

naos supervisor status main

Output:

SUPERVISOR: main
Strategy: one-for-one | Max Restarts: 3 | Status: running

CHILDREN:
  ├── researcher  running   4h 12m
  └── analyzer    running   4h 12m

RESTARTS: 0/3

Configuration

Define supervisors in nexus.config.yaml:

supervisors:
  main:
    strategy: one-for-one
    maxRestarts: 3
    children:
      - researcher
      - analyzer
  pipeline:
    strategy: rest-for-one
    maxRestarts: 5
    children:
      - fetcher
      - processor
      - writer

Restart Behavior

When an agent fails:

  1. Supervisor detects the failure
  2. Applies the restart strategy
  3. Increments the restart counter
  4. If max restarts exceeded, supervisor itself fails
  5. Parent supervisor (if any) handles the failure

Nested Supervisors

Supervisors can supervise other supervisors:

naos supervisor create root --strategy one-for-one
naos supervisor add root main
naos supervisor add root pipeline
naos supervisor start root