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.
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:
import { report } from "./report/agent.js";
export const agents = [report];Stages
| Stage | Behavior |
|---|---|
.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
virtualorpod. - A flow always runs on our harness: its harness section's
idisnylorunor 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) andflowConcurrency(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---
name: brief
description: Researches a topic, then writes a short brief on it.
---{ "chain": [{ "agent": "researcher" }, { "agent": "writer" }] }---
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.---
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.