Agent Lifecycle

What you'll accomplish: Understand the agent state machine and manage agent lifecycle transitions.

State machine

States and valid transitions

Current State	Valid Commands	Description
Created	`start`	Agent exists but isn't processing messages yet
Running	`stop`, `suspend`	Agent is active and responding to messages
Suspended	`resume`	Agent is paused — preserves state but stops processing
Terminated	`delete`	Agent is stopped — can only be deleted

Any other transition is rejected with an error:

Cannot apply 'start' to agent in Running state

CLI commands

# Start an agent
hoziron agent start <agent-id>

# Stop (terminates the agent)
hoziron agent stop <agent-id>

# Suspend (preserves state, stops processing)
hoziron agent suspend <agent-id>

# Resume a suspended agent
hoziron agent resume <agent-id>

# Delete a terminated agent
hoziron agent delete <agent-id>

API vs CLI behavior

CLI (hoziron agent new): agents are started automatically after creation
API (POST /agents): agents start in Created state and require POST /agents/{id}/start

This difference exists because API consumers may want to configure the agent before starting it.

Suspend vs Stop

	Suspend	Stop
State preserved	Yes	No
Can resume	Yes	No
Use case	Temporary pause	Permanent shutdown
Next state	Running (via resume)	Terminated (then delete)

Use suspend when you want to pause an agent temporarily (maintenance, cost control). Use stop when you're done with the agent.

Graceful shutdown

When the daemon receives SIGTERM:

All running agents are suspended
Memory stores are flushed to disk
Database connections are closed

On next startup, suspended agents can be resumed.

Per-agent overhead

Memory: ~10 MB base + conversation context (proportional to history length)
Storage: ~1 MB per 1000 messages
CPU: Negligible when idle; bursts during LLM interactions

Next steps

Related: