Creating Agents

What you'll accomplish: Author an agent as a package, install it, and understand how competencies get attached to it.

Agents are packages, not runtime objects you construct by hand

Hoziron follows a single rule for every package type (ADR-029: install is instantiation): catalog install takes a package, places it on disk, registers it, and makes it live. There is no separate "create" step and no intermediate "installed but not running" state for an agent — install hydrates it straight into the kernel, starting Suspended unless you ask it to auto-activate.

There is no hoziron-cli agent new command and no POST /agents endpoint — agent creation is fully on the package/catalog path.

From a template package

1. Scaffold

hoziron-cli package init --type agent-template claims-intake-agent

This creates:

claims-intake-agent/
├── MANIFEST.toml            # package identity: name, version, description
└── payload/
    └── AGENT.md              # YAML frontmatter + system prompt body

2. Write payload/AGENT.md

The frontmatter declares what the agent has; the markdown body after the closing --- is folded into the agent's system prompt. Here's the real fnol-intake-agent shipped in this repo's seed packages (packages/agents/intake/fnol-intake-agent/payload/AGENT.md), trimmed:

---
description: "FNOL intake agent for SA Personal Lines Auto: multi-channel loss capture, ACORD+SA field extraction, claim draft creation, and empathetic acknowledgement."
competencies:
  - sa-claims-data-extraction
  - client-facing-communication
  - pii-boundary
  - cost-cap-enforcement
  - audit-trail
allow_integration_tools:
  - claim.create
  - policy.lookup
  - notify_send_sms
  - notify_send_whatsapp
  - notify_send_email
---
# FNOL Intake Agent — SA Personal Lines Auto

You are the first point of contact in a South African motor insurer's
claims pipeline. ...

Frontmatter fields (deny_unknown_fields — anything else fails to parse):

There is no triggers field — deny_unknown_fields means a manifest with a triggers: key fails to parse. Every agent implicitly accepts direct API calls; Channel/Cron/Workflow acceptance is determined structurally (channel binding + RBAC, the cron job's own agent binding, the workflow step's own agent reference) rather than declared on the agent — see invocation-model.md.

There is no model field. Routing decides which model an agent's invocation uses (ADR-049/ADR-054) — an agent package cannot override it. A manifest that has a model: block fails to parse.

3. Declare competency dependencies in MANIFEST.toml

Every competency listed in competencies: above must appear in [dependencies] so the catalog resolver can pull it in:

[package]
type = "agent-template"
name = "claims-intake-agent"
version = "0.1.0"
description = "Processes inbound FNOL claims"
license = "Apache-2.0"
min_platform_version = "0.0.5"

[dependencies]
"sa-claims-data-extraction" = ">=1.0.0"
"client-facing-communication" = ">=1.0.0"
"pii-boundary" = ">=1.0.0"

4. Build, lint, publish, install

hoziron-cli package lint ./claims-intake-agent/
hoziron-cli package build ./claims-intake-agent/
hoziron-cli package publish ./claims-intake-agent/     # registry signs at publish time

# Install cascades: pulls in every competency (and its skills) the agent
# declares, then hydrates the agent into the kernel — Suspended by default.
hoziron-cli catalog install claims-intake-agent

# Or install and start it in one step:
hoziron-cli catalog install claims-intake-agent --activate

If you didn't pass --activate, start it explicitly:

hoziron-cli agent activate <agent-id>

See Agent lifecycle for the Suspended/Running state machine.

How competencies attach to the agent

This is not a live "equip" toggle. A competency is folded into the agent — its system prompt appended, its skills attached, its cron schedule registered, its permissions[] checked against what the agent grants — as a step of the agent's own install/hydrate (ADR-044). To change an agent's competencies, edit the competencies: list in AGENT.md, bump the package version, and reinstall:

hoziron-cli package build ./claims-intake-agent/
hoziron-cli package publish ./claims-intake-agent/
hoziron-cli catalog install claims-intake-agent   # upgrade — same name, same UUID, re-realises

See Using competencies for the full realisation model, including multi-competency ordering.

Auto-loading raw manifests (advanced, boot-time only)

A second, lower-level mechanism exists for GitOps-style directory drops of the kernel's native AgentManifest TOML format (not the package AGENT.md frontmatter above — the full kernel schema, including model, resources, capabilities, etc.):

# config.toml
[agents]
manifests_dir = "/data/agents/"   # default: $HOZIRON_HOME/agents/

Every .toml file in that directory is parsed as a kernel AgentManifest and spawned once, at boot only — it is not live-reloaded, and an agent with the same name is skipped (idempotent). This path bypasses the package/catalog system entirely (no dependency resolution, no versioning, no cascade) and is a much lower-level surface than authoring an agent-template package. Prefer the package-based flow above unless you specifically need boot-time raw manifests.

Listing and inspecting agents

# List all agents
hoziron-cli agent list

# Detailed status: state, equipped competencies, uptime, task counters
hoziron-cli agent status <agent-id>

Next steps

• Agent lifecycle management
• Sending messages to agents
• Using competencies

Related:

• Agent lifecycle
• Using competencies
• Reference: CLI agent commands
• Reference: API agents endpoints