Workflows vs runbooks

The short version

A runbook is an ordered list of steps, like a recipe. An agent executes the steps top to bottom. Good for incident response, deployment procedures, onboarding sequences, anything where you want a predictable playbook an agent (or a human) can follow.

A workflow is a directed acyclic graph of nodes with explicit inputs and outputs. Data flows from the input node through a pipeline of agent stages to the output node. Good for content pipelines, research-then-write-then-review flows, multi-stage data processing, anything where one stage consumes another’s output.

Both get saved, named, and re-run any number of times. Both can be triggered on a schedule. The difference is shape: runbooks are linear, workflows have structure.

Runbooks — the playbook pattern

A runbook is a named sequence of steps. Each step is one instruction an agent can execute. When you run the runbook, the agent walks the steps in order, executing each one before moving to the next.

Runbook: incident-response
  1. Page on-call via send_email
  2. Snapshot relevant logs to the data store
  3. Run a diagnostic web_fetch against /health
  4. Post a status update to #incidents

The agent reads step 1, executes it, moves to step 2, and so on. Between steps it can pause, wait for a tool result, or decide how to interpret the instruction. But it can’t skip around — runbooks are strictly ordered.

Use runbooks when:

• You have a procedure a human could follow from a sheet of paper
• The order matters
• The steps are mostly self-contained (one step’s output isn’t the next step’s input)
• You want something simple to author

Author a runbook by:

1. Opening /runbooks in the dashboard and clicking New runbook
2. Or asking an agent in chat: “Create a runbook called deploy-production with the following steps…”
3. Or calling the runbooks API directly

You run it with the Execute button on the runbook detail page, or via the API.

Workflows — the graph pattern

A workflow is a directed graph. Each node is a stage. Edges define how one stage’s output flows into another’s input. A valid workflow has one input node, at least one output node, and no cycles.

[input: topic]
    ↓
[researcher] → produces "outline"
    ↓
[creative-writer] → reads outline, produces "draft"
    ↓
[editor] → reads draft, produces "polished"
    ↓
[output: polished]

You run the workflow by providing the top-level input (in this case, a topic string). Exolvra walks the graph: first the researcher runs, its output becomes the input to the writer, the writer’s output becomes the input to the editor, and the editor’s output is the workflow’s final output.

Graphs can fan out (one node feeds three next nodes that run in parallel) and fan back in (those three feed a fourth node that combines their results). The only hard rule is no cycles — if node A feeds into node B, B can’t feed back into A.

Use workflows when:

• The work decomposes into stages where each stage’s output is the next stage’s input
• You want explicit parallelism (fan-out)
• You need a named, versioned pipeline you can call like a function
• The same shape will run over and over with different inputs

Author a workflow by:

1. Opening /workflows in the dashboard and using the visual node editor
2. Or asking an agent in chat: “Build a workflow called blog-post-pipeline with these nodes…”
3. Or calling the workflows API directly

Picking between them

The mental test: if you can describe the work as an ordered checklist where each step stands alone, runbook. If you can describe it as a pipeline where data flows through stages, workflow. If it’s one-off work, don’t bother with either — put it in an issue.

Triggers

Both runbooks and workflows can be attached to a trigger — a cron schedule that runs them automatically. Triggers are how you build recurring automation: a daily digest runbook, a weekly competitor-scan workflow, an hourly health-check runbook. Triggers fire on schedule, execute the linked runbook or workflow, and report results to the project’s activity timeline.

Authoring from chat vs the dashboard

Both authoring paths work. The dashboard gives you a visual editor that’s easier for complex workflows — you drag nodes, connect edges, and see the graph laid out. Chat authoring is faster for simple runbooks and workflows you can describe in one sentence.

The common pattern is: describe the runbook or workflow to a specialist agent in chat, let the agent create it for you, then open the dashboard to review and refine. This plays to the strengths of both interfaces.

Common pitfalls

Using a runbook where you need a workflow. If you’re tempted to write step 2 as “Use the output of step 1 to do X”, you probably want a workflow instead. Runbooks don’t have formal dataflow between steps — each step is its own island.

Making a workflow too deep. Long pipelines (more than ~5 stages) are hard to debug and slow to execute. If you find yourself building a 10-stage workflow, consider splitting it into two smaller ones that can run independently.

Confusing workflows with orchestration patterns. The seven orchestration patterns are about how agents coordinate; workflows are one specific shape (the Pipeline pattern). You can run any pattern ad-hoc without building a workflow — and a workflow is just the pipeline pattern with a name.

Where to go next

• Runbooks — dashboard reference for authoring and running runbooks
• Workflows — dashboard reference for the visual editor
• Triggers — run either on a cron schedule
• Orchestration patterns — the full catalogue including the pipeline pattern