Supervisor Best Practices

1. Start with one-for-one

Unless you have a specific reason for one-for-all or rest-for-one, use one-for-one. It's the simplest and most predictable.

2. Set Reasonable Max Restarts

• 3 restarts is a good default
• 1 restart for agents that shouldn't fail at all
• 10 restarts for agents in unstable environments

3. Use Supervisor Trees

Don't put all agents under one supervisor. Group related agents:

# ✗ Bad: flat structure
supervisor → [agent1, agent2, agent3, agent4, agent5]

# ✓ Good: grouped by function
root-supervisor
├── api-supervisor → [auth, data]
└── worker-supervisor → [proc1, proc2, proc3]

4. Monitor Restart Counts

High restart counts indicate a systemic problem. Don't just restart — investigate.

5. Combine with Cost Controls

Supervisors respect budget status. An agent with budget_exceeded status won't be restarted.

6. Test Failure Scenarios

Deliberately crash agents during development to verify your supervision tree works correctly.

7. Log Everything

Enable audit logging for supervisor events. You'll need the history when debugging production issues.