Batching over a list
Run an agent once per item of a list input — fanned out in parallel, with an ordered list of results back.
Batching turns one agent into a fleet. Point the agent at a list input and it runs once per item — concurrently, up to a parallelism you set — and its response becomes a list of the per-item results, in order. There's no separate "loop" node to wire: batching is a property of the agent itself, driven by the shape of its input.
It's the natural partner of anything that produces a list — for example, the Document Splitter chunks a long document, and a batching agent processes every chunk in parallel.
Turning it on
Batching lives in the agent's configuration — in the agent builder's Configuration card, and in an agent node's Configuration on the canvas. Toggle Run once per item of a list input.
The toggle is available when the agent's input includes a list; until then it reads "Available when the agent's input is bound to a list." In the agent builder, that means an Object input with at least one Array field — and because a batching agent returns a list, give it an Object output too. On the canvas, the agent's input can be bound to any list an upstream step produces.
Inline agents only
Batching applies to agents configured in place. A node that references a standalone built agent can't batch — the reference runs the agent as-is.
Choosing the list
An agent's input can be a list itself, or an object with a list somewhere inside it. When more than one list is in scope, a List to batch over selector appears:
- the whole input — the input itself is the list; the agent runs once per element. (Canvas only, where the input can be bound directly to a list.)
- A field — one field of the input object is the list. The agent runs once per element of that field, and every other field is passed along unchanged to each item — useful for sending the same context or instructions with every chunk.
Parallelism
Parallel items controls how many items run at once (default 5). Each item is a full agent call of its own, so this is the knob that trades speed against how hard you hit your model provider.
What comes out
The agent's output becomes an ordered list — one entry per input item, in the same order as the input, regardless of which items finished first. If the agent has a structured output, downstream steps see an array of that type, so wiring the result into the rest of a workflow works like any other list.
Two edge cases worth knowing:
- An empty list runs nothing and returns an empty list.
- A failed item fails the execution. If one item can't complete, the whole node fails rather than silently returning a result with gaps — a quietly missing item is exactly the bug batching exists to eliminate.
In the trace
Batching stays fully observable. On the canvas, a batching agent wears a batch chip. While it runs, the live view counts items done out of the total. In the execution trace, selecting the agent's row explains the fan-out — how many items ran, over which list, and how many in parallel — and each item appears beneath it as its own entry — Item 1 of N, with its own steps, tokens, cost, and duration. Nothing is averaged away.
The builder's Test panel sends chat messages, so it can't feed a batching agent a list. Try one from a workflow, or from the API or CLI with an input file.