Subagents
Add an agent with .subagents() so the model can delegate a self-contained task.
Add an agent with .subagents() to let the model delegate to it.
import { Agent } from "@nylorun/agents";
import { z } from "zod";
const researcher = Agent({
id: "researcher",
description:
"Investigates an order's history. Returns a short summary with the ids it relied on.",
})
.instructions("Investigate one question about one order. Be exhaustive, then be brief.")
.tools(searchOrders, readTicket)
.output(z.object({ summary: z.string(), evidence: z.array(z.string()) }));
const support = Agent({ id: "support" })
.instructions(
"For anything needing more than two lookups, delegate to researcher with a complete, self-contained task.",
)
.tools(lookupOrder, refundOrder)
.subagents(researcher);The tool is named after the child's id and takes { task: string }. The
child's description (required) is what the parent's model reads. The child
starts with a fresh context: it sees its own instructions and the task, nothing
of the parent's conversation, and only its final text (or its .output()
result) comes back.
The child is part of the parent's harness section, so one save of the parent saves both. Children share the Agent the session runs on, its sandbox and its secrets, and keep their own tools, skills, and MCP servers. With memory on, a child may only view the Agent's memories. Several delegation calls in one model response run in parallel.
An empty answer, a failure (with the child's last text marked as evidence), or
a cancelled child reaches the parent's model as a failed tool result, never
as success. Runtime emits delegation.started and delegation.completed.
session.history({ agent }) filters by delegationId (one child invocation)
or by path such as support/researcher (every concurrent child that shares
that path).
This version is one level deep: a delegated agent cannot use agents as tools.
Delegation is not an approval boundary. The Tenant's
tool policy decides a child's MCP and HTTP calls like
the parent's, with agent set to the child's id: deny fails a call to the
child's model, and ask holds it and pauses the parent's turn until it is
approved on the parent's session.
Delegate when the parent should keep the answer. When a specialist should own the rest of the conversation, send the next message with a turn manifest that has the specialist's instructions instead; see Instructions.
As a folder
In an agent manifest without flow.json,
each agents/<id>/ beside AGENT.md is an agent manifest of its own, offered to
the agent as the tool <id> with input { task }, as .subagents() does:
support/
AGENT.md
agents/billing/AGENT.md---
name: support
description: Answers questions about a customer's orders.
---
Answer questions about the customer's orders. Hand a question about an invoice or a refund to
billing, with the order id and what the customer asked.---
name: billing
description: Answers one question about an invoice or a refund. Returns a short answer.
---
Answer the billing question you are given in two sentences at most.$ npx nylorun check support
support: ok, agent manifest support (2 files, agent-folder/1)Its description is what the parent's model reads. It nests one level deep,
has no runtime.json, triggers/ or files/ of its own, and runs on the
Agent the session runs on. The rules are on
Agent manifests.
Flow agents as subagents
A flow agent can be a subagent too, with a description
like any other:
const research = Agent({
id: "research",
description: "Researches a question and returns a short, sourced summary.",
})
.pipe(searcher, summarizer);
const lead = Agent({ id: "lead" })
.instructions("Delegate research questions to research.")
.subagents(research);The flow's manifest is inlined in its parent's, so it is saved with the parent. When
the model calls it, the flow runs on the Runtime in its own linked session, a
fresh one for each call, and its agents run in theirs. The parent's session
shows a node.agent event at lead/research that links to it. The flow's
output comes back as the tool result, and a failed flow is a failed tool
result. Cancelling the parent cancels the flow.
A flow subagent runs only on the Runtime, not in a local run(). A call the
tool policy holds inside the flow waits on the flow's own session, not on the
parent.
See Compatibility for the tested package set.