Skip to content

docs: add AEO cross-links for agents and orchestration #662

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
warp-factories wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: add AEO cross-links for agents and orchestration #662

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions src/content/docs/platform/handoff/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,13 +56,14 @@ Handoff is best-effort. When the receiving agent can apply the prior session's c

Each direction has a clear motivating workflow.

* **Local to cloud** - Use when a local conversation has grown into work that's better done in the cloud: long-running tasks you don't want to keep your laptop awake for, parallel variants of the same task, or steering work from another device once it's running.
* **Cloud to cloud** - Use when a cloud agent finished and you want to send a follow-up without losing the prior workspace state. Also useful when a Slack-triggered or scheduled run completes and someone on the team wants to push it further.
* **Local to cloud** - Use when a local conversation has grown into work that's better done in the cloud: long-running tasks you don't want to keep your laptop awake for, [parallel variants of the same task](/platform/orchestration/), or steering work from another device once it's running.
* **Cloud to cloud** - Use when a cloud agent finished and you want to send a follow-up without losing the prior workspace state. Also useful when a [Slack-triggered](/platform/integrations/slack/) or [scheduled](/platform/triggers/scheduled-agents/) run completes and someone on the team wants to push it further.
* **Cloud to local** - Use when a cloud agent has done the heavy lifting and you want to take over locally to verify, iterate, or polish before shipping.

## Related pages

* [Cloud agents overview](/platform/) - What cloud agents are, when to use them, and how they fit into the {VARS.WARP_AUTOMATION_PLATFORM}.
* [Multi-agent orchestration](/platform/orchestration/) - Fan out parallel cloud variants after a local-to-cloud handoff.
* [Managing cloud agents](/platform/managing-cloud-agents/) - Inspect handoff runs from the Agent Management Panel in the Warp app or the Runs page in the {VARS.WEB_APP} alongside local conversations.
* [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open and continue a cloud run locally with **Continue locally** or `/continue-locally`.
* [Cloud-synced conversations](/agents/local-agents/cloud-conversations/) - How conversations sync between local and cloud so handoff can find them.
Expand Down
6 changes: 4 additions & 2 deletions src/content/docs/platform/harnesses/claude-code.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@ This page covers Claude Code as a **cloud** harness, dispatched and orchestrated

## Key features

* **Cloud orchestration** - Launch Claude Code from any {VARS.WARP_AUTOMATION_PLATFORM} trigger: the Warp app, the {VARS.WEB_APP}, the {VARS.WARP_AGENT_CLI}, the REST API, schedules, Slack mentions, Linear issues, or GitHub Actions.
* **Cloud orchestration** - Launch Claude Code from any {VARS.WARP_AUTOMATION_PLATFORM} trigger: the Warp app, the {VARS.WEB_APP}, the {VARS.WARP_AGENT_CLI}, the REST API, [schedules](/platform/triggers/scheduled-agents/), [Slack](/platform/integrations/slack/) mentions, Linear issues, or GitHub Actions.
* **Claude model picker** - Choose the Claude model the harness uses, including the latest pinned Opus, Sonnet, and Haiku releases, the `best`/`opus`/`sonnet`/`haiku` aliases, and 1M-context variants.
* **First-class subagent** - A Warp Agent parent can dispatch Claude Code subagents to handle steps that require code review or nuanced judgment within a larger orchestration.
* **First-class subagent** - A Warp Agent parent can dispatch Claude Code subagents to handle steps that require code review or nuanced judgment within a larger [multi-agent orchestration](/platform/orchestration/).

## Available models

Expand Down Expand Up @@ -52,6 +52,8 @@ For setup steps, see [Connecting Claude Code credentials](/platform/harnesses/au
* [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/) — choose between Warp Agent, Claude Code, and Codex.
* [Authentication](/platform/harnesses/authentication/) — store Anthropic credentials as Warp-managed secrets.
* [Warp Agent with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/warp-agent/) — the {VARS.WARP_AUTOMATION_PLATFORM}'s default harness, the only one that can orchestrate Claude Code subagents.
* [Multi-agent orchestration](/platform/orchestration/) — coordinate a Warp Agent parent with Claude Code children across local and cloud runs.
* [Managing cloud agents](/platform/managing-cloud-agents/) — inspect Claude Code cloud runs in the Agent Management Panel and the Runs page.
* [Codex with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/codex/) — Codex as a cloud harness.
* [Claude Code in Warp](/agents/cli-agents/claude-code/) — Claude Code in your local Warp terminal.
* [Factory agents](/factories/factory-agents/#configuring-a-third-party-harness) — configure Claude Code as a factory agent's harness.
6 changes: 4 additions & 2 deletions src/content/docs/platform/harnesses/codex.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@ This page covers Codex as a **cloud** harness, dispatched and orchestrated by th

## Key features

* **Cloud orchestration** - Launch Codex from any {VARS.WARP_AUTOMATION_PLATFORM} trigger: the Warp app, the {VARS.WEB_APP}, the {VARS.WARP_AGENT_CLI}, the REST API, schedules, Slack mentions, Linear issues, or GitHub Actions.
* **Cloud orchestration** - Launch Codex from any {VARS.WARP_AUTOMATION_PLATFORM} trigger: the Warp app, the {VARS.WEB_APP}, the {VARS.WARP_AGENT_CLI}, the REST API, [schedules](/platform/triggers/scheduled-agents/), [Slack](/platform/integrations/slack/) mentions, Linear issues, or GitHub Actions.
* **Codex model picker** - Choose the OpenAI model Codex uses, including the GPT-5 lineup and Codex-tuned variants, each available at a configurable reasoning level.
* **First-class subagent** - A Warp Agent parent can dispatch Codex subagents to handle high-volume or well-defined coding steps inside a larger orchestration.
* **First-class subagent** - A Warp Agent parent can dispatch Codex subagents to handle high-volume or well-defined coding steps inside a larger [multi-agent orchestration](/platform/orchestration/).

## Available models

Expand Down Expand Up @@ -52,6 +52,8 @@ For setup steps, see [Connecting Codex credentials](/platform/harnesses/authenti
* [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/) — choose between Warp Agent, Claude Code, and Codex.
* [Authentication](/platform/harnesses/authentication/) — store OpenAI credentials as Warp-managed secrets.
* [Warp Agent with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/warp-agent/) — the {VARS.WARP_AUTOMATION_PLATFORM}'s default harness, the only one that can orchestrate Codex subagents.
* [Multi-agent orchestration](/platform/orchestration/) — coordinate a Warp Agent parent with Codex children across local and cloud runs.
* [Managing cloud agents](/platform/managing-cloud-agents/) — inspect Codex cloud runs in the Agent Management Panel and the Runs page.
* [Claude Code with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/claude-code/) — Claude Code as a cloud harness.
* [Codex CLI in Warp](/agents/cli-agents/codex/) — Codex in your local Warp terminal.
* [Factory agents](/factories/factory-agents/#configuring-a-third-party-harness) — configure Codex as a factory agent's harness.
7 changes: 5 additions & 2 deletions src/content/docs/platform/orchestration/multi-agent-runs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ Watch this walkthrough to see how to start and inspect an orchestrated agent run
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 {VARS.WARP_AGENT_CLI} (`oz agent run-cloud`), the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), or any integration (Slack, Linear, schedule). The parent runs in an environment and spawns children from there.
* **Parent in the cloud** - trigger the parent through the {VARS.WARP_AGENT_CLI} (`oz agent run-cloud`), the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), or any [integration](/platform/integrations/) such as [Slack](/platform/integrations/slack/), Linear, or a [schedule](/platform/triggers/scheduled-agents/). The parent runs in an environment and spawns children from there.

Cloud parents that spawn cloud children need access to one or more [environments](/platform/environments/) the children can run in.
Cloud parents that spawn cloud children need access to one or more [environments](/platform/environments/) the children can run in. To keep child execution on your own infrastructure, route those children to a [self-hosted worker](/platform/self-hosting/).

## Starting an orchestrated run from Warp

Expand Down Expand Up @@ -196,4 +196,7 @@ Self-hosted, local, and GitHub Action runs cannot be cancelled through this endp
* [{VARS.WARP_AGENT_CLI}](/reference/cli/) - command reference for `oz agent run-cloud` and `oz run`.
* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - full HTTP reference and typed SDKs.
* [Managing cloud agents](/platform/managing-cloud-agents/) - how parent and child runs appear in the Agent Management Panel in the Warp app and the Runs page in the {VARS.WEB_APP}.
* [Scheduled agents](/platform/triggers/scheduled-agents/) - start a recurring cloud parent that fans out children on a cron cadence.
* [Self-hosting](/platform/self-hosting/) - keep parent or child execution on your infrastructure while Warp tracks the runs.
* [Handoff between local and cloud agents](/platform/handoff/) - promote a local parent to the cloud, or continue a finished cloud parent with a follow-up.
* [Environments](/platform/environments/) - configure the runtime context cloud children execute in.
9 changes: 6 additions & 3 deletions src/content/docs/platform/self-hosting/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Self-hosting lets your team run cloud agent workloads on your own infrastructure

Self-hosting has two architectures. The core distinction is **who orchestrates agent runs** — not who owns the compute. Both models keep code and execution on your infrastructure.

* **Managed** — The {VARS.WARP_AUTOMATION_PLATFORM} orchestrates agent runs. You run the `oz-agent-worker` daemon on your infrastructure; it connects to the {VARS.WARP_AUTOMATION_PLATFORM} and waits for work. Slack mentions, Linear comments, schedules, API calls, and `oz agent run-cloud` commands all route tasks to your worker, which executes them in isolated Docker containers, Kubernetes Jobs, or directly on the host. Similar to a [GitHub self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners).
* **Managed** — The {VARS.WARP_AUTOMATION_PLATFORM} orchestrates agent runs. You run the `oz-agent-worker` daemon on your infrastructure; it connects to the {VARS.WARP_AUTOMATION_PLATFORM} and waits for work. [Slack](/platform/integrations/slack/) mentions, Linear comments, [schedules](/platform/triggers/scheduled-agents/), API calls, and `oz agent run-cloud` commands all route tasks to your worker, which executes them in isolated Docker containers, Kubernetes Jobs, or directly on the host. Similar to a [GitHub self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners).
* **Unmanaged** — You orchestrate agent runs. You invoke `oz agent run` directly from your existing CI pipeline, Kubernetes pod, VM, or dev box. The {VARS.WARP_AUTOMATION_PLATFORM} provides session tracking and observability for each run, but does not start or stop agents for you.

### At a glance
Expand Down Expand Up @@ -197,8 +197,8 @@ Musl-based Docker images (such as Alpine Linux) are not supported as task images

Self-hosted runs have the same observability as Warp-hosted runs:

* **Run history** — View task status, history, and metadata in the {VARS.DASHBOARD}, hosted in the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a>.
* **Session sharing** — Authorized teammates can attach to running tasks to monitor progress.
* **Run history** — View task status, history, and metadata in the {VARS.DASHBOARD}, hosted in the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a>, or filter by source and status in the [Agent Management Panel](/platform/managing-cloud-agents/).
* **Session sharing** — Authorized teammates can attach to running tasks to [monitor progress](/agents/local-agents/session-sharing/).
* **APIs and SDKs** — Query task history and build monitoring using the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/).

For infrastructure-level observability, the `oz-agent-worker` daemon can export OpenTelemetry metrics (worker health, task throughput, capacity saturation) to Prometheus, an OTLP collector, or the console. See [Monitoring](/platform/self-hosting/monitoring/) for setup, the full metric catalog, and sample PromQL queries.
Expand All @@ -217,5 +217,8 @@ For infrastructure-level observability, the `oz-agent-worker` daemon can export
* [Security and networking](/platform/self-hosting/security-and-networking/) — Data boundaries, network egress, and security considerations.
* [Troubleshooting](/platform/self-hosting/troubleshooting/) — Worker won't start, tasks not picked up, and other common issues.
* [Deployment patterns](/platform/deployment-patterns/) — How self-hosting compares to CLI-only and Warp-hosted deployment.
* [Scheduled agents](/platform/triggers/scheduled-agents/) — Route recurring cloud agent work to a self-hosted worker with `--host`.
* [Integrations](/platform/integrations/) — Point Slack, Linear, and other triggers at a self-hosted worker.
* [Managing cloud agents](/platform/managing-cloud-agents/) — Inspect self-hosted runs alongside Warp-hosted ones.
* [Environments](/platform/environments/) — Define the runtime context for agent tasks.
* [Customizing workspace snapshots](/platform/handoff/snapshots/) — Configure end-of-run snapshots so handoff works when running outside the bundled cloud agent image.
Loading