Multi-Agent Team#

Spawn, coordinate, and manage multiple AI sub-agents that work together on complex tasks. One agent is the orchestrator — it decomposes the task, assigns roles, collects results, and synthesizes the final output.

Patterns#

Pattern 1: Disposable Team (one-shot)#

Spawn multiple agents for a single task, collect results, done. Best for parallel research, generation, or data processing.

text

sessions_spawn(task="<task prompt>", runtime="subagent", mode="run")

Each agent gets a unique session. Results are auto-announced to the parent.

Pattern 2: Persistent Squad (ongoing collaboration)#

Spawn agents with mode="session" so they maintain context across multiple interactions. Use sessions_send to message them and sessions_list to track who's active.

Pattern 3: Agent Council (debate/decision)#

Spawn 3-5 agents with different perspectives/prompts, have each produce an analysis, then synthesize into a decision. Use sessions_yield to wait for all results.

Pattern 4: Hierarchical (orchestrator + workers)#

One orchestrator agent decomposes the task and spawns worker sub-agents for each subtask, then collects and merges results.

Spawning Agents#

json

sessions_spawn(
  task="You are a researcher agent. Research <topic> and return findings as a structured markdown summary.",
  runtime="subagent",
  runTimeoutSeconds=300,
  mode="run"  // or "session" for persistent
)

Key parameters:

• runtime="subagent" — spawn as OpenClaw sub-agent
• mode="run" — one-shot, exits when done
• mode="session" — persistent, stays alive for multiple interactions
• runTimeoutSeconds — kill after N seconds (0 = no timeout)
• task — the full agent prompt/instruction

Communicating with Agents#

json

sessions_send(sessionKey="<key>", message="Update: the requirements changed to X, please adjust your approach.")
sessions_list(kinds=["subagent"], activeMinutes=60)  // find active agents
sessions_history(sessionKey="<key>", limit=10)  // read their recent messages

Collecting Results#

Option A — Auto-announce: sub-agents announce results automatically (default).

Option B — Blocking wait: use sessions_yield to wait for sub-agent results before continuing:

json

sessions_yield(message="Waiting for research agents to report back...")

Option C — Poll history: after agents complete, fetch results:

json

sessions_history(sessionKey="<agent-session-key>", limit=20)

Orchestrator Template#

When receiving a complex task, follow this sequence:

text

1. Decompose task into N independent subtasks
2. For each subtask, spawn a sub-agent with sessions_spawn(mode="run")
3. Optionally use sessions_yield to wait for results
4. Collect outputs from each agent session via sessions_history
5. Synthesize findings into a unified response
6. Report back to the parent session

Example orchestrator prompt:

text

You are a team orchestrator. The user wants: <task>

Step 1: Break this into 3-5 independent subtasks
Step 2: Spawn research/coder/writer agents for each
Step 3: Wait for all results via sessions_yield
Step 4: Merge into one coherent output
Step 5: Present the final result

Start by decomposing the task and spawning the first wave of agents.

Coordination Patterns#

Fan-Out (parallel map)#

Spawn N agents, each doing the same operation on different data:

text

Agent 1: process(item=A)
Agent 2: process(item=B)
Agent 3: process(item=C)
→ Merge results

Fan-In (gather)#

Spawn agents that each contribute a piece, then one agent merges:

text

Agent 1: write introduction
Agent 2: write section A
Agent 3: write section B
Agent 4: write conclusion
→ Synthesis agent combines all sections

Sequential Pipeline#

Each agent's output becomes the next agent's input:

text

Agent 1: research topic → findings
Agent 2: analyze findings → insights
Agent 3: write article based on insights → draft

Team Memory#

For persistent squads, maintain shared context via files:

json

sessions_send(sessionKey="<orchestrator-key>", message="Update the team status in /workspace/team-status.md — mark task-2 as COMPLETE and note the findings.")

Workers can read/write to shared workspace files for state.

Cleanup#

Use subagents(action="list") to find and kill stale agents:

json

subagents(action="kill", target="<session-key>")

Anti-Patterns#

• Don't spawn 50 agents at once — the system may become unresponsive. Batch into waves of 3-5.
• Don't forget to collect results — agents that run to completion without reporting back waste their output.
• Don't use mode=session unless needed — persistent agents accumulate context and cost tokens. Use run for one-shot tasks.
• Don't spawn without a clear role — each agent needs a specific, focused prompt, not a vague "help me".

See Also#

• agent-orchestrator skill — skill-level orchestration (not task-level)
• agent-council skill — decision-making with agent debates
• subagent-spawn-command-builder skill — helper for constructing spawn commands