# Map (/docs/build/map)



`.map()` runs its child once per item of the previous stage's output,
concurrently, and returns the outputs in item order. The output must be an
array, or an object with an `items` array; an empty list returns `[]`.

```ts
import { Agent } from "@nylorun/agents";
import { z } from "zod";

const planner = Agent({ id: "planner" })
  .instructions("Plan section titles for the topic. Return { items: string[] }.")
  .output(z.object({ items: z.array(z.string()) }));

const sectionWriter = Agent({ id: "section-writer" }).instructions(
  "Write one short section for the given title.",
);

const editor = Agent({ id: "editor" })
  .instructions("Join the sections you are given into one digest, in order.")
  .output(z.object({ digest: z.string() }));

export const digest = Agent({ id: "digest" })
  .pipe(planner)
  .map(sectionWriter, { id: "write" })
  .pipe(editor);
```

Each item is one input to the child. To give each item more than one field, make
the previous agent return objects in `items`, for example
`z.object({ items: z.array(z.object({ title: z.string(), position: z.number() })) })`.

Any other output fails with `map.not-a-list`.

Each item runs in its own session: `section-writer[0]`, `section-writer[1]`,
and so on. An item can run a sequence, `.map(flow().pipe(write, edit))`, and
every agent in it gets the index (`write[2]`, `edit[2]`). If one item fails, the
others are cancelled.

A list longer than the Tenant's Runtime limit `flowMapItems` (1,000 by
default) fails the stage with `map.too-many-items` before any item starts. See
[Runtime limits](/docs/run/limits).

Use `.map()` for data-driven fan-out. Use [Parallel](/docs/build/parallel) when
branches have different names or behavior known when you write the flow.

See the shipped [`map` example](https://github.com/nylorun/agents/tree/main/examples/agents/map),
then use [Loop](/docs/build/loop) for repeat-until-accepted work.
