docs(orchestration): add multi-agent orchestration pages by hongyi-chen · Pull Request #84 · warpdotdev/docs

hongyi-chen · 2026-05-16T20:30:34Z

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: /orchestrate slash command, oz agent run-cloud (agent-driven and script-driven), Oz web app entry points, POST /agent/runs with mode: orchestrate or parent_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

/orchestrate slash command behavior: app/src/search/slash_command_menu/static_commands/commands.rs (gated by FeatureFlag::Orchestration, in PREVIEW_FLAGS).
Lifecycle event names: warp-server/logic/agent_lifecycle.go (run_in_progress, run_succeeded, run_failed, run_errored, run_blocked, run_cancelled).
REST surfaces: warp-server/router/handlers/public_api/agent_messaging.go (messages, events, SSE stream). parent_run_id field on RunAgentRequest/RunItem from warp-server/public_api/openapi.yaml.
Parent/child plumbing: warp-internal/app/src/ai/blocklist/action_model/execute/start_agent.rs, warp-internal/app/src/ai/agent/conversation.rs::orchestration_agent_id().
AgentRunMode enum (orchestrate vs plan): warp-server/public_api/openapi.yaml.

Open questions / needs PM confirmation

GA vs preview state of /orchestrate. It currently ships in PREVIEW_FLAGS (Preview/Friends-of-Warp), not in RELEASE_FLAGS. The new run-how-to page notes this with a :::note callout; please confirm the GA cutover plan so I can drop the note if it's already public at launch.
SSE stream availability. agent/events/stream is registered only on the RTC server tier and behind OrchestrationV2InfrastructureEnabled. 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-id flag. 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.
Image assets. No screenshots are included for the management view's nesting chip or the web app's children/post-execute pane. Once design ships final visuals, we should add captures to src/assets/agent-platform/orchestration/.

Out of scope (per gating plan)

No edits to src/sidebar.ts (reserved for the cross-cutting sidebar PR).
No edits to vercel.json (reserved for the cross-cutting redirects PR).
No edits to top-level landing pages.
No edits to multi-harness pages (owned by another agent).

Artifacts

Conversation: https://staging.warp.dev/conversation/2b44ca91-ea71-4a5b-ba42-820420f95fb5

Co-Authored-By: Oz oz-agent@warp.dev

vercel · 2026-05-16T20:30:40Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	May 19, 2026 9:36pm

oz-for-oss · 2026-05-16T20:30:46Z

@hongyi-chen

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 /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

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>

hongyi-chen · 2026-05-16T21:05:12Z

Revision pass

I addressed every actionable review comment and applied Slack-thread feedback. Summary of changes:

Review comments

r3253425053 — Fixed. oz agent run-cloud has no --parent-run-id flag, so the script-driven CLI fan-out couldn't link children to the parent. Replaced the example with two flows: (1) the recommended agent-driven oz agent run-cloud flow, and (2) a curl-based scripted fan-out using the public POST /agent/runs endpoint with parent_run_id. Added a :::note explaining script-driven parent linking requires the API.
r3253425056 — Fixed. Replaced the nonexistent oz run list --parent-run-id flag with the supported oz run list --ancestor-run, and the nonexistent oz run cancel CLI command with curl calls to the public POST /agent/runs/{runId}/cancel. Added a :::caution callout that self-hosted, local, and GitHub Action runs return 422.

Slack-thread + internal-only scrub

Removed the SSE stream and /agent/messages / /agent/events API sections (all marked x-internal: true in the OpenAPI spec, still gated behind dogfood flags) and reframed lifecycle events and messaging conceptually.
Removed internal type/field names (MessagesReceivedFromAgents, lifecycle_subscription) and infrastructure references (RTC / "real-time fan-out tier").
Fixed the API filter param: ?parent_run_id= → ?ancestor_run_id= everywhere. The field on a RunItem is parent_run_id; the supported list filter is ancestor_run_id.
Replaced "service account" with "agent identity" in deployment-patterns.mdx.
"Oz harness" noun phrase wasn't present; harness references already read as "harness" or "[harness] children."

New: conversations and artifacts in the API

Added a "Retrieving conversations and artifacts" section to multi-agent-runs.mdx covering GET /agent/runs?ancestor_run_id=, GET /agent/runs/{runId} (returns parent_run_id, conversation_id, artifacts), GET /agent/runs/{runId}/conversation, and GET /agent/runs/{runId}/transcript — all public endpoints — for both parent and child runs.

Senior-writer pass

Tightened 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 :::note Preview callout for /orchestrate.

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

Open questions

None blocking. Optional follow-up: when the public /agent/messages and /agent/events endpoints leave dogfood, add a dedicated "Messaging API" section back to multi-agent-runs.mdx.

hongyi-chen · 2026-05-16T21:21:21Z

+
+The supported event types are:
+
+* **`run_in_progress`** — the run started executing (or restarted after being paused or blocked).


do we need to expose these to the users?

hongyi-chen · 2026-05-16T21:30:51Z

Copy pass

Addressed the feedback in commit 97454cf:

Dropped implementation-detail framing. The "Each child run records its parent's run ID so the management view, API, and web app can render the hierarchy" sentence is gone, along with similar internals-leaking phrasings in multi-agent-runs.mdx (the parent_run_id linking explainer and the "orchestration tools available with model/harness" qualifier).
Shrunk "Messaging between agents" in orchestration/index.mdx from a paragraph + 3 bullets + a paragraph down to two high-level sentences. The detailed sender/recipient mechanics are gone; messaging now reads as a concept, not a spec.
General copy pass. Tightened the page opener, fixed "before paying for it," trimmed the Observability API bullet, collapsed the three "Retrieving conversations and artifacts" subsections into one section that states the response shape once, removed the now-redundant Messages bullet in oz-web-app.mdx, and dropped the "Each child is a full Oz run" framing from managing-cloud-agents.mdx.

Validation: style_lint --changed and check_links --internal-only both clean.

hongyi-chen · 2026-05-16T23:35:31Z

Applied the approved audit fixes (commit 80b7699):

Run state vocabulary. Replaced the wire-format event names (run_in_progress, run_succeeded, …) with the user-visible RunState values (INPROGRESS, SUCCEEDED, FAILED, BLOCKED, ERROR, CANCELLED) and reworded surrounding copy to talk about run state transitions rather than events. Same scrub in agent-notifications.mdx.
Sub-agents UI label. Dropped "Children" as a UI tab name and use Sub-agents to match RunDetailPane.tsx. Tightened the Oz web app orchestrated-runs section to what the Sub-agents tab actually surfaces (status + title per row; the parent badge reflects only the parent's work). Removed the post-execute aggregation claims.
Child agent status card. Repointed the local /orchestrate flow at the child agent status card above the agent input (child_agent_status_card.rs) instead of the conversation details panel; reframed managing-cloud-agents.mdx and agent-notifications.mdx around the same surface, and dropped the unimplemented "mailbox grouping" and "messages from children → Request notification on parent" bullets.
Scope tightening. Removed the Cloud → Local orchestration bullet from orchestration/index.mdx and dropped the /orchestrate Preview-builds callout. Replaced the lowercase my-env placeholder with YOUR_ENVIRONMENT_ID in the CLI example.

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 should_exclude_from_navigation), so the docs now distinguish local-child vs cloud-child surfacing rather than implying a unified nested view. Validation: style_lint --changed and check_links --internal-only both clean.

rachaelrenk

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.

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>

rachaelrenk

One small clarity suggestion for the orchestration location heading.

rachaelrenk · 2026-05-19T01:19:59Z

+
+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


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

One small wording suggestion for the run state transition intro sentence.

rachaelrenk

One small wording suggestion for the common patterns intro.

rachaelrenk

Follow-up suggestion to make the Common patterns section intro better introduce the H3 pattern list.

rachaelrenk · 2026-05-19T01:27:40Z

+
+## Common patterns
+
+Orchestration primitives are general-purpose. Teams typically compose them into a handful of recurring patterns.


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.

Applied the suggested wording in b52a764. The Common patterns intro now reads: '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.'

rachaelrenk

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.

@rachaelrenk

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>

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>

@rachaelrenk

* 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>

cephalonaut · 2026-05-19T14:23:26Z


+## Notifications in orchestrated runs
+
+In a [multi-agent orchestration](/agent-platform/cloud-agents/orchestration/), each child agent is its own conversation. Notifications fire on the child whose state changes — they aren't aggregated on the parent.


We don't fire notifications for children at all actually right now

Good catch — rewrote agent-notifications.mdx accordingly in b52a764. The new "Notifications in orchestrated runs" section now says in-app notifications fire on the parent's conversation only (child conversations are excluded from the toast stream and the notification mailbox via should_exclude_from_navigation()), and points readers at the orchestration pill bar and the Sub-agents tab for live per-child state. Dropped the earlier 'each child fires its own notification' framing.

cephalonaut · 2026-05-19T14:27:14Z

+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 Oz agent can become a parent the first time it spawns a child.
+* **Child agent** - an Oz agent spawned by a parent with its own prompt, environment, and (optionally) a different model or agent runtime. A child can spawn its own children, so orchestrations are arbitrarily deep.


Children can't spawn their own children, so it's only one level deep

Fixed in b52a764. The 'A child can spawn its own children, so orchestrations are arbitrarily deep' sentence is gone. The Child agent bullet now reads: 'A child runs its own work and reports back; it does not spawn its own children.' A follow-up paragraph also says explicitly that orchestrations today are exactly one level deep — a parent and its direct children — and that the Warp app, the Oz web app, and the Oz API all render that single level.

cephalonaut · 2026-05-19T14:29:20Z

+
+* **Local → local** - a [Warp Agent](/agent-platform/local-agents/overview/) conversation in the desktop 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](/agent-platform/cloud-agents/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. This is the canonical pattern for review swarms, large fan-outs, and any orchestration triggered from Slack, Linear, a schedule, or the API.


One wrinkle here is we also support cloud -> cloud where the child is local to the cloud orchestrator. Basically, if a cloud agent starts a local child as opposed to starting a cloud child.

Added in b52a764. The 'Where parent and child agents can run' section now lists four combinations: Local → local, Local → cloud, Cloud → cloud, and a new Cloud → cloud-local that describes a cloud orchestrator spawning a child that runs inside the parent's own cloud environment rather than getting its own environment. The bullet calls out the cases where this is useful (shared filesystem, long-running process, shell session, or when per-child environments would be wasteful).

cephalonaut · 2026-05-19T14:34:30Z

+
+## Approval mode
+
+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.


The distinction between /orchestrate and /plan isn't quite right. /orchestrate instructs the agent to apply orchestration to a task. /plan will plan a complex task and if appropriate propose orchestration as part of the plan because the agent will always consider orchestration while planning. Both require user approval to execute.

Rewrote the Approval mode section in b52a764. New phrasing: both /orchestrate and /plan enter a flow where the agent proposes an approach and waits for user approval before launching children. /orchestrate explicitly asks the agent to apply orchestration. /plan always considers orchestration as part of planning and proposes it when the work would benefit; when it does, the plan card surfaces an inline orchestration config block (model, harness, environment, host, parallelism, auth pickers) above the plan content, and the user approves the plan + config together. Mapped to mode: orchestrate and mode: plan on the API side.

cephalonaut · 2026-05-19T14:37:02Z

+
+## Starting an orchestrated run from Warp
+
+In the Warp desktop app, open the agent input and type `/orchestrate` followed by your task. The parent agent enters `orchestrate` mode and proposes a plan before spawning children.


We should probably also mention that the agent will propose orchestration as part of its planning flow. There is an orchestration config card that appears above the plan view when this occurs and the plan will contain a section describing the approach it intends.

Added a new 'Letting the agent propose orchestration during /plan' subsection in multi-agent-runs.mdx (in b52a764). It explains that during /plan the agent considers orchestration and proposes it when the work would benefit, that an inline orchestration config block appears above the plan content with the run-wide pickers (model, harness, environment, host, parallelism, auth), and that the user adjusts the config and then approves the plan to start spawning children. Cross-linked from the Approval mode section in the concept page.

cephalonaut · 2026-05-19T14:37:53Z

+* Each child's prompt and environment.
+* What it expects each child to return.
+
+Approve the plan to start spawning children. The parent's transcript renders each child as it spawns, and a child agent status card above the agent input shows each child's current state. Click a card to jump to that child's conversation.


This seems to document the old UI - the orchestration pill bar is the new UI - orchestrated children appear as pills at the top of the parent agent's view. Clicking on the pills switches the view to the child's view.

Replaced the legacy 'child agent status card above the agent input' framing with the orchestration pill bar across the affected pages in b52a764:

orchestration/multi-agent-runs.mdx — the section that describes what happens after approving an orchestration now says: 'an orchestration pill bar appears above the agent view header showing the parent on the left and one pill per child. Each pill displays the child's name and a live status badge. Click a child pill to switch the pane to that child's conversation in place; click the parent pill — or the breadcrumb that replaces the pill bar while you're viewing a child — to return.'

orchestration/index.mdx — the 'Track run state transitions' bullet and the Observability bullet both reference the pill bar instead of the legacy status card.

managing-cloud-agents.mdx — the new 'Orchestrated runs (parent and child)' section uses the pill bar wording for local children in the Warp app, and the Sub-agents tab wording for cloud children in the web app.

Grounding: pill bar product spec is warp-internal/specs/QUALITY-567/PRODUCT.md; the legacy child-agent status card is explicitly disabled when FeatureFlag::OrchestrationPillBar is on (app/src/ai/blocklist/block/status_bar.rs:1239-1248, 1312-1320).

…ch state Refreshes PR #84 with a single commit that: * Adds two new orchestration pages (concept + how-to) describing the launched multi-agent orchestration model. * Updates four existing pages (agent-notifications, deployment-patterns, managing-cloud-agents, oz-web-app) with orchestration cross-references that describe surfaces accurately. Matthew's review (cephalonaut): * Child agents do not spawn their own children today; orchestrations are one level deep. * Documents the four execution combinations including cloud -> cloud-local. * Rewrites /orchestrate vs /plan: both flows require user approval before children launch, and the agent considers orchestration during /plan and surfaces an inline orchestration config block on the plan card. * Replaces 'child agent status card above the agent input' with the orchestration pill bar that ships in the agent view pane header. * Rewrites 'Notifications in orchestrated runs' to reflect that in-app notifications fire on the parent's conversation only (child conversations are excluded from the toast stream and the notification mailbox). Rachael's review (rachaelrenk): * Tightens the Common patterns intro to directly frame the H3 list. Co-Authored-By: Oz <oz-agent@warp.dev>

hongyi-chen · 2026-05-19T19:42:30Z

Refresh: address Matthew's review, rebase on main

Force-pushed b52a764 (one squash-friendly commit) that:

Resets the diff to orchestration-only files. The branch was carrying duplicates of the multi-harness pages, agent identities page, secrets.mdx, federate.mdx, and cli-agents/* updates that PR docs: orchestration launch \u2014 platform credits, multi-harness, agent identities #98 already merged into main. The PR now diffs cleanly against main with 7 files / 349 insertions / 6 deletions.
Addresses Matthew's (cephalonaut) six review comments. All inline replies are posted on the threads themselves; a summary:
- Children no longer claim to spawn their own children. Orchestrations are described as exactly one level deep, matching the Warp app, Oz web app, and Oz API surfaces.
- The "Where parent and child agents can run" section now lists four execution combinations including Cloud → cloud-local (a cloud orchestrator spawning a child that runs inside its own cloud environment).
- /orchestrate vs /plan is rewritten: both flows require user approval before children launch, and the agent considers orchestration during /plan and surfaces an inline orchestration config block on the plan card with model/harness/environment/host/parallelism/auth pickers.
- All "child agent status card above the agent input" references are replaced with the orchestration pill bar in the agent view pane header (pills with live status badges, click-to-switch, parent breadcrumb).
- The "Notifications in orchestrated runs" section now correctly says in-app notifications fire on the parent's conversation only — child conversations are excluded from the toast stream and the notification mailbox via should_exclude_from_navigation(). Readers are pointed at the pill bar and the Sub-agents tab for live per-child state.
Folds in Rachael's last unresolved nit. ## Common patterns intro rewritten to directly frame the H3 list ("The following patterns show common ways…").
Adds the orchestration pages to the sidebar (src/sidebar.ts) under the Oz Cloud Agents & Orchestration topic. Both Multi-agent orchestration and Running orchestrated agents are now registered.

Validation

python3 .agents/skills/style_lint/style_lint.py --changed — 6 files scanned, 0 issues.
python3 .agents/skills/check_for_broken_links/check_links.py --internal-only — 330 files scanned, 2574 internal links, 0 broken.
npm run build — 332 pages built successfully (was previously failing because the new pages weren't registered in the sidebar).

Co-Authored-By: Oz oz-agent@warp.dev

…ess-agnostic, cross-location) Expands the 'Messaging between agents' section in the orchestration concept page to capture the architectural story behind agent-to-agent coordination, in response to a public X user asking how Warp handles state drift across parallel execution. The section now covers: * Durable, server-backed message bus with one inbox per agent (addressed by agent ID), grounded in warp-server/specs/QUALITY-519/TECH.md and the ai_run_event_log Postgres table. * Direct answer to the state-drift question: each run owns its own state; agents exchange explicit messages rather than reading each other's transcripts; messages and run state transitions share a global sequence so the parent never observes 'SUCCEEDED' before the message that produced the result. * Harness-agnostic claim: the mailbox is the same whether the recipient runs the default Warp Agent, Claude Code, Codex, or another runtime; a parent on one harness can message a child on another in either direction. * Cross-location claim: agent ID is the only address; local <-> cloud messaging works across all four execution combinations including the cloud -> cloud-local case. * Resumability: an idle child (terminal-state run) wakes up under the same agent ID when the parent sends a new message. * Cross-link to lifecycle events: same infrastructure delivers the six state-transition event types in parallel with messages, so the parent doesn't have to poll. Also adds a one-sentence pointer in the API section of the how-to page so callers landing on the REST docs find their way to the messaging concept. The public messaging endpoints (/agent/messages, /agent/events) are still x-internal in the OpenAPI spec; the docs describe the mechanism conceptually without exposing the wire format. Co-Authored-By: Oz <oz-agent@warp.dev>

hongyi-chen · 2026-05-19T21:22:53Z

Added: messaging-architecture coverage in the orchestration concept page

Follow-up commit 90066c6 on top of the approved diff. New content lives in the ## Messaging between agents section of src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx (+12 lines, no other content removed).

Motivation: a public X reply asked how Warp handles state drift across parallel execution. The thin existing paragraph didn't capture the architecture. The expanded section now says:

Durable, server-backed message bus. Each agent has its own inbox addressed by its agent ID; messages and run state transitions share a global sequence so the parent never observes a child's SUCCEEDED before the message that produced the result.
Why agents stay consistent without sharing state. Each run owns its conversation, working directory or environment, and credit usage. Agents exchange explicit messages rather than reading each other's transcripts. (This is the direct answer to the X user's framing.)
Harness-agnostic. A parent running with one harness can message a child running with another (Warp Agent ↔ Claude Code ↔ Codex etc.) in either direction.
Cross-location. The agent_id is the only address — local↔cloud, cloud↔cloud, cloud↔cloud-local all use the same mechanism.
Resumable. A child whose current run is in a terminal state wakes back up under the same agent_id when the parent sends a new message.
Lifecycle events flow on the same infrastructure as a parallel signaling channel, cross-linked back to ## Run state transitions.

Also added one cross-reference sentence in multi-agent-runs.mdx's API section opener so callers landing on the REST docs find their way to the model.

Not added: API details for /agent/messages or /agent/events — those routes are still x-internal: true in warp-server/public_api/openapi.yaml, so the docs describe the mechanism conceptually only.

Validation

style_lint --changed → 6 files / 0 issues
check_for_broken_links --internal-only → 2577 internal links / 0 broken
npm run build → 332 pages, green

Co-Authored-By: Oz oz-agent@warp.dev

) Cleanup after the orchestration-launch + multi-agent merges: * warp-hosting.mdx - drop 'Oz' prefix from description and body; remove 'easily' per style guide. * enterprise/analytics-api.mdx:139 - '(Oz cloud agents)' -> '(cloud agents)'. * reference/cli/artifacts.mdx:4 - 'produced by an Oz agent run' -> 'by an agent run'. * privacy.mdx telemetry table (4x) - 'ambient agent' -> 'cloud agent' in event descriptions. The literal event names in the left column (AmbientAgent.*, CLI.Execute.Agent.RunAmbient) stay as-is since they're emitted by product code. * warp-for-product-managers.mdx - '5 AI agent workflows…' -> '5 agent workflows…' (drop redundant 'AI' prefix). * cloud-agents/overview.mdx - add Multi-agent orchestration bullet to the Learn more list (was missing after PR #84 landed). Validation: 0 broken links / 2577 internal, lint clears all 11 previously-flagged OZ-TERM warnings, 332 pages build clean. Co-authored-by: Oz <oz-agent@warp.dev>

cla-bot Bot added the cla-signed label May 16, 2026

vercel Bot had a problem deploying to Preview May 16, 2026 20:31 Failure

oz-for-oss Bot reviewed May 16, 2026

View reviewed changes

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

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

vercel Bot had a problem deploying to Preview May 16, 2026 21:05 Failure

hongyi-chen commented May 16, 2026

View reviewed changes

vercel Bot had a problem deploying to Preview May 16, 2026 21:31 Failure

vercel Bot had a problem deploying to Preview May 16, 2026 23:36 Failure

rachaelrenk reviewed May 18, 2026

View reviewed changes

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

rachaelrenk reviewed May 18, 2026

View reviewed changes

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

rachaelrenk reviewed May 18, 2026

View reviewed changes

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

rachaelrenk reviewed May 18, 2026

View reviewed changes

hongyi-chen mentioned this pull request May 18, 2026

docs(agent-platform): add Agent Memory research-preview pages #86

Merged

vercel Bot had a problem deploying to Preview May 19, 2026 01:14 Failure

vercel Bot had a problem deploying to Preview May 19, 2026 01:16 Failure

rachaelrenk reviewed May 19, 2026

View reviewed changes

hongyi-chen requested a review from cephalonaut May 19, 2026 01:21

rachaelrenk reviewed May 19, 2026

View reviewed changes

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

rachaelrenk reviewed May 19, 2026

View reviewed changes

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

rachaelrenk reviewed May 19, 2026

View reviewed changes

vercel Bot had a problem deploying to Preview May 19, 2026 01:43 Failure

vercel Bot had a problem deploying to Preview May 19, 2026 01:45 Failure

vercel Bot had a problem deploying to Preview May 19, 2026 01:51 Failure

rachaelrenk approved these changes May 19, 2026

View reviewed changes

rachaelrenk mentioned this pull request May 19, 2026

docs(handoff): add local↔cloud handoff documentation #85

Merged

vercel Bot had a problem deploying to Preview May 19, 2026 03:40 Failure

vercel Bot had a problem deploying to Preview May 19, 2026 03:54 Failure

This was referenced May 19, 2026

docs: orchestration launch \u2014 platform credits, multi-harness, agent identities #98

Merged

Audit pass 2: factual corrections, terminology unification, style cleanup #99

Merged

Base automatically changed from hyc/orchestration-launch to main May 19, 2026 07:15

cephalonaut reviewed May 19, 2026

View reviewed changes

hongyi-chen force-pushed the hyc/orch/multi-agent branch from 4852f14 to b52a764 Compare May 19, 2026 19:40

vercel Bot deployed to Preview May 19, 2026 19:43 View deployment

cephalonaut approved these changes May 19, 2026

View reviewed changes

vercel Bot deployed to Preview May 19, 2026 21:24 View deployment

Merge branch 'main' into hyc/orch/multi-agent

c22a5cb

vercel Bot deployed to Preview May 19, 2026 21:36 View deployment

hongyi-chen merged commit 7231038 into main May 19, 2026
8 checks passed

hongyi-chen deleted the hyc/orch/multi-agent branch May 19, 2026 21:39

hongyi-chen mentioned this pull request May 19, 2026

docs(audit): tier 1 — terminology drift + orchestration cross-link #107

Merged


		The supported event types are:

		* `run_in_progress` — the run started executing (or restarted after being paused or blocked).


		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

	### Where each side can run
	### Where parent and child agents can run


		## Common patterns

		Orchestration primitives are general-purpose. Teams typically compose them into a handful of recurring patterns.

	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.


		## Notifications in orchestrated runs

		In a [multi-agent orchestration](/agent-platform/cloud-agents/orchestration/), each child agent is its own conversation. Notifications fire on the child whose state changes — they aren't aggregated on the parent.


		## Approval mode

		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.


		## Starting an orchestrated run from Warp

		In the Warp desktop app, open the agent input and type `/orchestrate` followed by your task. The parent agent enters `orchestrate` mode and proposes a plan before spawning children.

Conversation

hongyi-chen commented May 16, 2026

Summary

Pages

Research grounding

Open questions / needs PM confirmation

Out of scope (per gating plan)

Artifacts

Uh oh!

vercel Bot commented May 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot commented May 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

Uh oh!

Uh oh!

hongyi-chen commented May 16, 2026

Revision pass

Review comments

Slack-thread + internal-only scrub

New: conversations and artifacts in the API

Senior-writer pass

Validation

Open questions

Uh oh!

hongyi-chen May 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hongyi-chen commented May 16, 2026

Copy pass

Uh oh!

hongyi-chen commented May 16, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rachaelrenk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rachaelrenk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rachaelrenk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rachaelrenk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rachaelrenk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rachaelrenk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

vercel Bot commented May 16, 2026 •

edited

Loading

oz-for-oss Bot commented May 16, 2026 •

edited

Loading

hongyi-chen May 16, 2026 •

edited

Loading