1 · Beginner

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

Everything here except the agent step is free to run.

---

1.1 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 — and run it. The text moves. That’s 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

▶ Example: Hello wire

---

1.2 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.

---

1.3 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:

1. 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.
2. 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.

---

1.4 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.

▶ Example: Splice gate

---

1.5 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).

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

▶ Example: Workflow params

See Params.

---

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

---

Next

2 · Intermediate — branches, lists, and guard rails.