Spawning and Swarms

Open Astra supports hierarchical multi-agent orchestration where a root agent decomposes a complex task and delegates subtasks to specialized sub-agents. Sub-agents run with sandboxed permissions and share state via a blackboard. The root agent synthesizes results after all sub-agents complete.

Spawning model

Agent spawning is governed by three requirements that must all be satisfied:

1. The parent agent must have spawn.enabled: true in its config
2. The target agent ID must be listed in the parent's spawn.allowedTargets
3. The current spawn depth must be less than spawn.maxDepth (default 2, max 3)

agents:
  - id: orchestrator
    spawn:
      enabled: true
      allowedTargets:
        - research-agent
        - code-agent
        - review-agent
      maxDepth: 2

  - id: research-agent
    spawn:
      enabled: false    # Sub-agents cannot spawn further

Permission sandboxing

When a parent spawns a sub-agent, the sub-agent's effective tool permissions are the intersection of the parent's allow list and the sub-agent's allow list. This means spawning can never escalate privilege — a sub-agent can only do what both the parent and the sub-agent are individually allowed to do.

Parent allow list:    [web_search, file_read, shell_exec]
Sub-agent allow list: [file_read, file_write, shell_exec]
Effective list:       [file_read, shell_exec]
                       ^^ intersection only

Swarm lifecycle

A typical swarm execution proceeds in four phases:

1. Plan — The root agent receives a complex task and generates a decomposition plan: a list of subtasks with assigned agents
2. Spawn — The root agent spawns the required sub-agents, passing each its subtask and any shared state keys to read from the blackboard
3. Execute — Sub-agents work concurrently, writing intermediate results and observations to the shared blackboard
4. Synthesize — The root agent reads all sub-agent results from the blackboard and produces a final synthesized response

If two sub-agents produce conflicting conclusions, the debate protocol is triggered before synthesis. See Debate Protocol.

Concurrent execution

Sub-agents in a swarm execute concurrently by default. The root agent waits for all spawned sub-agents to complete (or time out) before proceeding to synthesis. The maximum number of concurrently running sub-agents is governed by quotas.spawn.maxConcurrent.

quotas:
  spawn:
    maxConcurrent: 5     # No more than 5 sub-agents running at once
    maxDepth: 2          # Spawn tree depth limit

Spawning via tool call

Root agents spawn sub-agents by calling the built-in spawn_agent tool. The tool accepts a target agent ID, a task description, and optional blackboard keys to share:

{
  "tool": "spawn_agent",
  "params": {
    "agentId": "research-agent",
    "task": "Search for recent papers on pgvector HNSW indexing and summarize key findings",
    "blackboardKeys": ["research_context", "output_format"]
  }
}

Timeouts and failure handling

Sub-agents have a configurable timeout. If a sub-agent does not complete within the timeout, it is marked as failed and the root agent receives a timeout error in the tool result. The root agent can then decide to retry, use partial results, or fail the overall task.

If a sub-agent exhausts its consecutive failure limit (configured in selfHealing.maxConsecutiveFailures), it is automatically paused and the parent is notified via the event bus.

Swarm monitoring and control

Open Astra provides tools for observing and managing swarms at runtime:

Blackboard topic channels

In addition to the flat key-value blackboard, swarms can use blackboard_topic to create named pub/sub channels. Sub-agents subscribe to topics they care about and receive updates selectively, reducing noise and token usage in large swarms. See Blackboard for details.