diff --git a/AGENTS.md b/AGENTS.md index 53984087..be218c56 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -177,6 +177,35 @@ Use formatting consistently to distinguish different types of content: - File naming: lowercase, hyphens, descriptive (`agent-mode-code-diff.png`, not `Screenshot 2026-03-15.png`) - Store PNGs in `src/assets/
/` (Astro optimizes them) and GIFs in `public/assets/
/` (to bypass optimization). See the "Assets" section below for the full convention. +#### Screenshot placement guidelines +Use screenshots to clarify product surfaces, configuration points, or visual states that are hard to understand from prose alone. Don't add screenshots for every step in a straightforward procedure. + +**Good screenshot placements:** +- **After the concept or behavior is introduced** — Place the screenshot immediately after the paragraph that explains the UI or state it shows. +- **Near configuration instructions** — Show settings panels, side panes, or menus where users make choices. +- **Near status or result explanations** — Show outputs, references, badges, progress indicators, or completion states that help users recognize success. +- **At the start of visual feature pages** — Use a broad orientation screenshot early when the page explains a new surface or layout. + +**Avoid:** +- Repeating the same surface in multiple screenshots unless each image shows a meaningfully different state. +- Screenshots that duplicate obvious text instructions without adding visual context. +- Screenshots that include sensitive workspace data, private repo names, tokens, customer data, or personal information. +- Images with stale UI labels, hidden feature flags, or unfinished internal-only surfaces. + +#### Screenshot sizing standards +Use consistent screenshot widths so docs pages feel visually balanced. Crop unnecessary empty space before resizing, then choose the closest standard size. + +**Standard widths:** +- **Large screenshots: default content width** — Use normal `
` or Markdown image rendering for full-window, full-pane, or broad product-surface screenshots where the surrounding layout matters. In legacy GitBook screenshots, this was usually `563px`. +- **Medium screenshots: ~375px** — Use for narrow UI surfaces such as popovers, command menus, side panes, dropdowns, and focused interaction flows. This is the preferred constrained size for most small Warp UI screenshots. +- **Small screenshots: ~300-350px** — Use for tightly cropped controls, chips, buttons, tooltips, and small menus. Use a smaller width only when the UI remains legible and the crop is intentionally compact. + +**Rules:** +- **Avoid arbitrary widths** — Choose the nearest standard size instead of one-off values. If a screenshot needs a different size, the reason should be clear from the UI being shown. +- **Keep sequences consistent** — Screenshots in the same section or step sequence should use the same width unless they show meaningfully different UI surfaces. +- **Preserve legibility** — Text in the screenshot must remain readable at the chosen size on the docs page. +- **Prefer the default figure size for large screenshots** — Only constrain width when the screenshot is a narrow UI element that looks oversized at full content width. + #### Image caption guidelines Captions orient the reader — they identify what the image shows so the reader knows where to look. They are not a place for instructions, marketing language, or exhaustive descriptions. diff --git a/src/assets/agent-platform/local-to-cloud-handoff-chip.png b/src/assets/agent-platform/local-to-cloud-handoff-chip.png new file mode 100644 index 00000000..1c907e58 Binary files /dev/null and b/src/assets/agent-platform/local-to-cloud-handoff-chip.png differ diff --git a/src/assets/agent-platform/local-to-cloud-handoff-environment-selector.png b/src/assets/agent-platform/local-to-cloud-handoff-environment-selector.png new file mode 100644 index 00000000..d893989b Binary files /dev/null and b/src/assets/agent-platform/local-to-cloud-handoff-environment-selector.png differ diff --git a/src/assets/agent-platform/local-to-cloud-handoff-follow-up-prompt.png b/src/assets/agent-platform/local-to-cloud-handoff-follow-up-prompt.png new file mode 100644 index 00000000..4de081aa Binary files /dev/null and b/src/assets/agent-platform/local-to-cloud-handoff-follow-up-prompt.png differ diff --git a/src/assets/agent-platform/local-to-cloud-handoff-input-entrypoint.png b/src/assets/agent-platform/local-to-cloud-handoff-input-entrypoint.png new file mode 100644 index 00000000..030d7ad5 Binary files /dev/null and b/src/assets/agent-platform/local-to-cloud-handoff-input-entrypoint.png differ diff --git a/src/assets/agent-platform/local-to-cloud-handoff-slash-command.png b/src/assets/agent-platform/local-to-cloud-handoff-slash-command.png new file mode 100644 index 00000000..b55d7c2e Binary files /dev/null and b/src/assets/agent-platform/local-to-cloud-handoff-slash-command.png differ diff --git a/src/content/docs/agent-platform/agent-memory/index.mdx b/src/content/docs/agent-platform/agent-memory/index.mdx index 2701051d..c0f3ca19 100644 --- a/src/content/docs/agent-platform/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/agent-memory/index.mdx @@ -1,8 +1,8 @@ --- title: Agent Memory (Research Preview) description: >- - Agent Memory is a persistent, cross-harness memory layer for agents in - Oz, including the Warp Agent, Claude Code, and Codex. + Agent Memory gives agents in Oz persistent memory across supported harnesses, + including the Warp Agent, Claude Code, and Codex. sidebar: label: "Agent Memory (Research Preview)" --- @@ -10,41 +10,41 @@ sidebar: Agent Memory is in **research preview** and is enabled per team for design partners. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your team. ::: -Agent Memory is a persistent memory layer that lives on Oz and is shared across every supported agent harness — the built-in Warp Agent, Claude Code, Codex, and others as they're added. Agents read from and write to it as they run, so durable facts, decisions, and outcomes from one conversation are available to the next — regardless of which harness, machine, or teammate triggers it. +Agent Memory is a persistent memory system that lives on Oz and is shared across every supported agent harness, including the built-in Warp Agent, Claude Code, Codex, and others as they're added. Agents read from and write to this memory system as they run, so durable facts, decisions, and outcomes from one conversation are available to the next — regardless of which harness, machine, or teammate triggers the work. Memory creation and retrieval are asynchronous and run in the background, so they don't consume tokens or add latency to the active task. -[Join the Agent Memory waitlist](https://warp.dev/oz/agent-memory#waitlist) +[Join the Agent Memory waitlist](https://warp.dev/oz/agent-memory#waitlist). ## Key features -* **Cross-harness memory** — One memory layer shared across the Warp Agent, Claude Code, Codex, and other harnesses as they're added. Third-party harnesses are covered when they run as cloud agents. -* **Both local and cloud agents** — Supports interactive local agents in Warp and background cloud agents. -* **Asynchronous by design** — Memory creation runs after a conversation ends. Retrieval runs in the background during a run. Neither consumes tokens or adds latency to the active task. -* **Automatic memory from conversations** — When a conversation ends, Oz extracts durable facts, learnings, and outcomes and writes them as memories. New knowledge merges with existing memories or supersedes them on conflict. -* **Agent-scoped, shareable stores** — By default, each agent has its own memory store. Stores can also be shared across multiple agents, or across an entire team, when the same knowledge should travel with the work. -* **Per-agent access and instructions** — Attach stores to specific agents with read-only or read-write access. Per-store instructions tell each agent how and when to use the store. -* **Fully accessible via API** — Memories and stores can be read, created, updated, and deleted through the [Oz API](/reference/api-and-sdk/). -* **Traceability** — For any agent run, you can see which memories influenced it. -* **Auditability** — Every change to a memory is recorded, so the full history of any memory can be inspected. -* **Self-hostable** — Enterprises can run Agent Memory on a [self-hosted Oz](/agent-platform/cloud-agents/self-hosting/) instance to meet security, privacy, and compliance requirements. +* **Cross-harness memory** - One memory system is shared across the Warp Agent, Claude Code, Codex, and other harnesses as they're added. Third-party harnesses are covered when they run as cloud agents. +* **Both local and cloud agents** - Supports interactive local agents in Warp and background cloud agents. +* **Asynchronous by design** - Memory creation runs after a conversation ends. Retrieval runs in the background during a run. Neither consumes tokens or adds latency to the active task. +* **Automatic memory from conversations** - When a conversation ends, Oz extracts durable facts, learnings, and outcomes and writes them as memories. New knowledge merges with existing memories or supersedes them on conflict. +* **Agent-scoped, shareable stores** - By default, each agent has its own memory store. Stores can also be shared across multiple agents, or across an entire team, when the same knowledge should travel with the work. +* **Per-agent access and instructions** - Attach stores to specific agents with read-only or read-write access. Per-store instructions tell each agent how and when to use the store. +* **Fully accessible via API** - Memories and stores can be read, created, updated, and deleted through the [Oz API](/reference/api-and-sdk/). +* **Traceability** - Memory retrievals are recorded so teams can inspect which memories contributed to a run's context. +* **Auditability** - Every change to a memory is recorded so teams can inspect how a memory has changed over time. +* **Self-hosting support** - Enterprises can run Agent Memory on a [self-hosted Oz](/agent-platform/cloud-agents/self-hosting/) instance to meet security, privacy, and compliance requirements. ## Where Agent Memory runs -Agent Memory is part of Oz. Storage, memory creation, and retrieval all run on the same Oz instance that hosts your agents — either Warp-hosted Oz (the default) or a [self-hosted Oz](/agent-platform/cloud-agents/self-hosting/) instance that your team operates inside its own perimeter. The same memory is accessible from any agent you run on Oz: +Agent Memory is part of Oz. Storage, memory creation, and retrieval all run on the same Oz instance that hosts your agents. That instance can be Warp-hosted Oz (the default) or a [self-hosted Oz](/agent-platform/cloud-agents/self-hosting/) instance that your team operates inside its own perimeter. The same memory is accessible from any agent you run on Oz: * The local Warp Agent. * Cloud agents triggered from the CLI, web app, schedules, or integrations. -* Third-party harnesses running as cloud agents — Claude Code, Codex, and others as they're added. (Running third-party harnesses locally isn't supported during the research preview.) +* Third-party harnesses running as cloud agents: Claude Code, Codex, and others as they're added. (Running third-party harnesses locally isn't supported during the research preview.) Memory stays bound to its owner (a user or a team), independent of which harness reads or writes. ## Memory stores -A memory store is a named collection of memories. By default, each agent has its own store and writes to it as it runs. Stores can also be shared across multiple agents when they need the same knowledge, and across teammates when knowledge should travel with the team. +A memory store is a named collection of memories. By default, each agent has its own store that it writes to as it runs. Stores can also be shared across multiple agents when they need the same knowledge, and across teammates when knowledge should travel with the team. -* **Personal stores** — Owned by a user. Hold preferences, working notes, and individual patterns. -* **Team stores** — Owned by a team. Hold shared knowledge like deployment runbooks, code review conventions, or on-call procedures. Every team member, and any agent the team authorizes, can read from the same store. +* **Personal stores** - Owned by a user. Store memories about preferences, working notes, and individual patterns. +* **Team stores** - Owned by a team. Store shared knowledge like deployment runbooks, code review conventions, or on-call procedures. Every team member, and any agent the team authorizes, can read from the same store. Use multiple stores to keep contexts separate, and share stores across agents when needed. For example, a code review agent can have its own store of review patterns, while a repo-specific store of architectural decisions is shared between the code review agent and a Sentry triage agent so both reason about the same codebase. @@ -52,9 +52,9 @@ Use multiple stores to keep contexts separate, and share stores across agents wh When a conversation finishes, Oz extracts durable facts, learnings, and outcomes from the transcript and writes them as memories. Memory creation runs in the background after the conversation ends, so it doesn't consume tokens or add latency during that run. -* **Memories evolve over time** — Agents update and supersede their own memories as new information arrives, including to resolve contradictions with prior memories. +* **Memories evolve over time** - Agents update and supersede their own memories as new information arrives, including to resolve contradictions with prior memories. -You can also explicitly ask an agent to remember something during a conversation, and it lands in the appropriate store. +You can also explicitly ask an agent to remember something during a conversation. Oz saves that memory to the appropriate store. ## How agents use memory @@ -62,7 +62,7 @@ When an agent starts a task, Oz searches the stores the agent can access for rel ## Attaching memory to your agents -Attach stores to agents with read-only or read-write access. Each attachment can include per-store instructions that tell the agent how and when to use the store — for example, "Reference this store for team naming conventions" or "Write a new memory after each successful deployment." Without instructions, the agent can access the store but won't know when to read from or write to it. +Attach stores to agents with read-only or read-write access. Each attachment can include per-store instructions that tell the agent how and when to use the store. For example, use instructions like "Reference this store for team naming conventions" or "Write a new memory after each successful deployment." Without instructions, the agent can access the store but won't know when to read from or write to it. ## Join the waitlist @@ -70,10 +70,10 @@ Agent Memory is rolling out to design partner teams during research preview. [Jo ## Related pages -* [Codebase Context](/agent-platform/capabilities/codebase-context/) — Let agents understand your codebase through semantic indexing. -* [Rules](/agent-platform/capabilities/rules/) — Define global and project-level guidelines that shape agent behavior. -* [Skills](/agent-platform/capabilities/skills/) — Reusable, scoped instructions that teach agents how to perform specific tasks. -* [Agent profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/) — Control what permissions and autonomy agents have. -* [Cloud agents overview](/agent-platform/cloud-agents/overview/) — Run background agents with team-wide observability. -* [Self-hosting overview](/agent-platform/cloud-agents/self-hosting/) — Run Oz, and Agent Memory along with it, on your own infrastructure. -* [Oz API and SDK](/reference/api-and-sdk/) — Read, create, update, and delete memories and stores programmatically. +* [Codebase Context](/agent-platform/capabilities/codebase-context/) - Let agents understand your codebase through semantic indexing. +* [Rules](/agent-platform/capabilities/rules/) - Define global and project-level guidelines that shape agent behavior. +* [Skills](/agent-platform/capabilities/skills/) - Reusable, scoped instructions that teach agents how to perform specific tasks. +* [Agent profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/) - Control what permissions and autonomy agents have. +* [Cloud agents overview](/agent-platform/cloud-agents/overview/) - Run background agents with team-wide observability. +* [Self-hosting overview](/agent-platform/cloud-agents/self-hosting/) - Run Oz, and Agent Memory along with it, on your own infrastructure. +* [Oz API and SDK](/reference/api-and-sdk/) - Read, create, update, and delete memories and stores programmatically. diff --git a/src/content/docs/agent-platform/capabilities/skills.mdx b/src/content/docs/agent-platform/capabilities/skills.mdx index 4270b928..7b70a851 100644 --- a/src/content/docs/agent-platform/capabilities/skills.mdx +++ b/src/content/docs/agent-platform/capabilities/skills.mdx @@ -413,7 +413,7 @@ These same skills also appear as suggested agents in the [Oz web app](/agent-pla ## Suggested skills from Agent Memory -Promoting recurring patterns from [Agent Memory](/agent-platform/agent-memory/) into reviewable skill drafts is in design as part of the research preview. See the Agent Memory page for current status. +Promoting recurring patterns from [Agent Memory](/agent-platform/agent-memory/) into reviewable skill drafts is in design as part of the research preview. See the Agent Memory page for a current status. ## Invoking skills with a prompt diff --git a/src/content/docs/agent-platform/cli-agents/claude-code.mdx b/src/content/docs/agent-platform/cli-agents/claude-code.mdx index 69076d3f..1707dd17 100644 --- a/src/content/docs/agent-platform/cli-agents/claude-code.mdx +++ b/src/content/docs/agent-platform/cli-agents/claude-code.mdx @@ -73,7 +73,7 @@ Claude Code supports the full set of Warp's agent integration features: * [How to set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) — step-by-step setup guide * [Claude Code in Warp](https://www.warp.dev/agents/claude-code) — product overview -* [Third-Party CLI Agents Overview](/agent-platform/cli-agents/overview/) +* [Third-Party CLI Agents Overview](/agent-platform/cli-agents/overview/) — supported CLI agent integrations * [Claude Code with Oz](/agent-platform/cloud-agents/harnesses/claude-code/) — Claude Code as a cloud harness -* [OpenCode](/agent-platform/cli-agents/opencode/) -* [Codex](/agent-platform/cli-agents/codex/) +* [OpenCode](/agent-platform/cli-agents/opencode/) — OpenCode in Warp +* [Codex](/agent-platform/cli-agents/codex/) — Codex in Warp diff --git a/src/content/docs/agent-platform/cli-agents/codex.mdx b/src/content/docs/agent-platform/cli-agents/codex.mdx index 18f1034e..530918be 100644 --- a/src/content/docs/agent-platform/cli-agents/codex.mdx +++ b/src/content/docs/agent-platform/cli-agents/codex.mdx @@ -48,7 +48,7 @@ Codex supports the full set of Warp's agent integration features: * [How to set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) — step-by-step setup guide * [Codex in Warp](https://www.warp.dev/agents/codex) — product overview -* [Third-Party CLI Agents Overview](/agent-platform/cli-agents/overview/) +* [Third-Party CLI Agents Overview](/agent-platform/cli-agents/overview/) — supported CLI agent integrations * [Codex with Oz](/agent-platform/cloud-agents/harnesses/codex/) — Codex as a cloud harness -* [Claude Code](/agent-platform/cli-agents/claude-code/) -* [OpenCode](/agent-platform/cli-agents/opencode/) +* [Claude Code](/agent-platform/cli-agents/claude-code/) — Claude Code in Warp +* [OpenCode](/agent-platform/cli-agents/opencode/) — OpenCode in Warp diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx index bd36b50b..6b6c98ac 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -1,13 +1,13 @@ --- title: Handoff from cloud to cloud description: >- - Send a follow-up to a finished cloud run. The run continues with the prior - workspace state restored, so the agent picks up where it left off. + Send follow-up instructions to a finished cloud agent run. The run continues + with restored workspace state, so the agent picks up where it left off. sidebar: label: "Cloud to cloud" --- -Hand off a cloud agent run to a fresh cloud session when the original session has ended but you still want to push the same unit of work further. The run continues in the same conversation, with the prior session's workspace state restored, so the agent picks up where it left off instead of starting fresh. +Cloud-to-cloud handoff in Warp lets you send follow-up instructions to a finished cloud agent run and continue it in a fresh cloud session. The run keeps the same conversation and restores the prior workspace state, so the agent can pick up where it left off instead of starting over. Use this handoff direction when: @@ -19,15 +19,15 @@ Use this handoff direction when: When you send a follow-up to a run whose session has ended, the run continues with: * **The same conversation** - The follow-up is appended to the same conversation. From your perspective, the run is one continuous conversation across sessions. -* **The prior workspace state** - The prior session's repository changes (tracked and untracked) are restored before the agent answers your follow-up. For git-managed sessions, the new session continues on the same Git branch. You can [customize which repositories and files get snapshotted](/agent-platform/cloud-agents/handoff/snapshots/) when running outside the bundled cloud agent image. +* **The prior workspace state** - The prior session's repository changes (tracked and untracked) are restored before the agent answers your follow-up. For Git-managed sessions, the new session continues on the same Git branch. You can [customize which repositories and files get snapshotted](/agent-platform/cloud-agents/handoff/snapshots/) when running outside the bundled cloud agent image. * **Stable run identity** - The run's ID, task, creator, environment, schedule trigger, and integration source are preserved. Compute usage is recorded per session but rolls up to the same run. -If applying any change fails, the agent reports what couldn't be applied and proceeds with what it could rather than starting over silently. +If any changes fail to apply, the agent reports which changes failed and continues with the changes that applied cleanly. ## Prerequisites -* **An ended cloud agent run** - The run must be in a terminal state — for example, succeeded, failed, or canceled — and have an associated agent conversation. Blocked runs that are waiting on user input or approval can't be continued via cloud-to-cloud handoff; respond to the prompt on the original run instead. Very old runs that predate the agent conversation model can't be continued via handoff. -* **A snapshot from the prior session** - Cloud agent runs capture a workspace snapshot at the end of each session. If the prior session couldn't capture one (for example, due to a transient storage error), the run still continues, just without restored workspace state. +* **An ended cloud agent run** - The run must be in a terminal state, such as succeeded, failed, or canceled, and have an associated agent conversation. Blocked runs that are waiting on user input or approval can't be continued via cloud-to-cloud handoff; respond to the prompt on the original run instead. Very old runs that predate the agent conversation model can't be continued via handoff. +* **A snapshot from the prior session** - Cloud agent runs capture a workspace snapshot at the end of each session. If the prior session couldn't capture one (for example, due to a transient storage error), the run still continues but without restored workspace state. * **Access to the run** - You need permission to submit follow-ups for the run. For team runs, this is typically any team member. Cloud runs that originated from a local-to-cloud handoff can be continued only by the user who created them, not by other team members. :::caution @@ -36,25 +36,35 @@ Cloud-to-cloud handoff relies on a snapshot from the prior session. Older cloud ## Sending a follow-up -You don't take a separate "hand off" action — you send a follow-up from the Warp app, and the run continues. The handoff happens automatically when the original session has ended. +To continue an ended cloud run, open the run in Warp and send the next message in the conversation. When the original session has ended, Warp automatically starts a fresh cloud session and restores the prior workspace state. -1. **Open the ended cloud run.** Find it on the [Runs page](https://oz.warp.dev/runs) in the Oz web app or in the conversation panel. +1. **Open the ended cloud run.** Find it on the [Runs page](https://oz.warp.dev/runs) in the Oz web app or in the conversation panel in the Warp app. 2. **Send your follow-up.** Enter the next message in the conversation's input and submit it. The run picks up where it left off, with workspace state restored. ### Third-party agent runtimes -Cloud-to-cloud handoff also works for supported third-party agent runtimes, but the affordance is a **Continue** button followed by an input prompt instead of the standard follow-up input. Click **Continue** on the ended run (from the conversation details panel or the artifacts shown after the run) and enter the next message you want the agent to act on. +Cloud-to-cloud handoff also works for supported third-party agent runtimes, but the flow is slightly different from Warp Agent runs: + +1. Open the ended run from the conversation panel in the Warp app, or from the artifacts shown after the run completes. +2. Click **Continue**. +3. Type your follow-up prompt and submit it. ## Inspecting a run that's been handed off -The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions. Click into the run to see the full transcript: each session appears in order, and you can scan the transcript to see where one session ended and the next began. Per-session timestamps aren't currently exposed in the API; the transcript is the source of truth. +The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions. + +1. Open the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app or Oz web app. +2. Select the handed-off run. +3. Review the transcript. Each session appears in order, so you can see where one session ended and the next began. + +Per-session timestamps aren't currently exposed in the API; the transcript is the source of truth. ## Troubleshooting **The run continued but no workspace state was restored.** -The prior session didn't capture a snapshot. This is rare but possible — snapshot capture is best-effort. The run still continues with the same conversation, so the agent has the full transcript context even without the workspace state. +The prior session didn't capture a snapshot. This is rare but possible because snapshot capture is best-effort. The run still continues with the same conversation, so the agent has the full transcript context even without the workspace state. **The run is in a terminal state with no conversation and follow-ups are rejected.** Very old runs predate the agent conversation model and can't be continued via handoff. Start a new cloud agent run with the prompt you want, referencing the prior run if needed. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx index 584a4276..6f39e50c 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx @@ -1,14 +1,18 @@ --- title: Handoff between local and cloud agents description: >- - Move agent work between a local Warp session and the cloud, or continue a - finished cloud run with workspace state restored, without re-explaining the - task. + Understand how agent handoff moves work between local Warp sessions and cloud + agent runs, including what context carries over in each direction. sidebar: label: "Handoff overview" --- -Handoff lets you move a unit of agent work between a local Warp session and the cloud, or continue a finished cloud run, without re-explaining the task. The receiving agent picks up the conversation history, your workspace state, and any conversation attachments from the prior session. +Handoff moves agent work between local Warp sessions and cloud agent runs without making you restart the task. Depending on the direction, Warp carries over conversation history, workspace changes, and attachments so the receiving agent can continue from the prior session instead of starting from scratch. + +
+![A Handoff control in a local Warp Agent conversation.](../../../../../assets/agent-platform/local-to-cloud-handoff-chip.png) +
The Handoff control in a local conversation.
+
## Directions of handoff @@ -22,8 +26,8 @@ Handoff supports three directions: Handoff coverage depends on which agent is running the conversation: -* **Cloud to cloud** works for both the Warp Agent and supported third-party agent runtimes. For supported third-party agent runtimes, the affordance is a **Continue** button followed by an input prompt, instead of the streamlined follow-up flow you get with the Warp Agent. -* **Local to cloud** works for the Warp Agent. It isn't available for supported third-party agent runtimes. +* **Cloud to cloud** works for the Warp Agent and the [third-party cloud harnesses currently supported in Oz](/agent-platform/cloud-agents/harnesses/): Claude Code and Codex. For Claude Code and Codex runs, click **Continue**, then enter your follow-up prompt. Warp Agent runs use the streamlined follow-up input. +* **Local to cloud** works for the Warp Agent. It isn't available for third-party CLI agent sessions. ## What carries over @@ -33,7 +37,7 @@ Handoff preserves enough state that the receiving agent can resume the work, not * **Workspace state** - Local-to-cloud and cloud-to-cloud capture the prior session's repository changes (tracked and untracked) and apply them in the receiving run before the agent answers the next prompt. The cloud-to-local direction doesn't currently apply workspace patches to your local checkout; review the cloud agent's branch or pull request artifact to inspect those changes. * **Conversation attachments** - Files attached during the prior session remain available to the receiving agent. -Handoff is best-effort. When the receiving agent can apply the prior session's changes cleanly, it picks up where the prior agent left off. When it can't, the agent reports what failed and proceeds with what it could rather than starting over silently. +Handoff is best-effort. When the receiving agent can apply the prior session's changes cleanly, it picks up where the prior agent left off. When it can't, the agent reports which changes failed to apply and continues with the changes that applied cleanly. ## When to use handoff diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx index 76c636f7..d1dd79a8 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx @@ -1,14 +1,13 @@ --- title: Handoff from local to cloud description: >- - Promote a local Warp Agent conversation to a cloud agent run with the full - transcript and your uncommitted workspace changes — without re-explaining - the task. + Move an in-progress local Warp Agent conversation into a cloud agent run for + longer-running work, parallel exploration, or remote follow-up. sidebar: label: "Local to cloud" --- -Hand off a local Warp conversation to a cloud agent run when the work outgrows your local session. The cloud agent inherits a fork of your local conversation and a snapshot of your uncommitted workspace changes, so it picks up where you left off instead of starting fresh. +Local-to-cloud handoff in Warp promotes an active local Warp Agent conversation into a cloud agent run. Warp forks the conversation, snapshots your uncommitted workspace changes, and sends both to the cloud so the agent can continue the same task with the context and files it needs. Use this handoff direction when: @@ -22,14 +21,14 @@ Use this handoff direction when: When you hand off from local to cloud, the receiving cloud agent inherits: * **A forked conversation** - Warp forks your local conversation so the cloud agent inherits the full transcript without modifying the source. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) for related sync behavior. -* **A workspace snapshot** - Warp captures your uncommitted repository changes — both tracked modifications and untracked files — and packages them for the cloud agent. The cloud agent applies them before answering your follow-up. +* **A workspace snapshot** - Warp captures your uncommitted repository changes, including both tracked modifications and untracked files, and packages them for the cloud agent. The cloud agent applies them before answering your follow-up. * **Conversation attachments** - Files attached to the local conversation remain available in the cloud run. -If applying any change fails in the cloud run, the cloud agent reports what couldn't be applied and proceeds with what it could rather than silently dropping changes. +If any changes fail to apply in the cloud run, the cloud agent reports which changes failed and continues with the changes that applied cleanly. ## Prerequisites -* **An active local conversation** - Have an [Agent](/agent-platform/local-agents/overview/) conversation open in Warp with the work you want to hand off. +* **An active local conversation** - Have a [Warp Agent](/agent-platform/local-agents/overview/) conversation open in Warp with the work you want to hand off. * **A configured environment** - The cloud agent needs an [environment](/agent-platform/cloud-agents/environments/) that includes the same repositories you're working in locally. The environment's repos must match your local checkout so the workspace snapshot applies cleanly. * **Cloud conversation storage enabled** - In the Warp app, go to **Settings** > **Privacy** and turn on **Store AI conversations in the cloud** so the conversation can be forked. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/). * **Sufficient credits** - Cloud agent runs consume credits. See [Credits](/support-and-community/plans-and-billing/credits/) for how credit usage works, and [Access, billing, and identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for team-specific credit requirements. @@ -40,13 +39,37 @@ If applying any change fails in the cloud run, the cloud agent reports what coul 2. **Choose the environment for the cloud run.** Pick the one whose repositories match the directories your local conversation has been editing. If you don't have a matching environment yet, create one and add the repos you've been working in. 3. **Add a follow-up prompt and submit.** Enter the next message you want the cloud agent to act on. +The `&` entry point and `/handoff` slash command both open the same handoff flow. + +
+![The ampersand entry point for handoff in a local Warp Agent conversation.](../../../../../assets/agent-platform/local-to-cloud-handoff-input-entrypoint.png) +
The ampersand handoff entry point.
+
+ +
+![The slash command menu showing the handoff command in Warp.](../../../../../assets/agent-platform/local-to-cloud-handoff-slash-command.png) +
The `/handoff` slash command.
+
+ +After the flow opens, choose the cloud environment and add the follow-up prompt the cloud agent should act on. + +
+![The handoff flow showing an environment selector for the cloud run.](../../../../../assets/agent-platform/local-to-cloud-handoff-environment-selector.png) +
The environment selector in the handoff flow.
+
+ +
+![The handoff flow with a follow-up prompt entered before submitting.](../../../../../assets/agent-platform/local-to-cloud-handoff-follow-up-prompt.png) +
A follow-up prompt before handoff.
+
+ :::note The cloud agent runs with the same model your local conversation was using. Changing the model during handoff isn't supported. ::: -After you submit, the cloud agent applies your workspace snapshot and addresses your follow-up. The local conversation stays untouched — you can keep working in it locally or close it. +After you submit, the cloud agent applies your workspace snapshot and responds to your follow-up. The local conversation is not modified, so you can keep working in it locally or close it. -To check on the new run, open it from the [Runs page](https://oz.warp.dev/runs) in the Oz web app or the conversation panel. +To check on the new run, open it from the [Runs page](https://oz.warp.dev/runs) in the Oz web app or the conversation panel in the Warp app. ## Troubleshooting @@ -54,10 +77,10 @@ To check on the new run, open it from the [Runs page](https://oz.warp.dev/runs) The most common cause is a repository mismatch between your local checkout and the environment. The workspace snapshot is generated against your local repo's current state; the environment must be on a compatible branch and commit for the changes to apply cleanly. Switch the environment's repo to the branch you were on locally and retry the handoff. **The cloud agent doesn't see my uncommitted changes.** -Cloud conversation storage must be enabled for handoff to work. In the Warp app, open **Settings** > **Privacy** and confirm **Store AI conversations in the cloud** is on. Otherwise, the conversation can't be forked and the run falls back to starting fresh. +Cloud conversation storage must be enabled for handoff to work. In the Warp app, open **Settings** > **Privacy** and confirm **Store AI conversations in the cloud** is on. Otherwise, the conversation can't be forked and the run falls back to starting over. **The conversation doesn't appear in the cloud run.** -The source conversation may not have finished syncing to the cloud when you triggered the handoff. Wait a moment and retry. If the problem persists, check the conversation panel to confirm the conversation has a cloud-synced indicator. +The source conversation may not have finished syncing to the cloud when you triggered the handoff. Wait a moment and retry. If the problem persists, check the conversation panel in the Warp app to confirm the conversation has a cloud-synced indicator. ## Related pages diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx index a16b1fc6..c5f95ed7 100644 --- a/src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx @@ -7,7 +7,7 @@ sidebar: label: "Authentication" --- -Third-party cloud agents — [Claude Code](#connecting-claude-code-credentials) and [Codex](#connecting-codex-credentials) — call their provider directly, so you need to store credentials as Warp-managed secrets before launching a run. This page walks through the one-time setup for each. +Third-party cloud agent authentication in Oz stores provider credentials for cloud runs as Warp-managed secrets. Third-party cloud agents, like [Claude Code](#connecting-claude-code-credentials) and [Codex](#connecting-codex-credentials), call their providers directly, so set up an Anthropic or OpenAI credential once before launching a third-party harness. Auth secrets can be scoped to a **team** (available to all teammates' runs) or **personal** (only your own runs), like any other Warp-managed secret. @@ -21,21 +21,22 @@ Claude Code is Anthropic's agentic coding tool. For more on Claude Code authenti ### Create an Anthropic API key -1. Go to the [Anthropic Console](https://platform.claude.com/login?returnTo=/?) and sign in (or create an account). -2. Navigate to **API keys** and create a new key. -3. Make sure your account has API credits — Claude Code runs are billed against your Anthropic API balance. +1. Go to the [Anthropic Console](https://platform.claude.com/login?returnTo=/?) and sign in or create an account. +2. Navigate to the API keys section, then click **Get API key**. +3. Create a new API key and copy the value. +4. Confirm your account has API credits. Claude Code runs are billed against your Anthropic API balance. Oz also supports Bedrock-routed credentials (**Anthropic Bedrock API key** and **Anthropic Bedrock access key**) if your team consumes Anthropic models through AWS. -### Store the key in Oz +### Store API key in Oz #### Warp desktop app -In Cloud Mode, click the key icon above the input and add your Anthropic credential. +In the Warp app, start a new cloud agent run and choose **Claude Code** from the **Agent harness** dropdown. In the harness auth secret field, add or select your Anthropic credential. #### Oz web app -Start a new run, choose **Claude Code** as the harness, and add a new key in the harness auth secrets dropdown. +Start a [new run](https://oz.warp.dev/runs/new), choose **Claude Code** as the harness, and add a new key in the harness auth secrets dropdown. #### Oz CLI @@ -58,18 +59,20 @@ A ChatGPT subscription (Plus, Pro, Team) does not include API access. You need a ### Create an OpenAI API key 1. Go to the [OpenAI Platform](https://platform.openai.com/) and sign in (or create an account). -2. Navigate to **API keys** and click **Create new secret key**. -3. Make sure your account has API credits — Codex runs are billed against your OpenAI API balance, not a ChatGPT subscription. +2. Click **Create API key**. +3. In the **Create new secret key** dialog, choose the owner, project, and permissions for the key. +4. Click **Create secret key**, then copy the value. +5. Confirm your account has API credits. Codex runs are billed against your OpenAI API balance, not a ChatGPT subscription. -### Store the key in Oz +### Store API key in Oz #### Warp desktop app -In Cloud Mode, click the key icon above the input and add your OpenAI credential. +In the Warp app, start a new cloud agent run and choose **Codex** from the **Agent harness** dropdown. In the harness auth secret field, add or select your OpenAI credential. #### Oz web app -Start a new run, choose **Codex** as the harness, and add a new key in the harness auth secrets dropdown. +Start a [new run](https://oz.warp.dev/runs/new), choose **Codex** as the harness, and add a new key in the harness auth secrets dropdown. #### Oz CLI