Creating Workflows

What you'll accomplish: Define multi-agent workflows with JSON, reference agents, pass variables between steps, and run workflows.

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.

Workflow JSON format

{
  "name": "claims-pipeline",
  "description": "End-to-end claims processing",
  "steps": [
    {
      "name": "extract",
      "agent": {"ByName": "document-agent"},
      "prompt_template": "Extract claim details from: {{input}}",
      "output_var": "extracted_data",
      "timeout_secs": 120
    },
    {
      "name": "validate",
      "agent": {"ByName": "validation-agent"},
      "prompt_template": "Validate: {{extracted_data}}",
      "output_var": "validation_result",
      "timeout_secs": 60
    },
    {
      "name": "decide",
      "agent": {"ByName": "decision-agent"},
      "prompt_template": "Given data: {{extracted_data}} and validation: {{validation_result}}, route this claim"
    }
  ]
}

Agent references

Steps reference agents by name or ID:

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

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)

Running a workflow

# Create the workflow
hoziron workflow create ./claims-pipeline.json

# Run it with an initial input
hoziron workflow run claims-pipeline --input "New claim: auto collision on 2024-06-01..."

# Check status
hoziron workflow status <run-id>

Via the API:

curl -X POST http://localhost:4200/workflows/claims-pipeline/run \
  -H "Content-Type: application/json" \
  -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. This ensures sensitive data never leaks across agent boundaries in multi-agent pipelines.

Run lifecycle

The engine retains up to 200 workflow runs. Oldest completed/failed runs are evicted when exceeded.

Next steps

Related: