> ## 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.

# Spawn Tool

> Delegate tasks to sub-workflows from within an agent

The spawn tool allows an agent to delegate tasks to sub-workflows during execution. When an agent encounters a task better suited for a specialist, it can spawn a sub-workflow configured with a specific preset and keep working while that specialist runs in the background.

Think of spawn as "asking a specialist for help." The parent agent describes what needs to be done, the spawned workflow does the work in isolation, and the result comes back to the parent agent in a later turn.

**Spawn is asynchronous.** The call returns a handle immediately — it does not block. The child's result is not in the spawn tool call's result; the parent is notified once the child finishes. Because the parent stays free, it can read files, edit, plan, and spawn additional agents while children are still running, and work discovered mid-run can join an in-flight fan-out rather than waiting for the next wave.

## Important Limitations

Before diving into configuration, understand what spawn can and cannot do:

**Current constraints:**

* **Single workflow target**: Spawn only supports `builtin://agent` as the target workflow. You cannot spawn arbitrary custom workflows.
* **Preset selection only**: The spawned workflow must be configured via a preset. You cannot pass arbitrary parameters or override individual settings.
* **Self-contained tasks**: The spawned workflow runs in its own thread with its own context. It cannot access the parent's conversation history or tool results directly—it only receives the prompt you provide.
* **Results arrive later, not inline**: Because spawn is asynchronous, the parent cannot treat a spawn call as a value it can use in the same turn. It must be written to continue working and react to the result when it lands.

These limitations exist by design. Spawn provides a controlled way to delegate work while maintaining isolation between parent and child workflows.

## How Spawn Works

When an agent calls the spawn tool:

1. **New thread created**: The spawned workflow gets its own conversation thread, completely separate from the parent.
2. **Preset applied**: The selected preset configures the child agent's model, temperature, tools, and system prompt.
3. **Handle returned immediately**: The spawn call settles right away with a handle identifying the child agent. The parent's turn is not held open waiting for the child.
4. **Task executed in the background**: The child workflow runs until completion, following the same agent loop pattern as any other agent workflow, while the parent keeps working.
5. **Result delivered later**: When the child finishes, its final response reaches the parent as a message it reacts to on a subsequent turn, prefixed with the preset name for clarity.

The parent agent can then use this result to inform its next steps. While a child is running, the parent can call `spawn_status` to check on it (passing `wait: true` to block until it finishes, when the parent truly cannot proceed without the answer) or `spawn_send` to give it new instructions mid-flight.

```mermaid theme={null}
sequenceDiagram
    participant P as Parent Agent
    participant S as Spawn Tool
    participant C as Child Workflow
    P->>S: spawn(preset, prompt)
    S->>C: Create new thread + apply preset
    S-->>P: Handle (returns immediately)
    par Child runs in background
        C->>C: Agent loop (LLM → tools → repeat)
    and Parent keeps working
        P->>P: Read, edit, plan, spawn more agents
    end
    C-->>P: [preset] Result text (later turn)
    P->>P: React to result
```

## Configuring Spawn

Spawn availability is controlled by the `spawn_presets` input in workflows that use the agent loop. This input determines which presets appear as options in the spawn tool.

### The spawn\_presets Input

In the built-in agent workflow, `spawn_presets` is configured as a multi-select enum:

```yaml theme={null}
spawn_presets:
  type: enum
  multi: true
  enum:
    - general
    - researcher
    - planner
    - reviewer
    - documentation
    - refactor
    - debug
    - tester
    - reproducer
    - git
    - ux
    - workflow_builder
    - auditor
  default:
    - general
    - researcher
    - reviewer
  description: Presets available for spawn tool (empty = spawn disabled)
```

The key points:

* **Empty selection disables spawn**: If no presets are selected, the spawn tool does not appear in the agent's toolset.
* **Default includes common presets**: By default, agents can spawn general, researcher, and reviewer sub-workflows.
* **Enum values must be valid presets**: Each value must correspond to a preset that exists, built-in or custom.

### Tool Filter Syntax

Behind the scenes, spawn configuration flows through the tool filter system. The spawn filter syntax is:

```text theme={null}
spawn:builtin://agent(preset1,preset2,preset3)
```

For example, the agent workflow builds its tool filter using the `spawn()` CEL function:

```yaml theme={null}
tool_filter: "{{inputs.tools + [spawn(workflow.name, inputs.spawn_presets)]}}"
```

The `spawn()` function takes a workflow reference and a list of presets, returning the spawn filter spec string. If the presets list is empty, it returns an empty string, disabling spawn.

### Disabling Spawn

To disable spawn entirely:

**Via UI**: Deselect all presets in the `spawn_presets` parameter.

**Via workflow configuration**: Omit the spawn filter or use empty presets:

```yaml theme={null}
# Spawn disabled - empty presets
tool_filter:
  - tag:default
  - spawn:builtin://agent()  # Empty parens = disabled
```

Or simply do not include any spawn filter:

```yaml theme={null}
# Spawn disabled - no spawn filter at all
tool_filter:
  - tag:default
```

## Spawn Tool Parameters

When an agent has access to spawn, the tool accepts these parameters:

| Parameter         | Required | Description                                                  |
| ----------------- | -------- | ------------------------------------------------------------ |
| `preset`          | Yes      | Name of the preset to use and it must be in the allowed list |
| `prompt`          | Yes      | Detailed task description for the spawned workflow           |
| `agent_id`        | No       | Agent ID to resume an existing conversation                  |
| `worktree`        | No       | Worktree name to run this workflow in                        |
| `create_worktree` | No       | Configuration to create a new worktree                       |

### Basic Example

```json theme={null}
{
  "preset": "researcher",
  "prompt": "Investigate how authentication is implemented in this codebase. Find all authentication-related files, understand the flow from login to session validation, and document the key components involved."
}
```

### Resuming a Previous Agent

If a spawned agent was previously used, you can resume its conversation:

```json theme={null}
{
  "preset": "researcher",
  "prompt": "Continue investigating the authentication flow. Now focus on how tokens are refreshed.",
  "agent_id": "previously-returned-agent-id"
}
```

### Running in a Worktree

For tasks that modify files, you can isolate changes in a worktree:

```json theme={null}
{
  "preset": "refactor",
  "prompt": "Rename the UserService class to AccountService throughout the codebase.",
  "create_worktree": {
    "name": "refactor-user-service",
    "base_branch": "main"
  }
}
```

## Use Cases

### Research Before Implementation

Spawn a researcher to investigate before making changes:

```text theme={null}
Agent receives: "Add caching to the database queries"

Agent thinks: "I should understand the current database architecture first"

Agent spawns researcher:
  preset: researcher
  prompt: "Analyze the database query patterns in this codebase. Find where queries are made, identify any existing caching, and document the query hot spots that would benefit from caching."

Agent continues with other preparation while the researcher works

When the analysis arrives, the agent proceeds with implementation
using the research findings
```

### Specialized Code Review

Get focused feedback from a specialist:

```text theme={null}
Agent receives: "Review my changes to the authentication module"

Agent spawns reviewer:
  preset: reviewer
  prompt: "Review the recent changes to the auth/ directory. Focus on security implications, error handling, and whether the changes follow the existing patterns in the codebase."

Structured review feedback arrives when the reviewer finishes

Agent summarizes findings for the user
```

### Breaking Down Complex Tasks

Delegate subtasks to specialists:

```text theme={null}
Agent receives: "Modernize the user management system"

Agent creates a plan, then for each major component:

Agent spawns refactor for UserService cleanup
Agent spawns researcher to investigate external integrations
Agent spawns documentation to update API docs
(all three in the same turn — they run concurrently)

Each specialist completes their portion and reports back

Agent synthesizes results and reports overall progress
```

### Parallel Independent Tasks

Because spawn never blocks, independent work should be started together rather than one at a time:

```text theme={null}
Agent needs to:
1. Get research on component A (spawn researcher)
2. Get research on component B (spawn researcher)
3. Search for related files (shell tool)

All three spawn calls are emitted in ONE turn. The agent keeps working —
searching files, writing the next brief — while both researchers run.
Each result arrives as it completes.
```

The anti-pattern is dribbling spawns out one per turn and waiting on each before starting the next. That serializes work which had no dependency between its parts.

## What Gets Returned

The spawn call itself returns a handle for the new agent. The child's final response is delivered separately, once it finishes, prefixed to indicate the source:

```text theme={null}
[researcher] Based on my investigation of the authentication system...

The codebase uses JWT tokens with the following flow:
1. Login endpoint in auth/handlers.go creates tokens
2. Middleware in auth/middleware.go validates on each request
3. Refresh logic in auth/refresh.go handles token renewal

Key files:
- auth/handlers.go:45-120 - Login and logout handlers
- auth/middleware.go:20-80 - Token validation middleware
- auth/models.go:10-50 - Token structures and claims
```

If the child workflow encounters an error, the error message is delivered with an `is_error` flag.

## Best Practices

**Start independent work together**: Spawn does not block, so batching every independent unit into one turn costs no more than spawning one. Hold a spawn back only when it genuinely consumes another agent's output.

**Write detailed prompts**: The spawned workflow only knows what you tell it. Include context about what you are trying to accomplish, what you have already learned, and what specific questions need answering.

**Do not idle while children run**: The parent is free during a fan-out. Use that time to prepare the next brief, read files, or start more units — not to poll.

**Choose appropriate presets**: Match the task to the specialist. Use researcher for investigation, reviewer for quality feedback, refactor for systematic changes.

**Handle results appropriately**: The spawn result is just information. The parent agent should interpret the findings and decide what to do next.

**Do not over-delegate**: Simple tasks do not need spawn. Use spawn when the task benefits from a specialist's focused attention or when you want isolation between concerns.

**Consider worktrees for modifications**: When spawning workflows that will modify files, consider using worktrees to isolate changes until you are ready to merge them.

## Related Topics

* [Presets](/workflows/presets) - Understanding the presets that configure spawned workflows
* [Worktrees & Workspaces](/features/worktrees) - Isolating file changes in separate working directories
* [Multi-Agent Patterns](/workflows/patterns) - Broader patterns for coordinating multiple agents