NylorunDocsBeta
BuildCompose

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
support/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.
support/agents/billing/AGENT.md
---
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.

Next step

On this page