agent_spawn
System catalog module. One tool: agent (alias Agent). Requires a
coordinator-role agent.
When agent spawn is enabled, the injected spec also includes
context_builder.kv (session-tree key-value store).
Modes (params)
| Mode | Params |
|---|---|
| Spawn one | agent (or specialist), task (or prompt); optional memory_seed, type (isolated / fork), wait, timeout |
| Spawn many | agents: [{agent, task, ...}]; optional wait, timeout |
| Collect one | run_id, wait: true |
| Collect many | run_ids: [...], wait: true |
| Status | run_id (prefer wait instead of polling) |
| List | list: true |
| Cancel | cancel: true, run_id (optional cancel_tree) |
Default spawn is non-blocking (wait defaults false).
type: fork / inherit_context inherits parent conversation context.
Catalog YAML only lists agent / task on the Spec; the live tool
schema from AgentToolSpec() is authoritative for the LLM.
Enable
agent_spawn declared/granted app-wide (tools.modules.agent_spawn
and/or a tools.capabilities.grant entry), plus a role: coordinator
agent with a non-empty delegate_to: [id, ...]. Both are required:
a delegate_to on an agent while agent_spawn is never
declared/granted anywhere in the app is a compile error (DGT-E0409),
and every spawn call is rejected at runtime for a target that isn't
in the caller's own delegate_to - it's the actual authorization
list, not just a prompt hint. See
Multi-agent for the full
mechanics, including the {id, instructions} form.