Your First Agent

What you'll accomplish: Install an agent from the catalog, chat with it interactively, and equip a competency.

Prerequisites

You should have a running, licensed Hoziron instance. If not, pick an install method:

How agents get created

There is no hoziron-cli agent new command and no POST /agents API route — agents are authored as installable packages. An agent template package is installed from a catalog registry, and installing it with --activate spawns and starts the agent in one step:

# Find an agent-template package
hoziron-cli catalog search "customer service"

# Install it and start it immediately
hoziron-cli catalog install customer-service-agent --activate

A fresh Hoziron instance has no packages available until you've configured at least one catalog registry (hoziron-cli catalog registry add <url> --name <name>) pointing at a registry that has packages published to it — either your own (hoziron-server --surfaces registry) or one Hoziron gives you access to.

Chat interactively

There is no default agent — the platform ships empty, and nothing runs until you install it. You must always pass an agent ID explicitly:

hoziron-cli agent list                    # find the ID
hoziron-cli agent chat <agent-id>

Type messages and get responses. Press Ctrl+C to exit.

For scripted, non-interactive sends, call the API directly:

curl -X POST -H "Authorization: Bearer $HOZIRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize the key points of our insurance policy renewal process"}' \
  http://localhost:4200/agents/{id}/send

Managing agent lifecycle via the API

# List agents
curl -H "Authorization: Bearer $HOZIRON_API_KEY" http://localhost:4200/agents

# Detailed status
curl -H "Authorization: Bearer $HOZIRON_API_KEY" http://localhost:4200/agents/{id}

# Suspend / re-activate (gate-checked)
curl -X POST -H "Authorization: Bearer $HOZIRON_API_KEY" http://localhost:4200/agents/{id}/suspend
curl -X POST -H "Authorization: Bearer $HOZIRON_API_KEY" http://localhost:4200/agents/{id}/activate

(Omit the Authorization header if the server is running with auth.mode = "disabled", which is only appropriate on a loopback-only bind — see the authentication guide.)

Equip a competency

Competencies define what an agent can do — its personality, tools, and operational parameters. They attach to an agent by being declared in the agent's own AGENT.md, not through a runtime "activate" command (ADR-044) — see using-competencies.md for the full model.

# List available competencies
hoziron-cli competency list

# Install one from a local directory
hoziron-cli competency install ./my-competency/

---
description: "..."
competencies:
  - claims-intake
---

Adding claims-intake to the agent's competencies: list and reinstalling that agent package (a version bump, not a live toggle) folds the competency's system prompt, skills, and permissions into the agent.

Check agent status

hoziron-cli agent list
hoziron-cli agent status <agent-id>

What just happened

When you installed and activated an agent-template package, Hoziron:

  1. Resolved and installed the package's dependencies (skills, competencies) from the catalog
  2. Registered the agent in the kernel with the model/provider the package (or your override) specifies
  3. Started the agent lifecycle (Created → Running), if you passed --activate
  4. Made it available for messages via CLI and API

The agent maintains its own conversation history, memory scope, and lifecycle state.

Next steps

Now that you have a working agent, explore what's possible:

Related: