Iterator
The ∀ Iterator turns one text wire into a list. Downstream, an agent runs once per item instead of once for the whole blob.
It requires an input — an unwired iterator is a loose end.
Split modes
Section titled “Split modes”| Mode | Node label | Behavior |
|---|---|---|
lines | lines | Split on newlines; each line trimmed, blanks dropped |
blocks | blank-line blocks | Split on blank lines; each block trimmed, blanks dropped |
json | JSON array | JSON.parse the text; array elements become items (non-string elements are re-serialized) |
Several inbound wires are joined with a blank line before splitting.
max caps the list — leave it empty (∞) for no limit. The cap is applied after splitting, so it takes the first N items.
JSON that fails to parse is a difference between the two runners: the canvas run raises iterator: input is not a JSON array, while a detached run falls back to treating the whole text as a single item.
The run log records the result: ∀ iterator: 3 item(s) (lines).
What downstream sees
Section titled “What downstream sees”The iterator emits both the original joined text and the item list. Only an agent consumes the list:
- ⟨/⟩ Agent — runs once per item, in order, and the result texts are collected.
- Anything else — sees the unsplit text and behaves normally.
The per-item loop is sequential, not parallel, and it reuses one conversation: after the first run the agent continues with the session id returned by the previous item. Ply concurrency does not fan an iterator out across workers.
Collected replies leave the agent joined with \n\n---\n\n, and the item list is carried forward so a further agent could iterate again. The session the agent emits is the one from the last item.
✎ Prompt ──▶ ∀ Iterator ──▶ ⟨/⟩ Agent ──▶ ⇤ Output 3 lines lines 3 runs joined- A per-item run costs a provider call each. Pair an iterator with max and a tripwire when the upstream list length is not under your control.
- Bypass on the iterator forwards the inbound text untouched, so the agent runs once — a quick way to test the tail of a graph.
- Partial runs that start below an iterator forward text unsplit; only an executed iterator fans out.
Examples
Section titled “Examples”Both ship in the bundled Examples table:
| Example | Level | Shape |
|---|---|---|
iterator-lines | intermediate | prompt (3-line checklist) → ∀ lines → output — shows the split alone, no agent needed |
iterator-agent | advanced | prompt (3 questions) → ∀ lines, max 3 → Cursor ask → output — one agent run per question |
threadle run iterator-lines --approve-alliterator-agent calls a real provider CLI unless you are in the test suite.
Related
Section titled “Related”- Prompt, converter & output — feeding the iterator
- Agents & sessions — the node that consumes items
- Ply — concurrency across independent branches
- Knot — merging results back together
- Examples