Agent Lifecycle

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

State machine

Hoziron agents have two lifecycle states (ADR-056: unified activation gate). There is no Created/Terminated/Stopped state exposed at the platform level — an agent exists (installed) or it doesn't.

Any other transition is rejected with an error naming the current state and the valid commands, e.g.:

Cannot apply 'activate' to agent in Running state. Valid commands: suspend

Suspend is gated only one way

• activate (Suspended → Running) is gate-checked: the platform re-validates the agent's competency/skill dependencies and permission contracts before allowing it to run.
• suspend (Running → Suspended) is ungated — always available. It pauses the agent without discarding state: session, memory, channel bindings, cron registrations, and capability bindings all remain intact and resumable via a later activate. Any task the agent is mid-execution on is aborted.

Both transitions are persisted durably to SQLite (ADR-044 Gap 2) — a suspended agent stays suspended across a restart; it does not silently come back Running.

CLI commands

# Activate a suspended agent (gate-checked)
hoziron-cli agent activate <agent-id>

# Suspend a running agent (always allowed)
hoziron-cli agent suspend <agent-id>

# Check current state, uptime, and task counters
hoziron-cli agent status <agent-id>

REST API

curl -X POST http://localhost:4200/agents/{id}/activate \
  -H "Authorization: Bearer hzk_..."

curl -X POST http://localhost:4200/agents/{id}/suspend \
  -H "Authorization: Bearer hzk_..."

curl http://localhost:4200/agents/{id} \
  -H "Authorization: Bearer hzk_..."

GET /agents/{id} returns state ("Suspended" or "Running"), equipped_competencies, uptime, tasks_received, tasks_completed, and invocation_metrics. It does not return a trust_policy body — agent-level PII policy is not a thing (ADR-049); the field is retained internally for observability only and is never serialized in API responses.

There is no stop or delete verb

• There is no Created or Terminated state, and no Start/Stop/Resume lifecycle command (ADR-056) — only activate/suspend.
• There is no DELETE /agents/{id} or hoziron-cli agent delete (ADR-044). The single removal path is suspend → catalog uninstall:

hoziron-cli agent suspend <agent-id>
hoziron-cli catalog uninstall <agent-package-name>

catalog uninstall performs full teardown (kernel registry, durable SQLite rows, channel bindings, cron jobs, sessions) and is refused if the agent is still Running — suspend it first.

Graceful shutdown

When the daemon receives SIGTERM:

1. Running agents' in-flight tasks are aborted
2. Memory stores are flushed to disk
3. Database connections are closed

Agent lifecycle state is persisted on every activate/suspend call, so on restart each agent resumes from its last persisted state rather than being force-started.

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

• Sending messages
• Scheduling agents
• Creating agents

Related:

• Creating agents
• Sending messages
• Reference: CLI agent commands