Child Spawning

A task can spawn child tasks at runtime — including other durable tasks or entire DAG workflows. Children run independently on any available worker, and the parent can wait for their results before continuing. You can spawn children out of any task (durable or not).

Spawning a child task

You can spawn child tasks similarly to how you run tasks normally, but the implementation details differ slightly by language. Any task can spawn child tasks.

from examples.fanout.worker import ChildInput, child_wf

# 👀 example: run this inside of a parent task to spawn a child
child_wf.run(
    ChildInput(a="b"),
)

export const parentSingleChild = hatchet.task({
  name: 'parent-single-child',
  fn: async () => {
    const childRes = await child.run({ N: 1 });

    return {
      Result: childRes.Value,
    };
  },
});

// Inside a parent task
childResult, err := childWorkflow.Run(hCtx, ChildInput{
	Value: 1,
})
if err != nil {
	return err
}

FANOUT_CHILD_WF.run({ "a" => "b" })

Spawning many children at once

You can also spawn children in bulk, exactly the same as you can spawn any other tasks in bulk.

async def run_child_workflows(n: int) -> list[dict[str, Any]]:
    return await child_wf.aio_run_many(
        [
            child_wf.create_bulk_run_item(
                input=ChildInput(a=str(i)),
            )
            for i in range(n)
        ]
    )

What you can spawn

A durable task can spawn any runnable:

Error handling

try:
    child_wf.run(
        ChildInput(a="b"),
    )
except Exception as e:
    print(f"Child workflow failed: {e}")

Ways to use child spawning

Fan-out: spawning many children in parallel

Process a list of items whose length is only known at runtime. Spawn one child per item, collect all results, then continue. Document processing and batch processing are the canonical examples: when a batch of files arrives, a parent fans out to one child per document; each child parses, extracts, and validates its document in parallel across your worker fleet.

Concurrency controls how many children run at once. Hatchet distributes child tasks across available workers, so adding workers increases throughput without code changes. For rate-limited external services (OCR, LLM APIs), combine with Rate Limits to throttle child execution across all workers.

Agent reasoning loops

An agent loop runs by having a durable task spawn a new child run of itself with updated input until a termination condition is met. Each iteration is a separate child task, so you get full observability in the dashboard. AI agents use this when they reason about what to do next, spawn a subtask (or a sub-workflow), inspect the result, and decide whether to continue, branch, or stop.

Spawning trees of work

A durable task can spawn child durable tasks, each of which may spawn their own children. This creates a tree of work that’s entirely driven by runtime logic — useful for crawlers, recursive search, and tree-structured computations.

// Inside a parent task
childResult, err := childWorkflow.Run(hCtx, ChildInput{
	Value: 1,
})
if err != nil {
	return err
}