Spawn a child agent with parent-child hierarchy tracking.

Unlike Spawn, this directive specifically spawns another Jido agent and sets up the logical parent-child relationship:

• Child's parent reference points to the spawning agent
• Parent monitors the child process
• Parent tracks child in its children map by tag
• Child exit signals are delivered to parent as jido.agent.child.exit
• Child can use emit_to_parent/3 while attached

The logical relationship is independent from OTP supervisory ancestry. If the child later becomes orphaned, the current parent ref is cleared and the child must be explicitly reattached with AdoptChild before emit_to_parent/3 works again. The active logical binding is mirrored into Jido.RuntimeStore, so child restarts continue to use the current parent relationship instead of stale startup metadata.

Fields

• agent - Agent module (atom) or pre-built agent struct to spawn
• tag - Tag for tracking this child (used as key in children map)
• opts - Additional options passed to child AgentServer. Supports standard child startup options like :id, :initial_state, and :on_parent_death, but not InstanceManager lifecycle/persistence options like :storage, :idle_timeout, :lifecycle_mod, :pool, :pool_key, or :restored_from_storage
• meta - Metadata to pass to child via parent reference
• restart - Restart policy for the child under supervision (default: :transient)

Examples

# Spawn a worker agent
%SpawnAgent{agent: MyWorkerAgent, tag: :worker_1}

# Spawn with custom ID and initial state
%SpawnAgent{
  agent: MyWorkerAgent,
  tag: :processor,
  opts: %{id: "custom-id", initial_state: %{batch_size: 100}}
}

# Spawn with metadata for the child
%SpawnAgent{
  agent: MyWorkerAgent,
  tag: :handler,
  meta: %{assigned_topic: "events.user"}
}

# Override restart behavior for long-lived workers
%SpawnAgent{
  agent: MyWorkerAgent,
  tag: :supervised,
  restart: :permanent
}