documentation
03 dashboard

Workflows

Workflows are directed acyclic graphs of agent work — an input flows through a sequence of specialist steps to an output. Compose them in the dashboard visual editor or ask an agent to build one for you in chat.

What this page is for

The Workflows page is where you author, save, and execute named DAG workflows. Use it when you have a repeatable pipeline that transforms an input through several stages into an output — a research-to-publish pipeline, a data-processing pipeline, an issue-triage pipeline, anything with stages that consume each other’s output.

Not every multi-step task needs a workflow. Ad-hoc work belongs in an issue. Linear playbooks belong in a runbook. Workflows earn their keep when there’s real dataflow between stages — and especially when you’ll run the same shape more than once.

Layout

The Workflows page lists every saved workflow with:

  • Name and description
  • Node count
  • Status — Draft, Published, or Archived
  • Last executed — timestamp
  • Last run outcome — success, failed, or running

Click any workflow to open its detail page, which has three tabs: Graph (the visual editor), Runs (execution history), and API (how to trigger it programmatically).

Common tasks

Create a workflow from the dashboard

  1. Click New workflow in the header
  2. Pick a name and description
  3. You land in the visual editor with one input node and one output node
  4. Drag agent nodes from the palette onto the canvas
  5. Wire edges by dragging from one node’s output port to another’s input port
  6. Every agent node needs a target agent id, an input mapping (which upstream output it reads), and an output name
  7. Click Validate — the editor runs a quick check that the graph has an input, at least one output, and no cycles
  8. Click Save

Create a workflow from chat

You can ask any agent with the workflow tool to create a workflow for you. The agent writes the JSON, calls the workflow tool’s create action, and the workflow appears on the Workflows page ready to run. This is often faster than the visual editor for workflows you can describe in one sentence.

Example chat:

“Create a workflow called blog-pipeline. Input: a topic string. Node 1: researcher writes an outline. Node 2: creative-writer writes a draft from the outline. Node 3: editor polishes the draft. Output: the polished draft.”

The agent produces the JSON, validates it, and saves. Open /workflows to see the new one.

Execute a workflow

  1. Open the workflow detail page
  2. Click Run
  3. Fill in the input values (whatever your input node declared)
  4. Click Execute
  5. Watch the run tab — each node lights up as it starts, the input and output of each stage are visible in real time

You can also trigger a workflow on a cron schedule — see Triggers.

Edit a workflow

Open the workflow detail page and click Edit. You can change names, descriptions, add or remove nodes, and rewire edges. Edits don’t affect runs that are in progress — they take effect on the next execution.

View run history

The Runs tab shows every past execution with its input, output, status, duration, and cost. Click any run to see the step-by-step timeline of what each node produced.

Workflow validation

Every workflow must satisfy four rules:

  1. At least one input node — the entry point
  2. At least one output node — the exit point
  3. No cycles — the graph must be acyclic
  4. Every agent node’s inputs must reference an existing upstream output

The editor runs these checks on save. If your graph fails, the editor highlights the problem and refuses to save. You can also run Validate before saving to preview the check.

Common pitfalls

Too many nodes. Workflows with more than ~5–7 stages get hard to debug and slow to execute. If your graph is growing, consider splitting into two smaller workflows that can be chained via a trigger.

Forgetting fan-out. A workflow with three stages running serially often should have two of them running in parallel. If two stages don’t depend on each other’s output, wire them both to the same upstream node and both outputs into a downstream combiner. You get parallelism for free.

Using a workflow where a runbook fits. If you don’t have real dataflow between stages — if each step is an isolated instruction — use a runbook instead. Workflows have overhead (inputs, outputs, validation) that runbooks don’t.

Where to go next