Loops

By the end of this page you will have a graph that sends work back for another pass and always finishes.

Prerequisites

A graph with at least two connected agents (Canvas tour).
A condition you can test — see Connections & conditions.
Admin or Developer role.

What a loop is

A loop is an ordinary connection that points back to an agent that already ran. Draw the connection, open it, and switch on Send the flow back.

The classic shape is review-and-revise:


   Content Writer  ──▶  Editorial Reviewer
         ▲                      │
         └── send back while it still needs work

The reviewer decides, with a condition on the loop-back connection:


'##VERDICT_REWORK##' in stm.editorial_reviewer_output

While that holds, the writer runs again. When the reviewer approves instead — or the repeat limit is reached — the flow carries on.

A connection with Send the flow back switched on, showing Maximum repeats and What re-runs

A loop needs a condition and a limit

Both are required, and the editor will not save without them.

Setting	Why it is required
A condition	Without one the loop always runs to its limit, which is never what you meant. The editor says: “Add a condition deciding when … should repeat.”
Maximum repeats	Without one the loop could run forever. The field shows an error until you set it.

Maximum repeats can be between 1 and 10.

A loop connection with Maximum repeats empty, showing the required-field error

ℹ️

Because a loop always has both a condition and a ceiling, an Agent Graph cannot run forever. When the repeats are used up the turn carries on with whatever it has.

What re-runs

A loop re-runs more than the agent it points at. You choose how much:

Option	What re-runs
The target and everything after it	The agent you looped back to, and every step downstream of it. This is the default and usually what you want.
The target only	Only that one agent. Use it when the rest of the branch does not depend on the revised output.

Loops and cost

A loop multiplies work, so it has its own budget rule.

Every repeat re-runs the whole set you chose above. A loop of three repeats over four downstream agents is twelve agent runs, not three. That total is checked against Most agent runs per request in Graph settings, and the editor blocks the save if the graph could go over:

With these loops a turn could run up to N agent steps, above the budget of M — raise “Total agent runs per turn” to at least N, lower an iteration count, or narrow a loop’s reset scope

The message names all three fixes. Narrowing the scope to the target only is often the cheapest one.

Nested loops multiply with each other, and the editor checks that too.

Rules the editor enforces

Rule	Message you see
A loop must point back to a step that runs before it	”… must point back to a node that runs before it”
A step may loop back to one target only	”Node … sends the flow back to N different nodes — a node may only loop back to one”
A circle you have not marked as a loop is not allowed	”These connections form a cycle — mark the closing connection as a loop instead”

That last one is the common first mistake. Drawing a connection back to an earlier agent does not make it a loop. You have to switch on Send the flow back, which is also what reveals the limit and scope settings.

Save your changes

Click Save in the header, then test in the preview and watch the Live tab to see how many times the loop actually ran.

Common issues

“mark the closing connection as a loop instead” — You drew a circle. Open the closing connection and switch on Send the flow back.
The loop always runs the full number of times — Its condition is always true. Check the expression itself, and the value the earlier agent actually writes.
Save is blocked over the budget — Lower the repeats, narrow What re-runs, or raise Most agent runs per request.
The loop stopped early — It reached Maximum repeats. The turn continues with what it has.