Loop
Run, verify, and retry with the feedback until the output passes.
.loop() runs its body, asks a verifier to judge the output, and either returns
the output or runs the body again with the feedback.
import { Agent, VerdictSchema } from "@nylorun/agents";
import { z } from "zod";
const coder = Agent({ id: "coder" })
.instructions("Answer the task. Prefer one clear sentence.")
.output(z.object({ answer: z.string() }));
const checker = Agent({ id: "checker" })
.instructions(
"Check the response's answer: it must be a complete sentence. Return pass, and feedback when it fails.",
)
.output(VerdictSchema);
export const polish = Agent({ id: "polish" }).loop(coder, { verify: checker, max: 3 });verify and max are required. A pass returns the output. A fail runs the body
again with the feedback as its input. After max failed attempts the flow fails
with loop.exhausted. A loop never runs more iterations than the Tenant's Runtime limit
flowLoopIterations (100 by default): the iteration past it fails with
loop.too-many-iterations, so a max above the limit is never reached.
Verifier agent
A verifier agent gets { task, response, iteration } in a fresh session for
each attempt, so it never sees an earlier verdict. It returns a verdict:
{ pass: true }
{ pass: false, feedback: "What to improve" }Give it .output(VerdictSchema) from @nylorun/agents. Feedback is required
when pass is false. Any other answer fails the loop with
loop.verify-failed.
HTTP verifier
When your own code should judge the output, serve the check from your service
and pass http({ url }) as verify:
import { Agent, http } from "@nylorun/agents";
export const fixTests = Agent({ id: "fix-tests" }).loop(fixer, {
verify: http({ url: "https://ci.example.com/verify", credential: "ci" }),
max: 3,
});An HTTP verifier takes url, and optionally method (POST, PUT or
PATCH), credential, and timeoutMs; it has no name or input, and its URL
names no {field}. Any other method, or a {field} in the URL, throws when it
is built. The Runtime makes one request per attempt
through its Tool Gate, as for an HTTP tool, with the body
{ input, output, iteration }: the Loop's input, the attempt's output, and its
number. Your service answers { pass: true } or { pass: false, feedback }.
Any other answer, a failure status, or a timeout fails the loop with
loop.verify-failed. Each request ends in a node.completed event, and the
Tenant's tool policy decides it as it decides an HTTP
stage.
Attempts
Each verdict is recorded as a loop.verified event. The body keeps its session
across attempts, so it sees its earlier tries; wrapping an existing stage in a
Loop keeps that session. The body can be an agent, an HTTP tool, a flow agent or
a flow(): .loop(flow().pipe(coder, tester), { verify, max: 5 }) repeats the
whole sequence. A body that starts with an HTTP stage is retried with the Loop's
input, not the feedback. Runtime checkpoints each iteration. In Studio, the
Progress and Iterations views of the session's Events tab show its
status and history.
As a folder
In a flow manifest's flow.json, a loop is
{ "loop": { "run", "verify", "max" } }, and verify takes { "agent" } or
{ "tool" }:
{ "loop": { "run": { "agent": "coder" }, "verify": { "agent": "checker" }, "max": 3 } }coder and checker are agents/coder/ and agents/checker/. Give the
verifier agent an outputSchema with a boolean pass and a string
feedback, as VerdictSchema is; the editor of
repo-brief-folder
names schemas/verdict.json.
See the shipped loop example
or return to Flow agents.