# Subagents (/docs/build/subagents)



Add an agent with `.subagents()` to let the model delegate to it.

```ts
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](/docs/run/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](/docs/run/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](/docs/build/instructions#instructions-for-one-turn).

## As a folder [#as-a-folder]

In an [agent manifest](/docs/build/agent-manifests#subagents) 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:

```text
support/
  AGENT.md
  agents/billing/AGENT.md
```

```markdown title="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.
```

```markdown title="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.
```

```text
$ 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](/docs/build/agent-manifests#subagents).

## Flow agents as subagents [#flow-agents-as-subagents]

A [flow agent](/docs/build/flows) can be a subagent too, with a `description`
like any other:

```ts
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](/docs/compatibility) for the tested package set.

## Next step [#next-step]

<Cards>
  <Card title="Tools" description="HTTP tools the Runtime calls." href="/docs/build/tools" />

  <Card title="Flow agents" description="Compose agents into a fixed path." href="/docs/build/flows" />
</Cards>
