hoziron-cli workflow

Run multi-agent workflows and inspect their execution. This is a read/execute surface only — workflow authoring happens through the package pipeline, not the CLI.

Synopsis

hoziron-cli workflow <subcommand> [options]

Subcommands

There is no hoziron-cli workflow create, update, or delete. Issue #357 removed the runtime create/update side doors: author a workflow package (hoziron-cli package init --type workflow-template), build it, and install it via hoziron-cli catalog install, matching the skill/competency/agent/integration pattern. See Authoring a Workflow below.

Authoring a Workflow

# Scaffold a workflow-template package
hoziron-cli package init --type workflow-template claims-pipeline
# Edit MANIFEST.toml + the workflow definition JSON (see below), then:
hoziron-cli package build ./claims-pipeline/
hoziron-cli package publish ./claims-pipeline/

# Install it — this registers the workflow (and any referenced agent templates)
hoziron-cli catalog install claims-pipeline

Workflow Definition Format (JSON)

The package's payload/workflow.json — scaffolded by hoziron-cli package init --type workflow-template <name>. The workflow's name comes from the package name in MANIFEST.toml; workflow.json itself carries no name field. agents_required lists every agent-template package the workflow depends on — catalog install cascades into installing each one (and its own competency/skill dependencies) before installing the workflow.

{
  "description": "End-to-end claims processing pipeline",
  "agents_required": [
    "claims-intake-agent",
    "policy-validator-agent",
    "claims-router-agent"
  ],
  "steps": [
    {
      "name": "intake",
      "agent": { "ByName": "claims-intake-agent" },
      "prompt_template": "Process this claim: {{input}}",
      "mode": "Sequential",
      "timeout_secs": 120,
      "error_mode": "Fail"
    },
    {
      "name": "validation",
      "agent": { "ByName": "policy-validator-agent" },
      "prompt_template": "Validate coverage for: {{input}}",
      "mode": "Sequential",
      "timeout_secs": 60,
      "error_mode": { "Retry": { "max_retries": 2 } }
    },
    {
      "name": "routing",
      "agent": { "ByName": "claims-router-agent" },
      "prompt_template": "Route this claim based on validation: {{input}}",
      "mode": "Sequential",
      "timeout_secs": 30,
      "error_mode": "Skip"
    }
  ]
}

Field name flexibility

The step parser accepts two spellings for two fields (the scaffold template and this repo's seed packages don't agree with each other); if both 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).

Step Modes

Error Modes

Agent References

Steps reference agents by name or ID:

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

Template Variables

• {{input}} — the workflow's initial input (first step) or previous step's output (subsequent steps)
• {{var_name}} — any variable stored via output_var in a previous step

Run Lifecycle

A run moves through more states than just "succeeded or failed":

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

hoziron-cli workflow list

$ hoziron-cli workflow list
ID                                     NAME                            STEPS
a1b2c3d4-e5f6-7890-abcd-ef1234567890   claims-pipeline                 3
b2c3d4e5-f6a7-8901-bcde-f12345678901   onboarding-flow                 5

hoziron-cli workflow get

Prints the raw JSON response from GET /workflows/{id} (see ../api/workflows.md).

$ hoziron-cli workflow get a1b2c3d4-e5f6-7890-abcd-ef1234567890
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "claims-pipeline",
  "description": "End-to-end claims processing pipeline",
  "steps": [
    {"name": "intake", "agent": {"ByName": "claims-intake-agent"}, "mode": "Sequential"},
    {"name": "validation", "agent": {"ByName": "policy-validator"}, "mode": "Sequential"},
    {"name": "routing", "agent": {"ByName": "claims-router"}, "mode": "Sequential"}
  ]
}

hoziron-cli workflow run

Execute a workflow with input text (POST /workflows/{id}/run). Prints the raw JSON response.

hoziron-cli workflow run <id> <input>

Example

$ hoziron-cli workflow run a1b2c3d4 "New auto claim: rear-end collision on I-95, policy POL-2024-200"
{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "workflow_name": "claims-pipeline",
  "input": "New auto claim: rear-end collision on I-95...",
  "state": "Completed",
  "step_results": [
    {"step": "intake", "output": "Claim data collected...", "duration_ms": 2300},
    {"step": "validation", "output": "Coverage confirmed...", "duration_ms": 1100},
    {"step": "routing", "output": "Routed to auto-collision queue", "duration_ms": 800}
  ],
  "output": "Claim #CLM-2026-042 created. Routed to adjuster queue: auto-collision-moderate.",
  "started_at": "2026-06-04T10:15:00Z",
  "completed_at": "2026-06-04T10:15:04Z"
}

hoziron-cli workflow runs

List all runs for a workflow.

$ hoziron-cli workflow runs a1b2c3d4
RUN ID                                 STATE        STARTED
c3d4e5f6-a7b8-9012-cdef-123456789012   Completed    2026-06-04T10:15:00Z
d4e5f6a7-b8c9-0123-def0-234567890123   Failed       2026-06-04T09:30:00Z

hoziron-cli workflow status

Show detailed status of a specific run (GET /runs/{run_id}). Prints raw JSON.

Same response shape as workflow run above (GET /runs/{id} returns the full run status, same format as POST /workflows/{id}/run).

$ hoziron-cli workflow status c3d4e5f6-a7b8-9012-cdef-123456789012
{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "workflow_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "workflow_name": "claims-pipeline",
  "input": "New auto claim: rear-end collision on I-95...",
  "state": "Completed",
  "step_results": [
    {"step": "intake", "output": "Claim data collected...", "duration_ms": 2300},
    {"step": "validation", "output": "Coverage confirmed...", "duration_ms": 1100},
    {"step": "routing", "output": "Routed to auto-collision queue", "duration_ms": 800}
  ],
  "output": "Claim #CLM-2026-042 created. Routed to adjuster queue: auto-collision-moderate.",
  "started_at": "2026-06-04T10:15:00Z",
  "completed_at": "2026-06-04T10:15:04Z"
}

Failed run

$ hoziron-cli workflow status d4e5f6a7-b8c9-0123-def0-234567890123
{
  "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
  "state": "Failed",
  "step_results": [
    {"step": "intake", "output": "...", "duration_ms": 2100}
  ],
  "error": "Step 'validation' timed out after 60 seconds",
  "started_at": "2026-06-04T09:30:00Z",
  "completed_at": "2026-06-04T09:31:02Z"
}

Key Concepts

PII Boundary

Data flowing between workflow steps passes through PII tokenization. Each agent only sees tokenized versions of sensitive data from other agents. This is automatic and transparent.

Memory Isolation

Each agent in a workflow maintains its own separate memory scope. Agent A cannot read Agent B's memory, even within the same workflow. Data passes between agents only through step outputs.

Default Timeout

Steps default to 30 seconds if timeout_secs is not specified. For LLM operations, 60–300 seconds is typical.

See Also

• agent.md — Agents referenced by workflows
• package.md — Authoring workflow-template packages
• catalog.md — Installing workflow-template packages
• ../api/workflows.md — Underlying REST API