NylorunDocsBeta
BuildCompose

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" }:

polish/flow.json
{ "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.

On this page