Skip to main content

Workflows

An agent is an LLM loop. A workflow is a deterministic DAG of steps that runs the same way every time. Reach for one when you know the sequence up front (fetch → validate → transform → publish) and you want each step to be observable and resumable, with no model guesswork.

A workflow is just an agent with a definition, so you author, push, and run it with the same commands you already use for agents.

Shape​

A workflow is a JSON file with agent_type: "workflow_agent" and a definition holding the steps:

{
  "agent_type": "workflow_agent",
  "name": "api-test",
  "description": "List agents and skills, then summarize",
  "version": "0.1.0",
  "input_schema": {
    "type": "object",
    "properties": { "api_base": { "type": "string" } },
    "required": ["api_base"]
  },
  "definition": {
    "id": "api-test",
    "steps": [
      { "id": "list_agents", "label": "List agents",
        "kind": { "type": "tool_call", "tool_name": "list_agents" }, "execution": "parallel" },
      { "id": "list_skills", "label": "List skills",
        "kind": { "type": "tool_call", "tool_name": "list_skills" }, "execution": "parallel" },
      { "id": "summarize", "label": "Summarize",
        "kind": { "type": "checkpoint", "message": "Scan complete." },
        "depends_on": ["list_agents", "list_skills"] }
    ]
  }
}

Each step declares what it does (kind) and what it waits on (depends_on). Steps with no unmet dependency run together; execution: "parallel" opts a step into concurrent execution with its siblings.

Step kinds​

KindRuns
tool_callA single tool, once (not a full agent loop).
agent_runDelegates to a Distri agent (prompt, tools, skills, model).
api_callAn HTTP request.
scriptA shell/script step with its own cwd, env, and timeout.
conditionBranches on an expression.
checkpointA marker / progress point in the run.
wait_for_inputPauses for human or external input, then resumes.
replyEmits a message (with optional buttons) to a channel.

Step input and skip_if interpolate {input.x}, {steps.step_id.x}, and {env.x}, so a later step can consume an earlier step's output.

Human-in-the-loop​

A wait_for_input step pauses the run until a person (or an external system) supplies the missing value, then continues from where it stopped. Entry points let you start a run partway through, e.g. a review_and_publish entry that presets earlier results and begins at the review step.

Push and run​

Workflows ship through the normal agent commands. There is no separate distri workflows command:

distri agents push my_workflow.json     # deploy it to your workspace
distri run --agent api-test --task "…"  # run it like any agent

distri push (no arguments) picks up workflow JSON alongside your agents, skills, and templates.

Recently unified

Workflows were folded into the agent model, one store, one orchestrator, one push command. Older docs and the legacy distri workflows push/run commands no longer apply; use distri agents push and distri run.

In the client​

useWorkflow and the WorkflowProgress component render step progress and surface wait_for_input prompts. See Using Distri in your product.