Workflows

What is a Workflow?

A workflow is a durable, multi-step run. You declare the steps and how they connect once, in TypeScript; the platform then executes every run of it, records every step and event, survives restarts, waits for people when a step needs a decision, and lets you watch, cancel, retry and replay the run from the CLI or the desktop.

Think of it as:

A checklist the platform runs for you - each item is a piece of code, a turn of an agent, a review by a specialist role, or a question for a person - with a full record of what happened at every step.

A run can be started by a person (CLI, desktop, chat), by a skill or tool your agent runs, by a schedule, by a trigger or webhook, by a template, or by another workflow.

Anatomy of a workflow

Definition

A createWorkflow({...}) chain in your project. Pushed and versioned like a skill; deployed with lua workflows deploy.

Run

One execution of a definition with a given input. Has an id (wfr_...), a status, a budget, an input and an output.

Steps

The units of work inside a run. Each step has its own status, attempts, input, output and error.

Events

The append-only ledger of everything that happened to a run, streamed live over SSE and kept after the run ends.

Step kinds

Kind	Builder call	What it does
Code step	`.then(createStep({...}))`	Runs your `execute` function with typed input and output.
Agent step	`.agentStep(id, {...})`	One turn of an agent (yours, or `$self`), with a prompt template and an optional output schema.
Specialist step	`.specialistStep(id, {...})`	A turn of your own agent under an additive role (name, instructions, tool allowlist) - for example a sceptical reviewer.
Tool step	`.toolStep(id, tool, {...})`	Calls one of your `LuaTool`s directly, without a model turn.
Approval	`.approval(id, {...})`	Pauses the run until a person approves or denies (optionally editing the payload).
Signal wait	`.waitForSignal(id, {...})`	Pauses the run until an external system delivers a named signal.
Sleep	`.sleep(ms)` / `.sleepUntil(iso)`	Waits without holding compute.
Map	`.map({...})`	Reshapes data between steps.
Nested workflow	`.workflow(id, ref, input)`	Runs another workflow as a child run.

Steps are arranged with containers: .parallel([...]), .switch([...], otherwise) / .branch([...]), .foreach(step, {...}) and .dowhile(...) / .dountil(...).

Graph form

A workflow’s control flow is a static graph, not a program that runs at push time. Predicates are built from typed helpers (eq, gt, exists, and, …) and data flow from mapping helpers (fromInit, fromStep, template, …). A closure where a predicate or a binding is expected is a build error. This is what lets the platform draw the graph, replay a run locally, and resume a run on a fresh machine.

Two execution tiers

Tier	Where a step runs	Step timeout	Use for
Worker (default)	The agent’s sandbox	1-600 s (default 300 s)	API calls, data shaping, short model turns
Job	Its own container, with an optional git workspace	Up to 4 h per code step, up to 24 h per agent step	Cloning a repository, running a test suite, a full coding session

See Job tier.

Example

import { z } from 'zod';
import { createStep, createWorkflow, fromStep, template } from 'lua-cli';

const fetchSources = createStep({
  id: 'fetchSources',
  inputSchema: z.object({ topic: z.string() }),
  outputSchema: z.object({ urls: z.array(z.string().url()) }),
  timeoutSeconds: 60,
  async execute({ inputData, log }) {
    const res = await fetch(`https://api.example.com/search?q=${encodeURIComponent(inputData.topic)}`);
    const json = (await res.json()) as { url: string }[];
    log(`found ${json.length} sources`);
    return { urls: json.slice(0, 10).map((r) => r.url) };
  },
});

export const researchBrief = createWorkflow({
  name: 'research-brief',
  description: 'Fetch sources, summarise, ask for sign-off.',
  inputSchema: z.object({ topic: z.string() }),
  outputSchema: z.object({ brief: z.string() }),
  budget: { maxCredits: 40 },
})
  .then(fetchSources)
  .agentStep('draft', {
    agentId: 'analyst',
    prompt: template('Write a one-page brief on ${initData.topic} using ${stepResults.fetchSources.urls}'),
    outputSchema: z.object({ brief: z.string() }),
  })
  .approval('signOff', { title: 'Publish this brief?', approver: 'org-admins', timeoutHours: 48 })
  .map({ brief: fromStep('draft', 'brief') }, { id: 'result' })
  .commit();

Workflows next to skills, jobs and templates

	Skill	Job	Workflow	Agent template
What it is	Tools the agent calls during a conversation	Code that runs on a schedule	A durable graph of steps with its own runs	A packaged agent (skills, jobs, workflows, persona) others can install
Runs for	One tool call	One execution	Minutes to weeks	n/a
Waits for people	No	No	Yes (approvals, input, signals)	n/a
Survives restarts	n/a	No	Yes - every step and event is recorded	n/a
Starts from	The model, in chat	The scheduler	CLI, desktop, chat, a skill, a schedule, a trigger, a webhook, a template, another workflow	The marketplace

A workflow can carry its own schedule, so a scheduled workflow replaces the “job that calls an agent” pattern when you want step-level visibility, retries and approvals.

When to use a workflow

Use a workflow when

The work has more than one step and you want each step recorded and retryable
A person must approve, edit or answer something part-way through
Steps run in parallel, over a list, or in a review loop
A step needs hours, a repository checkout, or a coding session
An external system reports back later (a PR review, a payment webhook)

Use a skill or job when

One tool call answers the user in the same turn (skill)
A short piece of code runs on a timer and nobody needs to intervene (job)
You do not need per-step history, replay or a human in the loop

Next Steps

Quick Start

Define, push, deploy, start and approve your first workflow

Authoring

The SDK: steps, containers, bindings, approvals and Workflows.start

Job tier

Long steps, git workspaces and coding turns

Runs and events

Run lifecycle, the events ledger, SSE, approvals and the desktop Runs pages

CLI reference

Every lua workflows subcommand

Welcome

Build with AI

Key Concepts

Featured Demos

What is a Workflow?

Think of it as:

Anatomy of a workflow

Definition

Run

Steps

Events

Step kinds

Graph form

Two execution tiers

Example

Workflows next to skills, jobs and templates

When to use a workflow

Use a workflow when

Use a skill or job when

Next Steps

Quick Start

Authoring

Job tier

Runs and events

CLI reference

​What is a Workflow?

Think of it as:

​Anatomy of a workflow

Definition

Run

Steps

Events

​Step kinds

​Graph form

​Two execution tiers

​Example

​Workflows next to skills, jobs and templates

​When to use a workflow

Use a workflow when

Use a skill or job when

​Next Steps

Quick Start

Authoring

Job tier

Runs and events

CLI reference

What is a Workflow?

Anatomy of a workflow

Step kinds

Graph form

Two execution tiers

Example

Workflows next to skills, jobs and templates

When to use a workflow

Next Steps