hoziron-cli agent

Manage agents — lifecycle control (activate/suspend), status, chat, and property updates.

Synopsis

hoziron-cli agent <subcommand> [options]

Subcommands

There is no hoziron-cli agent new, spawn, start, stop, kill, or resume — agent creation goes through catalog install, and lifecycle changes are only activate/suspend. See Creating an Agent below.

Agent Lifecycle

Hoziron agents have two platform-level lifecycle states (ADR-056: unified activation gate) — there is no Created/Terminated/Stopped state exposed above the kernel; 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.

• activate (Suspended → Running) is gate-checked (ADR-056): the platform re-validates competency/skill dependencies and permission contracts before allowing the agent to run.
• suspend (Running → Suspended) is ungated and always available. It pauses the agent without discarding state — session, memory, triggers, cron registrations all remain intact and resumable via a later activate. Any in-flight task is aborted.

There is no stop, kill, resume, start, new, or spawn verb — an earlier Created → Running → Suspended/Terminated state machine and a separate DELETE /agents/{id} were both retired. The only removal path is suspend then catalog uninstall (which refuses to run while the agent is still Running):

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

Creating an Agent

Agents are packages, not runtime objects constructed by hand — there is no hoziron-cli agent new command and no POST /agents endpoint (ADR-029: install is instantiation). They come from installing an agent-template package, the same package/catalog pipeline used for skills, competencies, and integrations:

# Author an agent-template package
hoziron-cli package init --type agent-template claims-processor
# Edit MANIFEST.toml + payload/AGENT.md (frontmatter + system prompt), then:
hoziron-cli package lint ./claims-processor/
hoziron-cli package build ./claims-processor/
hoziron-cli package publish ./claims-processor/     # registry signs at publish time

# Install — hydrates the agent into the kernel, Suspended by default
hoziron-cli catalog install claims-processor
# Or install and start it in one step:
hoziron-cli catalog install claims-processor --activate

catalog install --activate runs the same activation path as hoziron-cli agent activate — including the ADR-056 gate check — so a template that references a provider/contract you haven't installed will fail activation with a clear error rather than silently creating a half-configured agent. See Creating Agents for the full AGENT.md frontmatter reference.

hoziron-cli agent list

List all registered agents.

hoziron-cli agent list [--json]

Examples

# Human-readable table
$ hoziron-cli agent list
ID                                    NAME              STATE      COMPETENCY
550e8400-e29b-41d4-a716-446655440000  assistant-01      Running    —
7c9e6679-7425-40de-944b-e07fc1f90ae7  claims-processor  Running    claims-intake
a1b2c3d4-e5f6-7890-abcd-ef1234567890  research-bot      Suspended  —

# JSON output — mirrors GET /agents (see ../api/agents.md)
$ hoziron-cli agent list --json
{
  "agents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "assistant-01",
      "state": "Running"
    }
  ]
}

hoziron-cli agent status

Show detailed status for an agent.

hoziron-cli agent status <id>

Prints the raw JSON response from GET /agents/{id} (see ../api/agents.md) — there is no separate human-readable formatting for this subcommand.

Example

$ hoziron-cli agent status 550e8400-e29b-41d4-a716-446655440000
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "assistant-01",
  "state": "Running",
  "equipped_competency": null,
  "tasks_received": 42,
  "tasks_completed": 40
}

hoziron-cli agent activate

Activate a suspended (or newly created) agent: Suspended → Running.

hoziron-cli agent activate <id>

ADR-056 gate check

Every call to activate — whether via this command or catalog install --activate — unconditionally checks that every contract the agent's competencies require has an installed provider. There is no caching: the check runs fresh on every activation attempt.

Examples

$ hoziron-cli agent activate a1b2c3d4-e5f6-7890-abcd-ef1234567890
Agent a1b2c3d4-e5f6-7890-abcd-ef1234567890 activated

# Gate check failure
$ hoziron-cli agent activate a1b2c3d4-e5f6-7890-abcd-ef1234567890
Error: Cannot activate agent: contract(s) [claimcenter] have no installed
provider. Install a provider that declares these contracts before activating.

hoziron-cli agent suspend

Suspend a running agent (preserves state, stops processing): Running → Suspended.

hoziron-cli agent suspend <id>

Example

$ hoziron-cli agent suspend 7c9e6679-7425-40de-944b-e07fc1f90ae7
Agent 7c9e6679-7425-40de-944b-e07fc1f90ae7 suspended

# Resume later
$ hoziron-cli agent activate 7c9e6679-7425-40de-944b-e07fc1f90ae7
Agent 7c9e6679-7425-40de-944b-e07fc1f90ae7 activated

hoziron-cli agent chat

Start an interactive chat session with an agent, directly from the terminal.

hoziron-cli agent chat <id>

Type exit or quit to end the session; each line you enter is POSTed to /agents/{id}/send and the response is printed.

Example

$ hoziron-cli agent chat 550e8400-e29b-41d4-a716-446655440000
Chat with agent: 550e8400-e29b-41d4-a716-446655440000 (type 'exit' to quit)

> What's the status of claim #CLM-2024-001?
Claim #CLM-2024-001 is Open, pending adjuster review.

> exit

hoziron-cli agent set

Set a property on an agent (sent as PUT /agents/{id} with {field: value}).

hoziron-cli agent set <id> <field> <value>

Examples

# Change the model
$ hoziron-cli agent set 550e8400 model "groq/llama-3.1-70b-versatile"
Agent 550e8400 updated: model = groq/llama-3.1-70b-versatile

# Set a custom property
$ hoziron-cli agent set 550e8400 system_prompt "You are a helpful assistant."
Agent 550e8400 updated: system_prompt = You are a helpful assistant.

Common Patterns

Bulk agent management (scripting)

# Suspend all running agents
hoziron-cli agent list --json | jq -r '.agents[] | select(.state == "Running") | .id' | \
  xargs -I {} hoziron-cli agent suspend {}

See Also

• competency.md — Equipping competencies to agents
• package.md — Authoring agent-template packages
• catalog.md — Installing agent-template packages (--activate)
• memory.md — Agent memory management
• ../api/agents.md — Underlying REST API