diff --git a/src/content/docs/agent-platform/capabilities/agent-notifications.mdx b/src/content/docs/agent-platform/capabilities/agent-notifications.mdx index b285948..db53795 100644 --- a/src/content/docs/agent-platform/capabilities/agent-notifications.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-notifications.mdx @@ -99,10 +99,21 @@ For **third-party CLI agents**, each agent requires a one-time setup. The proces If auto-install doesn't work or you're running an agent over SSH, Warp displays an installation-instructions chip in the terminal with setup steps you can follow directly. +## Notifications in orchestrated runs + +In a [multi-agent orchestration](/agent-platform/cloud-agents/orchestration/), the parent agent and each child agent are separate conversations. Today, in-app notifications fire on the parent's conversation only: child agent conversations are excluded from the toast stream and the notification mailbox so the mailbox doesn't get cluttered with per-child status churn. + +That means: + +* **Toasts and the mailbox** - watch the parent's conversation for `Complete`, `Request`, and `Error` notifications. +* **Per-child state** - use the orchestration pill bar above the agent view header (in the Warp app) or the parent's **Sub-agents** tab on the [Runs page](https://oz.warp.dev/runs) (in the Oz web app) to see each child's live status. Both surfaces update as children transition through `INPROGRESS`, `SUCCEEDED`, `BLOCKED`, `FAILED`, `ERROR`, and `CANCELLED`. +* **Blocked children** - if a child blocks on user input (for example, a command approval request), open that child from the pill bar to resolve the block. The parent's transcript also reflects the child's `BLOCKED` state so the parent can wait, send a follow-up, or cancel the child. + ## Related pages * [Desktop Notifications](/terminal/more-features/notifications/) - configure system-level notification permissions and troubleshoot delivery * [Managing Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - monitor all agent conversations, filter by status, and inspect sessions +* [Multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) - parent/child model, run state transitions, and the orchestration pill bar * [Third-Party CLI Agents](/agent-platform/cli-agents/overview/) - overview of supported CLI agents and Warp features * [Claude Code](/agent-platform/cli-agents/claude-code/) - setup and notification plugin installation * [Codex](/agent-platform/cli-agents/codex/) - setup and notification configuration diff --git a/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx b/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx index c83a962..8b8b3bf 100644 --- a/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx +++ b/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx @@ -101,12 +101,7 @@ Use this when you want Oz to run agent workloads on Warp-managed infrastructure, #### Example recipe: fan-out parallel work (sharding) -If a task is naturally divisible: - -* Launch multiple cloud agents via `oz agent run-cloud`, each with: - * A shard of the repo (directory/module ownership) - * A shard of the prompt (one responsibility) -* Aggregate results (PRs, notes, plans) in whatever system you prefer. +When a task is naturally divisible, use [multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) to spawn one child agent per shard from a single parent run. The parent owns coordination and result aggregation; the children execute in parallel, each with their own repo subset, prompt, and (optionally) model. See [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/) for slash command, CLI, web app, and API examples. #### Example recipe: same task across multiple models diff --git a/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx b/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx index 087b5d6..44a0ac0 100644 --- a/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx @@ -100,9 +100,22 @@ In both _Personal_ and _All_ views, you can open the filter menu and filter by: This is the fastest way to isolate "everything that failed today," "runs from Slack," or "what a specific teammate triggered via integrations." +--- + +### Orchestrated runs (parent and child) + +When a parent agent spawns one or more child agents through [multi-agent orchestration](/agent-platform/cloud-agents/orchestration/), the parent and each child are tracked as separate runs. Where you see them depends on the surface: + +* **Local children in the Warp app** - while you're viewing the parent agent, an orchestration pill bar above the agent view header shows one pill per child with 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. Local children don't appear as separate rows in the management view list. +* **Cloud children in the Warp app** - appear in the management view list as their own rows alongside the parent and other runs. Filter by source, status, or creator to isolate them. +* **Cloud children in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/)** - grouped under the parent's row on the Runs page, and surfaced together inside the parent's detail pane on a **Sub-agents** tab. + +The parent's own status reflects only its work - a parent can finish successfully while a child is still running or has failed. To verify that an orchestration completed, check each child individually from the pill bar (in the Warp app) or the **Sub-agents** tab (in the Oz web app). + ## Related pages * [Cloud agents overview](/agent-platform/cloud-agents/overview/) — What cloud agents are and when to use them. +* [Multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) — Parent/child model, run state transitions, and common orchestration patterns. * [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) — Open and inspect a remote cloud agent run. * [Handoff between local and cloud agents](/agent-platform/cloud-agents/handoff/) — Move agent work between local and cloud, or continue a finished cloud run. * [Oz web app](/agent-platform/cloud-agents/oz-web-app/) — Manage runs and schedules from any browser. diff --git a/src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx b/src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx new file mode 100644 index 0000000..cdaa7a5 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx @@ -0,0 +1,119 @@ +--- +title: Multi-agent orchestration +description: Coordinate a parent agent and its direct child agents across local and cloud runs to build supervisor/worker, fan-out, critic, DAG, and swarm workflows on the Oz Platform. +sidebar: + label: "Orchestration" +--- + +Multi-agent orchestration lets one agent spawn and coordinate other agents to parallelize work, delegate specialized tasks, or verify another agent's output. The parent/child model works from the Warp app, the [Oz CLI](/reference/cli/), and the [Oz API](/reference/api-and-sdk/), and supports local, cloud, and mixed execution. + +This page covers the orchestration model and the patterns it supports. To learn how to start an orchestrated run, see [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/). + +## The parent/child model + +An orchestrated workflow always has one **parent agent** and one or more **child agents**. + +* **Parent agent** - the agent that decides what work needs to be done, spawns child agents, and (optionally) merges their results. Any agent can become a parent the first time it spawns a child. +* **Child agent** - an agent spawned by a parent with its own prompt, environment, and (optionally) a different model or agent runtime. A child runs its own work and reports back; it does not spawn its own children. + +Orchestrations today are exactly one level deep: a parent and its direct children. The Warp app, the [Oz web app](/agent-platform/cloud-agents/oz-web-app/), and the [Oz API](/reference/api-and-sdk/) render that single level. The parent and each child each have an independent **run** with its own lifecycle, transcript, conversation, and credit usage. + +### Where parent and child agents can run + +The parent and child don't have to run in the same place. Orchestration supports four combinations: + +* **Local → local** - a [Warp Agent](/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 that each run in their own environment. This is the canonical pattern for review swarms, large fan-outs, and any orchestration triggered from Slack, Linear, a schedule, or the API. +* **Cloud → cloud-local** - a cloud parent spawns children that run inside the parent's own cloud environment, rather than each child getting its own environment. Useful when children need to share state with the parent (a filesystem, a long-running process, a shell session) or when spinning up an environment per child would be wasteful. + +Children can also run with a different agent runtime than the parent. A parent running with the default Warp Agent can spawn children that run with [Claude Code](/agent-platform/cli-agents/claude-code/) or [Codex](/agent-platform/cli-agents/codex/), and vice versa. + +## Run state transitions + +Each run progresses through a small set of states. The parent observes these transitions to decide what to do next - keep waiting, send a follow-up, spawn a replacement, or finish. + +The main user-visible states a child run can reach are: + +* **`INPROGRESS`** - the run is actively executing (or has restarted after being blocked). +* **`SUCCEEDED`** - the run completed successfully. +* **`FAILED`** - the run hit a terminal failure. +* **`BLOCKED`** - the run is waiting on a user action (for example, command approval or a permission request). +* **`ERROR`** - the run encountered an error during startup or execution. +* **`CANCELLED`** - the run was cancelled before reaching a terminal state. + +Track run state transitions in these places: + +* **The parent's transcript** - the parent agent receives child state transitions as it runs and reflects them in its own conversation. +* **The orchestration pill bar** - in the Warp desktop app, while you're viewing the parent agent, a horizontal pill bar above the agent view header shows the parent on the left and one pill per child. Each pill displays the child's name and a status badge that updates live. Click a pill to switch the pane to that child's conversation in place; click the parent pill to switch back. +* **The Oz web app** - cloud children appear under the parent on the [Runs page](https://oz.warp.dev/runs) and in the parent's **Sub-agents** tab, with their status updating live. +* **The Oz API** - `GET /agent/runs/{runId}` returns the latest state of any run, and `GET /agent/runs?ancestor_run_id=PARENT_RUN_ID` lists every descendant in one call. + +## Messaging between agents + +Orchestration is built on a durable, server-backed message bus. Every agent in an orchestration - parent and children - has its own inbox addressed by its agent ID, and the parent and children send each other short, structured messages to coordinate, hand off work, and stay in sync as they run. + +This is how parallel agents stay consistent without sharing mutable state. Each run owns its own conversation, working directory or environment, and credit usage; agents don't read each other's transcripts or live working trees. Instead, they exchange explicit messages whenever they need to communicate a decision, a result, or a question. Messages and run state transitions share a global sequence number so the parent never observes a child's `SUCCEEDED` state before the message that produced the result. + +The same messaging infrastructure works across every combination of agent runtimes and execution locations: + +* **Harness-agnostic** - the mailbox is the same whether the recipient runs the default Warp Agent, [Claude Code](/agent-platform/cli-agents/claude-code/), [Codex](/agent-platform/cli-agents/codex/), or another agent runtime. A parent running with one harness can message a child running with another, in either direction. +* **Cross-location** - the agent ID is the only address that matters. A local parent can message a cloud child, a cloud parent can message a local-to-cloud child running inside its own environment, and cloud parents can fan out messages to cloud children running in different environments. +* **Resumable** - a child whose current run has reached a terminal state (`SUCCEEDED`, `FAILED`, `CANCELLED`, or `ERROR`) is not gone. It is still addressable by its agent ID and will wake up to handle follow-up instructions when the parent sends a new message. + +Alongside messages, every run emits **lifecycle events** on the same infrastructure when its state changes - the six states listed in [Run state transitions](#run-state-transitions). The parent observes these events to decide what to do next (keep waiting, send a follow-up, spawn a replacement, finish) without polling any child. + +Use messages for coordination signals - handoffs, decisions, blocked-on-input requests, status updates, and final results - rather than for piping full transcripts around. The parent's prompt to a child and the child's final output carry the substance of the work; messages are how the agents talk *about* the work as it happens. + +## Common 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. + +### Supervisor / worker + +A parent supervisor agent breaks the task into a queue of work items, spawns worker children to claim and complete each item, and writes a summary when the queue is empty. Use this when the task is naturally divisible and you want a single agent to own coordination. + +### Fan-out / fan-in + +The parent spawns N children in parallel, each with a sharded prompt (one module, one file set, one test target, one model), then waits for all of them to complete and merges their results. Use this for large refactors, repo-wide migrations, or running the same task across multiple targets. + +### Critic / verifier + +The parent (the "writer") proposes a solution, then spawns a critic child to review it. The critic returns notes; the writer revises; the cycle repeats until the critic approves or a budget is exhausted. Useful when correctness matters more than throughput. + +### Review swarm (cloud → cloud) + +A scheduled or webhook-triggered parent spawns one cloud child per open pull request to run reviews in parallel. Each child posts its findings as a comment and exits. The parent fans in the results and posts a summary back to the triggering system. + +### DAG + +The parent encodes a directed acyclic graph of subtasks where some nodes depend on the outputs of others. It spawns ready nodes, waits on their state transitions, and spawns dependents as upstream nodes complete. Use this when the workflow has explicit ordering constraints (build → test → deploy, for example). + +### Swarm + +A flat group of peer agents discover each other through messaging and coordinate without a strict hierarchy. The parent acts more like a coordinator than a supervisor. Use sparingly - swarms are powerful but harder to debug than hierarchical patterns. + +## Approval mode + +Two slash commands surface orchestration in the Warp app, and both require explicit user approval before any children launch: + +* **`/orchestrate`** asks the agent to apply orchestration to the task. The agent proposes a breakdown - number of children, prompts, environments, parallelism - and waits for approval. The API equivalent is setting `mode: orchestrate` on `POST /agent/runs`. +* **`/plan`** asks the agent to research and produce a plan for a complex task. The agent always considers orchestration while planning, and proposes it as part of the plan when the work would benefit. When orchestration is part of the plan, the plan card surfaces an inline **orchestration config** block above the plan with model, harness, environment, host, and parallelism pickers; you can adjust the config and then approve the plan to start spawning children. The API equivalent is `mode: plan`. + +In both cases, approval is required before the parent launches children. Approving an orchestration also approves the run-wide config (model, harness, environment, host) that every child inherits unless the parent overrides it per child. + +## Observability + +Because every parent and child is tracked as its own conversation or run, the existing observability surfaces work without changes: + +* **[Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/)** - in the Warp app, the orchestration pill bar above the agent view header lets you switch between the parent and each child while you're viewing the parent. Cloud children also appear as their own rows in the management view list. +* **[Oz web app](/agent-platform/cloud-agents/oz-web-app/)** - the Runs page groups cloud children under the parent's row, and the parent's detail pane adds a **Sub-agents** tab. +* **[Oz API](/reference/api-and-sdk/)** - list every descendant of a parent in one call and fetch any run with its conversation, transcript, and artifacts. See [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/#retrieving-conversations-and-artifacts). +* **[Agent notifications](/agent-platform/capabilities/agent-notifications/)** - in-app notifications fire on the parent agent's conversation only. Use the pill bar or the **Sub-agents** tab to drill into a specific child. + +## Related pages + +* [Running orchestrated agents](/agent-platform/cloud-agents/orchestration/multi-agent-runs/) - how to start an orchestrated run from the CLI, slash command, web app, or API. +* [Oz API and SDK](/reference/api-and-sdk/) - REST endpoints for runs, conversations, and artifacts. +* [Cloud agents overview](/agent-platform/cloud-agents/overview/) - what a cloud agent run is and how it fits into the Oz Platform. +* [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) - higher-level deployment models that orchestration composes with. diff --git a/src/content/docs/agent-platform/cloud-agents/orchestration/multi-agent-runs.mdx b/src/content/docs/agent-platform/cloud-agents/orchestration/multi-agent-runs.mdx new file mode 100644 index 0000000..8a3ec0e --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/orchestration/multi-agent-runs.mdx @@ -0,0 +1,190 @@ +--- +title: Running orchestrated agents +description: Start multi-agent orchestrations from the Warp app, the Oz CLI, the Oz web app, or the Oz API, and inspect parent and child conversations and artifacts. +sidebar: + label: "Running orchestrated agents" +--- + +An orchestrated run starts with a parent agent that spawns one or more child agents. You can start a parent from the Warp app, the Oz CLI, the Oz web app, or the Oz API. Use orchestrated runs to review a plan before fan-out, execute children locally or in the cloud, and inspect parent and child conversations as they work. + +## Before you start + +Pick where the parent will run. Every orchestration starts with a single parent that spawns children: + +* **Parent in the Warp app** - use the `/orchestrate` or `/plan` slash command. This is the fastest way to try orchestration. +* **Parent in the cloud** - trigger the parent through the Oz CLI (`oz agent run-cloud`), the [Oz API](/reference/api-and-sdk/), or any integration (Slack, Linear, schedule). The parent runs in an environment and spawns children from there. + +Cloud parents that spawn cloud children need access to one or more [environments](/agent-platform/cloud-agents/environments/) the children can run in. + +## Starting an orchestrated run from Warp + +In the Warp desktop app, open the agent input and type `/orchestrate` followed by your task. The agent enters `orchestrate` mode and proposes a breakdown before spawning any children. + +```text +/orchestrate Migrate every test file in this repo from Jest to Vitest. Spawn one child per top-level directory under packages/. +``` + +The agent responds with a proposal that describes: + +* How many children it intends to spawn. +* Each child's prompt and environment. +* What it expects each child to return. + +Approve the proposal to start spawning children. The parent's transcript renders each child as it spawns, and 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 to the parent. + +### Letting the agent propose orchestration during /plan + +You can also reach the same approval flow from `/plan`. When you ask the agent to plan a complex task, it considers orchestration as part of planning and proposes it whenever the work would benefit. When that happens, the plan card includes an inline **orchestration config** block above the plan content with model, harness, environment, host, parallelism, and auth pickers. Edit the config as needed, review the plan's orchestration section (number of children, what each child owns), and approve the plan to start spawning children with the configured run-wide settings. + +### Spawning cloud children from a local parent + +A local parent - a Warp Agent conversation in the desktop app - can spawn cloud children by specifying an environment for each child. The parent asks for the environment if it isn't already clear from context. You can select any environment from your account or team. + +Cloud children inherit the parent's authentication; the same credit and credentials rules from the [Cloud agents overview](/agent-platform/cloud-agents/overview/) apply. + +## Starting an orchestrated run from the CLI + +Use `oz agent run-cloud` to start a parent and let the agent itself spawn children as it works. + +```bash +oz agent run-cloud \ + --prompt "Review the open pull requests in this repo and post a summary on each. Spawn one child agent per PR." \ + --environment YOUR_ENVIRONMENT_ID +``` + +This is the recommended way to fan work out from the CLI: the parent decides how many children to spawn, links them to itself automatically, and you get a single parent run ID back to follow. + +:::note +If you need to fan out from a script and want each child linked to a specific parent, use the [API](#starting-an-orchestrated-run-from-the-api). `oz agent run-cloud` doesn't currently accept a parent run ID flag, so script-launched runs from the CLI are independent runs. +::: + +## Starting an orchestrated run from the Oz web app + +In the Oz web app's [**Runs** page](https://oz.warp.dev/runs): + +1. Click **New run** in the header. +2. Select an environment and, optionally, a skill that performs orchestration. The [oz-skills repo](https://github.com/warpdotdev/oz-skills) includes orchestration skills like review swarms and fan-out runners. +3. Enter the parent's prompt. Describe both the high-level task and the orchestration shape you want (number of children, parallelism, success criteria). +4. Click **Run**. + +The parent run starts and children appear in the Runs list as the parent spawns them, nested under the parent row. + +## Starting an orchestrated run from the API + +Spawn the parent with `POST /agent/runs`. Children can either be spawned by the parent agent at runtime, or you can spawn each child explicitly from your code and link it to the parent with `parent_run_id`. Once they're running, coordination between the parent and its children flows through Warp's durable agent-to-agent messaging - see [Messaging between agents](/agent-platform/cloud-agents/orchestration/#messaging-between-agents) for the model. + +### Agent-driven orchestration + +Start a single parent run with `mode: orchestrate`: + +```http +POST /api/v1/agent/runs +Authorization: Bearer YOUR_API_KEY +Content-Type: application/json + +{ + "prompt": "Coordinate a code review across every open PR in the repo. Spawn one child per PR.", + "mode": "orchestrate", + "config": { + "environment_id": "YOUR_ENVIRONMENT_ID" + }, + "title": "PR review swarm" +} +``` + +The parent decides how many children to spawn. Children inherit the parent's authentication and bill to the same account. + +### Caller-driven orchestration + +Spawn each child explicitly with `parent_run_id` set to the parent's `run_id`: + +```http +POST /api/v1/agent/runs +Authorization: Bearer YOUR_API_KEY +Content-Type: application/json + +{ + "prompt": "Review PR #123", + "config": { + "environment_id": "YOUR_ENVIRONMENT_ID" + }, + "parent_run_id": "YOUR_PARENT_RUN_ID", + "title": "Review PR #123" +} +``` + +Setting `parent_run_id` is what links the child to its parent across the management view, the web app, and the descendants query (`?ancestor_run_id=`). + +A scripted fan-out, including parent linking, looks like this: + +```bash +PARENT_RUN_ID=$(curl -sS -X POST https://app.warp.dev/api/v1/agent/runs \ + -H "Authorization: Bearer $WARP_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "prompt": "Coordinate the migration", + "mode": "orchestrate", + "config": {"environment_id": "YOUR_ENVIRONMENT_ID"}, + "title": "Jest to Vitest migration" + }' | jq -r .run_id) + +for shard in pkg-a pkg-b pkg-c; do + curl -sS -X POST https://app.warp.dev/api/v1/agent/runs \ + -H "Authorization: Bearer $WARP_API_KEY" \ + -H "Content-Type: application/json" \ + -d "{ + \"prompt\": \"Migrate $shard from Jest to Vitest\", + \"config\": {\"environment_id\": \"YOUR_ENVIRONMENT_ID\"}, + \"parent_run_id\": \"$PARENT_RUN_ID\", + \"title\": \"Migrate $shard\" + }" +done +``` + +## Retrieving conversations and artifacts + +Every parent and child started through the Oz API is tracked as an Oz run. Run responses include the run's `state`, `parent_run_id` (set on children only), `conversation_id`, `session_link`, and an `artifacts` array of any pull requests, plans, screenshots, or files the run produced. Use the same endpoints you'd use for any other run: + +* **List every descendant of a parent** - `GET /api/v1/agent/runs?ancestor_run_id=YOUR_PARENT_RUN_ID`. From the CLI: `oz run list --ancestor-run YOUR_PARENT_RUN_ID`. +* **Get one run's details and artifacts** - `GET /api/v1/agent/runs/YOUR_RUN_ID`. +* **Read the normalized conversation** - `GET /api/v1/agent/runs/YOUR_RUN_ID/conversation` returns a structured sequence of messages, tool calls, and events. +* **Download the raw transcript** - `GET /api/v1/agent/runs/YOUR_RUN_ID/transcript` returns a redirect to a time-limited download URL. + +All four endpoints work the same for the parent and any child. + +## Cancelling a fleet + +Cancel any run with `POST /agent/runs/{runId}/cancel`: + +```http +POST /api/v1/agent/runs/YOUR_RUN_ID/cancel +Authorization: Bearer YOUR_API_KEY +``` + +Cancelling the parent does **not** automatically cancel its children. This is intentional: in many orchestrations, you want children to finish even after the parent ends. To cancel everything, list the descendants and cancel each one, then cancel the parent: + +```bash +# List every descendant of the parent, then cancel each. +oz --output-format json run list --ancestor-run "$PARENT_RUN_ID" \ + | jq -r '.runs[].run_id' \ + | xargs -I{} curl -sS -X POST \ + https://app.warp.dev/api/v1/agent/runs/{}/cancel \ + -H "Authorization: Bearer $WARP_API_KEY" + +# Finally cancel the parent. +curl -sS -X POST \ + "https://app.warp.dev/api/v1/agent/runs/$PARENT_RUN_ID/cancel" \ + -H "Authorization: Bearer $WARP_API_KEY" +``` + +:::caution +Self-hosted, local, and GitHub Action runs cannot be cancelled through this endpoint and return a `422`. Stop them through your own infrastructure. +::: + +## Related pages + +* [Multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) - parent/child model, run state transitions, and common patterns. +* [Oz CLI](/reference/cli/) - command reference for `oz agent run-cloud` and `oz run`. +* [Oz API and SDK](/reference/api-and-sdk/) - full HTTP reference and typed SDKs. +* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - how parent and child runs appear in the management view. +* [Environments](/agent-platform/cloud-agents/environments/) - configure the runtime context cloud children execute in. diff --git a/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx b/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx index 6d29a54..d7085b8 100644 --- a/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx +++ b/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx @@ -289,9 +289,28 @@ For detailed integration setup instructions, see [Slack](/agent-platform/cloud-a --- +## Orchestrated runs + +The Oz web app renders [multi-agent orchestrations](/agent-platform/cloud-agents/orchestration/) as nested rows on the [**Runs** page](https://oz.warp.dev/runs) so you can follow parent and child execution together. + +### Where to start an orchestration + +* **New run** - when starting a new run, choose a skill that performs orchestration or write an `orchestrate`-mode prompt. The parent decides how many children to spawn based on the prompt. +* **Agents page** - the **Suggested** tab on the [**Agents** page](https://oz.warp.dev/agents) includes orchestration skills like review swarms and fan-out runners. Click **Run** on one to dispatch a parent. + +### Inspecting an orchestration + +Open a parent run from the Runs page. When the run has children, the detail pane adds a **Sub-agents** tab next to **Details**: + +* Each child agent row shows the child's current status and title. Click a row to open that child's detail pane; closing it returns you to the parent's **Sub-agents** tab. +* The parent's own status badge at the top of the detail pane reflects the parent's work, not its children. Open a child to inspect its state directly. + +--- + ## Related resources * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — Learn about cloud agents and when to use them +* [Multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) — Parent/child model and common orchestration patterns * [Agent identities](/agent-platform/cloud-agents/agents/) — Team-scoped bot accounts that own and execute runs * [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/) — Run agents based on reusable skill definitions * [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) — Run agents automatically on a cron schedule diff --git a/src/sidebar.ts b/src/sidebar.ts index cabd740..4fdd029 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -351,6 +351,14 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ }, 'agent-platform/cloud-agents/environments', { slug: 'agent-platform/cloud-agents/managing-cloud-agents', label: 'Managing cloud agents' }, + { + label: 'Orchestration', + collapsed: true, + items: [ + { slug: 'agent-platform/cloud-agents/orchestration', label: 'Multi-agent orchestration' }, + { slug: 'agent-platform/cloud-agents/orchestration/multi-agent-runs', label: 'Running orchestrated agents' }, + ], + }, { slug: 'agent-platform/cloud-agents/agents', label: 'Agent identities' }, { slug: 'agent-platform/cloud-agents/oz-web-app', label: 'Oz web app' }, { slug: 'agent-platform/cloud-agents/skills-as-agents', label: 'Skills as agents' },