> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Delegate work to parallel AI sub-agents

> Have one agent split a task across parallel AI sub-agents: a shared plan, a briefing file, spawn in one turn, then steer, stop and combine the results.

By the end of this guide one agent has split a task, started a sub-agent per piece in parallel, and combined their reports, and you know how to watch, steer and stop them.

Each sub-agent reads in a thread of its own and returns a summary, so the parent's context holds the summary, not the reading ([how this works](https://docs.reliantlabs.io/deep-dives/sub-agents-and-threads.md)).

## Before you begin

* A chat in the Reliant app, or the `reliant` CLI v1.21 or later, signed in ([Sign in and tokens](https://docs.reliantlabs.io/cli/sign-in.md)), with a connected machine ([Run a machine from the terminal](https://docs.reliantlabs.io/cli/run-a-machine.md)).
* A task that splits into independent pieces: one per file, service, question or approach.
* For pieces that edit code at the same time, a workspace each. That is [Run parallel coding agents in separate git worktrees](https://docs.reliantlabs.io/guides/workflows/parallel-agents-git-worktrees.md).

**1. Check that the agent can spawn**

An agent can start sub-agents only when its `spawn_presets` list is not empty. The built-in agent allows `general`, `researcher` and `code_reviewer` by default, and most built-in presets set their own list. To see a preset's list, open **Settings → Presets** and choose **View** ([Configuring sub-agents](https://docs.reliantlabs.io/workflows/spawn.md#configuring-sub-agents)).

Nesting stops at two levels. Your chat's agent can spawn, and so can its sub-agents. Their sub-agents cannot.

**2. Write a prompt that delegates**

Say how to split the work, ask for a plan and a briefing file, and ask for every spawn in the same turn:

```text Chat message theme={null}
Review this repository for missing test cases. First create a plan with one task per Python file.
Write a short briefing to notes/brief.md (what the project is, how to run the tests). Then start
one researcher sub-agent per file, all in the same turn, and give each the path to notes/brief.md
and its task number. Do not edit code. When they report back, combine their findings into one list.
```

* **A plan.** Sub-agents read their nearest ancestor's plan, so it becomes the board they report on. Only its creator can change its shape.
* **A briefing file.** A sub-agent starts with only its prompt. A file it is pointed to holds what the parent already learned.
* **One turn.** `spawn` returns at once, so starting every sub-agent together costs no more than starting one.

In a real run the agent called `create_plan`, wrote `notes/brief.md`, then made both [`spawn`](https://docs.reliantlabs.io/workflows/spawn) calls in one turn:

```json spawn call theme={null}
{ "preset": "researcher", "title": "Review text.py",
  "prompt": "Read the briefing at notes/brief.md first (relative to your working directory). You own task 1 of the plan (task id 2fba1c4c-…): \"Review text.py for untested behaviour\". Mark it in_progress when you start and completed when done. …" }
```

**3. Set the concurrency caps (optional)**

By default one agent runs at most 8 sub-agents at once, and a run at most 16. To set other caps for a run you start from the CLI, put them in a JSON file as numbers:

```json caps.json theme={null}
{ "max_concurrent_sub_agents": 4, "max_concurrent_sub_agents_total": 8 }
```

```bash terminal theme={null}
reliant workflow run agent --project-path . --input-file caps.json -m "Review this repository for missing test cases. …"
```

The caps are ceilings: past about six at once, the model provider starts throttling every agent.

**4. Watch the sub-agents**

In the app, each sub-agent has a thread tab beside **All** and **Main** ([Threads](https://docs.reliantlabs.io/features/threads.md#viewing-thread-history)). From a terminal, `reliant workflow status` prints the run's tree. The run's id is the chat id:

```bash terminal theme={null}
reliant workflow status b7a75115-d553-474a-8fcc-0de377fd36f9
```

```text theme={null}
Execution b7a75115-d553-474a-8fcc-0de377fd36f9
  Workflow:  builtin://agent
  Status:    RUNNING
  Started:   2026-11-20T10:24:42Z

NODE THREADS (child workflows)
  builtin://agent  [RUNNING]
  builtin://agent  [RUNNING]
```

Each `builtin://agent` row is a sub-agent. Sub-agents also mark their tasks on the plan with [`update_task`](https://docs.reliantlabs.io/reference/tools#update_task):

```text theme={null}
Task updated successfully!

ID: 2fba1c4c-8c54-4cb4-9b42-bb0c2e350669
Title: Review text.py for untested behaviour
Status: completed
```

**5. Steer or stop a sub-agent**

To redirect one, send a message in its thread in the app, or ask the main agent to use [`spawn_send`](https://docs.reliantlabs.io/reference/tools#spawn_send). To stop one, ask the main agent to call [`spawn_stop`](https://docs.reliantlabs.io/reference/tools#spawn_stop).

Both take effect at the sub-agent's next step boundary, after its current tool call returns, so `spawn_send` reports the message as queued, not read. [`spawn_status`](https://docs.reliantlabs.io/reference/tools#spawn_status) with `wait: true` shows when an agent has finished or stopped. A wait ends early when any message arrives:

```text theme={null}
Stopped waiting on agent a75bbdc7-9a38-5318-ad37-b84246f450e8 after 20.0s. It is STILL RUNNING and has not been stopped.
...
[A message arrived for you while this call was running, so it returned early. The message follows this result.]
```

**6. Verify the result**

When every sub-agent has reported, the main agent answers. The run's tree shows each sub-agent finished:

```text theme={null}
Execution b7a75115-d553-474a-8fcc-0de377fd36f9
  Workflow:  builtin://agent
  Status:    COMPLETED
  Started:   2026-11-20T10:24:42Z
  Completed: 2026-11-20T10:26:03Z

NODE THREADS (child workflows)
  builtin://agent  [COMPLETED]  27.0s
  builtin://agent  [COMPLETED]  38.0s
```

The answer combined both reports and noted where they disagreed:

```text theme={null}
Both reviewers are done. ... No code was changed. The only file I wrote is the briefing at `notes/brief.md`.

## Missing test cases
| 1 | More than one valid name | `"Bob"` → `"Hello, Bob!"` | A function that always returns `"Hello, Ada!"` would pass the current suite. ...
| 4 | No argument | `greet()` → `TypeError` | The reviewers disagreed on whether this is defined. ...
```

Read each sub-agent's own thread when you want its evidence, not just the summary.

## What you see from inside a sub-agent

A sub-agent two levels below the main agent shows this. Its tool list has `spawn_send`, to report to its parent, and no `spawn`, `spawn_status` or `spawn_stop`, because it is at the depth limit. Its `list_tasks` returns the main agent's plan, past the orchestrator in between, which made none:

```text theme={null}
This plan belongs to an ancestor thread (1ea43ece-9763-5119-b2a2-e23dc8a2de6b) — you are reading the board you were spawned from.
You cannot modify it; update the task you were given, or create_plan for work of your own.
```

## What this does not do

* **Sub-agents do not see your conversation.** They get the prompt, the preset and the project's memory.
* **It does not isolate files.** Without a workspace, every sub-agent works in the parent's checkout. Parallel edits need [a workspace each](https://docs.reliantlabs.io/guides/workflows/parallel-agents-git-worktrees.md).
* **There is no queue.** A spawn past a cap starts nothing; the agent spawns again when a sub-agent finishes.
* **Siblings cannot message each other.** Messages go between a parent and its direct sub-agents.
* **Nesting depth is fixed at 2.** Only the caps are configurable.

## Troubleshooting

> [accordion] Spawn refused, and nothing was started
>
> The agent hit a concurrency cap; the message names it and the input that sets it. The agent waits for a sub-agent to finish and spawns again. To change the caps, see step 3.

> [accordion] Spawning is not available to this sub-agent: spawn nests at most 2 levels deep
>
> A sub-agent of a sub-agent asked to spawn. It does the work itself or tells its parent which parts to fan out. Give depth-2 helpers leaf work.

> [accordion] Spawning is not available to this agent: spawn is offered only by a workflow node that declares spawn presets
>
> The agent's `spawn_presets` list is empty. Choose a preset that lists some, or set `spawn_presets` on the workflow node ([Configuring sub-agents](https://docs.reliantlabs.io/workflows/spawn.md#configuring-sub-agents)).

## Next steps

> [card] [Run parallel coding agents in separate git worktrees](https://docs.reliantlabs.io/guides/workflows/parallel-agents-git-worktrees.md)
>
> Give each agent its own workspace and branch, then join the results.

> [card] [How sub-agents and threads isolate context](https://docs.reliantlabs.io/deep-dives/sub-agents-and-threads.md)
>
> Mailboxes, the plan's single writer, nesting and the caps.

> [card] [Best of Three](https://docs.reliantlabs.io/guides/best-of-three.md)
>
> Three candidates in separate workspaces and a reviewer.

> [card] [Sub-agents reference](https://docs.reliantlabs.io/workflows/spawn.md)
>
> The `spawn` tool's parameters, presets, errors and resuming.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.