Workflows
Loops
A Loop node fans out over a list with a mapper agent, then collapses results with a reducer agent. Configure parallelism, batch size, and timeout.
What you'll learn
- How the mapper / reducer split works
- How to set batch size and timeout
- When to use a Loop instead of a Sub-Workflow
Configure a Loop node
- 1
Pick the input list
Point the Loop at a list field from upstream — trigger.tickets or agent.results. The Loop will iterate one element at a time. - 2
Choose the mapper agent
The mapper runs once per element. Its input is the single item; its output goes into the result array. Common mappers: classify, score, summarize, enrich. - 3
Choose the reducer agent
The reducer runs once at the end with the full array of mapper outputs. Its job is to aggregate — count, rank, summarize, pick top-N. Optional: skip the reducer to return the raw array. - 4
Set batch size
Controls how many mapper instances run in parallel. Higher batch size means faster completion but more concurrent LLM calls. Default 5; raise it for short tasks, lower it for rate-limit-sensitive models. - 5
Set timeout
Per-element timeout in seconds. An element that exceeds it is marked failed and excluded from the reducer input. The whole Loop succeeds even if some elements fail.
Loop vs. Sub-Workflow
Reach for a Loop when you have a homogeneous list and want parallel fan-out. Reach for a Sub-Workflow when each step is a different shape of work that needs its own graph. Loops are optimized for throughput; Sub-Workflows are optimized for composition.
Frequently asked questions
- What happens to partial failures?
- Failed elements are recorded in the trace with their error and excluded from the reducer input. Successful elements still flow through. You can configure the Loop to fail the whole workflow if more than N elements fail.
- Is there a limit on list size?
- The Loop streams elements through the batch executor, so list size itself is not bounded. The practical limits are total LLM cost and the workflow's overall timeout.
- Can the reducer call tools?
- Yes. The reducer is a regular agent — it can call any tool the agent is configured with. A common pattern is reducer-writes-to-database after mapper-classifies-each-item.