docs(orchestration): add multi-agent orchestration pages#84
Open
hongyi-chen wants to merge 14 commits into
Open
docs(orchestration): add multi-agent orchestration pages#84hongyi-chen wants to merge 14 commits into
hongyi-chen wants to merge 14 commits into
Conversation
Add concept and run-how-to pages under cloud-agents/orchestration/. Wire orchestration cross-references into deployment-patterns, managing-cloud-agents, oz-web-app, and agent-notifications. Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
This PR adds new orchestration concept and how-to documentation plus cross-links from existing agent platform pages.
Concerns
- The CLI fan-out example captures a parent run ID but never uses it when launching children, so the example does not actually create an orchestration hierarchy.
- The fleet cancellation example publishes a parent-run CLI filter that the PR description identifies as unverified; this should be confirmed or replaced with the supported API/CLI surface before launch.
Verdict
Found: 0 critical, 2 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
- Replace broken CLI fan-out example (no `--parent-run-id` flag on
`oz agent run-cloud`) with a curl-based scripted fan-out that uses the
public `POST /agent/runs` endpoint with `parent_run_id`. Add a note
pointing script-driven callers at the API.
- Replace the fleet-cancellation example: use `oz run list --ancestor-run`
(supported) instead of the nonexistent `--parent-run-id` flag, and
curl the public `POST /agent/runs/{runId}/cancel` endpoint instead of
the nonexistent `oz run cancel` CLI command.
- Remove the SSE and `/agent/messages` / `/agent/events` API sections
(still internal-only / dogfood-gated) and reframe lifecycle events
and messaging conceptually.
- Add a new "Retrieving conversations and artifacts" section covering
`GET /agent/runs?ancestor_run_id=`, `GET /agent/runs/{runId}`,
`GET /agent/runs/{runId}/conversation`, and the `artifacts` field on
RunItem for both parent and child runs.
- Fix `parent_run_id` query param to `ancestor_run_id` everywhere.
- Replace "service account" with "agent identity" in deployment-patterns.
- Senior-writer pass: tighten frontmatter descriptions, standardize
em-dash usage in bold-term lists, ALL_CAPS placeholders, drop
ambiguous modal verbs.
Addresses PR #84 review comments r3253425053 and r3253425056.
Co-Authored-By: Oz <oz-agent@warp.dev>
Collaborator
Author
Revision passI addressed every actionable review comment and applied Slack-thread feedback. Summary of changes: Review comments
Slack-thread + internal-only scrub
New: conversations and artifacts in the APIAdded a "Retrieving conversations and artifacts" section to Senior-writer passTightened frontmatter descriptions to single-sentence standalone summaries, standardized em-dash usage in bold-term lists, replaced ambiguous modal verbs ("may," "could"), switched placeholders to ALL_CAPS, and kept the Validation
Open questionsNone blocking. Optional follow-up: when the public |
hongyi-chen
commented
May 16, 2026
|
|
||
| The supported event types are: | ||
|
|
||
| * **`run_in_progress`** — the run started executing (or restarted after being paused or blocked). |
Collaborator
Author
There was a problem hiding this comment.
do we need to expose these to the users?
…essaging
- Drop "Each child run records its parent's run ID so the management
view, API, and web app can render the hierarchy" implementation detail
in favor of a user-facing sentence.
- Shrink "Messaging between agents" in orchestration/index.mdx to a
two-sentence high-level overview (was 1 paragraph + 3 bullets + 1
paragraph).
- Tighten the orchestration index opener, the Observability API bullet,
and the approval-mode "before paying for it" phrasing.
- Drop the "tools available with model/harness" qualifier from the CLI
section in multi-agent-runs.mdx.
- Collapse the three "Retrieving conversations and artifacts" subsections
into a single section that states the response shape once.
- Trim oz-web-app.mdx (remove redundant Messages bullet, tighten
post-execute summary) and managing-cloud-agents.mdx ("Each child is a
full Oz run" framing).
- Simplify the Messages-from-children notification bullet.
Co-Authored-By: Oz <oz-agent@warp.dev>
Collaborator
Author
Copy passAddressed the feedback in commit
Validation: |
- Drop the Cloud -> Local orchestration bullet; out of scope for launch. - Replace internal wire-format event names with the user-visible RunState values (INPROGRESS, SUCCEEDED, FAILED, BLOCKED, ERROR, CANCELLED) and reword surrounding copy to talk about run state transitions. - Point the /orchestrate flow at the child agent status card above the agent input instead of the conversation details panel. - Tighten the Oz web app orchestrated-runs section to match the actual Sub-agents tab (status + title per row; parent badge reflects parent work only). Drop the post-execute aggregation claims. - Reframe the managing-cloud-agents orchestrated-runs section: local children surface via the child agent status card; cloud children appear as rows in the management view; the Oz web app nests cloud children under the parent. - Rewrite the agent-notifications orchestrated-runs section to match per-conversation notifications and drop the unimplemented mailbox grouping and 'messages from children -> Request on parent' claims. - Use YOUR_ENVIRONMENT_ID placeholder in the CLI example. Co-Authored-By: Oz <oz-agent@warp.dev>
Collaborator
Author
|
Applied the approved audit fixes (commit 80b7699):
Judgment calls: the desktop management view's only orchestration-aware surface is the child agent status card (local children are excluded from the navigation list via |
rachaelrenk
reviewed
May 18, 2026
rachaelrenk
reviewed
May 18, 2026
rachaelrenk
reviewed
May 18, 2026
rachaelrenk
reviewed
May 18, 2026
Contributor
rachaelrenk
left a comment
rachaelrenk
left a comment
There was a problem hiding this comment.
Copy/style pass on orchestration docs: a few suggested edits for user-facing terminology and local/cloud run distinctions, plus confirmation questions for launch-only API/CLI surfaces.
Resolve conflicts: - deployment-patterns.mdx: take the base branch's agent identities link (the agents page now exists in the base). - oz-web-app.mdx: merge both sides additively. Keep base's new Secrets row, manage agent identities phrasing, and Agent identities resource link, plus this branch's child agents reference in the Runs row and Multi-agent orchestration resource link. Co-Authored-By: Oz <oz-agent@warp.dev>
Co-Authored-By: Oz <oz-agent@warp.dev>
Apply the suggested edits left on PR #84: - orchestration/index.mdx: 'For how to start' -> 'To learn how to start'; 'a different model or harness' -> 'a different model or agent runtime'; 'Children can also use a different harness...' -> 'Children can also run with a different agent runtime...'; 'The states a child run can reach are:' -> 'The main user-visible states a child run can reach are:'; 'every parent and child is a normal Oz run' -> 'every parent and child is tracked as its own conversation or run'. - orchestration/multi-agent-runs.mdx: 'Every parent and child run is a normal Oz run.' -> 'Every parent and child started through the Oz API is tracked as an Oz run.' - agent-notifications.mdx: split the orchestration intro sentence into two for scannability. - oz-web-app.mdx: 'Each sub-agent row' -> 'Each child agent row' in prose while keeping 'Sub-agents' as the UI tab name. Co-Authored-By: Oz <oz-agent@warp.dev>
…rch/multi-agent Resolve one conflict in orchestration/index.mdx: - Keep Rachael's bullet-separator normalization (em-dash -> hyphen) in the parent/child model section. - Keep my 'harness' -> 'agent runtime' content edit on the Child agent bullet. Co-Authored-By: Oz <oz-agent@warp.dev>
rachaelrenk
reviewed
May 19, 2026
Contributor
rachaelrenk
left a comment
rachaelrenk
left a comment
There was a problem hiding this comment.
One small clarity suggestion for the orchestration location heading.
|
|
||
| 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. | ||
|
|
||
| ### Where each side can run |
Contributor
There was a problem hiding this comment.
This heading could be more explicit about the parent/child relationship.
Suggested change
| ### Where each side can run | |
| ### Where parent and child agents can run |
rachaelrenk
reviewed
May 19, 2026
Contributor
rachaelrenk
left a comment
rachaelrenk
left a comment
There was a problem hiding this comment.
One small wording suggestion for the run state transition intro sentence.
rachaelrenk
reviewed
May 19, 2026
Contributor
rachaelrenk
left a comment
rachaelrenk
left a comment
There was a problem hiding this comment.
One small wording suggestion for the common patterns intro.
rachaelrenk
reviewed
May 19, 2026
Contributor
rachaelrenk
left a comment
rachaelrenk
left a comment
There was a problem hiding this comment.
Follow-up suggestion to make the Common patterns section intro better introduce the H3 pattern list.
|
|
||
| ## Common patterns | ||
|
|
||
| Orchestration primitives are general-purpose. Teams typically compose them into a handful of recurring patterns. |
Contributor
There was a problem hiding this comment.
Building on the previous wording note: since this H2 introduces the pattern-specific H3s below, this transition can more directly frame the list.
Suggested change
| Orchestration primitives are general-purpose. Teams typically compose them into a handful of recurring patterns. | |
| The following patterns show common ways to structure parent and child agents, depending on whether you need parallel execution, review, dependency ordering, or loose coordination. |
Co-Authored-By: Oz <oz-agent@warp.dev>
Co-Authored-By: Oz <oz-agent@warp.dev>
rachaelrenk
approved these changes
May 19, 2026
Contributor
rachaelrenk
left a comment
rachaelrenk
left a comment
There was a problem hiding this comment.
I reviewed the new multi-agent orchestration docs with a focus on clarity, user-facing terminology, launch accuracy, and consistency with the docs style guide. I left suggested edits and comments to clarify the parent/child model, run state observability, notifications for child agents, and where orchestrated runs appear across Warp, the Oz web app, the CLI, and the API. I also flagged a few launch-surface details for confirmation, including mode: orchestrate and oz run list --ancestor-run.
I pushed a few scoped commits directly to keep well-understood changes moving:
• Normalized bold-term list separators from em dashes to hyphens across the PR.
• Added AEO citation summaries to the new orchestration pages.
• Added direct links to relevant Oz web app pages, including the Runs and Agents pages.
• Made small wording improvements where the docs benefited from more explicit, action-oriented phrasing.
…ex.mdx Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
…ex.mdx Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
hongyi-chen
added a commit
that referenced
this pull request
May 19, 2026
Apply all 9 of @rachaelrenk's suggested edits on PR #85 and run a final senior-copywriter pass for consistency across the three handoff pages. index.mdx - Intro: "your local Warp terminal" -> "a local Warp session" so the intro talks about a session rather than the terminal application. - "Third-party harness coverage" -> "Third-party agent runtime coverage"; same swap in the two bullets underneath. "Harness" is internal vocabulary; "agent runtime" is the user-facing term. - "spiraled into work" -> "grown into work" (less idiomatic). - "Managing Cloud Agents" -> "Managing cloud agents" in Related pages to match the sentence-case nav style used elsewhere. - Consistency polish: "Fork a cloud conversation into your local terminal" -> "into a local Warp session" so the cloud-to-local bullet uses the same terminology as the rewritten intro. local-to-cloud.mdx - Intro: "Hand off a conversation from the Warp terminal" -> "Hand off a local Warp conversation" (same reason as above). - "This direction is the right move when:" -> "Use this handoff direction when:" (less conversational, matches docs voice). - Post-handoff pointer: linked the management view doc -> deep-linked the [Runs page](https://oz.warp.dev/runs) in the Oz web app, which matches the pattern added in PR #84. - "Cloud Agents quickstart" -> "Cloud agents quickstart" (sentence case). cloud-to-cloud.mdx (consistency polish, same patterns Rachael called out in the other two pages) - "This direction is the right move when:" -> "Use this handoff direction when:". - Step 1 of "Sending a follow-up": linked the management view doc -> deep-linked the Runs page in the Oz web app. - Removed a stray duplicate `### Third-party harnesses` heading that was sitting directly above the correct `### Third-party agent runtimes` heading, and inserted a missing blank line before the next `## Inspecting a run that's been handed off` section. - "Managing Cloud Agents" -> "Managing cloud agents" in Related pages. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues. - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken links (2,439 internal links across 321 files). Co-Authored-By: Oz <oz-agent@warp.dev>
* 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>
hongyi-chen
added a commit
that referenced
this pull request
May 19, 2026
The "cross-cutting sidebar PR" that the original PR description referred to doesn't exist — none of the orchestration-launch content is currently registered in `src/sidebar.ts`. PR #84 (multi-agent) doesn't touch the sidebar either; only PR #86 (memory) adds its own entries. Following that pattern: register the three handoff pages here so they actually appear in the docs sidebar when this branch merges. src/sidebar.ts - Added a new "Handoff" collapsible group inside the "Oz Cloud Agents & Orchestration" topic, slotted right after "Viewing cloud agent runs" since that's the closest thematic neighbor (it covers `Continue locally` / `/continue-locally`, the cloud-to-local path). The group contains: - Overview -> agent-platform/cloud-agents/handoff - Local to cloud -> agent-platform/cloud-agents/handoff/local-to-cloud - Cloud to cloud -> agent-platform/cloud-agents/handoff/cloud-to-cloud Mirrors the existing collapsible-group shape used by Triggers, Integrations, and Self-hosting in the same section. src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx - "(from the conversation details panel or the end-of-run tombstone)" -> "(from the conversation details panel or the artifacts shown after the run)". "Tombstone" is the internal code-level term for the post-run view (`shared_session/conversation_ended_tombstone_view.rs`). Even though it shows up in telemetry-event descriptions in `privacy.mdx`, it's not natural user-facing copy. Switched to a plainer reference to the artifacts surfaced after the run. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues on the files this PR touches. (The pre-existing pricing-faqs.mdx warnings are out of scope.) - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken (2,440 links, 322 files). - `npm run build` fails on an UNRELATED orphan page (`agent-platform/cloud-agents/agents.mdx` is not registered in the sidebar). That page was added earlier on this branch by a different PR and is pre-existing breakage on `hyc/orch/handoff` — my edits don't touch it. Co-Authored-By: Oz <oz-agent@warp.dev>
This was referenced May 19, 2026
hongyi-chen
added a commit
that referenced
this pull request
May 19, 2026
* docs(handoff): add local↔cloud handoff documentation Add a new handoff section under cloud-agents that documents the three directions of handoff supported by the orchestration launch: - Overview (conceptual) explaining what handoff is, the three directions, and what carries over. - Local→cloud (procedural) for promoting a local Warp Agent conversation to a cloud agent run. - Cloud→local (procedural) for picking up a cloud run inside the Warp terminal via /continue-locally and equivalent UI entrypoints. - Cloud→cloud (procedural) for follow-ups that span multiple executions of the same run. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(handoff): scrub internals, drop cloud-to-local, tighten copy Address PR review feedback and Slack-thread direction. - Drop cloud-to-local.mdx; existing fork-to-local docs in viewing-cloud-agent-runs.mdx already cover the capability. Overview now references that page for cloud-to-local. - Scope the snapshot rehydration mechanism in the overview to local-to-cloud and cloud-to-cloud only; cloud-to-local does not apply workspace patches. - Replace the inaccurate `git diff --binary HEAD` capture description in local-to-cloud with a high-level summary that covers tracked and untracked changes without committing to a specific git command. - Soften the local-to-cloud entry point: do not document a specific keyboard shortcut, add a note that the affordance may evolve during the Oz launch rollout. - Strip internal-only details from user-facing copy: GCS paths, manifest filenames, `git apply` mechanics, internal routing names (appended/injected/requeued), API endpoint paths, and rehydration checklist references. - Senior-writer pass: tighten descriptions to 50-160 chars, reduce marketing fluff, normalize cross-references. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(handoff): second editor pass to drop residual internal jargon - Replace 'execution' with 'session' across cloud-to-cloud.mdx so the user-facing unit of work stays 'the run', not the internal model. - Drop 'rehydrate'/'rehydration' in favor of 'restore'/'carry over'; fold the standalone 'Rehydration behavior' section into 'What carries over' in the overview. - Drop the 'server-side' qualifier on 'fork' throughout; users don't care where the fork happens. - Collapse the cloud-to-cloud 'How follow-ups route' state-machine into a single user-facing description; remove the two routing-paths items from troubleshooting since they describe normal behavior, not problems. - Collapse local-to-cloud's 'Verifying the handoff' debugging walkthrough into one sentence pointing readers to the management view. - Cut meta self-descriptions: 'The handoff entry point is integrated into the cloud agent launch flow...' and 'Cloud-to-cloud handoff is automatic...'. - Drop the rollout caveat note on local-to-cloud. - Reduce 'sandbox' references where they leak infrastructure. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(handoff): trim overview description to fit 50-160 char range Co-Authored-By: Oz <oz-agent@warp.dev> * docs(handoff): address audit findings - cloud-to-cloud.mdx: soften per-session timeline claim to API-only (UI render not present) - cloud-to-cloud.mdx: gloss 'ambient agent task' inline for clarity - local-to-cloud.mdx: switch primary credits link to credits page; fix link text casing for access page Co-Authored-By: Oz <oz-agent@warp.dev> * docs(handoff): address Safia's review feedback - index.mdx: drop launch-anchored framing; reframe Directions list as evergreen capability statement; add third-party-harness coverage subsection (cloud<->cloud works on 3P with Continue+input prompt; local->cloud is Warp Agent only). - local-to-cloud.mdx: replace /cloud-agent entry-point claim with the '&' shortcut and the '/handoff' slash command; add note that the model can't be changed during handoff. - cloud-to-cloud.mdx: consolidate duplicate scheduled/integration bullets; add 'same Git branch' detail to workspace-state carryover; add :::caution that handoff requires a prior-execution snapshot; note that local->cloud-originated runs can only be continued by the creating user; scope send-follow-up to the Warp app and drop the Oz-web-app/integration follow-up sections; add third-party harness Continue-button flow; soften per-execution timeline claim (transcript is the source of truth, not the API). Co-Authored-By: Oz <oz-agent@warp.dev> * Update src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> * docs(handoff): apply Rachael's review suggestions and final copy polish Apply all 9 of @rachaelrenk's suggested edits on PR #85 and run a final senior-copywriter pass for consistency across the three handoff pages. index.mdx - Intro: "your local Warp terminal" -> "a local Warp session" so the intro talks about a session rather than the terminal application. - "Third-party harness coverage" -> "Third-party agent runtime coverage"; same swap in the two bullets underneath. "Harness" is internal vocabulary; "agent runtime" is the user-facing term. - "spiraled into work" -> "grown into work" (less idiomatic). - "Managing Cloud Agents" -> "Managing cloud agents" in Related pages to match the sentence-case nav style used elsewhere. - Consistency polish: "Fork a cloud conversation into your local terminal" -> "into a local Warp session" so the cloud-to-local bullet uses the same terminology as the rewritten intro. local-to-cloud.mdx - Intro: "Hand off a conversation from the Warp terminal" -> "Hand off a local Warp conversation" (same reason as above). - "This direction is the right move when:" -> "Use this handoff direction when:" (less conversational, matches docs voice). - Post-handoff pointer: linked the management view doc -> deep-linked the [Runs page](https://oz.warp.dev/runs) in the Oz web app, which matches the pattern added in PR #84. - "Cloud Agents quickstart" -> "Cloud agents quickstart" (sentence case). cloud-to-cloud.mdx (consistency polish, same patterns Rachael called out in the other two pages) - "This direction is the right move when:" -> "Use this handoff direction when:". - Step 1 of "Sending a follow-up": linked the management view doc -> deep-linked the Runs page in the Oz web app. - Removed a stray duplicate `### Third-party harnesses` heading that was sitting directly above the correct `### Third-party agent runtimes` heading, and inserted a missing blank line before the next `## Inspecting a run that's been handed off` section. - "Managing Cloud Agents" -> "Managing cloud agents" in Related pages. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues. - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken links (2,439 internal links across 321 files). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(handoff): second copy polish pass on handoff pages A senior-copywriter follow-up on commit b45a4e8. Focuses on terminology consistency, list parallelism, active voice, and a few style-guide nits caught on the second read. index.mdx - Frontmatter description: "Move an agent conversation between your terminal and the cloud" -> "Move agent work between a local Warp session and the cloud" so the description matches the body intro (which Rachael's review moved to "local Warp session" terminology). - "Directions of handoff" Local-to-cloud bullet: "more compute, longer-running work, or to fan out variants in parallel" -> "more compute, longer-running work, or parallel variants of the same task". Now all three list items are parallel noun phrases. - "Workspace state" bullet: "The cloud-to-local direction does not currently apply" -> "doesn't currently apply" (contractions are encouraged in the style guide for an approachable tone). local-to-cloud.mdx - "Use this handoff direction when:" list: first bullet started with "The task is going to run for a long time..." while the other three start with "You want...". Rewrote it to "You have a long-running task and don't want to keep your laptop awake." so all four bullets open the same way. - Step 1: "trigger handoff with the `&` shortcut or the `/handoff` slash command" -> "press `&` or run the `/handoff` slash command". Direct verbs match the style guide pattern for keyboard / slash commands. - Step 2: "Pick the environment whose..." -> "Pick the one whose..." (avoids repeating "environment" right after the bold header). "create one first and add" -> "create one and add" ("first" was doing no work). - Post-steps prose: "After submission, the cloud agent applies your workspace snapshot" -> "After you submit, the cloud agent...". Active voice; readers don't talk about "submission." - Troubleshooting (uncommitted changes): "Without it, the conversation can't be forked" -> "Otherwise, the conversation can't be forked". "Without it" had a fuzzy antecedent; "Otherwise" reads cleanly off the preceding sentence. cloud-to-cloud.mdx - "Use this handoff direction when:" list: first bullet "A cloud agent finished and you want to send a follow-up after the session has ended." -> "You want to send a follow-up to a cloud agent after its session has ended." Now parallel with the second bullet ("You want to continue an ambient agent run..."). - Cleaned up three lingering uses of "execution" that the earlier internals scrub missed. All three were re-introduced when applying Safia's audit-fix feedback in e4bdd4b. Replaced with "session": - "the new execution runs on the same Git branch as the prior session" -> "the new session continues on the same Git branch" (avoids both the internal term and the "new ... prior" cycle). - ":::caution Cloud-to-cloud handoff relies on a snapshot from the prior execution" -> "...the prior session". - "Click into the run to see the full transcript: each execution appears in order, and you can scan the transcript to see where one execution ended and the next began. Per-execution timestamps aren't currently exposed in the API..." -> all three "execution"s -> "session" / "Per-session". - "What carries over" trailing sentence: "...proceeds with what it could before continuing to your follow-up." -> "...rather than starting over silently." Now parallel with the same sentence on the other two handoff pages. - "Sending a follow-up" lead-in: dropped the orphan third sentence ("Send-follow-up support is available in the Warp app.") and folded it into the first: "you send a follow-up from the Warp app, and the run continues." - Step 2: "Type the next message into the conversation's input" -> "Enter the next message in the conversation's input" ("Enter" is the style guide's verb for text fields). - Troubleshooting (old runs): "Start a new cloud agent run with the prompt you want and reference the prior run in the prompt if needed." -> "Start a new cloud agent run with the prompt you want, referencing the prior run if needed." (drops the "prompt" repetition). Final grep over the handoff folder for "execution", "harness", "spiraled", "right move", "Cloud Agents", "Warp terminal" -> zero hits. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues. - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken links (2,439 internal links across 321 files). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(handoff): address two missed Rachael comments on cloud-to-cloud I missed two of @rachaelrenk's review comments on the cloud-to-cloud page in earlier passes because they weren't returned by the first `gh pr view` query. Applying them now. cloud-to-cloud.mdx - "ambient agent run" -> "background cloud agent run". Rachael flagged "ambient agent run" as abstract/internal-feeling; "background cloud agent run" keeps the example concrete and matches the user-facing framing on the surrounding pages. Per her suggested edit verbatim. - Removed `blocked` from the example list of terminal states. The API treats BLOCKED as terminal for cancellation purposes, but the spec describes it as "awaiting user input or approval" — so it isn't a natural place to send a follow-up via cloud-to-cloud handoff (responding to the prompt on the original run is the right path). Added a sentence to the prereq calling that out explicitly so readers don't try to hand off a blocked run. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues. - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken (2,439 internal links, 321 files). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(handoff): audit polish for cloud-to-cloud prereqs Two small consistency fixes caught on a third audit round: - L29 "An ended cloud agent run" prereq: "Blocked runs ... aren't continued through cloud-to-cloud handoff" -> "...can't be continued via cloud-to-cloud handoff". Makes the carve-out parallel with the very next sentence ("Very old runs ... can't be continued via handoff"), and reads more directly than "aren't continued through". - L30 "A snapshot from the prior session" prereq: "the run still continues -- it just starts without restored workspace state" -> "the run still continues, just without restored workspace state". The em dash + "it just starts" was colloquial and a bit redundant ("continues" and "starts" describe the same event); the comma-led adjective phrase is cleaner. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues. - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken (2,439 internal links, 321 files). Co-Authored-By: Oz <oz-agent@warp.dev> * docs(handoff): add Handoff sidebar group + drop tombstone wording The "cross-cutting sidebar PR" that the original PR description referred to doesn't exist — none of the orchestration-launch content is currently registered in `src/sidebar.ts`. PR #84 (multi-agent) doesn't touch the sidebar either; only PR #86 (memory) adds its own entries. Following that pattern: register the three handoff pages here so they actually appear in the docs sidebar when this branch merges. src/sidebar.ts - Added a new "Handoff" collapsible group inside the "Oz Cloud Agents & Orchestration" topic, slotted right after "Viewing cloud agent runs" since that's the closest thematic neighbor (it covers `Continue locally` / `/continue-locally`, the cloud-to-local path). The group contains: - Overview -> agent-platform/cloud-agents/handoff - Local to cloud -> agent-platform/cloud-agents/handoff/local-to-cloud - Cloud to cloud -> agent-platform/cloud-agents/handoff/cloud-to-cloud Mirrors the existing collapsible-group shape used by Triggers, Integrations, and Self-hosting in the same section. src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx - "(from the conversation details panel or the end-of-run tombstone)" -> "(from the conversation details panel or the artifacts shown after the run)". "Tombstone" is the internal code-level term for the post-run view (`shared_session/conversation_ended_tombstone_view.rs`). Even though it shows up in telemetry-event descriptions in `privacy.mdx`, it's not natural user-facing copy. Switched to a plainer reference to the artifacts surfaced after the run. Validation - python3 .agents/skills/style_lint/style_lint.py --changed -> 0 issues on the files this PR touches. (The pre-existing pricing-faqs.mdx warnings are out of scope.) - python3 .agents/skills/check_for_broken_links/check_links.py --internal-only -> 0 broken (2,440 links, 322 files). - `npm run build` fails on an UNRELATED orphan page (`agent-platform/cloud-agents/agents.mdx` is not registered in the sidebar). That page was added earlier on this branch by a different PR and is pre-existing breakage on `hyc/orch/handoff` — my edits don't touch it. Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev> Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds documentation for multi-agent orchestration (Codename Maestro): a new concept page describing the parent/child model and supported patterns, and a how-to page covering every way to start an orchestrated run (slash command, Oz CLI, Oz web app, REST API). Cross-references are wired into the deployment-patterns, managing-cloud-agents, oz-web-app, and agent-notifications pages so an existing reader can find the new content from the surfaces they already use.
Pages
New:
src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx— concepts: parent/child model, local/cloud combinations, lifecycle event types, messaging API, common patterns (supervisor/worker, fan-out, critic, review swarm, DAG, swarm), approval (orchestrate) mode, observability.src/content/docs/agent-platform/cloud-agents/orchestration/multi-agent-runs.mdx— how-to:/orchestrateslash command,oz agent run-cloud(agent-driven and script-driven), Oz web app entry points,POST /agent/runswithmode: orchestrateorparent_run_id, SSE + batch poll for lifecycle events,POST /agent/messages, fleet cancellation.Edited:
src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx— replaced the inline 'fan-out parallel work (sharding)' recipe with a link to the new orchestration pages.src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx— added an 'Orchestrated runs (parent and child)' section describing how the hierarchy is rendered in the management view.src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx— added an 'Orchestrated runs' section covering where to start an orchestration, the live detail pane, and the post-execute roll-up.src/content/docs/agent-platform/capabilities/agent-notifications.mdx— added a 'Notifications in orchestrated runs' section describing child lifecycle events, child messages, and blocked-child propagation.Research grounding
/orchestrateslash command behavior:app/src/search/slash_command_menu/static_commands/commands.rs(gated byFeatureFlag::Orchestration, inPREVIEW_FLAGS).warp-server/logic/agent_lifecycle.go(run_in_progress,run_succeeded,run_failed,run_errored,run_blocked,run_cancelled).warp-server/router/handlers/public_api/agent_messaging.go(messages, events, SSE stream).parent_run_idfield onRunAgentRequest/RunItemfromwarp-server/public_api/openapi.yaml.warp-internal/app/src/ai/blocklist/action_model/execute/start_agent.rs,warp-internal/app/src/ai/agent/conversation.rs::orchestration_agent_id().orchestratevsplan):warp-server/public_api/openapi.yaml.Open questions / needs PM confirmation
/orchestrate. It currently ships inPREVIEW_FLAGS(Preview/Friends-of-Warp), not inRELEASE_FLAGS. The new run-how-to page notes this with a:::notecallout; please confirm the GA cutover plan so I can drop the note if it's already public at launch.agent/events/streamis registered only on the RTC server tier and behindOrchestrationV2InfrastructureEnabled. I described it as supported with a 'real-time fan-out tier' caveat. Please confirm whether external API users get this endpoint at launch or whether we should call it 'preview only' for now.oz run list --parent-run-idflag. The cancellation example uses this flag; the Oz CLI surface for filtering by parent run is implicit from the API but I did not verify a public CLI flag exists. Please confirm the exact CLI surface before launch.src/assets/agent-platform/orchestration/.Out of scope (per gating plan)
src/sidebar.ts(reserved for the cross-cutting sidebar PR).vercel.json(reserved for the cross-cutting redirects PR).Artifacts
Co-Authored-By: Oz oz-agent@warp.dev