Spawn Tool

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:

New thread created: The spawned workflow gets its own conversation thread, completely separate from the parent.
Preset applied: The selected preset configures the child agent’s model, temperature, tools, and system prompt.
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.
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.
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.

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:

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:

spawn:builtin://agent(preset1,preset2,preset3)

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

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:

# Spawn disabled - empty presets
tool_filter:
  - tag:default
  - spawn:builtin://agent()  # Empty parens = disabled

Or simply do not include any spawn filter:

# 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

{
  "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:

{
  "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:

{
  "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:

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:

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:

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:

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:

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

Presets - Understanding the presets that configure spawned workflows
Worktrees & Workspaces - Isolating file changes in separate working directories
Multi-Agent Patterns - Broader patterns for coordinating multiple agents

Getting Started

Workflows

Workspace & Git

Agent Features

Settings

Architecture

Reference

Help

About

Important Limitations

How Spawn Works

Configuring Spawn

The spawn_presets Input

Tool Filter Syntax

Disabling Spawn

Spawn Tool Parameters

Basic Example

Resuming a Previous Agent

Running in a Worktree

Use Cases

Research Before Implementation

Specialized Code Review

Breaking Down Complex Tasks

Parallel Independent Tasks

What Gets Returned

Best Practices

​Important Limitations

​How Spawn Works

​Configuring Spawn

​The spawn_presets Input

​Tool Filter Syntax

​Disabling Spawn

​Spawn Tool Parameters

​Basic Example

​Resuming a Previous Agent

​Running in a Worktree

​Use Cases

​Research Before Implementation

​Specialized Code Review

​Breaking Down Complex Tasks

​Parallel Independent Tasks

​What Gets Returned

​Best Practices

​Related Topics

Important Limitations

How Spawn Works

Configuring Spawn

The spawn_presets Input

Tool Filter Syntax

Disabling Spawn

Spawn Tool Parameters

Basic Example

Resuming a Previous Agent

Running in a Worktree

Use Cases

Research Before Implementation

Specialized Code Review

Breaking Down Complex Tasks

Parallel Independent Tasks

What Gets Returned

Best Practices

Related Topics