Getting started on the canvas

Goal: in the Workflows addon, build a graph that asks an agent something, lets you review the answer, and can be re-run with different inputs.

Prerequisite: threadle-workflows at http://127.0.0.1:4571 (viewer sidebar Workflows). For why the addon exists, see Workflows addon.

Everything here except the agent step is free to run. Pair with Examples — Hello, Approval gate, Workflow params — or follow Quickstart for the same steps with screenshots.

Open the canvas

The addon is its own app (threadle-workflows, :4571). The viewer sidebar Workflows link opens it in a new tab. Routes live under /addon/workflows.

Area	Role
Palette (left)	Workflows tab: saved graphs, examples, recipes. Components: droppable nodes
Canvas	Graph editor. Double-click empty space to add a node
Inspector (right)	Selected node settings — model on agents is required before ▶
Top bar	▶ Run, ≫ (detached / approve-all), ≔ params, export/import
Bottom dock	Run log, Issues (hard blockers), Graph lint (soft hints)

Invalid wire types are refused while you drag, not at run time. See Bottom dock.

A wire is a value moving

A workflow is nodes joined by wires. Press ▶ Run and threadle sorts the graph into dependency order and executes each node once its inputs are ready.

Start with two nodes. A ✎ Prompt and an ⇤ Output. Run it. The text moves. That is the whole model.

Double-click empty canvas to add a node
Drag from a handle and drop on empty canvas to add and wire in one gesture
Invalid connections are refused while you drag, not at run time

A simple ▶ Run with no approval gates starts a server job — you can close the tab and reopen the workflow later. See Running.

▶ Example: Hello

Nodes have jobs

At this level you need four:

Node	Job
✎ Prompt	A text source you type into
⇄ Text → Prompt	Wraps inbound text in a template using `{{input}}`
⟨/⟩ Agent	Runs a real agent through its provider CLI
⇤ Output	A sink that shows and stores the result

▶ Example: Text → Prompt

See Prompt, converter & output.

Running an agent

Drag an agent definition from the palette’s Agents tab, set a model in the inspector, wire a prompt into it, and run.

Two things happen that surprise people:

A session node appears, wired to the agent. The run created a real session in that tool. It exists on disk exactly like one you started in the terminal.
Run it again and the same session continues. The conversation accumulates. The agent keeps its memory across runs.

▶ Example: One-shot agent

See Agents & sessions.

Putting a human in the loop

A ✓ Approval node parks the run and shows the inbound text in an editable box. You can rewrite it before approving. That edit is called a splice, and downstream nodes receive your version.

Reject stops the run.

Runs that include approval (or live-handoff) gates stay in the browser tab so splice works. For unattended runs use ≫ or --approve-all — see Running.

▶ Example: Approval gate

Params make a graph reusable

Define params in ≔ params, then reference them as {{param:name}} inside prompt text or converter templates. threadle asks for values before the run (and validates them against the declared type).

Graph settings in the same modal include parallelism and spend ceiling (USD) — set these before any multi-agent or unattended run.

threadle run <graphId> --param task="the auth refactor" --approve-all

▶ Example: Workflow params

See Params.

Send from the viewer

You do not have to start from an empty canvas. From the viewer, seed a workflow when context already exists:

Action	Result
Session or project → workflow	New graph with session/context wired for distill or agent steps
Blueprint → workflow	Graph seeded from blueprint structure
Library use in workflow	Payload lands on a context node in a new graph

Each action opens the addon on the new graph. Finish wiring, pick models, then ▶ Run. This is the usual handoff from observability to a repeatable job.

Examples and recipes

Under Workflows → examples, clone a teaching graph (Hello, Merge concat, Judge branch, …). Under Workflows → recipes, clone a job graph (plan-implement-review, repo-brief, …) and fill the contract (model, --dir, session slot).

threadle run hello
threadle recipes
threadle run plan-implement-review --param task="…" --approve-all --dir .

When a mechanic confuses you, find the matching row in Examples and read Patterns for when to use it in your own graphs.

You’re done when…

you can build prompt → agent → approval → output from memory
you know why an agent node refuses to run without a model
you understand that re-running continues the same session
you can turn a hard-coded prompt into a param
you know where examples, recipes, and send-from-viewer live

Patterns · Running · Recipes