Your first workflow

This page takes you from a fresh install to a running, inspectable workflow in about five minutes. Run the workflow a fresh install shows first, then inspect it and make it your own.

If any term below is unfamiliar, the core concepts page has the full glossary.

1. Seed the examples#

If you haven't initialised Roscoe yet, do it now. This writes a set of example workflows into ~/.roscoe/workflows/ so you have something to run.

roscoe init

You should see ~/.roscoe/workflows/demo-1-the-panel.workflow.yaml among the files it created. That's the one we'll use: hand a brain-teaser to five solvers who work it independently, then watch the panel go with the answer most of them land on.

2. Look at the workflow#

Open it in any editor:

$EDITOR ~/.roscoe/workflows/demo-1-the-panel.workflow.yaml

name: demo-1-the-panel
version: 1
description: >-
  Hand a brain-teaser to five solvers who work it independently, no comparing
  notes, then watch the panel go with the answer they mostly landed on.
initial: panel
spendingCap:
  usd: 5
inputs:
  - name: riddle
    type: string
    optional: true
    description: The puzzle for the panel to crack.
    default: >-
      You're on a game show with three doors. Behind one is a car; behind the
      other two, goats. You pick Door 1. The host, who knows what's behind
      every door, opens Door 3 to reveal a goat, then asks whether you'd like
      to switch to Door 2. What should you do to give yourself the best odds
      of winning?
states:
  panel:
    type: consensus
    label: Put it to the panel
    model: claude-haiku-4-5
    prompt: |
      Solve this puzzle. Reason it through carefully on your own, then commit
      to one answer.

        "{{ riddle }}"
    agentCount: 5
    quorum: 3
    validator:
      kind: answer
      choices:
        - Switch to Door 2
        - Stay with Door 1
        - It makes no difference
    on:
      decided: chair
      undecided: chair
  chair:
    type: ai_agent
    label: Explain the answer
    model: claude-sonnet-5
    prompt: |
      Five solvers just worked this puzzle independently: "{{ riddle }}"

      Where they landed: {{ panel.winningValue || "no clear answer" }}
      How the vote split: {{ panel.distribution }}

      Give the person a short, clear readout of the panel's answer.
    on:
      next: done
  done:
    type: end
    label: Answer in
    outcome: success

The real seeded file also points two of the five solvers at a second model and sets a per-agent timeout. This trimmed version keeps the moving parts visible.

The structure to know:

initial: panel sets where execution starts: the state called panel.
spendingCap: { usd: 5 } stops the run once it's spent $5, so a first run can't surprise you.
inputs: declares riddle, an optional string with a default. Run the workflow untouched and it solves the Monty Hall problem above; pass your own riddle to solve something else.
type: consensus runs the same prompt through agentCount (5) independent model calls that don't see each other's reasoning, then checks whether at least quorum (3) of them landed on the same answer. validator: kind: answer restricts each solver to one of the listed choices. See consensus.
on: decided / undecided are the two transitions an answer-mode consensus node can emit. This workflow sends both to chair, so the panel gets an explanation whether or not it converged.
type: ai_agent is a single model call, no voting. chair reads panel.winningValue (the majority answer) and panel.distribution (how the vote split) and writes the readout. See ai_agent.
{{ riddle }} and {{ panel.winningValue }} interpolate: each pulls a value, from an input or an earlier step's output, into a prompt before it runs. That's how data flows between nodes.
type: end with outcome: success is a terminal state. The run finishes with a green check.

For the full schema, see YAML structure.

3. Run it#

Make sure the server is up:

roscoe serve

Then in another terminal:

roscoe run demo-1-the-panel

Five solvers work the Monty Hall problem independently. Watch for a split: some fall for the 50/50 trap, most don't. The majority answer routes to chair, which writes a short explanation, and the run ends with a green check.

4. Inspect the run#

Open the web UI:

Production install: http://localhost:7777
Dev (bun run dev): http://localhost:3000

The Runs view lists every run, newest first. Click the one you just triggered. You'll see:

The graph of the workflow with the path that was taken highlighted.
A per-node trace with each state's inputs and outputs, plus the transition key it emitted.
The structured result each step returned: panel's five individual votes and the winning answer, then chair's readout.

This is the same trace you'll use to debug anything that goes wrong, so it's worth poking around now. Notice how panel's vote split threads into chair's prompt, and from there into the plain-language readout.

5. Make it your own#

Swap in your own riddle without touching the file. Pass it as a named input with --input:

roscoe run demo-1-the-panel --input riddle="Is it worth paying extra for the aisle seat on a two-hour flight?"

Re-run it a couple of times. Each solver reasons independently, so the vote split moves around from puzzle to puzzle, and sometimes from run to run, while chair keeps making sense of whatever the panel lands on.

Where to next#

YAML structure — every field, every type.
consensus and ai_agent — full reference for the two node types you've used.
Core concepts — the vocabulary in one place.