README
¶
parallel-spawn — one turn fans out three background subagents
A single assistant turn emits three spawn_agent calls in one
model response; the children run in parallel under the
background.Manager; their completion reports drain back into the
parent's next turn as a [Background reports] block. Credential-free
end to end — the parent replays a scripted transcript, the children
replay their own.
What this shows
- Parallel function calling as the fan-out gesture: the scripted
parent's first response carries three
spawn_agentfunction calls, so ONE turn launches all three workers. background.NewManager(background.WithProvider(...), ...)+background.NewSpawnTools(mgr)registered on the parent viaagent.WithTools, withagent.WithBackgroundManager(mgr)stamping the parent back-reference — the documented construction order.- Children calling the autonomous driver's
report_donetool; the manager turns that into acompletedalert carrying the done detail. - The pre-turn drain:
parent.Run(ctx, "")(the same empty-prompt shape a wake-loop turn uses) prepends every pending report to the model's prompt viaPrependPendingAlerts— the parent model reacts to all three reports in one turn.
Run it
go run ./examples/parallel-spawn
Hermetic: scripted + per-spawn scripted mocks, temp dir for the transcripts, no listeners. Exits 0.
Key APIs
| Step | API |
|---|---|
| manager | background.NewManager, WithProvider, WithDefaultBudgets, WithMaxConcurrent, WithAllowAdhoc |
| per-spawn replay | mock.NewScriptedPerCall (a fresh script cursor per Model call) |
| tools on the parent | background.NewSpawnTools (spawn_agent + stop_agent) |
| wiring | agent.WithBackgroundManager (+ construction order in Manager docs) |
| observe | Manager.OnAlert (non-consuming), Manager.List, Handle.Done/Status |
| drain | Agent.Run(ctx, "") → Manager.PrependPendingAlerts internally |
Two subtleties worth copying:
mock.NewScriptedPerCall, notmock.NewScripted. The manager asks its provider for one LLM per spawn, andNewScriptedhands the same replay — one cursor — to all of them, so three children would divide the two-turn transcript between them.NewScriptedPerCallbuilds a fresh replay perModelcall, so every child starts at turn 0.background.WithAllowAdhoc(true). These children are ad-hoc: the parent's model writes eachsystem_promptat spawn time. That is off by default, because an unattended daemon should only spawn operator-vetted specs — a daemon fans out by name instead (spawn_agent{agent: "recon-logs"}against a subagent declared in config). The example opts in so the fan-out gesture, rather than the roster wiring, is what you read.
What you should see
== turn 1: spawn fan-out ==
-> spawn_agent(recon-logs)
-> spawn_agent(recon-metrics)
-> spawn_agent(recon-traces)
== waiting for the three subagents (parallel) ==
recon-... -> completed
== reports pending for the next turn (prompt-visible) ==
[Background reports]
- [recon-logs] (completed) area scanned; nothing anomalous found
== turn 2: empty prompt — Run drains the reports into the model ==
text: All three scouts reported back. ...
Next pointers
- Manager lifecycle without a model in the loop (direct
Spawn):examples/background-monitor. Synchronous in-turn delegation:examples/with-subagent. - Budgets, depth caps, alert semantics:
docs/background-subagents-design.md.
Documentation
¶
Overview ¶
Example: one assistant turn fans out three independent background subagents via the spawn_agent tool family, and their reports drain back into the parent's next turn — all with no LLM credentials.
The parent runs on the scripted mock provider: its first recorded response emits THREE spawn_agent function calls in a single model response (parallel function calling), so one turn launches the whole fan-out. The spawned children run on a scripted provider supplied via background.WithProvider — each child replays a small transcript that calls report_done, which pushes a "completed" report onto the manager's alert channel.
The parent's next Run — an empty prompt, the same shape a wake-loop turn uses — drains those reports via PrependPendingAlerts: the model sees a "[Background reports]" block before anything else.
go run ./examples/parallel-spawn
Narrative printed: spawn fan-out -> parallel completion -> reports drained into the next turn.
Source Files