Creating Workflows

What you'll accomplish: Author a multi-agent workflow as a package, install it, and run it.

What is a workflow?

A workflow is a named sequence of steps where each step routes a task to a specific agent. The engine supports sequential pipelines, parallel fan-out, conditional branching, and iterative loops.

Workflows are packages, not runtime objects you construct by hand

Like agents, workflow creation went through the same package/catalog consolidation (Issue #357): there is no hoziron-cli workflow create command and no runtime "define a workflow" API call anymore. You author a workflow-template package, build/publish it, and catalog install it — install cascades into installing every agent the workflow declares in agents_required.

hoziron-cli package init --type workflow-template claims-pipeline

This scaffolds:

claims-pipeline/
├── MANIFEST.toml
└── payload/
    └── workflow.json

workflow.json format

The package name in MANIFEST.toml becomes the workflow's name — workflow.json itself does not carry a name field. Here is a trimmed version of the real fnol-claims-pipeline package shipped in this repo (packages/workflows/claims/fnol-claims-pipeline/payload/workflow.json):

{
  "description": "End-to-end First Notice of Loss pipeline for South African Personal Lines Auto: intake, validation & enrichment, fraud signalling, severity scoring, severity routing, and STP resolution.",
  "agents_required": [
    "fnol-intake-agent",
    "fnol-validation-agent",
    "fnol-fraud-signal-agent",
    "fnol-severity-agent",
    "fnol-routing-agent",
    "fnol-resolution-agent"
  ],
  "steps": [
    {
      "name": "Phase 1 — Intake & Notification",
      "agent": { "ByName": "fnol-intake-agent" },
      "mode": "Sequential",
      "prompt": "A loss has been reported. ...\n\n---\n\nInput data:\n{{input}}",
      "timeout_seconds": 180
    },
    {
      "name": "Phase 2 — Validation & Enrichment",
      "agent": { "ByName": "fnol-validation-agent" },
      "mode": "Sequential",
      "prompt": "You receive the intake record ...",
      "timeout_seconds": 300
    }
  ]
}

agents_required declares the cascade dependency set (every named agent must resolve to an installed agent-template package). Each step's agent field resolves against those installed agents by name.

Field name flexibility

The step parser accepts either of two spellings for two fields — useful because the scaffold template and the seed packages in this repo don't agree with each other:

Canonical field	Accepted alias
`prompt_template`	`prompt`
`timeout_secs`	`timeout_seconds`

If both spellings are present, the canonical one wins. mode and error_mode string values are matched case-insensitively ("Sequential", "sequential", "FanOut", "fan_out", "fanout" are all accepted).

Agent references

Steps reference agents by name or ID:

{"agent": {"ByName": "claims-agent"}}
{"agent": {"ById": "550e8400-e29b-41d4-a716-446655440000"}}

A bare string ("agent": "claims-agent") is also accepted as shorthand for ByName. Resolution happens at run start — if an agent is not found, the workflow fails before executing any steps.

Template variables

Steps can store their output and reference previous outputs:

{{input}} — the current step input (previous step's output, or initial input for the first step)
{{var_name}} — any previously stored output_var
Variables persist for the entire workflow run
Undefined variables are left as-is (not replaced)

Build, lint, publish, install

hoziron-cli package lint ./claims-pipeline/
hoziron-cli package build ./claims-pipeline/
hoziron-cli package publish ./claims-pipeline/

# Cascades: installs every agent in agents_required (and each agent's own
# competency/skill dependencies) before installing the workflow itself.
hoziron-cli catalog install claims-pipeline

Running a workflow

Workflows are addressed by their UUID (assigned at install time), not by name, once installed:

# Find the workflow's ID
hoziron-cli workflow list

# Run it with an initial input
hoziron-cli workflow run <workflow-id> "New claim: auto collision on 2024-06-01..."

# Check status of a specific run
hoziron-cli workflow status <run-id>

# List all runs for a workflow
hoziron-cli workflow runs <workflow-id>

Via the API:

curl -X POST http://localhost:4200/workflows/{workflow-id}/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hzk_..." \
  -d '{"input": "New claim: auto collision..."}'

PII boundaries

Data flowing between agents passes through PII tokenization. Each agent's memory scope is isolated — no cross-agent memory access, enforced structurally by the kernel's BoundMemoryHandle (a handle bound to one agent's ID has no method that can address another agent's scope). This ensures sensitive data never leaks across agent boundaries in multi-agent pipelines. PII escalation (what may leave the box tokenised to a cloud LLM, what may be hydrated to a named tool destination) is governed entirely by the operator-owned carrier PII policy file — never by the workflow or agent definitions.

Run lifecycle

Runs are durably persisted (checkpoint-per-step, ADR-044) — a crash or restart mid-run resumes from the last completed step rather than losing the run. A step that dispatched a state-changing write to a system of record (e.g. claim.create) but crashed before confirmation is never blindly re-executed: it escalates to Escalated for a human to check, rather than risking a duplicate write.

A workflow definition also has an admission state

Independent of any single run, the workflow definition has its own Active/Draining/Suspended admission state (distinct from a run's RunState) that governs whether start_workflow_run accepts new runs at all — see Agent lifecycle for the analogous agent state, and ADR-044 for the drain semantics.

Known limitation: the FNOL reference pipeline

The seed fnol-claims-pipeline package (used above) is the real 6-agent regulatory example this platform is built around, but it does not currently complete end-to-end: it fails partway through Phase 3b — Severity Scoring (tracked as Issue #589). A simplified 4-step, single-agent stand-in workflow demonstrates the trigger → reasoning → claim-minted flow working today while the real pipeline's Phase 3b issue is open. Don't present the full 6-agent pipeline as working end-to-end until #589 is resolved.

Next steps

Related: