Skip to content

Commit 4852f14

Browse files
committed
docs(orchestration): polish wording in orchestration pages
* Make the 'Where parent and child agents can run' header explicit about the parent/child relationship. * Tighten 'plan for itself plus a fleet of children' to 'plan for itself and the child agents it intends to spawn'. * Replace 'jump straight to' with 'navigate directly to' in the agent notifications observability bullet. * Reword the opening of multi-agent-runs.mdx so 'orchestrated run' is the subject and the surfaces are listed cleanly. * Clarify how a local parent spawns cloud children: 'by specifying an environment for each child' and 'You can select any environment'. * Rephrase the cancellation guidance: 'in many orchestrations, you want children to finish' and split out 'then cancel the parent'. Co-Authored-By: Oz <oz-agent@warp.dev>
1 parent 26e83cb commit 4852f14

2 files changed

Lines changed: 6 additions & 6 deletions

File tree

src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ An orchestrated workflow always has one **parent agent** and one or more **child
1818

1919
The parent and child each have an independent **run** with its own lifecycle, transcript, conversation, and credit usage. The management view, web app, and API all surface a parent alongside its children.
2020

21-
### Where each side can run
21+
### Where parent and child agents can run
2222

2323
The parent and child don't have to run in the same place. Orchestration supports three combinations:
2424

@@ -84,7 +84,7 @@ A flat group of peer agents discover each other through messaging and coordinate
8484

8585
When an agent runs in `orchestrate` mode (set by the `/orchestrate` slash command or the API's `mode: orchestrate` field), the agent **proposes** an orchestration plan and waits for approval before spawning any children. Use this to review the breakdown — number of children, prompts, environments, parallelism — before any children start. Once you approve, the parent starts spawning children.
8686

87-
`orchestrate` mode is distinct from `plan` mode. A `plan`-mode agent produces a written plan for *itself* to execute. An `orchestrate`-mode agent produces a plan for itself plus a fleet of children.
87+
`orchestrate` mode is distinct from `plan` mode. A `plan`-mode agent produces a written plan for *itself* to execute. An `orchestrate`-mode agent produces a plan for itself and the child agents it intends to spawn.
8888

8989
## Observability
9090

@@ -93,7 +93,7 @@ Because every parent and child is tracked as its own conversation or run, the ex
9393
* **[Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/)** - in the Warp app, local children appear in a child agent status card above the parent's input, while cloud children appear as their own rows in the management view.
9494
* **[Oz web app](/agent-platform/cloud-agents/oz-web-app/)** - the Runs page groups cloud children under the parent's row, and the parent's detail pane adds a **Sub-agents** tab.
9595
* **[Oz API](/reference/api-and-sdk/)** - list every descendant of a parent in one call and fetch any run with its conversation, transcript, and artifacts. See [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/#retrieving-conversations-and-artifacts).
96-
* **[Agent notifications](/agent-platform/capabilities/agent-notifications/)** - each child's state transitions generate notifications on the child's own conversation so you can jump straight to whichever one needs attention.
96+
* **[Agent notifications](/agent-platform/capabilities/agent-notifications/)** - each child's state transitions generate notifications on the child's own conversation, so you can navigate directly to whichever one needs attention.
9797

9898
## Related pages
9999

src/content/docs/agent-platform/cloud-agents/orchestration/multi-agent-runs.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ sidebar:
55
label: "Running orchestrated agents"
66
---
77

8-
Running orchestrated agents starts a parent Oz agent that can spawn child agents from the Warp app, Oz CLI, Oz web app, or Oz API. Use orchestrated runs to review a plan before fan-out, execute children locally or in the cloud, and inspect parent and child conversations as they work.
8+
An orchestrated run starts with a parent Oz agent that spawns one or more child agents. You can start a parent from the Warp app, the Oz CLI, the Oz web app, or the Oz API. Use orchestrated runs to review a plan before fan-out, execute children locally or in the cloud, and inspect parent and child conversations as they work.
99

1010
## Before you start
1111

@@ -34,7 +34,7 @@ Approve the plan to start spawning children. The parent's transcript renders eac
3434

3535
### Spawning cloud children from a local parent
3636

37-
A local parent — a Warp Agent conversation in the desktop app — can spawn cloud children by passing an environment when it spawns them. The parent agent will ask you for the environment if it isn't already clear from context. Point it at any environment from your account or team.
37+
A local parent — a Warp Agent conversation in the desktop app — can spawn cloud children by specifying an environment for each child. The parent agent asks you for the environment if it isn't already clear from context. You can select any environment from your account or team.
3838

3939
Cloud children inherit the parent's authentication; the same credit and credentials rules from the [Cloud agents overview](/agent-platform/cloud-agents/overview/) apply.
4040

@@ -157,7 +157,7 @@ POST /api/v1/agent/runs/YOUR_RUN_ID/cancel
157157
Authorization: Bearer YOUR_API_KEY
158158
```
159159

160-
Cancelling the parent does **not** automatically cancel its children. This is intentional: many orchestrations want the children to finish even after the parent ends. To cancel everything, list the descendants first and cancel each one, then the parent:
160+
Cancelling the parent does **not** automatically cancel its children. This is intentional: in many orchestrations, you want children to finish even after the parent ends. To cancel everything, list the descendants and cancel each one, then cancel the parent:
161161

162162
```bash
163163
# List every descendant of the parent, then cancel each.

0 commit comments

Comments
 (0)