NylorunDocsBeta
BuildCompose

Flow agents

Compose agents and HTTP tools into an agent whose stages decide what runs next.

A flow agent is an Agent whose body is a flow: its stages, not the model, decide what runs next. Stages run agents, HTTP tools, and nested flows. A flow is data, so it runs no code of yours. It is exported, saved, opened as a session, and observed exactly like a ReAct agent.

agents/report/agent.ts
import { Agent, http } from "@nylorun/agents";
import { z } from "zod";

const researcher = Agent({ id: "researcher", description: "Gathers concise findings." })
  .instructions("Research the topic and return { findings }.")
  .output(z.object({ findings: z.string() }));

const analyst = Agent({ id: "analyst", description: "Summarizes findings." })
  .instructions("Turn the findings into one paragraph. Return { summary }.")
  .output(z.object({ summary: z.string() }));

const publish = http({
  name: "publish",
  input: z.object({ summary: z.string() }),
  output: z.object({ published: z.boolean() }),
  url: "https://reports.example.com/publish",
});

export const report = Agent({ id: "report", name: "Report" }).pipe(researcher, analyst, publish);

Export it from the registry exactly as you export an agent:

agents/index.ts
import { report } from "./report/agent.js";

export const agents = [report];

Stages

StageBehavior
.pipe(a, b, …)Runs agents, HTTP tools, flow agents or flow()s in order; each output is the next input
.switch({ ...cases, default? })Runs the case the previous output names: a string, or its route field
.parallel(branches)Runs named branches at once on the same input; output is keyed by branch
.map(each)Runs each once per item of the previous output: an array, or its items
.loop(body, { verify, max })Runs, asks a verifier, and retries with the feedback until it passes, at most max times

Every stage but .pipe() takes { id } to name it; .loop() takes it beside verify and max. In .pipe(), rename a child with .withId().

A flow agent has no model, so ReAct methods such as .instructions() and .tools() are not on it (flow.no-model). An agent is either a ReAct loop or a flow; mixing them fails the build (agent.mixed-body). Put the ReAct part in its own Agent and add it with .pipe().

Data between stages

The first stage gets the flow's input, and every later stage gets the previous stage's output. Nothing reshapes data between stages, so each agent returns, through its .output() schema, what the next stage needs. An agent after the first stage also sees the flow's input, as the original request, before its own input.

Types flow from each stage's .output() schema to the next stage and to the flow agent's output.

HTTP stages

An HTTP tool is a stage too: in .pipe(), a Switch case, a Map item, or a Loop body. Its input is the previous output, which must match the tool's input (an object). A mismatch the build can see, such as an agent with no .output() before it, is refused (flow.input-mismatch); any other fails the stage when it runs (tool.invalid-input).

The Runtime makes the request as for an agent's HTTP tool, with Nylorun-Agent-Id set to the flow's agent manifest name and the credential taken from the secrets of the Agent the flow session runs on. Its answer is the next stage's input. A failure status, a timeout, or an answer that does not match output fails the stage with its code (http.status, http.timeout, tool.invalid-output, …). Each HTTP stage ends in a node.completed event with its status and durationMs; see Events.

The Tenant's tool policy decides HTTP stages as it decides an agent's HTTP tools, with tool matching the stage's id (the tool's name, or the id given with .withId()) and agent the flow's agent manifest name. A deny fails the stage with tool.denied. An ask holds the request and pauses the flow's turn until it is approved on the flow's session.

A code tool stage (tool({ run })) runs only in the local engine. client.agentManifests.save refuses a flow agent with one, before sending anything; use an HTTP stage instead.

Sequences with flow()

A case, branch, map item or loop body is often more than one stage. Build it with flow(), which has the same stage methods and no id:

import { Agent, flow } from "@nylorun/agents";

export const support = Agent({ id: "support" })
  .pipe(triage)
  .switch({
    bug: flow().pipe(fixer, tester),
    default: general,
  });

Sessions and ids

Each agent in a flow runs in its own session, linked from the flow agent's session and named by the agent:

  • its id, or the id you give it: .pipe(writer.withId("final-writer"))
  • with [i] for each Map item it runs in: implementer[0], implementer[1]
  • under a nested flow agent's id: review/reader

Control stages add nothing, so wrapping a stage in a Loop or moving it out of a Switch keeps its session and transcript. An agent may appear once per flow agent, even in different Switch cases; use it again under a new id (flow.duplicate-leaf): .parallel({ a: reviewer, b: reviewer.withId("reviewer-b") }).

A running flow keeps the manifest version it started with.

Nest flow agents

A flow agent can be a stage of another flow agent, or a subagent of a ReAct agent:

const review = Agent({ id: "review" }).pipe(reader, checker);

export const ship = Agent({ id: "ship" }).pipe(coder, review, prWriter);

A nested flow agent runs in the parent flow's session. Its input is what its stage received.

Input, output, and the Agent

export const issueDesk = Agent({ id: "issue-desk", name: "Issue desk" })
  .input(z.object({ repo: z.string(), issue: z.number().int() }))
  .output(z.object({ url: z.string() }))
  .pipe(triage);
  • .input(schema) types the flow's input, which the first stage receives.
  • .output(schema) types the flow agent's output, for a parent flow or a client.
  • Agents in a flow share the Agent the flow session runs on, its sandbox and its secrets. Their turns run at the same time as any other session's on that Agent. See Agents.
  • A flow whose agents carry skills needs a sandbox: save it with a runtime of kind virtual or pod.
  • A flow always runs on our harness: its harness section's id is nylorun or left out.
  • How many items a Map fans out to, how many iterations a Loop runs, and how many effects one flow turn runs at once are the Tenant's Runtime limits flowMapItems (1,000), flowLoopIterations (100) and flowConcurrency (8). See Runtime limits.

Sessions and manifests

Save a flow agent and open sessions on it exactly as for any agent:

await client.agentManifests.save({ agent: report, runtime: { kind: "none" } });
await client.agents.put("teams/reports", { manifest: "report" });
const session = await client.createSession({ agent: "teams/reports", ownerUserId: "user-123" });

Use input, observe, pending, approve, and cancel as for agents. session.input() sends a string as content and other JSON as data; the flow's first stage receives it. When the tool policy holds a call of one of the flow's agents, that agent's session pauses and so does the flow's turn: session.pending() on the flow session lists the held call with the sessionId that owns it, and the approval goes to that session. See Pauses and control.

On the wire a flow agent's harness section has kind: "workflow", its root stage, and an agents map that embeds every agent it runs, so one agent manifest and one hash cover the whole flow. The agents inside it are not saved on their own. session.observe({ follow: true }) merges the linked agent sessions' events. In Studio, the flow session's Events tab adds a Progress view, the flow's tree with each stage's live status, and an Iterations view of its loops. See Studio.

As a folder

In an agent manifest, flow.json makes the folder a flow agent. Its stages name the agents under the folder's agents/ by id:

brief/
  AGENT.md                 name and description, no body
  flow.json
  agents/researcher/AGENT.md
  agents/writer/AGENT.md
brief/AGENT.md
---
name: brief
description: Researches a topic, then writes a short brief on it.
---
brief/flow.json
{ "chain": [{ "agent": "researcher" }, { "agent": "writer" }] }
brief/agents/researcher/AGENT.md
---
name: researcher
description: Lists what matters about the topic.
---
List the five facts about the topic a newcomer most needs, each with one sentence of context.
brief/agents/writer/AGENT.md
---
name: writer
description: Writes the brief.
---
Write a brief of at most 200 words from the facts you are given, for a reader new to the topic.
$ npx nylorun check brief
brief: ok, agent manifest brief (4 files, agent-folder/1)

flow.json holds one node, written as the manifest's: chain (the folder form of .pipe()), switch, parallel, map, loop, agent, or tool, with an optional id. "tool": "<name>" names tools/<name>.json beside the flow.json. The flow's AGENT.md has frontmatter only and may set inputSchema. An agents/<id>/ with a flow.json of its own is a nested flow over the same agents/. The rules are on Agent manifests. repo-brief-folder is a whole flow as a folder: a switch, a map, a parallel stage, a loop, and an HTTP tool stage.

Examples

See the shipped chain, switch, parallel, map, loop, and ship-feature examples, and repo-brief-folder for a flow written as a folder.

Next step

Start with Pipe, or open Sessions to run a flow agent and Studio to watch its progress.

On this page