spawn

Run a child step in an isolated context with optional spawn-local memory layers.

Quick Example

import { spawn, step } from '@noetic/core';

const isolated = spawn({
  id: 'sub-agent',
  child: step.llm({
    id: 'researcher',
    model: 'gpt-4o',
    system: 'Research the topic thoroughly.',
  }),
});

What It Does

spawn runs a child step in an isolated context. The child starts with an empty ItemLog by default, giving it a fresh conversation history and preventing it from polluting the parent context.

You can attach spawn-local memory layers via the optional memory field. These layers use onSpawn hooks to provide items to the child and onReturn hooks to transform results back to the parent. Spawn-local memory fully replaces parent layer propagation, ensuring complete isolation.

This is the primitive for sub-agents, delegation, and sandboxed execution.

API Reference

Property	Type	Required	Description
`id`	`string`	Yes	Unique step identifier
`child`	`Step<I, O>`	Yes	The step to execute in isolation
`memory`	`MemoryLayer[]`	No	Spawn-local memory layers
`timeout`	`number`	No	Timeout in milliseconds

Memory Layers

Spawn-local memory layers control what the child sees and how results are transformed when the child completes.

onSpawn hooks provide items to the child's initial context. Each layer can inject items (e.g., relevant conversation history, cached knowledge, instructions) into the child's empty ItemLog.
onReturn hooks transform the child's results before they flow back to the parent. Layers can summarize, filter, or restructure the output.

import { spawn, step } from '@noetic/core';

const withMemory = spawn({
  id: 'research-agent',
  child: step.llm({
    id: 'researcher',
    model: 'gpt-4o',
    system: 'Research the topic thoroughly.',
  }),
  memory: [
    {
      id: 'context-layer',
      name: 'Context Provider',
      slot: 100,
      scope: 'execution',
      hooks: {
        onSpawn: async ({ parentState, childCtx }) => ({
          childState: parentState,
          items: [
            {
              kind: 'message',
              role: 'user',
              content: [
                {
                  type: 'input_text',
                  text: 'Here is background context for your research.',
                },
              ],
            },
          ],
        }),
        onReturn: async ({ childState, childLog, parentState, result }) => ({
          parentState: { ...parentState, lastResearch: result },
          result: result,
        }),
      },
    },
  ],
});

Timeout

Set a maximum execution time for the child. If the timeout is exceeded, the spawn throws an error.

const spawned = spawn({
  id: 'time-limited',
  child: myStep,
  timeout: 3e4, // 30 seconds
});

Real-World Example: Research Delegation with Memory

import { spawn, step, until } from '@noetic/core';

const researchAgent = spawn({
  id: 'delegated-research',
  child: {
    kind: 'loop',
    id: 'research-loop',
    body: step.llm({
      id: 'researcher-llm',
      model: 'gpt-4o',
      system: 'You are a research assistant. Use tools to find information.',
      tools: [searchTool, fetchTool],
    }),
    until: until.noToolCalls(),
    maxIterations: 10,
  },
  memory: [
    {
      id: 'research-briefing',
      name: 'Research Briefing',
      slot: 100,
      scope: 'execution',
      hooks: {
        onSpawn: async ({ parentState }) => ({
          childState: null,
          items: [
            {
              kind: 'message',
              role: 'user',
              content: [
                {
                  type: 'input_text',
                  text: `Research the following topic: ${parentState.topic}`,
                },
              ],
            },
          ],
        }),
        onReturn: async ({ childLog, parentState, result }) => ({
          parentState: { ...parentState, findings: result },
          result: result,
        }),
      },
    },
  ],
  timeout: 6e4, // 60 seconds
});

fork -- parallel execution without context isolation.
Loop & Until -- use a loop as a spawn child for iterative sub-agents.
Overview -- how spawn fits into the seven primitives.