afy spawn

Spawning an Aetherfy child agent

afy spawn <parent-agent> <child-agent> starts a type: job agent on behalf of a parent agent. It takes exactly two positional arguments: the parent first, the child second.


afy spawn orchestrator page-worker

The spawned Aetherfy agent runs once and terminates. This is the fan-out primitive: a long-running parent dispatches units of work to short-lived children, each with its own payload.

Flags accepted by afy spawn in the Aetherfy CLI

Flag	Short	Type	Default	Description
`--payload`	`-p`	string	empty	JSON payload to pass to the spawned agent
`--payload-file`	`-f`	string	empty	Read payload from JSON file
`--stdin`		bool	false	Read payload from stdin

All three payload flags are mutually exclusive — pass at most one.

There is no --wait flag on afy spawn. Unlike afy agents run --wait, the Aetherfy CLI cannot block on a spawned run; it returns as soon as the spawn is accepted.

Passing a payload to an Aetherfy spawned agent


# Inline JSON
afy spawn orchestrator page-worker --payload '{"url":"https://example.com/4","depth":2}'
 
# From a file
afy spawn orchestrator page-worker --payload-file ./task.json
 
# From stdin — useful when the payload is generated upstream
echo '{"url":"https://example.com/4"}' | afy spawn orchestrator page-worker --stdin

Spawning with no payload at all is valid:


afy spawn orchestrator page-worker

Requirements for an Aetherfy spawn to succeed

Four conditions must hold, or Aetherfy rejects the spawn.

Requirement	Detail
Parent has spawning enabled	`spawn.enabled: true` in the parent’s `aetherfy.yaml`
Child is a task agent	The child must be declared `type: job`
Neither agent is paused	A parent or child paused with `afy agents stop` cannot spawn or be spawned
Child is an allowed worker	If the parent declares `spawn.workers`, the child must appear in that list

The parent side of the contract, in aetherfy.yaml:


name: orchestrator
type: service
runtime: python3.12
entrypoint: main.py
spawn:
  enabled: true
  workers:
    - page-worker
    - summariser

Spawning can also be enabled at creation time with afy agents create <name> --spawn-enabled, and the current setting is shown as Spawn Enabled in afy agents status <name>. See /cli/agents.

Output of afy spawn in the Aetherfy CLI

afy spawn honours the global -o json.

Key	Meaning
Spawn ID	The identifier of this spawn
Deployment ID	The child deployment the spawn ran against
Machine ID	The machine running the spawned agent — printed only when present
Status	The state of the spawn as accepted by Aetherfy


afy spawn orchestrator page-worker -o json

Observing an Aetherfy spawned run

Spawned runs are deliberately not listed by afy agents runs <child>. They belong to the parent’s history, not the child’s, so the child’s run list stays a record of its own scheduled and manual runs.

To see what a spawned Aetherfy agent did, read its logs:


afy logs page-worker
afy logs page-worker --follow
afy logs page-worker --level ERROR --since 30m

Log filters and the follow-mode caveats are documented on /cli/logs.

Choosing between afy spawn and afy agents run on Aetherfy

Both start a type: job Aetherfy agent once. They differ in who is doing the starting and in whether you can wait.

	`afy spawn <parent> <child>`	`afy agents run <agent>`
Arguments	Parent and child	One agent
Requires a parent relationship	Yes	No
Requires `spawn.enabled` on a parent	Yes	No
Payload flags	`--payload`, `--payload-file`, `--stdin`	`--payload`, `--payload-file`
Can block on the result	No — there is no `--wait`	Yes — `--wait`, polling up to 30 minutes
Appears in `afy agents runs` for that agent	No	Yes

Use afy agents run to trigger a task agent yourself. Use afy spawn to model fan-out, where one Aetherfy agent dispatches work to another.

Note that afy spawn prints an Error: line and still exits 0 on failure, so a script must inspect the output rather than the exit status. The full exit-code table for the Aetherfy CLI is on /cli.