# Loop (/docs/build/loop)



`.loop()` runs its body, asks a verifier to judge the output, and either returns
the output or runs the body again with the feedback.

```ts
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 [#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:

```ts
{ 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 [#http-verifier]

When your own code should judge the output, serve the check from your service
and pass `http({ url })` as `verify`:

```ts
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](/docs/build/tools), 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](/docs/run/tool-policy) decides it as it decides an HTTP
stage.

## Attempts [#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 [#as-a-folder]

In a [flow manifest's](/docs/build/agent-manifests#flows) `flow.json`, a loop is
`{ "loop": { "run", "verify", "max" } }`, and `verify` takes `{ "agent" }` or
`{ "tool" }`:

```json title="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`](https://github.com/nylorun/agents/tree/main/examples/agents/repo-brief-folder)
names `schemas/verdict.json`.

See the shipped [`loop` example](https://github.com/nylorun/agents/tree/main/examples/agents/loop)
or return to [Flow agents](/docs/build/flows).
