Skip to main content
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:
  • A named workflow target: Each spawn filter names the workflow it can start, such as builtin://agent, along with the presets allowed for it. The stock agent, and the structured-agent used for typed responses, are the ones the builtins use; an agent can only spawn what its tool filter lists.
  • 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. A wait never makes the parent deaf. If a message arrives for the parent while it waits — from the user, from its own parent, or from any of its children finishing or reporting — the wait ends early so the parent reads it on its next turn. Nothing is stopped: the child it was waiting on keeps running, and the parent calls spawn_status with wait: true again to resume. shell_wait behaves the same way. Once an agent has spawned at least one child, spawn_status, spawn_send and spawn_stop are on its tool list from its next turn on — there is nothing to load by hand. Before its first spawn, spawn_status is left off, so an agent that never fans out does not pay for its schema on every request.

​
When a sub-agent stops on an error

A sub-agent whose step fails — its retries are used up, or the provider returns an error — stops on its own. Nothing else in the chat pauses. Its parent is told why, and so are you, in the sub-agent’s thread. A stopped sub-agent is not finished. A message sent to it resumes it where it stopped, and it reads that message on its first turn:
  • From the app: select the sub-agent’s thread and send it a message, or use Message this agent to resume it on its spawn card.
  • From its parent: spawn_send to the agent’s id, or spawn with its agent_id.
A provider usage limit is not a failure: a sub-agent that hits one waits for the limit to reset and then carries on by itself, and spawn_status reports it as waiting. A stopped sub-agent stays resumable after the chat goes idle. If the chat has finished its turn when you message the sub-agent, the chat starts again where it was: the sub-agent resumes first, and the main agent picks up when the sub-agent reports back. Switching a sub-agent’s model needs the chat to be running or paused; while it is idle, the sub-agent resumes on the model it had. A sub-agent that completed, or that you stopped, is finished: a message to it is refused, and its parent can start it again with spawn and its agent_id. A sub-agent whose parent sub-agent has finished is not resumed by a message, because its result would have nowhere to go; send a message to the chat and the main agent can resume it with spawn. If the parent stopped on an error too, message the parent first.

​
Branching a chat that has sub-agents

Branching a conversation copies its transcript, including the spawn calls, but not ownership of the agents those calls started. The original conversation keeps running, keeps receiving their results, and stays the only one that can wait on, message, or stop them. In the branch, spawn_status lists those agents under Inherited from … (read-only), and spawn_status(agent_id=…) without wait shows each one’s status and latest answer. spawn_send, spawn_stop and spawn_status(wait: true) on an inherited agent are refused with an error naming the conversation that owns it. Agents the original spawns after the branch point are not visible in the branch at all. The branch’s model is told this up front. Every branch starts with a hidden note, which the model sees but the transcript does not show. The note names the chat it was branched from and the fork point, and says the original may still be running. When there are inherited agents, it also says their results will not be delivered to the branch and that the model should re-spawn whatever it needs.

​
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 a multi-select preset input:
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 the general, researcher, and code_reviewer presets. A preset can set its own list, as most built-in presets do.
  • Any agent preset can be listed: The picker offers every preset tagged agent, built-in, project or your own.

​
The spawn field

Behind the scenes, the agent’s Call LLM node lists what it may spawn in its tools_config, as spawn:<workflow>(<presets>) specs:
The agent workflow builds its spec with the spawn() CEL function:
The spawn() function takes a workflow reference and a list of presets and returns the spec string. If the presets list is empty, it returns an empty string, which disables spawn.

​
Disabling Spawn

To disable spawn entirely: Via UI: Deselect all presets in the spawn_presets parameter. Via workflow configuration: Leave spawn out of the node’s tools_config, or pass builtin://agent an empty spawn_presets:

​
Spawn Tool Parameters

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

​
Basic Example

​
Resuming a Previous Agent

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

​
Running in a Worktree

For tasks that modify files, you can isolate changes in a worktree. The parent creates one with the worktree tool (action: create, a name and optionally a base_branch), then names it in the spawn:
The worktree appears in the app’s Workspaces like any other, so you can open it, review its branch, and archive it when you are done.

​
Use Cases

​
Research Before Implementation

Spawn a researcher to investigate before making changes:

​
Specialized Code Review

Get focused feedback from a specialist:

​
Breaking Down Complex Tasks

Delegate subtasks to specialists:

​
Parallel Independent Tasks

Because spawn never blocks, independent work should be started together rather than one at a time:
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:
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. Keep about six running at once: Past roughly six concurrent sub-agents the provider starts throttling, and every agent slows down. More units of work than that is fine: start six, and start the next as each one finishes. The spawn tool tells the model the same. Choose appropriate presets: Match the task to the specialist. Use researcher for investigation, code_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.