Multi-agent orchestration

Multi-agent orchestration lets one agent spawn and coordinate other agents to parallelize work, delegate specialized tasks, or verify another agent’s output. The parent/child model works from the Warp app, the Oz CLI, and the Oz API & SDK, and supports local, cloud, and mixed execution.

Watch this walkthrough to see how a cloud agent can coordinate a team of agents in the cloud.

To start an orchestrated run, see Running orchestrated agents.

To orchestrate work inside a Warp factory, dispatch through the factory API instead of calling POST /agent/runs with the foreman’s agent_identity_uid directly. The server resolves the foreman for you, and everything on this page still applies to the run it starts.

The parent/child model

An orchestrated workflow always has one parent agent and one or more child agents.

• Parent agent - the agent that decides what work needs to be done, spawns child agents, and (optionally) merges their results. Any agent can become a parent the first time it spawns a child.
• Child agent - an agent spawned by a parent with its own prompt, environment, and (optionally) a different model or agent runtime. A child runs its own work and reports back; it does not spawn its own children.

Orchestrations today are exactly one level deep: a parent and its direct children. The Warp app, the Oz web app, and the Oz API & SDK render that single level. The parent and each child each have an independent run with its own lifecycle, transcript, conversation, and credit usage.

Where parent and child agents can run

The parent and child don’t have to run in the same place. Orchestration supports four combinations:

• Local → local - a Warp Agent conversation in the Warp app spawns child Warp Agent conversations on the same machine. Useful for trying orchestration patterns without spinning up cloud infrastructure.
• Local → cloud - a local parent spawns one or more cloud children that run in environments on Warp-hosted or self-hosted infrastructure. The parent keeps working while children execute in parallel.
• Cloud → cloud - a cloud parent spawns cloud children that each run in their own environment. This is the canonical pattern for review swarms, large fan-outs, and any orchestration triggered from Slack, Linear, a schedule, or the API.
• Cloud → cloud-local - a cloud parent spawns children that run inside the parent’s own cloud environment, rather than each child getting its own environment. Useful when children need to share state with the parent (a filesystem, a long-running process, a shell session) or when spinning up an environment per child would be wasteful.

Children can also run with a different agent runtime than the parent. A parent running with the default Warp Agent can spawn children that run with Claude Code or Codex, and vice versa.

How a child agent is configured