From ea82dab43501c86b4cb87da08040960f4dbc2660 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 18 May 2026 16:09:20 -0700 Subject: [PATCH 01/10] docs(agent-platform): add agent identities page and expand secrets + web-UI coverage (#88) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(agent-platform): add named agents page and cross-link from related pages Adds a new dedicated page for named agents (agent identities) under cloud agents, and reconciles a handful of existing pages so that automation guidance and service-account references point to the new page. - New: src/content/docs/agent-platform/cloud-agents/agents.mdx — what a named agent is, plan limits, attaching descriptions/secrets/skills, REST endpoints, API keys bound to a named agent, running as a specific identity, and where named agents surface in the product. - Edit: agent-platform/cloud-agents/secrets.mdx — forward-links from the team-secrets recommendation and adds a brief note that secrets can be attached directly to a named agent. - Edit: agent-platform/cloud-agents/deployment-patterns.mdx — Pattern 1 checklist now references a named agent (recommended for automation) instead of an unscoped "service account". - Edit: agent-platform/cloud-agents/oz-web-app.mdx — reconciles the two meanings of the Agents page (skills browser + named-agent management) with a clear section split and a forward link. - Edit: reference/cli/index.mdx — keeps the literal `oz whoami` output intact and adds a one-line note pointing readers to the new agents page for what a service-account principal represents. - Edit: reference/cli/federate.mdx — keeps the literal `service_account:my-sa-id` example and adds a cross-reference to the new agents page. Hard rules: no edits to sidebar.ts, vercel.json, landing pages, or any pages owned by the five orchestration-launch PRs. Co-Authored-By: Oz * docs(agent-platform): rename to agent identities; expand secrets and web-UI coverage Revises the previous "named agents" page and related cross-links to use "agent identity" consistently, and folds in three product surfaces that land alongside agent identities at launch. - agents.mdx: retitled to "Agent identities" and reframed throughout to use the canonical term. Plan-limit table replaced with a single sentence pointing readers to warp.dev/pricing while preserving the default-identity / over-limit visibility behavior. Adds two new subsections: a service-account-to-agent-identity mapping (covers service_account: in oz whoami and oz federate) and a rationale paragraph for supporting multiple identities (CI, on-call, scheduled jobs). - secrets.mdx: new "Creating secrets in the Oz web app" walkthrough alongside the existing oz secret CLI section. New "Scoping secrets to environments and runs" section covering environment-level scoping and run-level scoping (default-inherit / explicit list / empty-list opt-out), with cross-links to environments and the Oz API reference. Terminology references updated. - oz-web-app.mdx: adds Secrets to the quick-reference table, reframes the Agents-page disambiguation to use "agent identity," and adds a step-by-step walkthrough of the New agent side pane (name, description, prompt, skills, harness, model, harness auth secret, secrets, memory stores). Cross-links to agents.mdx for the conceptual reference. - deployment-patterns.mdx: Pattern 1 checklist now references "an agent identity." - reference/cli/index.mdx and reference/cli/federate.mdx: leave literal CLI output intact; one-line notes tying service_account principals to agent identities, with cross-links to agents.mdx. Co-Authored-By: Oz * docs(secrets): fix two 'an cloud' → 'a cloud' grammar typos Pre-existing grammar slips picked up during the agent-identities PR audit. 'Cloud' starts with a consonant sound, so the article 'a' is correct. Co-Authored-By: Oz * docs(agent-identities): address audit findings - secrets.mdx: rephrase environment-level scoping as a default contribution to the run's allowlist (not a cap); drop the CLI environment-secret attachment claim; make the env-secret section self-contained with a web-UI walkthrough and attachment semantics - oz-web-app.mdx: fix the "Oz harness" noun-phrase slip in the base-harness bullet; drop the availability hedge on the memory-stores bullet while keeping the bullet Co-Authored-By: Oz --------- Co-authored-by: Oz --- .../agent-platform/cloud-agents/agents.mdx | 104 ++++++++++++++++++ .../cloud-agents/deployment-patterns.mdx | 2 +- .../cloud-agents/oz-web-app.mdx | 44 +++++++- .../agent-platform/cloud-agents/secrets.mdx | 70 +++++++++++- src/content/docs/reference/cli/federate.mdx | 2 +- src/content/docs/reference/cli/index.mdx | 2 +- 6 files changed, 213 insertions(+), 11 deletions(-) create mode 100644 src/content/docs/agent-platform/cloud-agents/agents.mdx diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx new file mode 100644 index 00000000..5fd5535c --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -0,0 +1,104 @@ +--- +title: Agent identities +description: >- + Agent identities are team-scoped bot accounts that own and execute cloud + agent runs. Use them to separate workflows, scope credentials, and attribute + automated work. +sidebar: + label: "Agent identities" +--- + +An **agent identity** is a team-scoped identity that can own and execute Oz cloud agent runs. Every Warp team starts with a single default agent identity. Creating additional agent identities lets you separate workflows, scope credentials, and attribute automated runs to a specific bot account instead of a person. + +Agent identities are useful when you want to: + +* **Separate workflows** - Give the deploy bot, the dependency-update bot, and the code-review bot distinct identities so runs are easier to filter and audit. +* **Scope credentials** - Attach a specific set of managed secrets and skills to one identity so its runs receive only the configuration that workflow needs. +* **Attribute automated work** - Bind an API key to an agent identity so CI pipelines and webhooks show up as that bot in run history rather than as a teammate. + +## How agent identities work + +Each team has one default agent identity that runs receive automatically when no specific identity is chosen. You can create additional agent identities on top of that default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities. + +You can attach the following configuration to an agent identity: + +* **Description** - A short, human-readable summary teammates see when picking the identity. +* **Managed secrets** - References (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the identity should have access to. +* **Skills** - Skill specs (for example, `org/repo:path/to/SKILL.md`) the identity comes preloaded with. Shorthand specs like `repo:skill_name` are accepted when they resolve unambiguously against the team's cloud environments. + +Skill specs are stored in their normalized fully-qualified form, and managed secret references are validated against the team's secret scope at attach time. If a secret is missing or a skill repo is not accessible to the team's GitHub App installation, the request is rejected before anything is saved. + +## Service accounts and agent identities + +"Agent identity" is the user-facing name for what Warp's CLI and REST API internally model as a **service account**. The two terms refer to the same underlying record: + +* When `oz whoami` reports a principal of `service_account:`, that principal is an agent identity on your team. +* When [`oz federate issue-token`](/reference/cli/federate/) emits a subject component like `service_account:my-sa-id`, the value identifies the agent identity the run is executing as. + +You don't need to distinguish the two terms in day-to-day use — pick the agent identity in the UI or pass its UID to the API, and the CLI surfaces the corresponding `service_account:` principal. + +## Supporting multiple agent identities + +Most teams start with the default agent identity and add more as their automation matures. Creating additional agent identities is worth it when distinct workflows have meaningfully different scopes — for example, a `ci-runner` identity that only needs read-only repo access, an `on-call` identity that holds production deploy credentials and is restricted to incident playbooks, and a `nightly-jobs` identity used by scheduled cleanups. Scoping each identity to a single workflow gives every run the minimum credentials it needs, keeps audit trails attributable to the right bot, and lets you revoke or rotate one workflow's access without touching the rest. + +## Plan limits + +Every team starts with a default agent identity. Additional identities are subject to plan-based limits — see [warp.dev/pricing](https://warp.dev/pricing) for current limits per plan. + +When a team is over its plan limit (for example, after downgrading), the extra identities remain visible in the list but are marked as unavailable. Unavailable identities cannot be used to start runs, cannot have new API keys generated for them, and cannot be edited. + +## Managing agent identities + +You can create, list, update, and delete agent identities through the public API. The full request and response shapes — including error codes — live on the [API Reference](/api) page; the operations to look for are `createAgent`, `listAgents`, `getAgent`, `updateAgent`, and `deleteAgent` under the **agent** tag. + +The endpoints behave as follows: + +* **Create** - `POST /agent/identities` with a `name` and optional `description`, `secrets`, and `skills`. Returns `201` with the new identity's `uid`, `name`, and `available` flag. +* **List** - `GET /agent/identities` returns every agent identity on the team, including the default. Each entry includes an `available` flag indicating whether it is within the plan limit. +* **Retrieve** - `GET /agent/identities/{uid}` returns a single identity by its UID. +* **Update** - `PUT /agent/identities/{uid}` replaces individual fields. Omitting a field preserves the current value; passing an empty string or empty array clears it. +* **Delete** - `DELETE /agent/identities/{uid}` soft-deletes the identity and atomically deletes every API key bound to it. The default agent identity cannot be deleted. + +### Caller requirements + +A few constraints apply across every endpoint: + +* **Team-scoped** - Agent identities belong to a team. The caller must be a member of exactly one team. If the caller is on zero teams or multiple teams, the request is rejected. +* **Human callers only** - Only human users can create, update, or delete an agent identity. A request authenticated as an agent identity itself is rejected. +* **Availability is enforced on use** - Over-plan-limit identities are returned by the list endpoint but cannot be used to update fields, generate new keys, or start new runs. + +## API keys bound to an agent identity + +A team API key can be bound to a specific agent identity at creation time. Calls authenticated with that key run as the chosen identity. The team is resolved automatically from the identity — you don't need to specify a team when generating the key. + +To create a key bound to an agent identity, pass the identity's UID to the `generateApiKey` mutation. See [API Keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between user-scoped and team-scoped keys. + +Once the key exists, the CLI and SDK authenticate as that agent identity for every call. There is no extra flag to set; the binding is on the key itself. + +## Running as an agent identity + +There are two ways to run a cloud agent as a specific agent identity: + +* **Authenticate with a key bound to the identity** - Every run started with that key executes as the bound agent identity. This is the typical path for CI pipelines and scheduled work. +* **Pass `agent_identity_uid` on `POST /agent/runs`** - For one-off runs, send the agent identity's `uid` in the request body. The field is only valid for team-owned runs. + +When neither path is used, runs execute under the default identity ("Quick run" in the web app). + +## Where agent identities appear in the product + +Agent identities surface across several Oz surfaces: + +* **Agents page** - The Agents page in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) is where teams view, create, edit, and delete agent identities. The same page lists the skills available to your team. +* **Agent picker** - Forms that start a new run or schedule include an **Agent** dropdown. **Quick run** is the default option (runs execute as the calling user); selecting an agent identity runs as that identity instead. +* **Run filters and detail** - The Runs view lets you filter by agent identity, and individual run detail pages show which identity executed the run. +* **Admin Panel** - Billing usage in the [Admin Panel](/knowledge-and-collaboration/admin-panel/) attributes credits consumed by agent identity runs to the team rather than to a person. + +## Related pages + +* [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) - Manage the team-managed secrets you can attach to an agent identity. +* [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) - When to use an agent identity for automation versus a personal identity. +* [Oz API & SDK](/reference/api-and-sdk/) - Programmatic access to the agent identity endpoints. +* [API Keys](/reference/cli/api-keys/) - Create keys bound to a specific agent identity. +* [Federated identity tokens](/reference/cli/federate/) - Issue OIDC tokens from inside a run, including ones executing as an agent identity. +* [Oz web app](/agent-platform/cloud-agents/oz-web-app/) - The web surface where you manage agent identities and inspect their runs. +* [Admin Panel](/knowledge-and-collaboration/admin-panel/) - Team-level billing and access controls. 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 d3ae1bff..7d933f74 100644 --- a/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx +++ b/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx @@ -53,7 +53,7 @@ Use this when you already have a system that schedules work (CI, dev boxes, inte #### Minimal setup checklist * A Warp team -* A service account (recommended for automation) +* An [agent identity](/agent-platform/cloud-agents/agents/) (recommended for automation) * The Oz CLI installed on the runner / box * Any needed credentials (often via secrets + environment variables) 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 c572f6bc..99925717 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 @@ -19,7 +19,7 @@ Watch this short demo to create an environment and run an agent using the Oz web ## Quick reference -
PagePathWhat you can do
Dashboard/dashboardQuick actions, suggested agents, recent agents, and featured reads
Runs/runsView all runs, filter by status/source/creator, start new runs, inspect transcripts
Agents/agentsBrowse skills from your environments, view suggested skills, dispatch skills as agents
Schedules/schedulesCreate scheduled agents, pause/enable schedules, view run history
Environments/environmentsCreate and manage environments with repos, Docker images, and setup commands
Integrations/integrationsConnect Slack and Linear to trigger agents from external tools
+
PagePathWhat you can do
Dashboard/dashboardQuick actions, suggested agents, recent agents, and featured reads
Runs/runsView all runs, filter by status/source/creator, start new runs, inspect transcripts
Agents/agentsBrowse skills from your environments, manage agent identities, dispatch skills as agents
Schedules/schedulesCreate scheduled agents, pause/enable schedules, view run history
Environments/environmentsCreate and manage environments with repos, Docker images, and setup commands
Secrets/secretsCreate and manage Warp-managed secrets for cloud agent runs
Integrations/integrationsConnect Slack and Linear to trigger agents from external tools
![The Oz Web App's management view.](../../../../assets/agent-platform/oz-web-app-runs-view.png) @@ -119,7 +119,12 @@ The skill provides base instructions; your prompt adds context for this particul ## Agents -The **Agents** page (`/agents`) shows all skills available from your environments, plus suggested skills from Warp's public [oz-skills repository](https://github.com/warpdotdev/oz-skills). +The **Agents** page (`/agents`) covers two related but distinct concepts: + +* **Skills** - Reusable instruction sets stored in repositories that an agent can execute. Browse skills available from your environments, plus suggested skills from Warp's public [oz-skills repository](https://github.com/warpdotdev/oz-skills). +* **Agent identities** - Team-scoped bot accounts that own and execute runs. The same page is where teams create and manage agent identities, attach descriptions and secrets to them, and bind API keys to a specific identity. + +For the full reference on agent identities — including plan limits, the REST endpoints, and how to run as a specific identity — see [Agent identities](/agent-platform/cloud-agents/agents/). ### Skill details @@ -142,15 +147,43 @@ Click any skill to view its details, then click **Run** to start an agent with t For more details on how skills work with cloud agents, see [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/). ::: -### Creating new agents +### Creating new skills -Click **New agent** to create a new skill. The guided flow helps you define the skill's instructions, which are then available for future runs. +Click **New skill** to create a new skill. The guided flow helps you define the skill's instructions, which are then available for future runs.
![Creating a new agent skill in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-new-agent.png) -
Creating a new agent skill in the Oz web app.
+
Creating a new skill in the Oz web app.
+### Agent identities + +Agent identities are managed from the same Agents page. From the agent-identities view, you can: + +* **Create an agent identity** - Give it a name, an optional description, a default model and harness, and the secrets and skills runs as that identity should receive. +* **Edit an existing identity** - Update its description, attached secrets, attached skills, or default configuration. +* **Delete an identity** - Soft-deletes the identity and atomically deletes every API key bound to it. The default agent identity cannot be deleted. + +When you start a new run or schedule from the web app, the form's **Agent** dropdown lets you pick which agent identity should execute the run. **Quick run** is the default option and runs as your own user. See [Agent identities](/agent-platform/cloud-agents/agents/) for the full reference. + +#### Creating an agent identity + +Click **New agent** to open the **New agent** side pane. The pane is split into collapsible sections; only the name is required. Walk through the fields in order: + +1. **Name** (required) — A short, scriptable identifier for the identity, such as `featureFlagRemover` or `deploy-bot`. +2. **Description** (optional) — A summary teammates see when picking the identity in run pickers. +3. **Prompt** (optional) — Additional instructions appended to every run started as this identity. +4. **Skills** — Use the multi-select to attach one or more skill specs the identity comes preloaded with. +5. **Base harness** — Choose the execution harness for this identity's runs: Oz (the default) or a supported third-party CLI agent. +6. **Base model** — When the chosen harness uses Warp's model picker, select the primary model the identity uses. You can leave this empty to fall back to the team default. +7. **Harness auth secret** — When the chosen harness needs its own authentication (for example, a third-party CLI agent), pick the Warp-managed secret to authenticate with. Can be overridden per run. +8. **Secrets** — Open the **Secrets** section and select the [Warp-managed secrets](/agent-platform/cloud-agents/secrets/) this identity should receive at run time. +9. **Memory stores** — Attach the memory stores this identity should read from or write to. + +Click **Create agent** to save. The new identity appears on the Agents page and is immediately available in run and schedule pickers. To edit an existing identity later, click it in the list, then click **Edit**. + +For the conceptual model — plan limits, the REST endpoints, and how API keys are bound to an identity — see [Agent identities](/agent-platform/cloud-agents/agents/). + --- ## Schedules @@ -259,6 +292,7 @@ For detailed integration setup instructions, see [Slack](/agent-platform/cloud-a ## Related resources * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — Learn about cloud agents and when to use them +* [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 * [Environments](/agent-platform/cloud-agents/environments/) — Configure runtime context for cloud agents diff --git a/src/content/docs/agent-platform/cloud-agents/secrets.mdx b/src/content/docs/agent-platform/cloud-agents/secrets.mdx index e2caff37..e9180f30 100644 --- a/src/content/docs/agent-platform/cloud-agents/secrets.mdx +++ b/src/content/docs/agent-platform/cloud-agents/secrets.mdx @@ -13,7 +13,7 @@ Warp-managed secrets are designed to work across [cloud agent](/agent-platform/c **Warp-managed secrets are useful when:** -* An cloud agent needs to call an API or CLI that does not support OAuth +* A cloud agent needs to call an API or CLI that does not support OAuth * You are using [MCP servers](/agent-platform/cloud-agents/mcp/) that expect static tokens or keys * An agent needs credentials for tools like cloud CLIs, databases, monitoring systems, or internal services * You want centralized auditing and control over what credentials agents can access @@ -57,7 +57,7 @@ Team secrets are shared across the entire team and are available to all cloud ag * Ideal for shared infrastructure credentials, service accounts, and read-only API keys :::note -Because team secrets are broadly available and may be used by fully automated or scheduled agents, they should generally be created **using bot or service accounts**, rather than credentials tied to an individual person. +Because team secrets are broadly available and may be used by fully automated or scheduled agents, they should generally be created **using bot or service accounts**, rather than credentials tied to an individual person. When you want a credential to be available to one workflow only, attach it to an [agent identity](/agent-platform/cloud-agents/agents/) instead of giving every run access to it. ::: **For example:** @@ -68,6 +68,10 @@ Because team secrets are broadly available and may be used by fully automated or This ensures credentials remain valid as team membership changes, permissions are tightly scoped, and ownership and rotation align with internal security policies. +:::note +Team secrets can also be attached directly to an [agent identity](/agent-platform/cloud-agents/agents/), so only runs executing as that identity receive them. The secret itself still lives in the team's secret scope; the agent identity just references it by name. +::: + #### Personal secrets Personal secrets belong to an **individual user**. @@ -78,6 +82,24 @@ Personal secrets belong to an **individual user**. --- +## Creating secrets in the Oz web app + +The [Oz web app](/agent-platform/cloud-agents/oz-web-app/) provides a guided side pane for creating Warp-managed secrets. Use it when you want a point-and-click flow without leaving the browser; the CLI flow below remains available for scripting and automation. + +To create a secret in the web app: + +1. In the Oz web app (oz.warp.dev), open the **Secrets** page. +2. Click **Add secret** to open the **Add secret** side pane. +3. Enter a **Name** (for example, `OPENAI_API_KEY`). This becomes the environment variable name injected into runs. +4. Enter the **Value**. The value is encrypted in your browser before it is sent to the server; Warp never sees the plaintext. +5. Optionally, enter a **Description** to help teammates identify the secret later. +6. Choose a **Scope** — **Team** to share the secret with everyone on the team, or **Personal** to keep it scoped to your user. +7. Click **Create secret**. + +The new secret appears in the Secrets list immediately. Its value is never readable from the UI after creation; to rotate the value, edit the secret and submit a new one. + +--- + ## Managing agent secrets with the Oz CLI Secrets are managed using the oz secret command family. @@ -181,7 +203,7 @@ MY_MCP_SERVER_TOKEN personal 10:00am ### How secrets are made available to cloud agents -When an cloud agent starts, Warp determines which secrets are in scope and sets them as environment variables in the agent’s execution environment. +When a cloud agent starts, Warp determines which secrets are in scope and sets them as environment variables in the agent’s execution environment. Today, secrets are provided as environment variables using the secret name as the variable name. For example: @@ -225,6 +247,48 @@ Personal secrets are never injected in these cases. --- +## Scoping secrets to environments and runs + +Owner scoping (team versus personal) controls **which secrets exist** for a caller. Two additional layers — environments and individual runs — let you narrow **which of those secrets are actually injected** for a given execution. Together with [agent identities](/agent-platform/cloud-agents/agents/), these layers form a broader access-scoping model where each layer contributes the secrets a run ends up with at execution time. + +### Environment-level scoping + +A [cloud environment](/agent-platform/cloud-agents/environments/) can declare its own list of secrets. When a run uses that environment, the environment's attached secrets are added to the run's allowlist by default. The run can still narrow the allowlist further by passing its own `secrets` list, which then takes precedence. Use this when a workflow's runtime needs a known, fixed set of credentials — for example, an `ops-tools` environment that only needs `DEPLOY_TOKEN` and `PAGERDUTY_API_KEY`. + +#### Attach secrets to an environment + +Use the environment form in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) to attach secrets to an environment: + +1. In the Oz web app (oz.warp.dev), open the **Environments** page. +2. Click an existing environment to edit it, or click **New environment** to create one. +3. In the environment form, open the **Secrets** section. +4. Select the team and personal secrets the environment should contribute to each run. Only secret names already in your scope are selectable; values are never displayed. +5. Click **Save**. + +#### Attachment semantics + +Environment-attached secrets behave as follows at run time: + +* **Secret names, not values** - The environment stores references by name. Underlying values stay in the team or personal secret scope, so rotating a value takes effect on the next run without re-attaching the secret. +* **Owner scope still applies** - A run only receives an attached secret if the trigger's owner scope already allows it. Personal secrets are still skipped for triggers without a user context, as described under [Secret availability by trigger type](#secret-availability-by-trigger-type). +* **Resolved at run start** - Warp resolves the environment's attached secrets when the run starts. If a referenced secret has been deleted or renamed since attachment, the run continues and the missing reference is surfaced in the run detail view. + +### Run-level scoping + +Individual runs can override which secrets the run receives by listing them on the run's config: + +* **Default (no list provided)** - The run inherits every secret the creator or team has access to that is in scope for the trigger, exactly as described under [Secret availability by trigger type](#secret-availability-by-trigger-type). +* **Explicit list of secret names** - Only the listed secrets are injected. Any other secrets the caller can access are skipped for this run. +* **Empty list** - The run opts out of all secret injection. No managed secrets are injected, even for triggers that would otherwise receive them. + +Run-level scoping is exposed through the public REST API on the run config. See the [Oz API & SDK reference](/reference/api-and-sdk/) for the exact field and shape. + +:::note +Secret names that don't exist in the caller's scope are silently skipped at injection time rather than failing the run. The run detail view surfaces any references that were requested but not resolved so you can spot typos or stale names. +::: + +--- + ### Auditing and security considerations Warp is designed to make secret usage auditable and predictable: diff --git a/src/content/docs/reference/cli/federate.mdx b/src/content/docs/reference/cli/federate.mdx index 4f1e0fad..fe638baa 100644 --- a/src/content/docs/reference/cli/federate.mdx +++ b/src/content/docs/reference/cli/federate.mdx @@ -44,7 +44,7 @@ oz federate issue-token \ The subject claim is what your cloud provider's policy will match on, so pick the combination that gives you the IAM granularity you need. Supported components: -* **`principal`** - The acting principal, like `user:my-user-id` or `service_account:my-sa-id`. +* **`principal`** - The acting principal, like `user:my-user-id` or `service_account:my-sa-id`. A `service_account:` principal corresponds to an [agent identity](/agent-platform/cloud-agents/agents/) on your team. * **`scoped_principal`** - The principal scoped to a team, like `principal:my-team-id/user:my-user-id`. * **`email`** - The principal's email, like `email:user@warp.dev`. * **`teams`** - The principal's team, like `teams:my-team-id`. diff --git a/src/content/docs/reference/cli/index.mdx b/src/content/docs/reference/cli/index.mdx index f37ef770..816674cf 100644 --- a/src/content/docs/reference/cli/index.mdx +++ b/src/content/docs/reference/cli/index.mdx @@ -156,7 +156,7 @@ Use `oz whoami` to print information about the currently authenticated principal oz whoami ``` -The output includes your user or service account ID, display name, email, and team (when available). For machine-readable output, set `--output-format json` or `--output-format text`. +The output includes your user or service account ID, display name, email, and team (when available). When the CLI is authenticated as a service account principal, that principal is an [agent identity](/agent-platform/cloud-agents/agents/) on your team. For machine-readable output, set `--output-format json` or `--output-format text`. ```sh # JSON output for scripts From 9375a44108d9306e95f0ed8b9e29715ba5c1ecea Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 18 May 2026 18:33:14 -0700 Subject: [PATCH 02/10] docs(cloud-agents): add multi-harness pages (Warp Agent, Claude Code, Codex) (#87) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(cloud-agents): add multi-harness pages for Oz orchestration launch Add a new harnesses section under agent-platform/cloud-agents documenting the harnesses available inside Oz (Warp Agent, Claude Code, Codex), plus a procedural authentication page for connecting Anthropic and OpenAI credentials. Add 'two contexts' callouts to the existing CLI-agent pages distinguishing the local terminal toolbelt from the cloud orchestration surface, and cross-link to the new harness pages. New pages: - agent-platform/cloud-agents/harnesses/index.mdx (overview) - agent-platform/cloud-agents/harnesses/warp-agent.mdx - agent-platform/cloud-agents/harnesses/claude-code.mdx - agent-platform/cloud-agents/harnesses/codex.mdx - agent-platform/cloud-agents/harnesses/authentication.mdx Edited pages: - agent-platform/cli-agents/overview.mdx (two-contexts callout) - agent-platform/cli-agents/claude-code.mdx (cross-link) - agent-platform/cli-agents/codex.mdx (cross-link) - agent-platform/cli-agents/opencode.mdx (fast-follow note) Sidebar wiring is intentionally deferred to the cross-cutting sidebar PR per the orchestration launch tracker. Co-Authored-By: Oz * docs(harnesses): address PR #87 feedback, reframe "Oz harness" terminology - Retitle harness pages to "Warp Agent with Oz", "Claude Code with Oz", "Codex with Oz"; index becomes "Harnesses in Oz". Update body copy and cross-references in cli-agents/* to match. - Reconcile billing claim: customer-supplied Anthropic and OpenAI API keys mean the provider bills your account directly for inference; Warp credits cover the platform layer only. Apply across overview, Claude Code, Codex, and authentication pages. - Remove ChatGPT-auth ambiguity from Codex model list; "default" now reads as "Codex picks its own recommended model" with no provider- account claim that does not match cloud auth options. - Qualify launch surfaces accurately: Warp terminal harness dropdown lists Warp Agent, Claude Code, Gemini today (no Codex); Oz CLI accepts --harness oz|claude|gemini today (Codex is fast-follow); Oz web app and API/SDK expose all four harnesses. Mark Codex CLI selection as fast-follow in the Codex page and authentication page. - Add conservative framing for Gemini and OpenCode harnesses on the overview. - Strip internal field-name jargon from user-facing examples. Co-Authored-By: Oz * docs(harnesses): drop OpenCode mentions, simplify CLI cross-link, audit implementation detail Address Slack-thread feedback on PR #87: - Drop OpenCode from the harnesses overview roadmap note and remove the OpenCode-in-Oz callout from cli-agents/opencode.mdx. OpenCode is no longer mentioned anywhere in the harness docs. - Replace the six-sentence 'two contexts' callout on cli-agents/overview with a two-sentence note: Claude Code and Codex are also supported as harnesses in Oz. The matching callouts on cli-agents/claude-code and cli-agents/codex shrink to the same shape. - Audit pass for over-explanation: harness 'How it works' sections drop Docker / cli-invocation walk-throughs in favor of user-facing copy; Claude and Codex model lists trim in-product aliases (opus[1m], sonnet[1m], opusplan, gpt-5.3-codex-spark, etc.) and defer to the picker for the full list; 'What stays the same' bullets lead with the user benefit; the authentication intro and BYOK callouts drop 'cloud container' / 'injected at runtime' phrasing. Co-Authored-By: Oz * docs(harnesses): address audit findings - Replace "the default Oz harness" with "Oz's default harness" in Related-pages bullets to avoid the "Oz harness" noun-phrase. - Sweep "on Oz" → "with Oz" across harness page descriptions and body copy. - Drop preview/fast-follow hedges around Codex CLI launch and the Warp app's harness dropdown — treat as launching at GA. - Rewrite "GPT-5.5 family" as "the GPT-5 lineup" and drop gpt-5.5 from the cloud Codex Common picks (gpt-5.5 is ChatGPT-auth only; cloud Codex authenticates with an OpenAI API key). gpt-5.4 is now framed as the recommended cloud Codex default. - Add the \`best\` alias to the Claude Code Common picks list with a note that it resolves to the current top-of-line Claude model. Co-Authored-By: Oz * Tweaking copy * docs(harnesses): copy polish on Lili's tweaks - Fix broken `[H]` link in cloud Claude Code Related pages. - Fix "OpenA credential type" typo in authentication.mdx. - Clean up Anthropic Console URL (drop ?returnTo=/? query string). - Capitalize "OpenAI Platform" to match "Anthropic Console". - Restore --team in CLI examples so the follow-up sentence parses. - Drop word-repeat in harnesses index ("harness from the harness dropdown"). - Switch backtick `Cloud Agent` to bold (UI/tab name per style guide). - Reword dangling preposition in Codex available-models bullet. - Trim trailing whitespace and a double-blank line. Co-Authored-By: Oz * docs(harnesses): second polish pass on multi-harness pages - Fix link-text/URL mismatch in harnesses overview: link reads 'triggers' but pointed to /integrations/; repoint to /triggers/. - Add Oxford comma to 'environment compute, triggers, and observability' in three places (style guide requires the serial comma). - Match the actual UI label: 'the harness dropdown' -> 'the **Agent harness** dropdown' on the Claude Code, Codex, and Warp Agent cloud pages (confirmed via harness_selector.rs). - Unify product descriptors so the auth page matches the harness pages: Claude Code is now 'Anthropic's agentic coding tool' and Codex is 'OpenAI's coding agent'. - 'Key icon above the input box' -> 'key icon above the input' (the spec uses lowercase 'key icon' and the rest of the docs say 'above the input'). - Drop redundant article: 'the same toolbelt the Warp Agent uses locally' -> '...the same toolbelt Warp Agent uses locally'. - Drop redundant qualifier: 'Warp Agent with Oz is the same agent runtime' -> 'Warp Agent is the same agent runtime' (page context already establishes Oz). - Disambiguate 'Claude Code and Codex call Anthropic or OpenAI directly' -> '...each call their provider directly' so it's clear each harness calls its own provider. Co-Authored-By: Oz * docs(harnesses): restore Lili's original Anthropic Console link Revert the Anthropic Console URL to platform.claude.com/login?returnTo=/? per PR review feedback that the original link was correct. Co-Authored-By: Oz * docs(harnesses): final polish pass on multi-harness pages - Match in-page link text to target page titles ('with Oz' instead of 'in Oz' / 'as a Cloud Agent'). - Point the harnesses index intro at the harness-specific pages instead of authentication anchors so readers land on the page that introduces each harness. - Surface every harness page from the index Related pages list. - Rename warp-agent's 'Starting a run' header to 'Starting a Warp Agent run' for parity with the Claude Code and Codex pages. - Split the team-admin disable sentence for clearer phrasing. Co-Authored-By: Oz --------- Co-authored-by: Oz Co-authored-by: liliwilson --- .../agent-platform/cli-agents/claude-code.mdx | 5 + .../docs/agent-platform/cli-agents/codex.mdx | 5 + .../agent-platform/cli-agents/overview.mdx | 4 + .../cloud-agents/harnesses/authentication.mdx | 122 ++++++++++++++++++ .../cloud-agents/harnesses/claude-code.mdx | 55 ++++++++ .../cloud-agents/harnesses/codex.mdx | 54 ++++++++ .../cloud-agents/harnesses/index.mdx | 49 +++++++ .../cloud-agents/harnesses/warp-agent.mdx | 69 ++++++++++ 8 files changed, 363 insertions(+) create mode 100644 src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx create mode 100644 src/content/docs/agent-platform/cloud-agents/harnesses/claude-code.mdx create mode 100644 src/content/docs/agent-platform/cloud-agents/harnesses/codex.mdx create mode 100644 src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx create mode 100644 src/content/docs/agent-platform/cloud-agents/harnesses/warp-agent.mdx 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 b765baaf..f86c4617 100644 --- a/src/content/docs/agent-platform/cli-agents/claude-code.mdx +++ b/src/content/docs/agent-platform/cli-agents/claude-code.mdx @@ -13,6 +13,10 @@ Warp auto-detects Claude Code when you run it, giving you access to rich input c For installation, authentication, project configuration, and productivity tips, see the [How to set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) guide. +:::note +Claude Code is also available as a harness in Oz for cloud orchestration. See [Claude Code with Oz](/agent-platform/cloud-agents/harnesses/claude-code/). +::: + ## Setting up notifications Warp supports agent notifications for Claude Code through a plugin. Once installed, Warp surfaces in-app and desktop alerts when Claude Code needs your input — such as command approval, code review, or error intervention. @@ -70,5 +74,6 @@ 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://warp.dev/agents/claude-code) — product overview * [Third-Party CLI Agents Overview](/agent-platform/cli-agents/overview/) +* [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/) diff --git a/src/content/docs/agent-platform/cli-agents/codex.mdx b/src/content/docs/agent-platform/cli-agents/codex.mdx index e4f0b1a3..bacc38ad 100644 --- a/src/content/docs/agent-platform/cli-agents/codex.mdx +++ b/src/content/docs/agent-platform/cli-agents/codex.mdx @@ -13,6 +13,10 @@ Warp auto-detects Codex when you run it, giving you access to rich input control For installation, authentication, project configuration, and productivity tips, see the [How to set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) guide. +:::note +Codex is also available as a harness in Oz for cloud orchestration. See [Codex with Oz](/agent-platform/cloud-agents/harnesses/codex/). +::: + ## Setting up notifications Codex supports native notifications that Warp surfaces as in-app and desktop alerts — such as when Codex completes a task, encounters an error, or needs your input. @@ -45,5 +49,6 @@ 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://warp.dev/agents/codex) — product overview * [Third-Party CLI Agents Overview](/agent-platform/cli-agents/overview/) +* [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/) diff --git a/src/content/docs/agent-platform/cli-agents/overview.mdx b/src/content/docs/agent-platform/cli-agents/overview.mdx index 9fbad2f1..c3fe7213 100644 --- a/src/content/docs/agent-platform/cli-agents/overview.mdx +++ b/src/content/docs/agent-platform/cli-agents/overview.mdx @@ -11,6 +11,10 @@ Warp auto-detects supported CLI agents and enhances them with IDE-level features This feature set is also known as **universal agent support**. +:::note +Claude Code and Codex are also supported as harnesses in Oz for cloud orchestration. See [Harnesses in Oz](/agent-platform/cloud-agents/harnesses/). +::: + ## Supported agents Warp currently supports the following CLI coding agents: diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx new file mode 100644 index 00000000..1da3d211 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx @@ -0,0 +1,122 @@ +--- +title: Third-party cloud agent authentication +description: >- + Connect your Anthropic or OpenAI credentials to Oz, then launch Claude Code + or Codex as cloud agents from the desktop app, Oz web app, or API. +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. + +Auth secrets can be scoped to a **team** (available to all teammates' runs) or **personal** (only your own runs), just like any other Warp-managed secret. + +:::note +[Bring Your Own Key (BYOK)](/support-and-community/plans-and-billing/bring-your-own-api-key/) configured in the Warp desktop app applies to local agent runs only. Cloud runs of Claude Code and Codex always use Warp-managed secrets. +::: + +## Connecting Claude Code credentials + +Claude Code is Anthropic's agentic coding tool. For more on Claude Code authentication, see [Anthropic's Claude Code auth docs](https://code.claude.com/docs/en/authentication). + +### 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. + +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 + +#### Warp desktop app + +In Cloud Mode, click the key icon above the input and add 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. + +#### Oz CLI + +```bash +oz secret create claude api-key --team +``` + +Add `--description "..."` to record rotation notes or owner info. Replace `--team` with `--personal` to make the secret available only to your own runs. + +**Expected outcome.** `oz secret list` shows the new secret with the matching Anthropic credential type. The value is never displayed. + +## Connecting Codex credentials + +Codex is OpenAI's coding agent. For more on Codex authentication, see [OpenAI's Codex auth docs](https://developers.openai.com/codex/auth). + +:::caution +A ChatGPT subscription (Plus, Pro, Team) does not include API access. You need a separate OpenAI API key with API credits. +::: + +### 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. + +### Store the key in Oz + +#### Warp desktop app + +In Cloud Mode, click the key icon above the input and add 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. + +#### Oz CLI + +```bash +oz secret create codex api-key --team +``` + +Add `--description "..."` to record rotation notes or owner info. Replace `--team` with `--personal` to make the secret available only to your own runs. + +**Expected outcome.** `oz secret list` shows the new secret with the matching OpenAI credential type. The value is never displayed. + +## Managing harness auth secrets + +Auth secrets follow the same management commands as any other Warp-managed secret. See [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) for the full reference. Common tasks: + +```bash +# List secrets you can see +oz secret list + +# Rotate a secret value (prompts for the new value) +oz secret update --team --value ANTHROPIC_API_KEY + +# Update the description +oz secret update --team --description "Rotated 2026-05-12; owned by platform team" ANTHROPIC_API_KEY + +# Delete a secret (irreversible) +oz secret delete --team ANTHROPIC_API_KEY +``` + +:::caution +Deleting an auth secret breaks any scheduled or integration-triggered run that references it by name. Update the schedules and integrations to point at a new secret first. +::: + +## Troubleshooting + +**Claude Code or Codex run fails with an authentication error.**\ +Confirm the run was started with a harness auth secret selected. From the Oz web app's run detail pane, the **Harness auth secret** field shows which secret (if any) was used. Re-launch the run with the correct secret selected, or create one if your team doesn't have one yet. + +**The harness auth secret dropdown is empty.**\ +The dropdown only lists secrets whose type matches the selected harness — Anthropic types for Claude Code, OpenAI for Codex. If you stored the credential as a raw value, recreate it using the typed flow above. + +**The selected harness is disabled.**\ +Your team admin has disabled the harness for your workspace. Contact your admin or pick a different harness for the run. + +## Related pages + +* [Harnesses in Oz](/agent-platform/cloud-agents/harnesses/) — overview of third-party harnesses in Oz. +* [Claude Code in Warp](/agent-platform/cli-agents/claude-code/) — run Claude Code locally in the Warp terminal. +* [Codex CLI in Warp](/agent-platform/cli-agents/codex/) — run Codex locally in the Warp terminal. +* [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) — the full Warp-managed secrets reference. diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/claude-code.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/claude-code.mdx new file mode 100644 index 00000000..ec8c85e4 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/claude-code.mdx @@ -0,0 +1,55 @@ +--- +title: Claude Code with Oz +description: >- + Run Claude Code with Oz. Strong at code review, deep bug investigation, large + feature planning, and frontend or UI work. +sidebar: + label: "Claude Code" +--- + +Claude Code is Anthropic's agentic coding tool. Running it with Oz puts Claude Code inside a Warp-managed environment and connects it to the rest of the Oz platform — triggers, environments, secrets, observability, and governance — while still behaving like the Claude Code your team already uses. + +:::note +This page covers Claude Code as a **cloud** harness, dispatched and orchestrated by Oz. To run Claude Code locally in your Warp terminal, see [Claude Code in Warp](/agent-platform/cli-agents/claude-code/) instead. +::: + +## Key features + +* **Cloud orchestration** - Launch Claude Code from any Oz trigger: the Warp app, the Oz web app, the Oz CLI, the REST API, schedules, 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 code-review-heavy or judgment-heavy steps within a larger orchestration. + +## Available models + +The Claude Code harness exposes Anthropic's coding-tuned model lineup. Common picks: + +* `best` - Resolves to the current top-of-line Claude model. +* `opus`, `sonnet`, `haiku` - Aliases that resolve to the current default for that family. + +For the full list — including 1M-context variants for very large codebases and planning-tuned models — open the model picker in the Warp app's Cloud Mode or the **Model** field on the Oz web app's new-run pane. + +## Credentials and billing + +Claude Code calls Anthropic directly using credentials your team provides. Oz supports three Anthropic credential types, stored as [Warp-managed secrets](/agent-platform/cloud-agents/secrets/): + +* **Anthropic API key** - For direct Anthropic API access. +* **Anthropic Bedrock API key** - For Bedrock-routed inference using an API key. +* **Anthropic Bedrock access key** - For Bedrock-routed inference using AWS access credentials. + +Anthropic bills your account directly for inference. Warp credits cover the rest of the platform — environment compute, triggers, and observability. + +For setup steps, see [Connecting Claude Code credentials](/agent-platform/cloud-agents/harnesses/authentication/#connecting-claude-code-credentials). + +## Starting a Claude Code run + +* **Warp app** - In Cloud Mode, click the **Agent harness** dropdown above the input and choose **Claude Code**. +* **Oz web app** - On the new run or new schedule pane, choose **Claude Code** in the **Harness** field. A **Claude Code auth secret** field appears below it; pick one of your stored Anthropic secrets. +* **API and SDK** - Set the agent config `harness` to `claude` and the Anthropic secret name on the matching auth-secret field. See the [API reference](/reference/api-and-sdk/). + +## Related pages + +* [Harnesses in Oz](/agent-platform/cloud-agents/harnesses/) — pick between Warp Agent, Claude Code, and Codex. +* [Authentication](/agent-platform/cloud-agents/harnesses/authentication/) — store Anthropic credentials as Warp-managed secrets. +* [Warp Agent with Oz](/agent-platform/cloud-agents/harnesses/warp-agent/) — Oz's default harness, the only one that can orchestrate Claude Code subagents. +* [Codex with Oz](/agent-platform/cloud-agents/harnesses/codex/) — Codex as a cloud harness. +* [Claude Code in Warp](/agent-platform/cli-agents/claude-code/) — Claude Code in your local Warp terminal. diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/codex.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/codex.mdx new file mode 100644 index 00000000..968ef6f8 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/codex.mdx @@ -0,0 +1,54 @@ +--- +title: Codex with Oz +description: >- + Run Codex with Oz. Strong at codebase migrations, release coordination, batch + test generation, and backend or DevOps automation. +sidebar: + label: "Codex" +--- + +Codex is OpenAI's coding agent. Running it with Oz puts Codex inside a Warp-managed environment and connects it to the rest of the Oz platform — triggers, environments, secrets, observability, and governance — while still behaving like the Codex CLI your team already uses. + +:::note +This page covers Codex as a **cloud** harness, dispatched and orchestrated by Oz. To run Codex locally in your Warp terminal, see [Codex CLI in Warp](/agent-platform/cli-agents/codex/) instead. +::: + +## Key features + +* **Cloud orchestration** - Launch Codex from any Oz trigger: the Warp app, the Oz web app, the Oz CLI, the REST API, schedules, Slack mentions, Linear issues, or GitHub Actions. +* **Codex model picker** - Choose the OpenAI model Codex uses, including the GPT-5 lineup, Codex-tuned variants, and a `default` option that lets Codex pick its own recommended model. +* **First-class subagent** - A Warp Agent parent can dispatch Codex subagents to handle high-volume or well-defined coding steps inside a larger orchestration. + +## Available models + +The Codex harness exposes OpenAI's Codex-tuned and general coding models. Common picks: + +* `default` - Lets Codex pick its own recommended model based on your OpenAI account access. +* `gpt-5.5`, `gpt-5.4` - Recent strong coding models from OpenAI with a configurable reasoning level. +* `gpt-5.4-mini` - A faster, lower-cost option for lighter coding tasks or subagents. + +For the full list — including older Codex-tuned and general models — open the model picker on the Oz web app's new-run pane. For details on each model, see [OpenAI's Codex model docs](https://developers.openai.com/codex/models). + +## Credentials and billing + +Codex calls OpenAI directly using credentials your team provides. Oz supports one credential type today, stored as a [Warp-managed secret](/agent-platform/cloud-agents/secrets/): + +* **OpenAI API key** - The Codex harness authenticates to OpenAI using this key for every run. + +OpenAI bills your account directly for inference. Warp credits cover the rest of the platform — environment compute, triggers, and observability. + +For setup steps, see [Connecting Codex credentials](/agent-platform/cloud-agents/harnesses/authentication/#connecting-codex-credentials). + +## Starting a Codex run + +* **Warp app** - In Cloud Mode, click the **Agent harness** dropdown above the input and choose **Codex**. +* **Oz web app** - On the new run or new schedule pane, choose **Codex** in the **Harness** field. A **Codex auth secret** field appears below it; pick the OpenAI secret your team has stored. +* **API and SDK** - Set the agent config `harness` to `codex` and the OpenAI secret name on the matching auth-secret field. See the [API reference](/reference/api-and-sdk/). + +## Related pages + +* [Harnesses in Oz](/agent-platform/cloud-agents/harnesses/) — pick between Warp Agent, Claude Code, and Codex. +* [Authentication](/agent-platform/cloud-agents/harnesses/authentication/) — store OpenAI credentials as Warp-managed secrets. +* [Warp Agent with Oz](/agent-platform/cloud-agents/harnesses/warp-agent/) — Oz's default harness, the only one that can orchestrate Codex subagents. +* [Claude Code with Oz](/agent-platform/cloud-agents/harnesses/claude-code/) — Claude Code as a cloud harness. +* [Codex CLI in Warp](/agent-platform/cli-agents/codex/) — Codex in your local Warp terminal. diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx new file mode 100644 index 00000000..cb5ed552 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx @@ -0,0 +1,49 @@ +--- +title: Harnesses in Oz +description: >- + Run Claude Code or Codex as Oz cloud agents. Both inherit the same triggers, + environments, secrets, and observability as Warp Agent. +sidebar: + label: "Overview" +--- + +Oz can run third-party agents — [Claude Code](/agent-platform/cloud-agents/harnesses/claude-code/) and [Codex](/agent-platform/cloud-agents/harnesses/codex/) — as cloud agents alongside Warp Agent. You choose the harness (agent runtime) that fits the task; the platform around the run stays the same. + +## What stays the same + +Third-party harnesses inherit the same Oz platform features as Warp Agent: + +* **Triggers** — Slack, Linear, schedules, CI, and API [triggers](/agent-platform/cloud-agents/triggers/) launch any harness. +* **Environments and secrets** — Reuse the same [environments](/agent-platform/cloud-agents/environments/) and [agent secrets](/agent-platform/cloud-agents/secrets/). +* **Skills and Rules** — Saved [Skills](/agent-platform/capabilities/skills/) and [Rules](/agent-platform/capabilities/rules/) apply across harnesses. +* **Observability** — Every run produces a transcript and shareable session in the [Oz dashboard](/agent-platform/cloud-agents/managing-cloud-agents/). + +## Billing + +Claude Code and Codex each call their provider directly using credentials you supply, and the provider bills your account for inference. Warp credits cover the orchestration platform — environment compute, triggers, and observability — but not third-party inference. + +## How to switch harnesses + +### Warp desktop app + +In Cloud Mode, choose a harness from the **Agent harness** dropdown above the input. + +:::note +You can enter Cloud Mode by creating a new **Cloud Agent** tab or by using the `/cloud-agent` slash command. +::: + +### Oz web app + +On the new run or new schedule pane, choose the harness in the **Harness** field. + +### API and SDK + +Set the `harness` field on the agent config. See the [API reference](/reference/api-and-sdk/) for the exact field names. + +## Related pages + +* [Warp Agent with Oz](/agent-platform/cloud-agents/harnesses/warp-agent/) — Oz's default first-party harness. +* [Claude Code with Oz](/agent-platform/cloud-agents/harnesses/claude-code/) — Claude Code as a cloud harness. +* [Codex with Oz](/agent-platform/cloud-agents/harnesses/codex/) — Codex as a cloud harness. +* [Authentication](/agent-platform/cloud-agents/harnesses/authentication/) — connect credentials and launch Claude Code or Codex. +* [Third-party CLI agents in the Warp terminal](/agent-platform/cli-agents/overview/) — run Claude Code, Codex, and other CLI agents locally. diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/warp-agent.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/warp-agent.mdx new file mode 100644 index 00000000..1dcc1376 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/warp-agent.mdx @@ -0,0 +1,69 @@ +--- +title: Warp Agent with Oz +description: >- + Warp Agent is Oz's default harness. It routes across leading models, has full + terminal access, and is the only harness that can orchestrate subagents. +sidebar: + label: "Warp Agent" +--- + +Warp Agent is the harness Warp builds and ships with Oz. It's the default for every cloud agent run unless you pick another harness, and it's the only harness that can spawn cross-harness subagents (for example, a Warp Agent parent dispatching a Claude Code or Codex child). + +Warp Agent is the same agent runtime that powers Agent Mode in the Warp terminal. Running it as a cloud harness gives you the same behavior — model routing, tool access, Skills, Rules, Memory — without tying execution to a single laptop. + +## Key features + +* **Multi-model auto-routing** - Routes between Anthropic, OpenAI, Google, and Fireworks-hosted models. Choose a specific model, or let Warp pick via `auto`, `auto-efficient`, `auto-genius`, or `auto-open`. See [Model choice](/agent-platform/capabilities/model-choice/) for the full catalog. +* **Full terminal and tool access** - Runs commands, edits files, reads logs, executes tests, navigates repos, and calls MCP servers — the same toolbelt Warp Agent uses locally. +* **Platform-native context** - Reads [Codebase Context](/agent-platform/capabilities/codebase-context/), applies [Rules](/agent-platform/capabilities/rules/), reuses saved [Skills](/agent-platform/capabilities/skills/), and respects Memory and Warp Drive context with no extra setup. +* **Multi-repo execution** - Clones every repo configured on the [environment](/agent-platform/cloud-agents/environments/) and works across them in a single run. +* **Cross-harness orchestration parent** - A Warp Agent parent run can spawn Claude Code or Codex [subagents](/agent-platform/cloud-agents/overview/) and coordinate their outputs. Other harnesses cannot act as parents in a multi-harness orchestration. +* **No extra credentials** - Warp Agent uses your existing Warp account and credits. There's no separate API key to configure. + +## How it works + +Warp Agent is the same agent runtime as Agent Mode in the Warp terminal: it plans, calls tools, edits code, runs tests, and reports progress. The cloud platform adds the [environment](/agent-platform/cloud-agents/environments/), triggers, observability, and team governance around the run, and the transcript is inspectable in real time and replayable afterward from the [Oz dashboard](/agent-platform/cloud-agents/managing-cloud-agents/). + +Team admins can disable any harness for their workspace. Users on that team can only start runs with the harnesses that remain enabled. + +### Available models + +Warp Agent supports the full Warp model catalog. Configure the model per [Agent Profile](/agent-platform/capabilities/agent-profiles-permissions/), or pick one at run time. See [Model choice](/agent-platform/capabilities/model-choice/) for the supported model IDs, including the `auto`, `auto-efficient`, `auto-genius`, and `auto-open` routing options. + +### Cross-harness orchestration + +Warp Agent is the orchestration host for multi-harness runs. A typical pattern: + +1. A Warp Agent parent run analyzes a task and breaks it into subtasks. +2. The parent dispatches Claude Code subagents for code-review-heavy steps and Codex subagents for high-volume edits. +3. The parent collects results, resolves conflicts, and returns a single final output (a PR, a report, a Slack reply). + +Subagents run in the same environment as the parent and share the same secrets, MCP servers, and integrations. The transcript shows the full tree, so reviewers can see exactly which subagent did what. + +## When to choose Warp Agent + +* The task spans multiple repos, languages, or domains. +* You want model auto-routing instead of pinning one provider. +* The run needs to orchestrate other harnesses as subagents. +* You want the deepest integration with Warp's platform features (Skills, Rules, Memory, Codebase Context). +* You're not sure which harness fits — Warp Agent is the safe default and can delegate to other harnesses when it decides that's the better fit. + +## Starting a Warp Agent run + +Warp Agent is the default, so there's nothing extra to configure. + +* **Warp app** - Start a cloud agent run from the input. The **Agent harness** dropdown defaults to **Warp Agent**. +* **Oz web app** - On a new run or new schedule pane, leave the **Harness** field set to **Warp Agent**. +* **Oz CLI** - Run `oz agent run-cloud --prompt "..."` with no `--harness` flag, or pass `--harness oz` explicitly. +* **API and SDK** - Omit the `harness` field on the agent config, or set it to `oz`. See the [API reference](/reference/api-and-sdk/). + +For a complete walkthrough, see the [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/). + +## Related pages + +* [Harnesses in Oz](/agent-platform/cloud-agents/harnesses/) — pick between Warp Agent, Claude Code, and Codex. +* [Claude Code with Oz](/agent-platform/cloud-agents/harnesses/claude-code/) — Claude Code as a cloud harness. +* [Codex with Oz](/agent-platform/cloud-agents/harnesses/codex/) — Codex as a cloud harness. +* [Model choice](/agent-platform/capabilities/model-choice/) — the model catalog Warp Agent routes across. +* [Agent Profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/) — configure the default model, autonomy, and tool access for Warp Agent. +* [Skills as agents](/agent-platform/cloud-agents/skills-as-agents/) — turn a saved skill into a reusable Warp Agent run. From 2143f361b3084bb22444da59c58c1fdbf67bcbf2 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 18 May 2026 21:26:56 -0700 Subject: [PATCH 03/10] docs: add Platform Credits page and three-bucket model (#83) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: add Platform Credits page and three-bucket model Adds a new conceptual page introducing Platform Credits as the third credit bucket in Warp, alongside AI credits and Cloud Agent Credits. Explains when Platform Credits apply (cloud agents on any plan, and local agents on Business/Enterprise with BYOK or BYOLLM inference), when they don't, and where they appear in usage views. Also updates the existing Credits and Plans pages to introduce the three-bucket model and cross-link to the new page. Pricing specifics are deferred to warp.dev/pricing. Co-Authored-By: Oz * docs(platform-credits): align charge matrix and tighten copy - Fix contradiction flagged in PR #83 review: cloud agents always charge Platform Credits regardless of inference source. Reframe intro, three- bucket section, and the multi-bucket example to match the matrix in 'When Platform Credits apply'. - Point Generate link at /agent-platform/local-agents/generate/. - Remove time-unit details from the rate section; defer to warp.dev/pricing. - Drop internal tooltip-label callouts from the admin section. - Tighten plans-pricing-refunds Platform Credits one-liner to match. Co-Authored-By: Oz * docs: reframe Platform Credits around inference / compute / platform infrastructure Per review feedback, lead with the three-infrastructure framing (inference, compute, platform) rather than the orchestration-layer framing. Each credit bucket now names the kind of infrastructure it covers. Also drop the enterprise custom-rate sentence; warp.dev/pricing remains the source of truth for rates. Co-Authored-By: Oz * docs(platform-credits): address audit findings - Reframe Platform Credits intro to lead with the rule (every cloud agent run, plus Business/Enterprise local agent runs with customer-supplied inference) instead of the negative 'when Warp isn't paying' framing. - Align cross-file framing in credits.mdx and plans-pricing-refunds.mdx so all three pages describe Platform Credits in the same terms. - Replace 'Workflow autofill' with linked 'AI Autofill'. - Replace 'Local Oz runs' with 'local agent runs' (Oz run is cloud-only). - Deduplicate the second BYOK parenthetical and normalize BYOLLM wording. - Clarify that self-hosted cloud workers count as cloud agents for Platform Credits purposes. Co-Authored-By: Oz * Update src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> * Update src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> * docs(platform-credits): apply Rachael's wording suggestions Address remaining suggested edits from Rachael's review on PR #83: - plans-pricing-refunds.mdx: rewrite Platform Credits bullet to action-oriented form, matching sibling bullets. - platform-credits.mdx: de-dupe "charge for" repetition in intro; convert three-bucket bullets to active-voice complete sentences; rewrite "When Platform Credits apply" with "Uses Platform Credits" / "Doesn't use Platform Credits" headers and complete-sentence bullets; replace internal "harness" jargon with "which agent runs the task"; rename "Third-party harnesses run directly" to "Third-party agent CLIs run directly". - credits.mdx: same active-voice and "agent CLI" updates in the three-bucket summary and Platform Credits subsection. Validation: style_lint --changed clean (9 files, 0 issues), check_links --internal-only clean (2435 links, 0 broken). Co-Authored-By: Oz * docs(platform-credits): reframe Cloud Agent Credits as compute bucket + add BYOK TOS rule Two pieces of feedback addressed on PR #83. 1. Cloud Agent Credits reframing. The bucket is described as compute infrastructure consumed by any agent run, local or cloud. Local agents rarely draw from it in practice because they don't run on Warp's compute, but the credit type is no longer tied to 'cloud-only by construction.' Updated: - platform-credits.mdx three-bucket bullet for Cloud Agent Credits (was 'cover compute infrastructure when cloud agents run on Warp-hosted compute,' now 'are the compute bucket... cover Warp-hosted compute consumed by any agent run, local or cloud'). - credits.mdx three-bucket bullet for Cloud Agent Credits with the same framing. - credits.mdx ### Cloud Agent Credits section intro reframed as 'the compute credits bucket - consumed when an agent run uses Warp-hosted compute. Both local and cloud agent runs can in principle draw from this pool...' - credits.mdx 'Not eligible' list intro tightened to make the reason explicit ('because they don't run on Warp-hosted compute') instead of implying the credit type is fundamentally cloud-only. 2. BYOK / customer-supplied inference TOS rule. Surfaces Warp's TOS rule wherever BYOK or customer-supplied inference is invoked as a workaround for Warp-paid inference. Added: - :::caution callout in platform-credits.mdx after the customer-supplied-inference paragraph, stating the individuals-and-organizations <=10 users rule and the Business or Enterprise requirement for orgs >10 users. Links to the canonical https://www.warp.dev/terms-of-service. - One-line forward reference at the end of the 'Local agents on Business or Enterprise with customer-supplied inference' bullet in platform-credits.mdx, pointing readers back to the callout for plan-size eligibility. - :::caution callout in bring-your-own-api-key.mdx directly after the existing :::note about BYOK paid-plan availability. - One-sentence summary of the TOS rule in the 'BYOK on Enterprise and Business plans' section, so admins reading that section see the eligibility constraint. Out of scope: renaming the 'Cloud Agent Credits' product term, changing pricing-faqs.mdx, or reworking BYOLLM enterprise gating (BYOLLM is already Enterprise-only, so the TOS rule is implicit). Validation: - style_lint --changed: 0 issues across 9 files scanned. - check_links --internal-only: 0 broken links across 319 files and 2,435 internal links. Co-Authored-By: Oz * docs(platform-credits): holistic polish pass after the compute/TOS reframe Tightens stale framing and copy that fell out of alignment after the last commit reframed Cloud Agent Credits as the compute bucket. credits.mdx: - Drop the orphaned 'small hosting fee, charged only when running agents in the cloud' sentence in the opener (L13). It predates the three-bucket model and now contradicts the new framing immediately below it; the bullet at the new L16 covers the same ground correctly. - Reframe the 'Cloud Agent Credits' bullet in Credit limits and billing (was L47, now L45). The old wording ('their normal Warp credits, Cloud Agent Credits, or a Build plan with available credits') treated Cloud Agent Credits as a separate currency. Rewritten as 'Cloud agents and integrations: Individual users can run cloud agents via the CLI and API, drawing from their plan credits. Slack and Linear integrations require team membership.' - Tighten 'in principle draw from this pool' to 'are eligible to draw from this pool' in the Cloud Agent Credits section intro (L122). platform-credits.mdx: - Frontmatter description shortened from 219 to 144 chars (back in the 50-160 SEO range). - Drop the redundant second sentence on L13 ('Platform Credits don't apply to local runs on Free, Build, or Max plans...'). The Doesn't use section below already covers it. The first sentence (defining customer-supplied inference) stays since the TOS callout depends on it. - Align the Admin usage breakdown bullet (L55): 'distinct from the AI and Compute segments' -> 'distinct from the AI credits and Cloud Agent Credits segments'. Uses the bucket names consistently with the rest of the page. Validation: - style_lint --changed: 2 pre-existing warnings on bring-your-own-api-key.mdx (Zero Data Retention is a proper term; Enterprise/Business are proper plan names). Acceptable. - check_links --internal-only: 0 broken links across 319 files and 2,433 internal links. Co-Authored-By: Oz * docs(platform-credits): rename Cloud Agent Credits -> compute credits + reframe as orthogonal credit-type/host model Per user correction: the credit type is 'compute credits' (lowercase), not 'Cloud Agent Credits.' The old name conflated the credit type (compute) with the host (cloud). The corrected conceptual model treats the three credit types (AI/inference, compute, platform) and the two host types (local, cloud) as orthogonal dimensions: any credit type can in principle apply to any host, with compute credits being the one that in practice only cloud agents consume (because local agents run on the user's machine). Files touched: Content (6): - credits.mdx: three-bucket bullets reframed to lead with the orthogonal dimension; section heading '### Cloud Agent Credits' -> '### Compute credits'; section intro rewritten; eligible/not- eligible subheadings renamed; all inline mentions and the '#cloud-agent-credits' anchor flipped to '#compute-credits'. - platform-credits.mdx: page intro three-bucket sentence updated to use 'compute credits'; three-bucket bullets reframed with the orthogonal-dimension intro; multi-bucket example updated; per-user and admin breakdown bullets updated to use bucket names consistently. - team-access-billing-and-identity.mdx: 3 references reworded to drop the 'normal Warp credits, Cloud Agent Credits, or a Build plan' stale enumeration and use plan credits / compute credits. - agent-platform/cloud-agents/overview.mdx: 2 references updated to the new terminology + anchor. - enterprise/support-and-resources/billing.mdx: 'small hosting fee' framing replaced with the explicit three-bucket model; 'no separate cloud agent credits or local credits' sentence replaced with a framing that aligns with the bucket model (credit type depends on infrastructure, not on local vs cloud). - terminal-and-agent-modes.mdx: Credits indicator description generalized from 'remaining cloud agent credits' to 'remaining credits.' Support / glossary (3): - AGENTS.md: 'Cloud Agent Credits' entry replaced with 'compute credits' (lowercase) entry; new 'Platform Credits' entry added (was previously implicit). - .agents/references/terminology.md: same swap in the billing glossary. - .agents/skills/style_lint/style_lint.py: 'Cloud Agent Credits' removed from PROPER_FEATURE_NAMES (no longer a Title-Case exception since it's now lowercase); 'Platform Credits' added to PROPER_FEATURE_NAMES; PRODUCT_CASING gains 'Cloud Agent Credits' -> 'compute credits' and 'Cloud Agent Credit' (singular) as one-way nudges so future contributors don't reintroduce the old name. Validation: - 0 remaining 'Cloud Agent Credit' or '#cloud-agent-credit' references in src/content/docs. - style_lint --changed: only the 2 pre-existing BYOK warnings (Zero Data Retention, BYOK on Enterprise and Business plans). Both are acceptable false positives flagged in prior commits. - check_links --internal-only: 0 broken across 319 files and 2,434 internal links. The Astro Starlight heading-to-anchor derivation (### Compute credits -> #compute-credits) resolves correctly. Out of scope: - Lowercasing 'Platform Credits' (user did not request). - Changes to pricing-faqs.mdx (no mentions). - vercel.json redirects (anchors aren't redirected; all inbound refs in our own docs were updated directly). Co-Authored-By: Oz * docs: normalize credits list separators Co-Authored-By: Oz * docs(platform-credits): restore descriptive 'cloud agent credits' on the Credits indicator UI label In the prior rename pass I over-corrected one spot: the 'Credits indicator' UI label in terminal-and-agent-modes.mdx, which described the cloud agent conversation's credit-balance indicator. The original text 'Shows your remaining cloud agent credits' was using 'cloud agent credits' descriptively (as in 'the credits cloud agents consume'), not as a formal product-name reference. Restoring the original wording. The PRODUCT_CASING lint nudge is case-sensitive on Title Case 'Cloud Agent Credits' / 'Cloud Agent Credit', so descriptive lowercase mentions like this one don't trigger it. Co-Authored-By: Oz * docs(platform-credits): revert compute credits rename back to Cloud Agent Credits Per user feedback: the product name is 'Cloud Agent Credits' (Title Case). The word 'compute' is the type description (what the bucket covers - the sandbox an agent runs in), not the product name. My prior rename pass conflated the two. Revert it. Kept from the prior pass: - The orthogonal credit-type/host conceptual reframe: 'Credit types and where an agent runs (local or cloud) are independent. Each agent run consumes from whichever credit types apply to it.' This framing was an improvement and stays. - The Enterprise billing page rewrite: the old 'small hosting fee' framing and the contradicting 'no separate cloud agent credits or local credits' sentence stay replaced by the explicit three-bucket explanation. Just substituted 'Cloud Agent Credits' back for the product-name reference. - The BYOK / customer-supplied inference TOS callouts in platform-credits.mdx and bring-your-own-api-key.mdx. - The Platform Credits glossary entry I added to AGENTS.md and terminology.md (was a real gap, not added by mistake). - The descriptive lowercase 'cloud agent credits' in terminal-and-agent-modes.mdx:126 (UI label restoration in 8833ded). Reverted: - credits.mdx: three-bucket bullets, section heading '### Compute credits' -> '### Cloud Agent Credits', section intro, eligible / not-eligible subheadings and intros. - platform-credits.mdx: page intro three-bucket sentence, three-bucket bullets, multi-bucket example, per-user and admin breakdown bullets. - team-access-billing-and-identity.mdx: 3 references and anchor link. - cloud-agents/overview.mdx: 2 references and anchors. - enterprise/support-and-resources/billing.mdx: product-name swap. - AGENTS.md: glossary entry back to 'Cloud Agent Credits'. - terminology.md: same. - style_lint.py: 'Cloud Agent Credits' back in PROPER_FEATURE_NAMES; removed the two PRODUCT_CASING nudges for Cloud Agent Credits -> compute credits. Validation: - 0 'compute credits' product-name references remain in src/content/docs. - style_lint --changed: only the 2 pre-existing BYOK header false positives. - check_links --internal-only: 0 broken across 319 files and 2,434 internal links. The '#cloud-agent-credits' anchor resolves via the restored '### Cloud Agent Credits' heading. Co-Authored-By: Oz * docs: add Platform Credits AEO summary Co-Authored-By: Oz * Split Cloud Agent Credits into Compute credits + Cloud agent credits; rename plan credits to normal Warp credits Address review feedback: 1. Split into two complementary concepts: - **Compute credits** (sentence case): the compute bucket itself, used alongside AI credits and Platform Credits when describing credit types. - **Cloud agent credits** (sentence case, 'Cloud' capitalized): credits consumed by cloud agents, in contrast with local agent credits. Both refer to the same underlying bucket; pick the term that fits the framing. 2. Rename 'plan credits' to 'normal Warp credits' in user-facing copy so it's no longer confused with 'Build plan credits' (the proper plan product noun, which is preserved). Files updated: - credits.mdx: Three-bucket bullets use 'Compute credits'. Section heading '### Cloud Agent Credits' becomes '### Compute credits' with anchor '#compute-credits', plus eligible/not-eligible subheadings switch to 'compute credits'. A short note explains the 'Cloud agent credits' alias for the host-context framing. - platform-credits.mdx: Bucket-context bullets and per-user/admin breakdown switch to 'Compute credits' (bucket framing) plus the three-bucket intro sentence. - team-access-billing-and-identity.mdx, cloud-agents/overview.mdx: Cloud-vs-local-host bullets use 'Cloud agent credits' (sentence case) pointing to '#compute-credits'. - enterprise/support-and-resources/billing.mdx: Three-bucket framing uses 'compute credits' alongside AI and Platform Credits. - add-on-credits.mdx, pricing-faqs.mdx: 'plan credits' (legacy term) swapped for 'normal Warp credits'; 'Build plan credits' (proper noun) is preserved. - AGENTS.md, .agents/references/terminology.md: Glossary updated with both 'Compute credits' and 'Cloud agent credits' entries, and the 'normal Warp credits' guidance. - .agents/skills/style_lint/style_lint.py: Removes 'Cloud Agent Credits' from PROPER_FEATURE_NAMES and adds a nudge to use sentence case ('Cloud agent credits') or 'compute credits' depending on framing. Validation: - 0 'Cloud Agent Credits' Title Case occurrences in src/content/docs - All 3 remaining 'plan credits' matches are 'Build plan credits' - style_lint --changed: only pre-existing BYOK false positives - check_links --internal-only: 0 broken across 2,434 internal links - '#compute-credits' anchor resolves via renamed section heading Co-Authored-By: Oz * Lowercase 'cloud agent credits' mid-sentence/mid-bullet Per review feedback: the term 'cloud agent credits' is a common noun and should be lowercased anywhere it appears mid-sentence or mid-bullet. Only capitalize the first letter at the start of a sentence or bullet. Files updated: - credits.mdx L124: the alias clarification ('referred to as **cloud agent credits**') is now lowercase. - team-access-billing-and-identity.mdx L21, L41, L84: all three are mid-bullet/mid-sentence references and are lowercased. - cloud-agents/overview.mdx L120, L135: mid-bullet references lowercased. - AGENTS.md, .agents/references/terminology.md: glossary entry header is now '**cloud agent credits**' (lowercase) to match the canonical form for common-noun terms (consistent with **credits**, **normal Warp credits**, etc.). The description was updated to explain when to capitalize. - .agents/skills/style_lint/style_lint.py: PRODUCT_CASING nudge now recommends lowercase 'cloud agent credits' with a note about capitalizing the first letter at sentence/bullet boundaries. Glossary entries that lead a bullet (e.g. '**cloud agent credits**') stay lowercase to follow the existing common-noun convention in terminology.md, not because they're mid-sentence. Co-Authored-By: Oz * Lowercase 'platform credits' mid-sentence/mid-bullet/mid-heading Per review feedback, apply the same common-noun convention to 'platform credits' that we applied to 'cloud agent credits' and 'compute credits'. Capitalize the first letter only at the start of a sentence, bullet, or heading; lowercase everywhere else. Files updated: - platform-credits.mdx: title -> 'Platform credits'. Every body, bullet, and heading occurrence reframed: - Three-bucket bullets and mid-sentence text -> 'platform credits' / '**Platform credits**' (bullet leads stay sentence-cased). - All H2/H3 headings ('## How platform credits are measured', '## When platform credits apply', '### Uses platform credits', '### Doesn't use platform credits', '## Where platform credits appear') lowercase the second word. - credits.mdx: three-bucket bullet, section heading '### Platform credits', subsection headings, and all in-text occurrences updated. Mid-sentence link text 'See [platform credits](...)' is also lowercased. - enterprise/support-and-resources/billing.mdx: the example sentence the reviewer flagged ('...AI credits..., compute credits..., and platform credits for the orchestration layer') and the three-types parenthetical (AI credits, compute credits, and platform credits) are lowercased. - plans-pricing-refunds.mdx: the related-links bullet now reads '[Platform credits](...) - learn how platform credits cover...'. - AGENTS.md, .agents/references/terminology.md: glossary entry header is now '**platform credits**' (matching the existing common-noun convention used for **credits**, **normal Warp credits**, **compute credits**, **cloud agent credits**) with a usage note explaining the casing rule. Adjacent **compute credits** entry is normalized the same way. - .agents/skills/style_lint/style_lint.py: 'Platform Credits' removed from PROPER_FEATURE_NAMES and a new PRODUCT_CASING nudge maps the title-cased form to lowercase 'platform credits' with a note about capitalizing at sentence/bullet/heading boundaries. Validation: - check_links --internal-only: 0 broken across 2,434 internal links. - The only remaining 'Platform Credits' Title Case match is the linter's own wrong->right mapping (expected). Co-Authored-By: Oz * docs: rename 'normal Warp credits' to 'Warp credits' Drops the 'normal' qualifier across user-facing copy, the terminology glossary, and AGENTS.md. 'Warp credits' is the cleaner brand-aligned term for credits included with a subscription plan. Co-Authored-By: Oz * docs: polish credit copy after rename - Drop now-redundant 'or Build plan credits' / 'or a Build plan with available credits' (Build plan credits are Warp credits). - Tighten 'individual Warp credits' to 'individual credits' to match the prior bullet's wording. - Remove duplicate 'Warp' in 'your included monthly Warp credits'. - Replace 'Build plan credits' with [Add-on Credits] in the cloud-agents requirements bullet so it mirrors the team-requirements bullet below it. - Restructure the Add-on Credits/limits sentence in platform-credits.mdx to make the consumption order explicit. - Update 'same plan credit pool' to 'same Warp credit pool' in credits.mdx. Co-Authored-By: Oz * docs: drop redundant credit-type enumerations The '(any type works)' parenthetical and the 'Warp credits, cloud agent credits, and Add-on Credits all work' bullet aren't actually telling the user anything actionable — they're all credits and they all draw from the same balance. Just say '20 credits' and let the linked billing pages handle the credit-type breakdown. Touched: - agent-platform/cloud-agents/overview.mdx (2 occurrences; removed the redundant credit-type bullet under Credit requirements as well as the vague 'Usage is billed based on credit type and team configuration' filler bullet). - agent-platform/cloud-agents/team-access-billing-and-identity.mdx (2). - agent-platform/cloud-agents/quickstart.mdx (1). - agent-platform/cloud-agents/integrations/slack.mdx (1). - agent-platform/cloud-agents/integrations/linear.mdx (1). Co-Authored-By: Oz --------- Co-authored-by: Oz Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> --- .agents/references/terminology.md | 6 +- .agents/skills/style_lint/style_lint.py | 9 ++- AGENTS.md | 6 +- .../cloud-agents/integrations/linear.mdx | 2 +- .../cloud-agents/integrations/slack.mdx | 2 +- .../agent-platform/cloud-agents/overview.mdx | 6 +- .../cloud-agents/quickstart.mdx | 2 +- .../team-access-billing-and-identity.mdx | 10 +-- .../support-and-resources/billing.mdx | 4 +- .../plans-and-billing/add-on-credits.mdx | 2 +- .../bring-your-own-api-key.mdx | 6 ++ .../plans-and-billing/credits.mdx | 58 ++++++++++++----- .../plans-pricing-refunds.mdx | 1 + .../plans-and-billing/platform-credits.mdx | 63 +++++++++++++++++++ .../plans-and-billing/pricing-faqs.mdx | 4 +- 15 files changed, 143 insertions(+), 38 deletions(-) create mode 100644 src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx diff --git a/.agents/references/terminology.md b/.agents/references/terminology.md index aea79cf4..3fcce82d 100644 --- a/.agents/references/terminology.md +++ b/.agents/references/terminology.md @@ -231,9 +231,11 @@ For the summary of the most critical terms (core features, Oz terms, terms to av ## Billing and credits - **Add-on Credits** — capitalized as a product feature name -- **Cloud Agent Credits** — capitalized as a billing feature name +- **compute credits** — lowercase common noun; capitalize the first letter only at the start of a sentence or bullet. The compute bucket, consumed when an agent run uses Warp-hosted compute. Use alongside AI credits and platform credits when describing credit types. +- **cloud agent credits** — lowercase common noun; capitalize the first letter only at the start of a sentence or bullet. Credits consumed by cloud agents, in contrast with local agent credits. Refers to the same compute bucket as compute credits; choose the term that fits the framing. +- **platform credits** — lowercase common noun; capitalize the first letter only at the start of a sentence or bullet. The platform-infrastructure bucket, consumed for every cloud agent run plus local runs with customer-supplied inference. - **credits** — the unit of usage for AI features in Warp (lowercase, not "AI credits") -- **plan credits** — credits included with a subscription plan +- **Warp credits** — credits included with a subscription plan. Use in user-facing copy rather than "plan credits." ## External product names diff --git a/.agents/skills/style_lint/style_lint.py b/.agents/skills/style_lint/style_lint.py index 488ed834..414f62e7 100644 --- a/.agents/skills/style_lint/style_lint.py +++ b/.agents/skills/style_lint/style_lint.py @@ -35,15 +35,18 @@ # Feature names that are correctly Title Case (exceptions to sentence-case rule) PROPER_FEATURE_NAMES = { "Admin Panel", "Agent Management Panel", "Agent Mode", "Agent Profiles", - "Ambient Agents", "Auto-detection Mode", "Cloud Agent Credits", + "Ambient Agents", "Auto-detection Mode", "Codebase Context", "Code Review", "Command Palette", "Global Rules", - "Oz CLI", "Oz Platform", "Project Rules", "Slash Commands", - "Terminal Mode", "Universal Input", "Warp Drive", "Warp Platform", + "Oz CLI", "Oz Platform", "Project Rules", + "Slash Commands", "Terminal Mode", "Universal Input", "Warp Drive", + "Warp Platform", } # Terminology: wrong → right (case-sensitive checks) PRODUCT_CASING = { "Warp Terminal": ("Warp", "Use 'Warp' unless specifically distinguishing from Oz"), + "Cloud Agent Credits": ("cloud agent credits", "Use lowercase 'cloud agent credits' (host-context) or 'compute credits' (bucket-context); capitalize first letter only at start of a sentence/bullet"), + "Platform Credits": ("platform credits", "Use lowercase 'platform credits'; capitalize first letter only at start of a sentence/bullet/heading"), "agent mode": ("Agent Mode", "Capitalize as a feature name"), "agent management panel": ("Agent Management Panel", "Capitalize as a UI surface name"), "warp drive": ("Warp Drive", "Capitalize as a feature name"), diff --git a/AGENTS.md b/AGENTS.md index d3ad135b..9e74eb38 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -610,8 +610,10 @@ Product feature names retain their standard capitalization. Match the exact casi ### Billing and credits - **credits** (lowercase, not "AI credits") - the unit of usage for AI features in Warp - **Add-on Credits** (capitalized as a product feature name) -- **Cloud Agent Credits** (capitalized as a billing feature name) -- **plan credits** - credits included with a subscription plan +- **compute credits** (lowercase common noun; capitalize the first letter only at the start of a sentence or bullet) - the compute bucket; consumed when an agent run uses Warp-hosted compute. Used alongside AI credits and platform credits when describing credit types. +- **cloud agent credits** (lowercase common noun; capitalize the first letter only at the start of a sentence or bullet) - credits consumed by cloud agents (in contrast with local agent credits). Refers to the same compute bucket as compute credits; pick the term that fits the framing. +- **platform credits** (lowercase common noun; capitalize the first letter only at the start of a sentence or bullet) - the platform-infrastructure bucket +- **Warp credits** - credits included with a subscription plan. Use in user-facing copy rather than "plan credits." - Use "credit" or "credits" without the "AI" prefix throughout documentation ### UI elements diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx index 3b8305f4..ecd2f177 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx @@ -66,7 +66,7 @@ Because PRs are created as _you_, this makes code review, auditing, and team col ### Requirements * **Team membership** - The Linear integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. -* **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available (any type of Warp credits work). See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. +* **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available. See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. * **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/agent-platform/cloud-agents/self-hosting/) on their own infrastructure. * **Identity** - You must be logged into Warp with the same email as your Linear workspace. * **GitHub authorization** - You must authorize the Warp GitHub app the first time you trigger an agent. diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx index 9d257977..f724666f 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx @@ -80,7 +80,7 @@ Because PRs are created as you, the workflow slots seamlessly into your team’s ### Requirements * **Team membership** - The Slack integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. -* **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available (any type of Warp credits work). See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. +* **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available. See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. * **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/agent-platform/cloud-agents/self-hosting/) on their own infrastructure. * **Identity** - You must be logged into Warp with the same email used in your Slack workspace. * **GitHub authorization** - You must authorize the **Warp GitHub app** the first time you trigger a Slack integration request. diff --git a/src/content/docs/agent-platform/cloud-agents/overview.mdx b/src/content/docs/agent-platform/cloud-agents/overview.mdx index dd242d5e..d5fe8c02 100644 --- a/src/content/docs/agent-platform/cloud-agents/overview.mdx +++ b/src/content/docs/agent-platform/cloud-agents/overview.mdx @@ -117,7 +117,7 @@ Cloud agents and [integrations](/agent-platform/cloud-agents/integrations/) run Individual users can run cloud agents without being on a team. Requirements: -* You need at least 20 credits (any type: normal Warp credits, [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits), or Build plan credits) +* You need at least 20 credits available * Cloud agents run on Warp-hosted infrastructure * Self-hosted agents require a team subscription @@ -130,9 +130,7 @@ Integrations require you to be part of a [Warp team](/knowledge-and-collaboratio * Not supported: Pro, Turbo, Lightspeed, legacy Business * Your plan must support Add-on Credits. * **Credit requirements** - * Your team must have at least 20 credits available (any type of Warp credits work) to run cloud agents and integrations. - * Usage is billed based on credit type and team configuration. - * Normal credits, [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits), and [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) all work. + * Your team must have at least 20 credits available to run cloud agents and integrations. For more details, see [Access, Billing, and Identity Permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/). diff --git a/src/content/docs/agent-platform/cloud-agents/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/quickstart.mdx index a8d1def8..19d1b643 100644 --- a/src/content/docs/agent-platform/cloud-agents/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/quickstart.mdx @@ -157,7 +157,7 @@ Use official Docker Hub images like `node`, `python`, or `rust` for best compati Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works). For automated workflows using team API keys, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get `. **Not enough credits to run cloud agents**\ -Your team needs at least 20 credits available (any type of Warp credits work). Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. +Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. **More resources** diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx index 298e9f95..e9c1ab37 100644 --- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx +++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx @@ -18,7 +18,7 @@ Cloud agents can be used in two ways: **Individual users** (without a team): * Can run cloud agents via CLI or API -* Can use normal Warp credits, [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits), or a Build plan with available credits +* Can use Warp credits, including [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) * Agents run on Warp-hosted infrastructure * Cannot use integrations (Slack, Linear) or self-hosted agents @@ -27,7 +27,7 @@ Cloud agents can be used in two ways: * Can use integrations (Slack, Linear) to trigger agents * Can self-host agents on their own infrastructure (Enterprise only) * Share team-level configuration (environments, secrets, integrations) -* Team must be on Build, Max, or Business plan with at least 20 credits (any type) for cloud agents and integrations +* Team must be on Build, Max, or Business plan with at least 20 credits for cloud agents and integrations --- @@ -38,7 +38,7 @@ Individual users can run cloud agents via the CLI or API without being part of a **How it works:** * Run agents using `oz agent run-cloud` or the Oz API -* Credits are drawn from your normal Warp credits, Cloud Agent Credits (if available), or Build plan credits +* Credits are drawn from your Warp credits (including cloud agent credits, when applicable) * Agents execute on Warp-hosted infrastructure **What you can do:** @@ -79,9 +79,9 @@ Your team must meet the following requirements to run integrations: * You must be on a plan that supports **[Reload Credits (Add-on Credits)](/support-and-community/plans-and-billing/add-on-credits/)**. * Supported: **Build, Max, Business** * Not supported: Pro, Turbo, Lightspeed, legacy Business. -* Your team needs at least **20 credits** available to run cloud agents and integrations (any type of Warp credits work) +* Your team needs at least **20 credits** available to run cloud agents and integrations -When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits in a specific order. It starts with any [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits) the user has, then moves to the user's base credits, followed by the team's Reload Credits, and finally the user's own Reload Credits. Enterprises may have different payment options and credit plans that affect this flow. If all applicable credit sources are exhausted, integrations and cloud agents will not work until credits are added. +When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits in a specific order. It starts with any [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) the user has, then moves to the user's base credits, followed by the team's Reload Credits, and finally the user's own Reload Credits. Enterprises may have different payment options and credit plans that affect this flow. If all applicable credit sources are exhausted, integrations and cloud agents will not work until credits are added. :::note If you're on an Enterprise plan, please reach out to [warp.dev/contact-sales](https://warp.dev/contact-sales) with any billing questions related to integrations. diff --git a/src/content/docs/enterprise/support-and-resources/billing.mdx b/src/content/docs/enterprise/support-and-resources/billing.mdx index 8110c6ab..5d4bb48e 100644 --- a/src/content/docs/enterprise/support-and-resources/billing.mdx +++ b/src/content/docs/enterprise/support-and-resources/billing.mdx @@ -31,11 +31,11 @@ Credit allocations vary by contract. Contact your account manager for details on ## Cloud agent billing -Oz cloud agents consume credits that include a small hosting fee in addition to AI usage costs. +Oz cloud agents consume AI credits for inference, compute credits for the sandbox they run in, and platform credits for the orchestration layer. See [Credits](/support-and-community/plans-and-billing/credits/) for the full breakdown of how each credit type is metered. ### How credits are consumed -On Enterprise plans, both local and cloud agent usage draw from the same team credit pool. There are no separate "cloud agent credits" or "local credits" — all agent usage consumes from your available credit sources. +On Enterprise plans, local and cloud agent usage both draw from the same team credit pool across all three credit types (AI credits, compute credits, and platform credits). The credit type a run consumes depends on what infrastructure it uses, not on whether it's local or cloud. For team API key runs (e.g., CI/CD pipelines, scheduled tasks), credits also draw from the team's shared pool since these runs are not tied to any individual user. diff --git a/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx b/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx index 8b032f02..193616e4 100644 --- a/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx @@ -71,7 +71,7 @@ The limit resets automatically at the start of each calendar month, so you can m When your monthly credit balance renews: -1. Warp first consumes your included monthly plan credits (e.g., Build plan credits). +1. Warp first consumes your included monthly credits (e.g., Build plan credits). 2. After those are used, Warp continues to draw from any available Add-on Credits. 3. If your Add-on Credits run out and Auto reload is enabled, Warp will automatically purchase more up to your monthly limit. diff --git a/src/content/docs/support-and-community/plans-and-billing/bring-your-own-api-key.mdx b/src/content/docs/support-and-community/plans-and-billing/bring-your-own-api-key.mdx index cd2f84c7..48f6354d 100644 --- a/src/content/docs/support-and-community/plans-and-billing/bring-your-own-api-key.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/bring-your-own-api-key.mdx @@ -15,6 +15,10 @@ BYOK provides greater flexibility in model access and ensures Warp **never consu BYOK is currently only available on Warp's paid plans, starting with Build. Learn more about plans and pricing [warp.dev/pricing](https://www.warp.dev/pricing). ::: +:::caution +BYOK and customer-supplied inference (BYOLLM via Amazon Bedrock or Google Vertex, plus custom endpoints) are available to individual users and organizations with 10 or fewer employees or users on any plan. Organizations with more than 10 employees or users must be on a Warp Business or Enterprise plan to use BYOK or customer-supplied inference. See Warp's [Terms of Service](https://www.warp.dev/terms-of-service) for details. +::: + ## How does BYOK work? When you add your own model API keys in Warp, those keys are stored **locally on your device** and are **never synced to the cloud**. @@ -113,6 +117,8 @@ Warp itself never stores your LLM API keys. ### BYOK on Enterprise and Business plans +Organizations with more than 10 employees or users must be on a Warp Business or Enterprise plan to use BYOK or customer-supplied inference. See Warp's [Terms of Service](https://www.warp.dev/terms-of-service) for the full eligibility rule. + Currently, BYOK is configured at the **user level**, not the team or admin level: * Each team member can add and manage their own API keys locally. diff --git a/src/content/docs/support-and-community/plans-and-billing/credits.mdx b/src/content/docs/support-and-community/plans-and-billing/credits.mdx index f039eedf..17f7a569 100644 --- a/src/content/docs/support-and-community/plans-and-billing/credits.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/credits.mdx @@ -10,7 +10,13 @@ description: >- Any interaction with Warp's Agent consumes credits. Credits are primarily based on AI usage — the number of credits a task consumes varies based on the size and complexity of your codebase, the size of the task, the model you're using, the amount of context the agent needs to gather, and more. -Credits also include a small hosting fee, charged only when running agents in the cloud, hosted on Warp's infrastructure. For details on cloud agent credits, see [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits). +Warp meters credits across three types of infrastructure — inference, compute, and platform — each with its own bucket. Credit types and where an agent runs (local or cloud) are independent: each agent run consumes from whichever credit types apply to it. + +* **AI credits** cover inference: the LLM call itself. Consumed when Warp pays for the model call through Warp-managed providers. +* **Compute credits** cover compute: the sandbox an agent runs in. Consumed when an agent run uses Warp-hosted compute. In practice this is cloud agent runs; local agent runs use your own machine and don't consume compute credits. See [Compute credits](/support-and-community/plans-and-billing/credits/#compute-credits). +* **Platform credits** cover Warp's platform layer: run lifecycle, integrations, dashboard, APIs, and observability. Apply to every cloud agent run, plus local agent runs on Business and Enterprise plans that use customer-supplied inference (BYOK or BYOLLM via Amazon Bedrock or Google Vertex). See [platform credits](/support-and-community/plans-and-billing/platform-credits/). + +All three buckets draw from the same Warp credit pool and [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/), so you can manage them as a single balance in the Warp app under **Settings** > **Billing and usage**. Each interaction consumes **at least one credit**, though more complex interactions may use **multiple credits**. Because of factors such as codebase size, model choice, number of tool calls, and the nature of LLMs, credit usage is **non-deterministic** — two similar prompts can still use a different number of credits. @@ -36,7 +42,7 @@ You can view your total credit usage, along with other billing details, in **Set #### Credit **limits and billing** * **Seat-level allocation**: On team plans, credit limits apply per seat — each team member has their own allowance. Individual users (not on a team) also have their own credit allocation. -* **Cloud Agent Credits**: Individual users can run cloud agents via CLI/API using their normal Warp credits, [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits), or a Build plan with available credits. Integrations (Slack, Linear) require team membership. +* **Cloud agents and integrations**: Individual users can run cloud agents via the CLI and API, drawing from their Warp credits. Slack and Linear integrations require team membership. * **Hitting the credit limits**: Once you hit your monthly credit limit, your access will depend on your plan. On the Free plan, AI access stops until your next billing cycle. On paid plans, you can continue using AI with usage-based billing via [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/). #### **Other features that use credits** @@ -111,22 +117,46 @@ Because cache results depend on model provider behavior and timing, two similar These are the most common factors affecting credit usage, though there are others. Understanding them can help you manage your credits more efficiently and get the most from your plan. -### Cloud Agent Credits +### Compute credits + +Compute credits cover Warp-hosted compute consumed by an agent run. In practice, cloud agent runs consume them because they run on Warp's compute; local agent runs typically don't, since they run on your own machine. + +Compute credits are sometimes referred to as **cloud agent credits** when the conversation is framed around cloud agents vs local agents — they're the same bucket described from a different angle. + +#### Eligible for compute credits + +The following scenarios use compute credits: + +* **First-party integrations** - Running agents through Slack or Linear integrations +* **Cloud agent runs** - Using `oz agent run-cloud` via the CLI +* **Oz API** - Running agents through Warp's Oz API +* **Cloud Mode** - Running an agent from Cloud Mode in the Warp app + +#### Not eligible for compute credits + +The following scenarios don't use compute credits because they don't run on Warp-hosted compute: + +* **Local agent runs** - Using `oz agent run` on your local machine +* **Self-hosted compute** - Using `oz agent run` on GitHub Actions, CI/CD pipelines, or other self-hosted infrastructure + +### Platform credits + +Platform credits cover Warp's platform infrastructure — run lifecycle, scheduling, integrations, dashboard, APIs, and observability — for every cloud agent run, plus local agent runs on Business and Enterprise plans that use customer-supplied inference. -Cloud Agent Credits are a type of credit consumed only by cloud agent runs — AI requests that run on Warp-hosted compute. +#### Eligible for platform credits -#### Eligible for Cloud Agent Credits +Platform credits are used in the following scenarios: -The following scenarios use Cloud Agent Credits: +* **Cloud agents on any plan** use platform credits for every cloud agent run, regardless of which agent runs the task or which inference source it uses. +* **Local agents on Business or Enterprise with customer-supplied inference** use platform credits when the local agent run uses [Bring Your Own API Key (BYOK)](/support-and-community/plans-and-billing/bring-your-own-api-key/) or BYOLLM via Amazon Bedrock or Google Vertex. -* **First-party integrations** — Running agents through Slack or Linear integrations -* **Cloud agent runs** — Using `oz agent run-cloud` via the CLI -* **Oz API** — Running agents through Warp's Oz API -* **Cloud Mode** — Running an agent from Cloud Mode in the Warp app +#### Not eligible for platform credits -#### Not eligible for Cloud Agent Credits +The following scenarios do **not** use platform credits: -The following scenarios do **not** use Cloud Agent Credits: +* **Local agents on Free, Build, or Max plans** don't use platform credits, regardless of inference source. +* **Local agents on Business or Enterprise using Warp-managed inference** don't use platform credits because Warp is already paying for the model call through AI credits. +* **Regular terminal usage** doesn't use platform credits. Shell commands and non-AI Warp features don't consume credits. +* **Third-party agent CLIs run directly** don't use platform credits when you run `claude`, `codex`, or another agent CLI outside of Oz. -* **Local agent runs** — Using `oz agent run` on your local machine -* **Self-hosted compute** — Using `oz agent run` on GitHub Actions, CI/CD pipelines, or other self-hosted infrastructure +For a full breakdown of how platform credits work, see [platform credits](/support-and-community/plans-and-billing/platform-credits/). diff --git a/src/content/docs/support-and-community/plans-and-billing/plans-pricing-refunds.mdx b/src/content/docs/support-and-community/plans-and-billing/plans-pricing-refunds.mdx index 4423f9d6..95307399 100644 --- a/src/content/docs/support-and-community/plans-and-billing/plans-pricing-refunds.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/plans-pricing-refunds.mdx @@ -20,6 +20,7 @@ Visit [warp.dev/pricing](https://warp.dev/pricing) to see the latest plans and w * [Credits](/support-and-community/plans-and-billing/credits/) — learn how credits are used and calculated across AI features. * [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) — purchase additional credits or enable automatic reloads at discounted rates. +* [Platform credits](/support-and-community/plans-and-billing/platform-credits/) — learn how platform credits cover Warp's platform infrastructure for cloud agent runs and local runs with customer-supplied inference. * [Bring Your Own API Key](/support-and-community/plans-and-billing/bring-your-own-api-key/) — connect your own model provider API keys for custom usage and billing. * [Overages (Legacy)](/support-and-community/plans-and-billing/overages-legacy/) — information for users on legacy plans with overages enabled. * [Pricing FAQs](/support-and-community/plans-and-billing/pricing-faqs/) — answers to common questions about plans, billing, and usage. Don’t have Warp yet? [Download Warp](https://warp.dev/download) and get started for free today. diff --git a/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx b/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx new file mode 100644 index 00000000..c70d85a2 --- /dev/null +++ b/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx @@ -0,0 +1,63 @@ +--- +title: Platform credits +description: >- + Platform credits cover Warp's platform layer on every cloud agent run + and on local runs with customer-supplied inference. Learn when they apply. +--- + +Platform credits cover Warp's platform infrastructure for coordinating, observing, and integrating agent runs. They apply to every cloud agent run, plus local agent runs on Business and Enterprise plans that use customer-supplied inference such as BYOK, Amazon Bedrock, or Google Vertex. + +Warp meters credits across three types of infrastructure: **inference** (the model call), **compute** (the sandbox an agent runs in), and **platform** (everything that runs around the agent — run lifecycle, integrations, dashboard, APIs, and observability). Each type maps to one credit bucket: [AI credits](/support-and-community/plans-and-billing/credits/), [Compute credits](/support-and-community/plans-and-billing/credits/#compute-credits), and platform credits. Credit types and where an agent runs (local or cloud) are independent. + +Customer-supplied inference covers [Bring Your Own API Key (BYOK)](/support-and-community/plans-and-billing/bring-your-own-api-key/) and BYOLLM via Amazon Bedrock or Google Vertex. + +:::caution +BYOK and customer-supplied inference (BYOLLM via Amazon Bedrock or Google Vertex, plus custom endpoints) are available to individual users and organizations with 10 or fewer employees or users on any plan. Organizations with more than 10 employees or users must be on a Warp Business or Enterprise plan to use BYOK or customer-supplied inference. See Warp's [Terms of Service](https://www.warp.dev/terms-of-service) for details. +::: + +## The three credit buckets + +Each credit bucket covers a different layer of the infrastructure Warp provides. Credit types and where an agent runs (local or cloud) are independent — each agent run consumes from whichever credit types apply to it. + +* **AI credits** cover inference: the LLM call itself. Consumed when Warp pays for the model call through Warp-managed providers. Used by agent conversations, [Generate](/agent-platform/local-agents/generate/), [AI Autofill](/knowledge-and-collaboration/warp-drive/workflows/#ai-autofill), and other AI features. See [credits](/support-and-community/plans-and-billing/credits/) for how AI credits are calculated. +* **Compute credits** cover compute: the sandbox an agent runs in. Consumed when an agent run uses Warp-hosted compute. In practice this is cloud agent runs (Slack and Linear integrations, `oz agent run-cloud`, the Oz API, and Cloud Mode in the Warp app); local agent runs use your own machine and don't consume compute credits. See [Compute credits](/support-and-community/plans-and-billing/credits/#compute-credits). +* **Platform credits** cover Warp's platform layer: run lifecycle, integrations, dashboard, APIs, and observability. Apply to every cloud agent run, plus local agent runs on Business and Enterprise plans that use customer-supplied inference. + +The three buckets are independent and a single run can consume from more than one. A Warp-managed cloud agent run, for example, consumes AI credits for the model call, compute credits for the hosted compute, and platform credits for the platform infrastructure that runs the agent. + +## How platform credits are measured + +Platform credits accrue while an Oz agent is actively working on a task — from when the task starts running to when it finishes, fails, or is cancelled. Idle time, time spent waiting on user input, and time before the task starts don't accrue platform credits. + +See [warp.dev/pricing](https://warp.dev/pricing) for current rates. + +## When platform credits apply + +Whether platform credits apply depends on where the agent runs and who's paying for inference. + +### Uses platform credits + +* **Cloud agents on any plan** use platform credits for every cloud agent run, regardless of which agent runs the task (Warp Agent, Claude Code, Codex, or Gemini), inference source (Warp-managed, BYOK, or BYOLLM), or compute source (Warp-hosted or self-hosted workers). Warp's platform infrastructure coordinates every cloud agent run. +* **Local agents on Business or Enterprise with customer-supplied inference** use platform credits when the local agent run uses [BYOK](/support-and-community/plans-and-billing/bring-your-own-api-key/) or BYOLLM via Amazon Bedrock or Google Vertex. Warp isn't paying for the model call, but Warp's platform infrastructure is still running the local agent. BYOK and customer-supplied inference are subject to plan-size eligibility — see the callout above. + +### Doesn't use platform credits + +* **Local agents on Free, Build, or Max plans** don't use platform credits, regardless of whether you use Warp-managed inference or BYOK. +* **Local agents on Business or Enterprise using Warp-managed inference** don't use platform credits because Warp is already paying for the model call through AI credits. +* **Regular terminal usage** doesn't use platform credits. Shell commands and non-AI Warp features don't consume credits. +* **Third-party agent CLIs run directly** don't use platform credits when you run `claude`, `codex`, or another agent CLI without going through Oz. + +## Where platform credits appear + +Platform credits appear in the same billing views as your other credit usage. + +* **Per-user credit totals** - In the Warp app, **Settings** > **Billing and usage** includes platform credits alongside AI credits and compute credits. +* **Admin usage breakdown** - For team admins, the Admin Panel billing view shows a per-bucket breakdown for each member and for the team as a whole. Platform credits appear as their own segment in the stacked usage bar, distinct from the AI credits and compute credits segments. +* **Add-on Credits and limits** - Platform credits draw from the same pools as your other usage — your monthly Warp credits first, then [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) once those are exhausted. + +## Related pages + +* [Credits](/support-and-community/plans-and-billing/credits/) - How AI credits are measured and calculated. +* [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) - Purchase additional credits or enable auto reload. +* [Bring Your Own API Key](/support-and-community/plans-and-billing/bring-your-own-api-key/) - Connect your own model provider keys. +* [Plans, pricing, and refunds](/support-and-community/plans-and-billing/plans-pricing-refunds/) - Compare plans and refund policies. diff --git a/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx b/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx index fa5abbc7..2ee0d98d 100644 --- a/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx @@ -305,7 +305,7 @@ Add-on credits replace overages with a simpler, prepaid system. They’re up to #### Do credits rollover? -For existing users on legacy plans, plan credits on Pro, Turbo, and Lightspeed do not rollover. +For existing users on legacy plans, Warp credits on Pro, Turbo, and Lightspeed do not rollover. For the Build plan, credits will not rollover but Add-on credits will rollover and be valid for 12 months from the date of purchase. @@ -347,6 +347,6 @@ If you’re part of a larger team (up to 50 members) that needs advanced adminis For teams on the Build or Business plans, credits are managed at two levels: * **Included monthly credits**: Each seat on a paid plan receives 1,500 individual credits per month. These credits are tied to the user and reset every 30 days based on their subscription or renewal date. -* **Add-on Credits**: Once individual plan credits are used up, team members draw from a shared Add-on Credit balance that can be topped up and managed by team admins. +* **Add-on Credits**: Once individual credits are used up, team members draw from a shared Add-on Credit balance that can be topped up and managed by team admins. This shared model gives teams the flexibility to handle variable AI usage – heavy users can consume more when needed, while the entire team benefits from shared value and volume-based discounts. From d7d5c8edb02fa785dbfdc9d75c759d0aefc1f261 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 18 May 2026 21:56:43 -0700 Subject: [PATCH 04/10] Audit pass: wire new orchestration-launch pages into sidebar; tidy stale terminology (#97) Audit pass over the three PRs merged into hyc/orchestration-launch (#83 Platform Credits, #87 Harnesses, #88 Agent identities) to catch wiring and cross-reference issues before rollout. Sidebar wiring (src/sidebar.ts): - Under 'Oz Cloud Agents & Orchestration', add 'Agent identities' (slug agent-platform/cloud-agents/agents) after Managing cloud agents, and a new collapsed 'Harnesses' subsection (Overview, Warp Agent, Claude Code, Codex, Authentication) after Secrets and before MCP servers. - Under 'Plans and billing', add 'Platform credits' after Add-on Credits. Terminology / cross-reference (one-line tweaks): - external-authentication-required.mdx:104: replace the inline '(service account)' parenthetical with 'bound to an [agent identity](...)'. Matches the alias formalized in agents.mdx and the existing phrasing in federate.mdx and cli/index.mdx. - cloud-agents/overview.mdx Learn more: add two bullets so the new Harnesses overview and Agent identities pages are discoverable from the parent overview. Validation: - check_links --internal-only: 0 broken across 2,495 internal links (up 3 from the 2,492 baseline, matching the 3 new links added). - style_lint --changed: 14 warnings, identical to baseline (all pre-existing proper-name false positives in pricing-faqs.mdx, bring-your-own-api-key.mdx, etc.). - npm run build: succeeds; 326 HTML files generated. Co-authored-by: Oz --- .../docs/agent-platform/cloud-agents/overview.mdx | 2 ++ .../errors/external-authentication-required.mdx | 2 +- src/sidebar.ts | 13 +++++++++++++ 3 files changed, 16 insertions(+), 1 deletion(-) diff --git a/src/content/docs/agent-platform/cloud-agents/overview.mdx b/src/content/docs/agent-platform/cloud-agents/overview.mdx index d5fe8c02..2bcc4a16 100644 --- a/src/content/docs/agent-platform/cloud-agents/overview.mdx +++ b/src/content/docs/agent-platform/cloud-agents/overview.mdx @@ -144,6 +144,8 @@ If your credit balance reaches zero, cloud agent runs will not be able to execut * [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/) — run your first cloud agent with an environment in ~10 minutes. * [Oz Platform](/agent-platform/cloud-agents/platform/) — CLI, Oz API/SDK, orchestration, tasks, environments, hosts, integrations, and more. +* [Harnesses](/agent-platform/cloud-agents/harnesses/) — pick between Warp Agent, Claude Code, and Codex for any cloud agent run. +* [Agent identities](/agent-platform/cloud-agents/agents/) — team-scoped bot accounts that own and execute cloud agent runs. * [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/) — run agents based on reusable skill definitions from the CLI, web app, API, or on a schedule. * [Oz CLI](/reference/cli/) — shows how to run Oz agents in non-interactive mode from CI, scripts, or remote machines, including auth and common commands. * [Environments](/agent-platform/cloud-agents/environments/) — explains how environments provide the runtime context (repo, image, startup commands) for agent tasks. diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx index 531b94d9..72433c1e 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx @@ -101,7 +101,7 @@ This error includes extra fields beyond the standard response format: 2. Ensure the app has access to all repositories listed in `inaccessible_repos`. 3. Retry the task. -If you are using a **team API key** (service account), ensure the Warp GitHub App is installed on the organization that owns the repositories. +If you are using a **team API key** bound to an [agent identity](/agent-platform/cloud-agents/agents/), ensure the Warp GitHub App is installed on the organization that owns the repositories. ### Account matching failed diff --git a/src/sidebar.ts b/src/sidebar.ts index c2e510a8..39a2aa9d 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -351,10 +351,22 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ }, 'agent-platform/cloud-agents/environments', { slug: 'agent-platform/cloud-agents/managing-cloud-agents', label: 'Managing cloud 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' }, { slug: 'agent-platform/cloud-agents/viewing-cloud-agent-runs', label: 'Viewing cloud agent runs' }, 'agent-platform/cloud-agents/secrets', + { + label: 'Harnesses', + collapsed: true, + items: [ + { slug: 'agent-platform/cloud-agents/harnesses', label: 'Overview' }, + { slug: 'agent-platform/cloud-agents/harnesses/warp-agent', label: 'Warp Agent' }, + { slug: 'agent-platform/cloud-agents/harnesses/claude-code', label: 'Claude Code' }, + { slug: 'agent-platform/cloud-agents/harnesses/codex', label: 'Codex' }, + { slug: 'agent-platform/cloud-agents/harnesses/authentication', label: 'Authentication' }, + ], + }, { slug: 'agent-platform/cloud-agents/mcp', label: 'MCP servers' }, { slug: 'agent-platform/cloud-agents/deployment-patterns', label: 'Deployment patterns' }, { slug: 'agent-platform/cloud-agents/warp-hosting', label: 'Warp-hosted agents' }, @@ -502,6 +514,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'support-and-community/plans-and-billing/plans-pricing-refunds', label: 'Plans, Pricing, & Refunds' }, 'support-and-community/plans-and-billing/credits', 'support-and-community/plans-and-billing/add-on-credits', + { slug: 'support-and-community/plans-and-billing/platform-credits', label: 'Platform credits' }, 'support-and-community/plans-and-billing/bring-your-own-api-key', 'support-and-community/plans-and-billing/overages-legacy', 'support-and-community/plans-and-billing/pricing-faqs', From 726f5927e558a6392cdc9c21155f2e021fff2d72 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 18 May 2026 22:51:29 -0700 Subject: [PATCH 05/10] Audit pass 2: factual corrections, terminology unification, style cleanup (#99) Comprehensive pass over the orchestration-launch branch to catch content issues that wiring-focused audit #97 left behind. Factual corrections: - agents.mdx: drop 'getAgent' from the operationId list and remove the 'Retrieve - GET /agent/identities/{uid}' bullet. The OpenAPI spec (developers/agent-api-openapi.yaml) only ships createAgent / listAgents / updateAgent / deleteAgent under the /agent/identities path; there is no single-resource GET. - agents.mdx: replace 'pass the identity\'s UID to the generateApiKey mutation' with 'choose the identity when creating the team API key'. No generateApiKey mutation exists in the OpenAPI, and api-keys.mdx describes a UI-driven creation flow. - agents.mdx: drop the ('Quick run' in the web app) parenthetical from the default-identity fallback note. oz-web-app.mdx defines Quick run as user-attributed ('runs as your own user'), so equating it with the default agent identity contradicts the rest of the docs. Terminology unification (post three-bucket / agents-launch model): - harnesses/index.mdx, claude-code.mdx, codex.mdx: replace the vague 'Warp credits cover the orchestration platform' wording with the explicit three-bucket framing 'Warp meters compute credits for the run\'s sandbox and platform credits for the orchestration layer'. - team-access-billing-and-identity.mdx: rename every 'Reload Credits' / 'Reload Credit pool' / 'Reload Credit balance' reference to the canonical 'Add-on Credits' (5 spots, including the parenthetical '[Reload Credits (Add-on Credits)](...)'). - oz-web-app.mdx: rename the page title and 6 image alt texts from 'Oz Web App' (Title Case) to 'Oz web app' to match the canonical glossary entry and the sidebar label. Style guide cleanup: - secrets.mdx: drop a trailing ' ' GitBook artifact, replace 'just references it by name' with 'only references it by name', and backtick the bare 'oz secret' in 'oz secret command family'. - harnesses/authentication.mdx: replace 'just like any other Warp- managed secret' with 'like any other Warp-managed secret'. - deployment-patterns.mdx: drop 'just' from 'and you just need a reliable, cloud-connected agent runner'. - cloud-agents/overview.mdx: lowercase two H4 headings ('For Cloud Agents via CLI/API' -> 'For cloud agents via CLI/API'; 'For Integrations (Slack/Linear)' -> 'For integrations (Slack/Linear)') per the sentence-case style guide. Validation: - check_links --internal-only: 0 broken across 2,501 internal links (up 6 from the 2,495 baseline, matching the new compute-credits / platform-credits anchors added in the harnesses billing sections). - style_lint --changed: only pre-existing proper-name false positives in pricing-faqs.mdx (Build / Business / Pro / Turbo / Lightspeed / Add-on Credits headings). - npm run build: 326 pages built; sidebar compiles; new anchor and slug references resolve. Co-authored-by: Oz --- .../docs/agent-platform/cloud-agents/agents.mdx | 7 +++---- .../cloud-agents/deployment-patterns.mdx | 2 +- .../cloud-agents/harnesses/authentication.mdx | 2 +- .../cloud-agents/harnesses/claude-code.mdx | 2 +- .../cloud-agents/harnesses/codex.mdx | 2 +- .../cloud-agents/harnesses/index.mdx | 2 +- .../docs/agent-platform/cloud-agents/overview.mdx | 4 ++-- .../agent-platform/cloud-agents/oz-web-app.mdx | 14 +++++++------- .../docs/agent-platform/cloud-agents/secrets.mdx | 6 +++--- .../team-access-billing-and-identity.mdx | 10 +++++----- 10 files changed, 25 insertions(+), 26 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx index 5fd5535c..29f1d839 100644 --- a/src/content/docs/agent-platform/cloud-agents/agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -49,13 +49,12 @@ When a team is over its plan limit (for example, after downgrading), the extra i ## Managing agent identities -You can create, list, update, and delete agent identities through the public API. The full request and response shapes — including error codes — live on the [API Reference](/api) page; the operations to look for are `createAgent`, `listAgents`, `getAgent`, `updateAgent`, and `deleteAgent` under the **agent** tag. +You can create, list, update, and delete agent identities through the public API. The full request and response shapes — including error codes — live on the [API Reference](/api) page; the operations to look for are `createAgent`, `listAgents`, `updateAgent`, and `deleteAgent` under the **agent** tag. The endpoints behave as follows: * **Create** - `POST /agent/identities` with a `name` and optional `description`, `secrets`, and `skills`. Returns `201` with the new identity's `uid`, `name`, and `available` flag. * **List** - `GET /agent/identities` returns every agent identity on the team, including the default. Each entry includes an `available` flag indicating whether it is within the plan limit. -* **Retrieve** - `GET /agent/identities/{uid}` returns a single identity by its UID. * **Update** - `PUT /agent/identities/{uid}` replaces individual fields. Omitting a field preserves the current value; passing an empty string or empty array clears it. * **Delete** - `DELETE /agent/identities/{uid}` soft-deletes the identity and atomically deletes every API key bound to it. The default agent identity cannot be deleted. @@ -71,7 +70,7 @@ A few constraints apply across every endpoint: A team API key can be bound to a specific agent identity at creation time. Calls authenticated with that key run as the chosen identity. The team is resolved automatically from the identity — you don't need to specify a team when generating the key. -To create a key bound to an agent identity, pass the identity's UID to the `generateApiKey` mutation. See [API Keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between user-scoped and team-scoped keys. +To create a key bound to an agent identity, choose the identity when creating the team API key. See [API Keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between user-scoped and team-scoped keys. Once the key exists, the CLI and SDK authenticate as that agent identity for every call. There is no extra flag to set; the binding is on the key itself. @@ -82,7 +81,7 @@ There are two ways to run a cloud agent as a specific agent identity: * **Authenticate with a key bound to the identity** - Every run started with that key executes as the bound agent identity. This is the typical path for CI pipelines and scheduled work. * **Pass `agent_identity_uid` on `POST /agent/runs`** - For one-off runs, send the agent identity's `uid` in the request body. The field is only valid for team-owned runs. -When neither path is used, runs execute under the default identity ("Quick run" in the web app). +When neither path is used, runs execute under the default identity. ## Where agent identities appear in the product 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 7d933f74..ecb3542d 100644 --- a/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx +++ b/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx @@ -22,7 +22,7 @@ Oz cloud agent setups usually have four moving parts: ### Pattern 1: CLI-only agents (bring your own orchestrator) -Use this when you already have a system that schedules work (CI, dev boxes, internal orchestrators), and you just need a reliable, cloud-connected agent runner. +Use this when you already have a system that schedules work (CI, dev boxes, internal orchestrators), and you need a reliable, cloud-connected agent runner. #### What it looks like 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 1da3d211..a16b1fc6 100644 --- a/src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx @@ -9,7 +9,7 @@ sidebar: 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. -Auth secrets can be scoped to a **team** (available to all teammates' runs) or **personal** (only your own runs), just like any other Warp-managed secret. +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. :::note [Bring Your Own Key (BYOK)](/support-and-community/plans-and-billing/bring-your-own-api-key/) configured in the Warp desktop app applies to local agent runs only. Cloud runs of Claude Code and Codex always use Warp-managed secrets. diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/claude-code.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/claude-code.mdx index ec8c85e4..c869e478 100644 --- a/src/content/docs/agent-platform/cloud-agents/harnesses/claude-code.mdx +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/claude-code.mdx @@ -36,7 +36,7 @@ Claude Code calls Anthropic directly using credentials your team provides. Oz su * **Anthropic Bedrock API key** - For Bedrock-routed inference using an API key. * **Anthropic Bedrock access key** - For Bedrock-routed inference using AWS access credentials. -Anthropic bills your account directly for inference. Warp credits cover the rest of the platform — environment compute, triggers, and observability. +Anthropic bills your account directly for inference. Warp still meters [compute credits](/support-and-community/plans-and-billing/credits/#compute-credits) for the run's sandbox and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the orchestration layer. For setup steps, see [Connecting Claude Code credentials](/agent-platform/cloud-agents/harnesses/authentication/#connecting-claude-code-credentials). diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/codex.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/codex.mdx index 968ef6f8..600ea9a0 100644 --- a/src/content/docs/agent-platform/cloud-agents/harnesses/codex.mdx +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/codex.mdx @@ -35,7 +35,7 @@ Codex calls OpenAI directly using credentials your team provides. Oz supports on * **OpenAI API key** - The Codex harness authenticates to OpenAI using this key for every run. -OpenAI bills your account directly for inference. Warp credits cover the rest of the platform — environment compute, triggers, and observability. +OpenAI bills your account directly for inference. Warp still meters [compute credits](/support-and-community/plans-and-billing/credits/#compute-credits) for the run's sandbox and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the orchestration layer. For setup steps, see [Connecting Codex credentials](/agent-platform/cloud-agents/harnesses/authentication/#connecting-codex-credentials). diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx index cb5ed552..91020cb4 100644 --- a/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx @@ -20,7 +20,7 @@ Third-party harnesses inherit the same Oz platform features as Warp Agent: ## Billing -Claude Code and Codex each call their provider directly using credentials you supply, and the provider bills your account for inference. Warp credits cover the orchestration platform — environment compute, triggers, and observability — but not third-party inference. +Claude Code and Codex each call their provider directly using credentials you supply, and the provider bills your account for inference. Warp meters [compute credits](/support-and-community/plans-and-billing/credits/#compute-credits) for the run's sandbox and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the orchestration layer. ## How to switch harnesses diff --git a/src/content/docs/agent-platform/cloud-agents/overview.mdx b/src/content/docs/agent-platform/cloud-agents/overview.mdx index 2bcc4a16..243f4119 100644 --- a/src/content/docs/agent-platform/cloud-agents/overview.mdx +++ b/src/content/docs/agent-platform/cloud-agents/overview.mdx @@ -113,7 +113,7 @@ Cloud agents and [integrations](/agent-platform/cloud-agents/integrations/) run [Bring Your Own Key (BYOK)](/support-and-community/plans-and-billing/bring-your-own-api-key/) is not supported for cloud agent runs. BYOK keys are stored locally on your device and are not accessible to cloud-hosted agents. All cloud agent runs consume Warp credits. ::: -#### For Cloud Agents via CLI/API +#### For cloud agents via CLI/API Individual users can run cloud agents without being on a team. Requirements: @@ -121,7 +121,7 @@ Individual users can run cloud agents without being on a team. Requirements: * Cloud agents run on Warp-hosted infrastructure * Self-hosted agents require a team subscription -#### For Integrations (Slack/Linear) +#### For integrations (Slack/Linear) Integrations require you to be part of a [Warp team](/knowledge-and-collaboration/teams/) and additional requirements: 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 99925717..1f1e4bd4 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 @@ -1,5 +1,5 @@ --- -title: Oz Web App for cloud agents +title: Oz web app for cloud agents description: >- Use the Oz web app to manage cloud agents, view runs, create schedules, and configure environments and integrations from any browser or mobile device. @@ -22,7 +22,7 @@ Watch this short demo to create an environment and run an agent using the Oz web
PagePathWhat you can do
Dashboard/dashboardQuick actions, suggested agents, recent agents, and featured reads
Runs/runsView all runs, filter by status/source/creator, start new runs, inspect transcripts
Agents/agentsBrowse skills from your environments, manage agent identities, dispatch skills as agents
Schedules/schedulesCreate scheduled agents, pause/enable schedules, view run history
Environments/environmentsCreate and manage environments with repos, Docker images, and setup commands
Secrets/secretsCreate and manage Warp-managed secrets for cloud agent runs
Integrations/integrationsConnect Slack and Linear to trigger agents from external tools
-![The Oz Web App's management view.](../../../../assets/agent-platform/oz-web-app-runs-view.png) +![The Oz web app's management view.](../../../../assets/agent-platform/oz-web-app-runs-view.png)
The Oz web app management view.
@@ -133,7 +133,7 @@ Each skill displays:
FieldDescription
NameThe skill's identifier
DescriptionWhat the skill does
EnvironmentsWhich environments have access to this skill
-![The Agents page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-agents.png) +![The Agents page in the Oz web app.](../../../../assets/agent-platform/oz-web-app-agents.png)
The Agents page in the Oz web app.
@@ -152,7 +152,7 @@ For more details on how skills work with cloud agents, see [Skills as Agents](/a Click **New skill** to create a new skill. The guided flow helps you define the skill's instructions, which are then available for future runs.
-![Creating a new agent skill in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-new-agent.png) +![Creating a new agent skill in the Oz web app.](../../../../assets/agent-platform/oz-web-app-new-agent.png)
Creating a new skill in the Oz web app.
@@ -197,7 +197,7 @@ Each schedule displays:
FieldDescription
NameA descriptive name for the scheduled task
FrequencyHuman-readable description of the cron schedule (e.g., "Every Monday at 10am")
Next runWhen the schedule will next execute
EnvironmentWhich environment the scheduled agent runs in
AgentWhich skill the schedule uses (if any)
StatusWhether the schedule is active or paused
-![The Schedules page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-schedules.png) +![The Schedules page in the Oz web app.](../../../../assets/agent-platform/oz-web-app-schedules.png)
The Schedules page in the Oz web app.
@@ -243,7 +243,7 @@ Each environment displays:
FieldDescription
NameThe environment's identifier
Docker imageThe container image used for execution
RepositoriesWhich repos the agent can access
Setup commandsCommands run before the agent starts
-![The Environments page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-environments.png) +![The Environments page in the Oz web app.](../../../../assets/agent-platform/oz-web-app-environments.png)
The Environments page in the Oz web app.
@@ -275,7 +275,7 @@ The **Integrations** page (`/integrations`) lets you configure first-party integ
IntegrationDescription
SlackTag @Oz in messages or threads to trigger agents directly from Slack conversations
LinearTag @Oz on issues to trigger agents from your issue tracker
-![The Integrations page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-integrations.png) +![The Integrations page in the Oz web app.](../../../../assets/agent-platform/oz-web-app-integrations.png)
The Integrations page in the Oz web app.
diff --git a/src/content/docs/agent-platform/cloud-agents/secrets.mdx b/src/content/docs/agent-platform/cloud-agents/secrets.mdx index e9180f30..28e5622d 100644 --- a/src/content/docs/agent-platform/cloud-agents/secrets.mdx +++ b/src/content/docs/agent-platform/cloud-agents/secrets.mdx @@ -30,7 +30,7 @@ Warp-managed secrets are designed to work across [cloud agent](/agent-platform/c Warp provides a set of CLI commands for creating, updating, and listing secrets. Secret values are stored securely and cannot be retrieved once created. -At runtime, **Warp sets the relevant secrets as environment variables** for each cloud agent run, based on who triggered the agent and how it was triggered. +At runtime, **Warp sets the relevant secrets as environment variables** for each cloud agent run, based on who triggered the agent and how it was triggered. :::note Secret values are available only to the agent process (and any subprocesses it spawns) during execution, and **can’t be viewed or retrieved afterward.** @@ -69,7 +69,7 @@ Because team secrets are broadly available and may be used by fully automated or This ensures credentials remain valid as team membership changes, permissions are tightly scoped, and ownership and rotation align with internal security policies. :::note -Team secrets can also be attached directly to an [agent identity](/agent-platform/cloud-agents/agents/), so only runs executing as that identity receive them. The secret itself still lives in the team's secret scope; the agent identity just references it by name. +Team secrets can also be attached directly to an [agent identity](/agent-platform/cloud-agents/agents/), so only runs executing as that identity receive them. The secret itself still lives in the team's secret scope; the agent identity only references it by name. ::: #### Personal secrets @@ -102,7 +102,7 @@ The new secret appears in the Secrets list immediately. Its value is never reada ## Managing agent secrets with the Oz CLI -Secrets are managed using the oz secret command family. +Secrets are managed using the `oz secret` command family. You can create secrets interactively or from a file. diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx index e9c1ab37..3d676612 100644 --- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx +++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx @@ -76,12 +76,12 @@ Integrations and [cloud agents](/agent-platform/cloud-agents/overview/) run insi Your team must meet the following requirements to run integrations: -* You must be on a plan that supports **[Reload Credits (Add-on Credits)](/support-and-community/plans-and-billing/add-on-credits/)**. +* You must be on a plan that supports **[Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/)**. * Supported: **Build, Max, Business** * Not supported: Pro, Turbo, Lightspeed, legacy Business. * Your team needs at least **20 credits** available to run cloud agents and integrations -When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits in a specific order. It starts with any [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) the user has, then moves to the user's base credits, followed by the team's Reload Credits, and finally the user's own Reload Credits. Enterprises may have different payment options and credit plans that affect this flow. If all applicable credit sources are exhausted, integrations and cloud agents will not work until credits are added. +When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits in a specific order. It starts with any [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) the user has, then moves to the user's base credits, followed by the team's Add-on Credits, and finally the user's own Add-on Credits. Enterprises may have different payment options and credit plans that affect this flow. If all applicable credit sources are exhausted, integrations and cloud agents will not work until credits are added. :::note If you're on an Enterprise plan, please reach out to [warp.dev/contact-sales](https://warp.dev/contact-sales) with any billing questions related to integrations. @@ -212,12 +212,12 @@ How credits are consumed depends on how the agent run is triggered and authentic **User-triggered runs** (CLI with personal API key, Slack, Linear, or the Warp app): * Runs are tied to the triggering user's identity -* Credits are consumed starting with any credit grants specifically allocated for cloud agent usage, then the user's base credits, followed by the team's Reload Credits, and finally the user's own Reload Credits +* Credits are consumed starting with any credit grants specifically allocated for cloud agent usage, then the user's base credits, followed by the team's Add-on Credits, and finally the user's own Add-on Credits **Team API key runs** (fully automated or headless workflows): * Runs are not tied to any individual user -* Only the team's Reload Credit pool is used—no individual base credits are available +* Only the team's Add-on Credit pool is used—no individual base credits are available * Ideal for CI/CD pipelines, scheduled tasks, and other automated workflows * For workflows that require code changes (opening pull requests, pushing branches, or writing to a repository), configure [team GitHub authorization](#team-github-authorization) so the agent can authenticate with the Oz by Warp GitHub App. Alternatively, use a [personal API key](/reference/cli/api-keys/) to authenticate as an individual user. @@ -236,7 +236,7 @@ All triggers and instructions used by cloud agents are defined and controlled by #### Staying aware of usage -Because triggers and instructions are configured by your team, any credits used when an agent runs are billed to your team's Reload Credit balance. +Because triggers and instructions are configured by your team, any credits used when an agent runs are billed to your team's Add-on Credit balance. * It’s the team’s responsibility to manage triggers, confirm they behave as intended, and monitor usage. * Reviewing triggers, prompts, and agent behavior periodically helps ensure that credit usage aligns with expectations. From 4f73acc8770c14fc8b7338c3afcbc7f37ecbe80b Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 18 May 2026 23:05:20 -0700 Subject: [PATCH 06/10] docs(agent-platform): add Agent Memory research-preview pages (#86) * docs(agent-platform): add Agent Memory research-preview pages Add overview, memory-stores, self-hosted-memory, and api pages under agent-platform/capabilities/agent-memory/. List the feature on the capabilities index and add a Suggested Skills from Agent Memory note to the skills page. The new pages are scoped to the agent-platform topic but are not yet wired into src/sidebar.ts; the cross-cutting sidebar PR will add the entries so the build resolves the topic association. Co-Authored-By: Oz * docs(agent-memory): scrub internals, downsize API page, tighten tone Address reviewer feedback and Slack-thread guidance on the Agent Memory research-preview pages. - Overview: narrow the API capability bullet to user-owned store creation (team-owned creation is in the Warp app only), drop the 'harness-support endpoint' internal reference, drop the service-account-granted-stores phrasing, trim the data flywheel section, and tighten the frontmatter description to fit the 50-160 char SEO range. - Memory stores: tighter description, generalize API references away from raw HTTP method/path callouts, drop schema field name leaks ('memory_stores' as wire field) in favor of conceptual prose, polish tone. - Self-hosted memory: present as forward-looking direction for the research preview, drop the specific Postgres/Turbopuffer/ Voyage AI vendor stack from the reference adapter section in favor of abstract relational + vector + embedding language. - API: downsize to a research-preview stub. Drop endpoint paths, request/response schemas, and HTTP method signatures. Keep authentication, capability surface at category level, attachment behavior rules, validation error patterns, and the design-partner contact path. - Skills: tighten Suggested Skills from Agent Memory section to honest, forward-looking direction-of-travel wording. - Capabilities overview: tighten the Agent Memory entry copy. Co-Authored-By: Oz * docs(agent-memory): drop remaining internal-implementation details Second pass of trimming on the Agent Memory research-preview pages, following the same direction as 1564a8d. - index.mdx: collapse the two-stage extraction/planning description of consolidation into a single user-facing paragraph; drop the internal facts/learnings/outcomes taxonomy; drop the reranker mention from the retrieval bullet; tighten the matching key-features and research-preview bullets for consistency. - memory-stores.mdx: remove the wire-format Update semantics section (omit / empty / non-empty) and link out to the API page instead; replace the dependency-order permanent-deletion sentence with a single user-facing line; drop the 409 Conflict HTTP status code while keeping the rule and remediation. - self-hosted-memory.mdx: replace the named interface-method list with a one-paragraph capability summary; drop the embedding-pipeline phrasing on both the in-scope and reference-adapter sections; drop the extraction/planning two-stage framing. - api.mdx: rename 'Validation errors' to 'Common rejection reasons' and drop the 400 invalid_request / 409 Conflict codes while keeping the rejection reasons; soften the wire-format mention for the identity-attachment endpoint. Co-Authored-By: Oz * docs(agent-memory): use canonical "agent identity" terminology Replace "named agent identity/identities" (and shorthand "named identity" forms) with "agent identity/identities" throughout the Agent Memory pages to align with the docs-wide canonical term. Co-Authored-By: Oz * docs(agent-memory): consolidate research-preview docs into a single page Replace the four-page Agent Memory subsection with a single research-preview overview page. The deleted pages (memory-stores, self-hosted-memory, api) were never published and overcommitted on behavior that's still in design. - Rewrite agent-memory/index.mdx as a tight overview: research-preview callout with waitlist CTA, what's available today, what's not yet available, how to get involved, related pages. - Tighten the "Suggested Skills from Agent Memory" subsection on skills.mdx to a single forward-looking paragraph without procedural claims. Co-Authored-By: Oz * docs(agent-memory): audit polish pass on the consolidated research-preview page Editorial copy pass on top of 2ea77ff. No structural or scope changes; no new claims, no new links. agent-memory/index.mdx: - Drop slight anthropomorphism in opener ("no recollection" -> "without context"). - Replace "verbose transcript dump" with neutral "the full conversation transcript." - Reorder the personal-memory bullet so the actor (Oz) leads and the harness clause doesn't bury the punchline. - Fix awkward SVO order on self-hosted bullet. - Replace vague "focused on the personal store" with precise "only reads from the personal store." - Tighten the two related-pages descriptions. skills.mdx: - Tighten the Suggested Skills from Agent Memory paragraph: drop the doubled "Agent Memory" reference, replace "is being explored" with "is in design," and remove the awkward "no concrete behavior" hedge. Validation: - style_lint --changed: one known false positive on the Suggested Skills header (Skills and Agent Memory are proper feature names per AGENTS.md). - check_links --internal-only: 0 broken links across 318 files and 2391 links. Co-Authored-By: Oz * docs(agent-memory): rewrite as unified SEO/waitlist page Drops the "What's available today" / "What's not yet available" split in favor of a single capability narrative. The page is now a marketing-pitched, SEO-oriented overview that walks a prospective user through the value of Agent Memory and pushes toward the waitlist three times (top caution, hero closer, dedicated Get early access section). Structural changes: - Tightened frontmatter description (132 chars, in SEO range) leading with the primary keyword "agent memory" and the value proposition. - Hero is now two short paragraphs that motivate the problem (cold runs) and introduce the product, ending with a request-early-access link. - Five keyword-rich H2 sections describe the capability surface in one unified narrative: Persistent memory across runs, Cross-harness retrieval, Automatic consolidation, Personal and team memory stores, Self-hosted memory backends. No shipped-vs-roadmap hedging in the body; the research-preview caution at the top covers "behavior may change." - New "What Agent Memory unlocks" section with three use-case vignettes (debugging that resumes; repeated maintenance agents that learn the codebase; team-shared knowledge) that give prospects concrete reasons to want it and add SEO surface area. - New "Get early access" section replaces the old "How to get involved." - Switched the Agent identities related-pages link from the absolute docs.warp.dev URL to a relative path, now that PR #88 has merged into the gating branch and been forward-merged into this branch. Validation: - style_lint --changed: 0 new issues on the rewritten page (the existing known false positive on skills.mdx:414 Suggested Skills header is untouched). - check_links --internal-only: 0 broken links across 319 files and 2,421 internal links. Co-Authored-By: Oz * docs(agent-memory): polish hero opener for clarity Drop the self-referential "by default" qualifier (the non-default mode it implied is Agent Memory itself, making the phrase quietly circular). Make the cold-start problem more concrete by spelling out that prior runs' learnings are lost \u2014 strengthens the value framing the page is trying to build for the waitlist CTA. Co-Authored-By: Oz * docs(agent-memory): consolidate PR #95 content, move to top-level Memory section Major restructure of the Agent Memory docs to address user feedback: 1. Promote Agent Memory to its own top-level section in the sidebar. New 'Memory (Research Preview)' group sits inside the Agents topic between Getting started and Warp Agents for top-of-list visibility. 2. Move the page from agent-platform/capabilities/agent-memory/ to agent-platform/agent-memory/ to match the new section's IA. The '/agent-platform/capabilities/agent-memory' URL now redirects to '/agent-platform/agent-memory/' via vercel.json. 3. Add '(Research Preview)' marker to the sidebar label, matching the page title and the existing Settings Sync (Beta) precedent. 4. Replace 'workspace' with 'team' in user-facing copy. The implementation-layer WORKSPACE enum is internal and unaffected. 5. Consolidate PR #95 (hyc/memory-waitlist) content into the page. PR #95 had been opened separately as a marketing/waitlist rewrite from another conversation. Taking its richer body (8 capability bullets, dedicated sections for Personal/team stores, Automatic memory from conversations with Sparse/Reasoned/Reversible sub-bullets, How agents retrieve memories with the Vector+BM25+Reranking pipeline, Attaching memory to agents covering identity-level and run-level attachments, and Built for teams), stronger CTAs (bold-link waitlist CTA after hero + 'Ready to give your agents memory?' closer), and richer 5-link related pages. Restores the research-preview caution callout that PR #95 had dropped, keeps the (Research Preview) title, and uses 'team' throughout. PR #95 will be closed in a follow-up. 6. Use generic 'agents' / 'your agents' / 'Warp agents' framing throughout. Memory is gated to cloud agents today but will work for local agents going forward, so the docs don't specify cloud vs local. The research-preview caution carries any 'behavior may change before GA' hedge. 7. Capability claims (deletion safety, per-store instructions, versioned history, hybrid semantic+keyword search) all match the QUALITY-585 and QUALITY-536 specs. Files touched: - src/content/docs/agent-platform/agent-memory/index.mdx (new) - src/content/docs/agent-platform/capabilities/agent-memory/index.mdx (deleted) - src/content/docs/agent-platform/capabilities/index.mdx (Agent Memory bullet removed) - src/content/docs/agent-platform/capabilities/skills.mdx (link URL updated) - src/sidebar.ts (new Memory group) - vercel.json (old URL redirect) Validation: - style_lint --changed: only the known pre-existing false positive on skills.mdx:414 Suggested Skills from Agent Memory header (both 'Skills' and 'Agent Memory' are proper feature names per AGENTS.md). - check_links --internal-only: 0 broken across 319 files and 2,422 internal links. New URL resolves cleanly. Co-Authored-By: Oz * docs(agent-memory): address Suraj's review feedback - Drop vector/keyword search and versioned history bullets; remove the 'recorded reason for every change' / 'Reasoned' bullet so the page stays high level for waitlist-phase customers (Slack feedback + pending inline comment). - Replace 'Warp agents' wording and explicitly call out cross-harness support (Warp Agent, Claude Code, Codex, Gemini) in the description and intro paragraph (pending inline comments on multi-harness and 'Warp agents'). - Reframe automatic-memory and bullets section around 'learning over time' instead of one-shot extraction (pending inline comment). - Rename 'Personal and team memory stores' to 'Memory stores', explain per-agent scoping with cross-agent sharing, and add the code-review + Sentry triage repo-store example (pending inline comment). - Replace 'runs a memory synthesis pass that extracts' with 'extracts' (pending inline comment). - Slim 'How agents retrieve memories' to 'How agents use memory' and note that agents can retrieve memories on demand throughout a conversation when they decide it's the right thing to do (pending inline comment + Slack 'how' removal). - Collapse 'Attaching memory to your agents' to one paragraph and remove the redundant 'Built for teams' section to keep the page scannable and 'what/why'-focused. Co-Authored-By: Oz * docs(agent-memory): lead with async + Oz-as-the-layer framing Follow-up to Suraj's feedback on PR #86. Verbiage inspiration from the Claude Managed Agents memory post. - Frontmatter description and hero paragraph now lead with the value prop ('Your agents should learn across every conversation, every harness, every run') instead of a descriptive opener, and explicitly position Warp as the platform the customer already uses to run their agents. - Hero paragraph + a new 'Async by design' bullet + a new sentence in each of 'Automatic memory from conversations' and 'How agents use memory' make it clear that memory creation and retrieval happen in the background. Agents never burn tokens or attention on memory work during a run. - 'Cross-harness persistence' is promoted to the first 'What you get' bullet and reframed as 'One memory layer for every agent in Warp'. Dropped the now-redundant 'Durable knowledge across conversations' bullet (the intro already says it). - New 'Built on the layer your agents already live on' subsection drives the Oz-as-the-layer pitch home: Warp Agent locally, Oz cloud agents in the background, and Claude Code/Codex/Gemini all go through the same platform, so memory is a free byproduct rather than new infrastructure. - Final CTA sharpened to 'Your agents already live on Warp. Give them a memory that lives there too.' Co-Authored-By: Oz * docs(agent-memory): polish pass - Trimmed frontmatter description so it fits the ~50-160 char target and reads as a standalone summary. - Split the long hero paragraph into shorter sentences so each beat (value prop, harness list, no infra, async, each run) lands on its own. Fixed the 'memory ... memory' repetition by referring to creation and retrieval with 'they'. - Reworded the 'Built on the layer your agents already live on' paragraph: opens with 'Warp is already the platform where your agents run', drops the dangling 'through the same platform' clause, and avoids the 'layer ... layer too' echo by saying 'Agent Memory turns that same platform into a memory layer'. - Used 'Memory creation' (instead of 'Synthesis') in the 'Automatic memory from conversations' paragraph so the async terminology matches the 'Async by design' bullet. - Switched the 'Sparse by design' / 'Learns over time' mini-headlines to the bold-term + em-dash + explanation pattern used by the rest of the page. - Tightened the 'Per-agent access control and instructions' bullet. - Replaced the awkward 'watch what they learn today make them sharper tomorrow' construction in the final CTA with 'so what they learn today makes them sharper tomorrow'. Co-Authored-By: Oz * docs(agent-memory): de-marketing pass, dev-doc tone Strip marketing-style phrasing and rewrite the page in the descriptive, factual tone used by the rest of the agent-platform capability pages (skills.mdx, codebase-context.mdx, cloud-agents/overview.mdx). - Description and intro now lead with what Agent Memory is, not a rule-of-three pitch. Dropped 'Your agents should learn across every conversation, every harness, every run' and 'Agent Memory makes that real.' Replaced with: 'Agent Memory is a persistent memory layer that lives on Warp and is shared across every supported agent harness...' - Renamed 'What you get with Agent Memory' to 'Key features' (matches skills.mdx). - Renamed 'Built on the layer your agents already live on' to 'Where Agent Memory runs' and rewrote it as factual coverage info: storage + creation + retrieval are all hosted on Warp infrastructure, with an explicit bulleted list of the agent types covered (local Warp Agent, Oz cloud agents, third-party harnesses). - Tightened bullets to bold-term + em-dash + plain explanation pattern. Dropped 'draws from the same well of knowledge', 'any harness you reach for next', 'leaves your team a little smarter than the last', and 'Instructions matter: they're the difference between an agent that has memory and an agent that knows what to remember and when.' - Tightened the 'How agents use memory' paragraph and changed 'whenever they decide it's the right thing to do' to 'when they determine it's relevant' (preserves the intent of Suraj's earlier feedback without the colloquial phrasing). - Replaced the 'Ready to give your agents memory?' CTA with a plain 'Join the waitlist' section, and switched the in-body waitlist link from bold + arrow to a plain markdown link. All seven of Suraj's earlier pending comments are still addressed (multi-harness, harness-agnostic wording, learning over time, no 'reason' mentions, Memory stores rename + use case, 'Warp extracts', and on-demand mid-conversation retrieval). Co-Authored-By: Oz * docs(agent-memory): address all of Suraj's review comments Addresses every inline comment from szgupta on PR #86: - Comment 3263750377 (lines 5-6, description, 'cross-harness covers it'): dropped the trailing 'that learns over time' clause from the description. - Comment 3263750945 (line 14, 's/Warp/Oz'): the platform that hosts Agent Memory is Oz. Replaced Warp -> Oz in the intro and anywhere else the page used Warp as the platform noun ('Where Agent Memory runs', the Oz API bullet, 'Oz extracts...', 'Oz searches...'). Kept Warp where it means the product (Warp Agent harness name, Warp client, warp.dev URLs). - Comment 3263752096 (line 14 reply, 'Gemini isn't officially supported in Oz yet'): removed every Gemini mention from the page (description, intro, Cross-harness bullet, 'Where Agent Memory runs' bullet). - Comment 3263755700 (line 25, 'focus more on sharing'): replaced the 'Personal and team stores' Key features bullet with 'Agent-scoped, shareable stores' that leads with default agent-scoping and cross-agent sharing. The Memory stores section now also notes that stores can be shared 'across teammates when knowledge should travel with the team'. - Comment 3263756525 (line 27, 'seems irrelevant?'): dropped the Deletion safety Key features bullet entirely. - Comment 3263761292 (line 20, suggested 5 new bullets): added Both local and cloud agents, Fully accessible via API, Traceability, Auditability, and Self-hostable to Key features. - Comment 3263763038 (line 31, 'we should mention self-hosted'): the 'Where Agent Memory runs' section now says memory runs on the same Oz instance that hosts your agents - Warp-hosted Oz by default, or a customer-hosted Oz instance for teams that need to keep memory inside their own perimeter. Paired with the new Self-hostable bullet in Key features. - Comment 3263765714 (line 35, '3P harnesses are Oz-cloud-only for now'): scoped the third-party harnesses bullet to 'Third-party harnesses running as Oz cloud agents' and added an explicit '(Running third-party harnesses locally isn't supported during the research preview.)' qualifier. Same scope is mirrored in the Cross-harness Key features bullet. - Comment 3263767235 (lines 52-53, replace Sparse/Learns with 'evolves+resolves contradictions'): replaced the two bullets with a single 'Memories evolve over time' bullet that says agents update and supersede their own memories as new information arrives, including to resolve contradictions with prior memories. Co-Authored-By: Oz * docs(agent-memory): polish pass after review-comment rewrite - Intro: separated the 'regardless of which harness' clause with an em-dash so the second sentence parses more cleanly. - 'Both local and cloud agents' bullet: 'Works for' -> 'Supports' for a slightly more formal verb. - Memory stores intro: replaced the em-dash construction with a comma so the two sharing scopes (across agents, across teammates) read as a single list, and tightened 'named container of memories' to 'named collection of memories'. - Attaching memory paragraph: 'free-form instruction string' -> 'per-store instructions', matching the terminology already used in the Key features bullet. No factual changes. Co-Authored-By: Oz * docs(agent-memory): make self-hosted explicit + small polish - 'Where Agent Memory runs' now calls out self-hosting by name: 'either Warp-hosted Oz (the default) or a self-hosted Oz instance that your team operates inside its own perimeter', replacing the previous 'customer-hosted Oz instance' phrasing. - 'Automatic memory from conversations': 'from what happened' -> 'from the transcript'; 'during the run that produced it' -> 'during that run'. - 'Attaching memory to your agents': 'Each attachment carries per-store instructions' -> 'Each attachment includes per-store instructions'; cleaned up the 'Without instructions' sentence to 'the agent can access the store but won't know when to read from or write to it'. Co-Authored-By: Oz * docs(agent-memory): cross-link self-hosting + Oz API, tighten store bullet The page mentions self-hosting and the Oz API prominently in Key features and 'Where Agent Memory runs', but those concepts weren't linked to the dedicated reference pages. Add the links so readers can follow up: - Inline-link 'Oz API' in the 'Fully accessible via API' bullet to /reference/api-and-sdk/. - Inline-link 'self-hosted Oz' in both the 'Self-hostable' bullet and the 'Where Agent Memory runs' paragraph to /agent-platform/cloud-agents/self-hosting/. - Inline-link 'Rules' and 'Codebase Context' in 'How agents use memory' (and capitalize 'rules' to match the feature name). - Add 'Self-hosting overview' and 'Oz API and SDK' to Related pages. Also tightened the 'Agent-scoped, shareable stores' bullet so its sharing phrasing varies slightly from the near-identical sentence in the Memory stores section ('shared across multiple agents, or across an entire team, when the same knowledge should travel with the work'). Co-Authored-By: Oz * docs(agent-memory): final scan nits - 'Attaching memory': 'Each attachment includes per-store instructions' -> 'Each attachment can include per-store instructions'. Removes a small logical contradiction with the very next sentence, which treats instructions as optional ('Without instructions, the agent can access the store but won't know when to read from or write to it.'). - 'Team stores' bullet: replaced the coined adjective 'any team-authorized agent' with 'any agent the team authorizes', matching the active-voice phrasing used elsewhere on the page. Co-Authored-By: Oz --------- Co-authored-by: Oz --- .../agent-platform/agent-memory/index.mdx | 79 +++++++++++++++++++ .../agent-platform/capabilities/skills.mdx | 4 + src/sidebar.ts | 6 ++ vercel.json | 5 ++ 4 files changed, 94 insertions(+) create mode 100644 src/content/docs/agent-platform/agent-memory/index.mdx diff --git a/src/content/docs/agent-platform/agent-memory/index.mdx b/src/content/docs/agent-platform/agent-memory/index.mdx new file mode 100644 index 00000000..f9b5b82c --- /dev/null +++ b/src/content/docs/agent-platform/agent-memory/index.mdx @@ -0,0 +1,79 @@ +--- +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. +sidebar: + label: "Agent Memory (Research Preview)" +--- +:::caution +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. + +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) + +## 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 Oz cloud agents. +* **Both local and cloud agents** — Supports interactive local agents in Warp and background Oz 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. + +## 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: + +* The local Warp Agent. +* Oz cloud agents triggered from the CLI, web app, schedules, or integrations. +* Third-party harnesses running as Oz 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. + +* **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. + +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. + +## Automatic memory from conversations + +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. + +You can also explicitly ask an agent to remember something during a conversation, and it lands in the appropriate store. + +## How agents use memory + +When an agent starts a task, Oz searches the stores the agent can access for relevant memories and injects them as context. The search runs in the background, so the agent only sees the memories returned. Agents can also retrieve additional memories on demand mid-conversation when they determine it's relevant, similar to how they consult [Rules](/agent-platform/capabilities/rules/) or [Codebase Context](/agent-platform/capabilities/codebase-context/). You don't need to write retrieval queries or pre-load memory. + +## 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. + +## Join the waitlist + +Agent Memory is rolling out to design partner teams during research preview. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access. + +## 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. diff --git a/src/content/docs/agent-platform/capabilities/skills.mdx b/src/content/docs/agent-platform/capabilities/skills.mdx index 6dbc30e9..df26afdf 100644 --- a/src/content/docs/agent-platform/capabilities/skills.mdx +++ b/src/content/docs/agent-platform/capabilities/skills.mdx @@ -411,6 +411,10 @@ Warp maintains a public collection of ready-to-use skills in the [warpdotdev/oz- These same skills also appear as suggested agents in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/), where you can run them directly in the cloud. +## 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. + ## Invoking skills with a prompt You can pass additional context or instructions to a skill when invoking it with a slash command. diff --git a/src/sidebar.ts b/src/sidebar.ts index 39a2aa9d..cdfb7ba6 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -246,6 +246,12 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ 'agent-platform/getting-started/faqs', ], }, + { + label: 'Memory (Research Preview)', + items: [ + { slug: 'agent-platform/agent-memory', label: 'Agent Memory' }, + ], + }, { label: 'Warp Agents', items: [ diff --git a/vercel.json b/vercel.json index a2df40b6..830d8d81 100644 --- a/vercel.json +++ b/vercel.json @@ -9572,6 +9572,11 @@ "source": "/oz", "destination": "/agent-platform/cloud-agents/overview/", "statusCode": 308 + }, + { + "source": "/agent-platform/capabilities/agent-memory", + "destination": "/agent-platform/agent-memory/", + "statusCode": 308 } ] } From b6ff96517489b89d5521c85f03157cb69ab559a4 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 18 May 2026 23:07:14 -0700 Subject: [PATCH 07/10] =?UTF-8?q?docs(handoff):=20add=20local=E2=86=94clou?= =?UTF-8?q?d=20handoff=20documentation=20(#85)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 * 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 * 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 * docs(handoff): trim overview description to fit 50-160 char range Co-Authored-By: Oz * 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 * 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 * 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 * 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 * 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 * 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 * 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 --------- Co-authored-by: Oz Co-authored-by: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> --- .../cloud-agents/handoff/cloud-to-cloud.mdx | 66 ++++++++++++++++++ .../cloud-agents/handoff/index.mdx | 52 ++++++++++++++ .../cloud-agents/handoff/local-to-cloud.mdx | 67 +++++++++++++++++++ src/sidebar.ts | 9 +++ 4 files changed, 194 insertions(+) create mode 100644 src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx create mode 100644 src/content/docs/agent-platform/cloud-agents/handoff/index.mdx create mode 100644 src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx 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 new file mode 100644 index 00000000..157138b8 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -0,0 +1,66 @@ +--- +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. +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. + +Use this handoff direction when: + +* You want to send a follow-up to a cloud agent after its session has ended. +* You want to continue a background cloud agent run, such as a scheduled or integration-triggered run, while preserving it as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). + +## What carries over + +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. +* **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. + +## 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. +* **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 +Cloud-to-cloud handoff relies on a snapshot from the prior session. Older cloud runs that don't have a snapshot on file can't be handed off; start a new run instead. +::: + +## 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. + +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. +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. + +## 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. + +## 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 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. + +## Related pages + +* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the directions it supports, and what carries over. +* [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/) - Promote a local conversation to a cloud run. +* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Find runs to send follow-ups to. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx new file mode 100644 index 00000000..c343763f --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx @@ -0,0 +1,52 @@ +--- +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. +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. + +## Directions of handoff + +Handoff supports three directions: + +* **Local to cloud** - Promote a local Warp Agent conversation to a cloud agent run when you need more compute, longer-running work, or parallel variants of the same task. The cloud agent starts from your conversation history and a snapshot of your uncommitted workspace changes. See [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/). +* **Cloud to cloud** - Send a follow-up to a cloud run after its session has ended. The run continues in the same conversation, with the prior session's workspace state restored. See [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/). +* **Cloud to local** - Fork a cloud conversation into a local Warp session with **Continue locally** or `/continue-locally`. See [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/#5-fork-the-session-to-your-local-warp). + +### Third-party agent runtime coverage + +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. + +## What carries over + +Handoff preserves enough state that the receiving agent can resume the work, not just read about it. + +* **Conversation history** - The receiving agent sees the full transcript of the prior session. Local-to-cloud forks the conversation so the source isn't modified; cloud-to-cloud continues in the same conversation. +* **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. + +## When to use handoff + +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. +* **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](/agent-platform/cloud-agents/overview/) - What cloud agents are, when to use them, and how they fit into the Oz Platform. +* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Inspect handoff runs from the management view alongside local conversations. +* [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) - Open and continue a cloud run locally with **Continue locally** or `/continue-locally`. +* [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) - How conversations sync between local and cloud so handoff can find them. +* [Environments](/agent-platform/cloud-agents/environments/) - The runtime context a cloud agent runs in after a 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 new file mode 100644 index 00000000..76c636f7 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx @@ -0,0 +1,67 @@ +--- +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. +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. + +Use this handoff direction when: + +* You have a long-running task and don't want to keep your laptop awake. +* You want to fan out variants of the same task across multiple cloud agents in parallel. +* You want to walk away and check on the agent from a different device. +* You want the agent to keep working while you start a new conversation locally. + +## What the cloud agent receives + +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. +* **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. + +## 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. +* **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. + +## Handing off a conversation to the cloud + +1. **Open the handoff flow from your active conversation.** With the local conversation focused, press `&` or run the `/handoff` slash command. Either entry point opens the handoff flow scoped to the current conversation. The `/cloud-agent` slash command always starts a fresh cloud conversation and isn't an entry point for handoff. +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. + +:::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. + +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. + +## Troubleshooting + +**The cloud agent reports that some changes couldn't be applied.** +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. + +**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. + +## Related pages + +* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the directions it supports, and what carries over. +* [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/) - Continue a finished cloud run with workspace state restored. +* [Environments](/agent-platform/cloud-agents/environments/) - Configure the repos, image, and setup commands the cloud agent starts in. +* [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/) - Run your first cloud agent from scratch. diff --git a/src/sidebar.ts b/src/sidebar.ts index cdfb7ba6..523d2b68 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -361,6 +361,15 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'agent-platform/cloud-agents/oz-web-app', label: 'Oz web app' }, { slug: 'agent-platform/cloud-agents/skills-as-agents', label: 'Skills as agents' }, { slug: 'agent-platform/cloud-agents/viewing-cloud-agent-runs', label: 'Viewing cloud agent runs' }, + { + label: 'Handoff', + collapsed: true, + items: [ + { slug: 'agent-platform/cloud-agents/handoff', label: 'Overview' }, + { slug: 'agent-platform/cloud-agents/handoff/local-to-cloud', label: 'Local to cloud' }, + { slug: 'agent-platform/cloud-agents/handoff/cloud-to-cloud', label: 'Cloud to cloud' }, + ], + }, 'agent-platform/cloud-agents/secrets', { label: 'Harnesses', From d1c35963f499c1777ce2e6c4cf16ccceab61dbc5 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Mon, 18 May 2026 23:28:04 -0700 Subject: [PATCH 08/10] Audit pass 3: Memory + Handoff polish, cross-references, glossary entries (#101) * Audit pass 3: Memory + Handoff polish, cross-references, glossary entries Final audit pass over hyc/orchestration-launch ahead of the rollout PR. Covers the deltas from #86 (Agent Memory research preview) and #85 (local\u2194cloud handoff) that landed after audit pass 2. Sentence case / Title Case: - capabilities/skills.mdx:414: '## Suggested Skills from Agent Memory' -> '## Suggested skills from Agent Memory'. The section body uses lowercase 'skill drafts', so the heading should match. Also clears the one new style_lint warning introduced by #86. Stale config: - agent-platform/agent-memory/index.mdx: drop '(Research Preview)' from the frontmatter sidebar.label. sidebar.ts already overrides the label to 'Agent Memory' under a group named 'Memory (Research Preview)'; the duplicate annotation was dead config. Cross-link gaps from neighboring pages: - cloud-agents/viewing-cloud-agent-runs.mdx (the '5. Fork the session to your local Warp' section): add a one-line reference to the new Handoff overview, so the cloud-to-local direction is discoverable from the broader handoff doc. - cloud-agents/managing-cloud-agents.mdx: add a Related pages section that links to the Handoff overview and the other neighbors that weren't surfaced before. - local-agents/cloud-conversations.mdx (Related features): add a link to the Handoff overview, since handoff relies on cloud-synced conversations. Style: - cloud-agents/handoff/index.mdx:30: drop 'just' from 'not just read about it' -> 'not only read about it'. Same ableist-language pattern audit pass 2 cleaned up elsewhere. Glossary additions: - .agents/references/terminology.md (Agent concepts) + AGENTS.md (Core features): add canonical entries for 'Agent Memory', 'memory store', and 'Handoff' so the launch terms ship with documented capitalization rules ('Agent Memory' Title Case as a feature; 'memory store' lowercase common noun; 'Handoff' Title Case as the feature, lowercase 'hand off' / 'handed off' as the verb). Validation: - check_links --internal-only: 0 broken across 2,543 internal links (up 6 from the 2,537 baseline, matching the 6 new cross-refs). - style_lint --changed: 14 warnings (one fewer than baseline; the skills.mdx Title Case heading is no longer flagged). The remaining warnings are all pre-existing proper-name false positives. - npm run build: 330 pages built; sidebar still resolves all slugs; new anchor reference (#5-fork-the-session-to-your-local-warp) resolves. Co-Authored-By: Oz * Restore (Research Preview) suffix in agent-memory sidebar.label Revert the sidebar.label change from the audit pass. Keeping the research-preview annotation in the frontmatter as a defensive fallback in case the sidebar.ts override is ever removed. Co-Authored-By: Oz --------- Co-authored-by: Oz --- .agents/references/terminology.md | 9 +++++++++ AGENTS.md | 2 ++ src/content/docs/agent-platform/capabilities/skills.mdx | 2 +- .../docs/agent-platform/cloud-agents/handoff/index.mdx | 2 +- .../cloud-agents/managing-cloud-agents.mdx | 7 +++++++ .../cloud-agents/viewing-cloud-agent-runs.mdx | 2 ++ .../agent-platform/local-agents/cloud-conversations.mdx | 1 + 7 files changed, 23 insertions(+), 2 deletions(-) diff --git a/.agents/references/terminology.md b/.agents/references/terminology.md index 3fcce82d..184d7b53 100644 --- a/.agents/references/terminology.md +++ b/.agents/references/terminology.md @@ -93,6 +93,15 @@ For the summary of the most critical terms (core features, Oz terms, terms to av - **Slash Commands** — Built-in commands you run by typing `/` to trigger actions (or run saved prompts). +- **Agent Memory** — Oz's persistent, cross-harness memory layer that lets agents read and write durable knowledge across conversations, harnesses, and devices. Currently in research preview. + *Usage note:* Capitalize as a feature name. Lowercase "memory" only when describing the generic concept (e.g., "the memory layer"). + +- **memory store** — A named collection of memories owned by a user (personal) or team. Multiple agents can share a store, and per-agent attachments control read/write access. + *Usage note:* Lowercase common noun. Capitalize the first letter only at the start of a sentence or bullet. + +- **Handoff** — The feature for moving an agent's work between a local Warp session and the cloud, or continuing a finished cloud run. Supports local-to-cloud, cloud-to-cloud, and cloud-to-local directions. + *Usage note:* Capitalize as a feature name. Use lowercase "hand off" / "handed off" only as a verb. + ## Coding terms (Warp features) - **Code** — Warp's coding experience for agent-assisted changes (editing, diffs, code review). diff --git a/AGENTS.md b/AGENTS.md index 9e74eb38..f957b6d1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -558,6 +558,8 @@ Product feature names retain their standard capitalization. Match the exact casi - **Codebase Context** - Warp indexes your Git-tracked codebase to help Agents understand your code. - **Admin Panel** - Team management surface for controlling members, roles, and billing. - **Agent Management Panel** - Interface for viewing and managing running agents (not "agent dashboard" or "agent manager"). +- **Agent Memory** - Persistent, cross-harness memory layer for Oz agents that captures durable facts, decisions, and outcomes across conversations (currently in research preview). Capitalize as a feature name; use lowercase "memory store" for individual stores. +- **Handoff** - Feature for moving agent work between a local Warp session and the cloud, or continuing a finished cloud run; supports local-to-cloud, cloud-to-cloud, and cloud-to-local. Capitalize as a feature name; lowercase "hand off" only as a verb. ### Oz terminology diff --git a/src/content/docs/agent-platform/capabilities/skills.mdx b/src/content/docs/agent-platform/capabilities/skills.mdx index df26afdf..4270b928 100644 --- a/src/content/docs/agent-platform/capabilities/skills.mdx +++ b/src/content/docs/agent-platform/capabilities/skills.mdx @@ -411,7 +411,7 @@ Warp maintains a public collection of ready-to-use skills in the [warpdotdev/oz- These same skills also appear as suggested agents in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/), where you can run them directly in the cloud. -## Suggested Skills from Agent Memory +## 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. 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 c343763f..584a4276 100644 --- a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx @@ -27,7 +27,7 @@ Handoff coverage depends on which agent is running the conversation: ## What carries over -Handoff preserves enough state that the receiving agent can resume the work, not just read about it. +Handoff preserves enough state that the receiving agent can resume the work, not only read about it. * **Conversation history** - The receiving agent sees the full transcript of the prior session. Local-to-cloud forks the conversation so the source isn't modified; cloud-to-cloud continues in the same conversation. * **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. 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 c5a96f1a..087b5d61 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 @@ -99,3 +99,10 @@ In both _Personal_ and _All_ views, you can open the filter menu and filter by: * Status This is the fastest way to isolate "everything that failed today," "runs from Slack," or "what a specific teammate triggered via integrations." + +## Related pages + +* [Cloud agents overview](/agent-platform/cloud-agents/overview/) — What cloud agents are and when to use them. +* [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/viewing-cloud-agent-runs.mdx b/src/content/docs/agent-platform/cloud-agents/viewing-cloud-agent-runs.mdx index 41698cb7..68af4ce6 100644 --- a/src/content/docs/agent-platform/cloud-agents/viewing-cloud-agent-runs.mdx +++ b/src/content/docs/agent-platform/cloud-agents/viewing-cloud-agent-runs.mdx @@ -71,6 +71,8 @@ If you still want to continue the conversation or work on the code, you can clic #### 5. Fork the session to your local Warp +Forking is the cloud-to-local direction of [Handoff between local and cloud agents](/agent-platform/cloud-agents/handoff/) — see that page for the other directions (local-to-cloud and cloud-to-cloud). + Forking brings the cloud agent conversation into your local machine, so you can pick up where the agent left off. Once forked: diff --git a/src/content/docs/agent-platform/local-agents/cloud-conversations.mdx b/src/content/docs/agent-platform/local-agents/cloud-conversations.mdx index 07a983b0..9e32fcdc 100644 --- a/src/content/docs/agent-platform/local-agents/cloud-conversations.mdx +++ b/src/content/docs/agent-platform/local-agents/cloud-conversations.mdx @@ -136,3 +136,4 @@ When you delete a conversation, it is removed permanently and immediately. Make * [Conversation Forking](/agent-platform/local-agents/interacting-with-agents/conversation-forking/) - Branch conversations to explore different directions. * [Session Sharing](/agent-platform/local-agents/session-sharing/) - Collaborate in real time on a live Agent session. * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) - Run agents in the cloud from triggers, schedules, or integrations. +* [Handoff between local and cloud agents](/agent-platform/cloud-agents/handoff/) - Promote a local conversation to a cloud agent run, or continue a finished cloud run. From 6b75e80d70fc0f347e19b453e50ae54a83297ece Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 19 May 2026 00:01:45 -0700 Subject: [PATCH 09/10] Merge main into hyc/orchestration-launch + address PR #98 / #102 review (#102) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Brings 121 files of main back into the orchestration-launch rollout branch, resolves two conflicts, reconciles terminology drift introduced on both sides, and addresses both rounds of Oz review feedback (#98 + #102). ## Conflict resolution * .agents/skills/style_lint/style_lint.py - PROPER_FEATURE_NAMES: combined main's 'Cloud Agents' rename (replacing 'Ambient Agents') with orchestration-launch's removal of 'Cloud Agent Credits' (split into 'compute credits' + 'cloud agent credits' as common nouns). * enterprise/.../billing.mdx: kept orchestration-launch's three-bucket framing but dropped the 'Oz ' prefix. ## Terminology drift fixups Aligned with main's new OZ_TERMS_TO_AVOID patterns: * agent-memory/index.mdx (4x), harnesses/index.mdx, cloud-agents/agents.mdx, platform-credits.mdx - 'Oz cloud agents' / 'Oz agent' → 'cloud agents' / 'agent' * deployment-patterns.mdx (2x) - wrapped 'oz agent run-cloud' CLI references in backticks * slack.mdx, federate.mdx - same drift fixups * agents-in-warp.mdx intro - 'Warp includes Oz agents' → 'Warp's agents' ## PR #98 review feedback * Remove Gemini reference from platform-credits.mdx * Resolve default-identity vs Quick run contradiction in cloud-agents/agents.mdx * Kept 'AI credits' in glossary (per user direction) * OpenAPI/Scalar sync deferred to a fast-follow PR ## PR #102 review feedback * IMPORTANT: agents-in-warp.mdx intro paragraph - deprecated 'Oz agents' terminology rewritten to 'Warp's agents' / 'They' * SUGGESTION: cloud-providers.mdx GCP federation caution - 'any agent' → 'any cloud agent' (scoped to OIDC-capable cloud agents) Validation: 0 broken links / 2539 internal, 14 baseline HEADER-CASE warnings only (plan-name false positives), 330 pages built. Co-Authored-By: Oz --- .agents/references/terminology.md | 49 ++-- .agents/rules/oz-style-guidelines.md | 38 +-- .agents/skills/answer_question/SKILL.md | 2 +- .../references/feature_surface_map.md | 2 +- .../missing_docs/references/stale_terms.md | 19 +- .agents/skills/style_lint/SKILL.md | 6 +- .agents/skills/style_lint/style_lint.py | 31 ++- .../references/error-page-template.md | 2 +- .agents/skills/validate_ui_refs/SKILL.md | 4 +- .agents/templates/faq.md | 2 +- .agents/templates/quickstart.md | 2 +- .agents/templates/troubleshooting.md | 2 +- .github/workflows/respond-to-comment.yml | 249 ------------------ .github/workflows/review-pr.yml | 196 -------------- AGENTS.md | 43 +-- README.md | 2 +- developers/agent-api-openapi.yaml | 4 +- package-lock.json | 30 ++- scripts/generate-og-api.mjs | 2 +- .../agent-platform/agent-memory/index.mdx | 8 +- .../capabilities/agent-notifications.mdx | 4 +- .../agent-profiles-permissions.mdx | 2 + .../capabilities/codebase-context.mdx | 2 +- .../capabilities/full-terminal-use.mdx | 2 +- .../agent-platform/capabilities/index.mdx | 4 +- .../capabilities/model-choice.mdx | 3 +- .../capabilities/slash-commands.mdx | 2 +- .../capabilities/task-lists.mdx | 4 +- .../agent-platform/cloud-agents/agents.mdx | 6 +- .../cloud-agents/deployment-patterns.mdx | 6 +- .../cloud-agents/environments.mdx | 2 +- .../docs/agent-platform/cloud-agents/faqs.mdx | 2 +- .../cloud-agents/harnesses/index.mdx | 2 +- .../integrations/azure-devops.mdx | 4 +- .../cloud-agents/integrations/bitbucket.mdx | 4 +- .../integrations/cloud-providers.mdx | 34 ++- .../integrations/demo-issue-triage-bot.mdx | 2 + .../integrations/github-actions.mdx | 10 +- .../cloud-agents/integrations/gitlab.mdx | 4 +- .../cloud-agents/integrations/linear.mdx | 2 +- .../quickstart-github-actions.mdx | 6 +- .../cloud-agents/integrations/quickstart.mdx | 6 +- .../cloud-agents/integrations/slack.mdx | 4 +- .../agent-platform/cloud-agents/overview.mdx | 4 +- .../cloud-agents/oz-web-app.mdx | 2 +- .../agent-platform/cloud-agents/platform.mdx | 6 +- .../cloud-agents/quickstart.mdx | 8 +- .../cloud-agents/self-hosting/index.mdx | 8 +- .../cloud-agents/self-hosting/quickstart.mdx | 2 +- .../self-hosting/security-and-networking.mdx | 2 +- .../cloud-agents/self-hosting/unmanaged.mdx | 4 +- .../team-access-billing-and-identity.mdx | 6 +- .../triggers/scheduled-agents-quickstart.mdx | 6 +- .../getting-started/agents-in-warp.mdx | 18 +- .../agent-platform/getting-started/faqs.mdx | 2 + src/content/docs/agent-platform/index.mdx | 8 +- .../agent-platform/local-agents/active-ai.mdx | 2 + .../agent-context/blocks-as-context.mdx | 2 + .../agent-context/images-as-context.mdx | 2 + .../agent-context/selection-as-context.mdx | 2 + .../agent-context/urls-as-context.mdx | 2 + .../agent-context/using-to-add-context.mdx | 2 + .../local-agents/code-diffs.mdx | 2 + .../agent-platform/local-agents/generate.mdx | 2 + .../interacting-with-agents/index.mdx | 2 + .../terminal-and-agent-modes.mdx | 14 +- .../local-agents/interactive-code-review.mdx | 2 + .../agent-platform/local-agents/overview.mdx | 4 +- .../local-agents/session-sharing.mdx | 2 +- src/content/docs/changelog/2026.mdx | 14 +- .../code-editor-vim-keybindings.mdx | 2 + .../docs/code/code-editor/file-tree.mdx | 2 + .../code/code-editor/find-and-replace.mdx | 2 + src/content/docs/code/code-review.mdx | 2 + src/content/docs/code/overview.mdx | 2 + .../architecture-and-deployment.mdx | 2 +- .../bring-your-own-llm.mdx | 4 +- .../getting-started-developers.mdx | 12 +- .../getting-started-enterprise.mdx | 4 +- .../enterprise/getting-started/quickstart.mdx | 22 +- src/content/docs/enterprise/index.mdx | 6 +- .../security-overview.mdx | 4 +- .../support-and-resources/billing.mdx | 6 +- .../team-management/admin-panel.mdx | 6 +- .../team-management/roles-and-permissions.mdx | 2 +- .../docs/getting-started/supported-shells.mdx | 2 + ...-self-serve-data-analytics-with-skills.mdx | 4 +- src/content/docs/index.mdx | 4 +- .../admin-panel.mdx | 2 + .../knowledge-and-collaboration/teams.mdx | 2 + .../warp-drive/agent-mode-context.mdx | 2 +- .../warp-drive/environment-variables.mdx | 2 + .../warp-drive/index.mdx | 2 + .../warp-drive/notebooks.mdx | 2 + .../warp-drive/prompts.mdx | 2 + .../warp-drive/web.mdx | 2 + .../warp-drive/workflows.mdx | 6 +- src/content/docs/quickstart.mdx | 4 +- .../demo-sentry-monitoring-with-sdk.mdx | 2 +- .../docs/reference/api-and-sdk/index.mdx | 6 +- .../docs/reference/cli/agent-profiles.mdx | 2 + src/content/docs/reference/cli/federate.mdx | 4 +- src/content/docs/reference/cli/index.mdx | 2 + .../docs/reference/cli/troubleshooting.mdx | 2 + src/content/docs/reference/cli/warp-drive.mdx | 2 + src/content/docs/reference/index.mdx | 4 +- .../community/open-source-partnership.mdx | 14 +- .../docs/support-and-community/index.mdx | 2 +- .../bring-your-own-api-key.mdx | 4 +- .../plans-and-billing/index.mdx | 2 +- .../plans-and-billing/platform-credits.mdx | 4 +- .../plans-and-billing/pricing-faqs.mdx | 2 +- .../known-issues.mdx | 2 +- .../using-warp-offline.mdx | 2 +- src/content/docs/terminal/blocks/index.mdx | 2 + src/content/docs/terminal/command-palette.mdx | 2 + src/content/docs/terminal/editor/index.mdx | 2 + .../docs/terminal/input/classic-input.mdx | 12 +- src/content/docs/terminal/sessions/index.mdx | 2 + .../docs/terminal/windows/vertical-tabs.mdx | 4 +- src/pages/api.astro | 20 +- 121 files changed, 417 insertions(+), 737 deletions(-) delete mode 100644 .github/workflows/respond-to-comment.yml delete mode 100644 .github/workflows/review-pr.yml diff --git a/.agents/references/terminology.md b/.agents/references/terminology.md index 184d7b53..17bf101a 100644 --- a/.agents/references/terminology.md +++ b/.agents/references/terminology.md @@ -69,8 +69,8 @@ For the summary of the most critical terms (core features, Oz terms, terms to av ## Agent concepts -- **Ambient Agents** — Oz agents that run automatically in the background on a schedule or trigger, without interactive input. - *Usage note:* Capitalize as a feature/section name. Use lowercase "ambient agents" only when describing the generic concept of agents running in the background. +- **Cloud Agents** — Agents that run in the cloud on a schedule, trigger, or integration, without interactive input. Managed by the Oz Platform. + *Usage note:* Use lowercase "cloud agents" in most contexts. Capitalize as "Cloud Agents" only when referring to the product section or feature name. - **Agent Profiles** — Saved configurations that define how an Agent runs (for example, permissions and model selection). *Usage note:* Use when describing "choose how your Agent behaves." @@ -130,33 +130,33 @@ For the summary of the most critical terms (core features, Oz terms, terms to av ## Oz terminology -### Oz vs Warp +### Warp Agent vs Oz -- **Warp** is the terminal and coding surface -- **Oz** is Warp's programmable agent for running and coordinating agents at scale +- **Warp Agent** — Warp's built-in agent harness. Use "Warp Agent" when specifically referring to the built-in harness, especially when contrasting with third-party agents (Claude Code, Codex, etc.), or when referencing the Settings label (**Settings** > **Agents** > **Warp Agent**). +- **Oz** — Warp's programmable platform for running and coordinating agents at scale - There is typically one Warp environment per user session. Oz can run many agents concurrently, across machines, repos, and teams. -### Core Oz terms +### Core terms -- **Environment** — The execution context for an Oz agent, including repo access, dependencies, secrets, compute, and runtime configuration. +- **agent** — A combination of agent instructions (skill or prompt), trigger (cron, webhook, manual), environment (local, cloud), profile, and host. Agents can be local or cloud. Use lowercase "agent" in most contexts; use "Warp Agent" only when referring specifically to the built-in Warp harness. + *Example:* Launch an agent from the CLI, the web app, an API or SDK, or directly inside Warp. -- **Oz** — Warp's programmable agent for running and coordinating agents at scale. - *Example:* With Oz, you can orchestrate multiple agents to automate and parallelize complex workflows. +- **cloud agent** — An agent running in the cloud, from a trigger, schedule, or started from someone's local machine. -- **Oz agent** — A combination of agent instructions (skill or prompt), trigger (cron, webhook, manual), environment (local, cloud), profile, and host. Agents can be local or cloud, and interactive or ambient. - *Example:* Launch an Oz agent from the CLI, the web app, an API or SDK, or directly inside Warp. +- **conversation** — An interactive execution lifecycle within the Warp Terminal, regardless of whether it's local or in the cloud. -- **Oz cloud agent** — An Oz agent running in the cloud, from a trigger, schedule, or started from someone's local machine. Cloud agents can be interactive or ambient. +- **Environment** — The execution context for an agent, including repo access, dependencies, secrets, compute, and runtime configuration. -- **Oz conversation** — An interactive execution lifecycle within the Warp Terminal. An Oz conversation is interactive, started in the terminal regardless of whether it's local or in the cloud. +- **Oz** — Warp's programmable platform for running and coordinating agents at scale. + *Example:* With Oz, you can orchestrate multiple agents to automate and parallelize complex workflows. - **Oz dashboard** — The app surface to manage all Oz runs, unified across the Warp app and web. -- **Oz run** — A single execution lifecycle of an Oz agent, including actions, outputs, and logs. An Oz run is always ambient and cloud-based. +- **Oz run** — A single execution lifecycle of an agent, including actions, outputs, and logs. An Oz run is always cloud-based. -- **Oz subagent** — A child Oz agent created by a parent Oz agent to parallelize or delegate work. +- **Oz web app** — The web app for configuring agents and managing runs. -- **Oz web app** — The web app for configuring Oz agents and managing runs. +- **subagent** — A child agent created by a parent agent to parallelize or delegate work. ### Oz CLI commands @@ -164,8 +164,8 @@ For the summary of the most critical terms (core features, Oz terms, terms to av - `oz agent run-cloud` — Run an adhoc cloud agent - `oz environment create/list/get/update/delete` — CRUD on environments - `oz integration create` — Install integrations (Slack, Linear) -- `oz run list/get` — Get info on ambient agent runs -- `oz schedule create/list/get/update/delete` — CRUD on scheduled ambient agents +- `oz run list/get` — Get info on cloud agent runs +- `oz schedule create/list/get/update/delete` — CRUD on scheduled cloud agents - `oz secret create/list/update/delete` — CRUD on Warp-managed secrets ### Preferred phrases @@ -176,11 +176,16 @@ For the summary of the most critical terms (core features, Oz terms, terms to av ### Terms to avoid -- ❌ "Ozzies" → Use "Oz agents", "instances", or "Oz subagents" -- ❌ "Deploying an Oz" → Use "Deploying an Oz agent" -- ❌ "The Oz Agent" → Use "An Oz agent" or "A parent Oz agent" -- ❌ "Oz is running" → Use "An Oz agent is running" or "A run is in progress" +- ❌ "Oz agent" / "Oz agents" → Use "agent" / "agents" (or "Warp Agent" / "Warp Agents" when referring to the built-in harness) +- ❌ "Oz cloud agent" → Use "cloud agent" +- ❌ "Oz subagent" → Use "subagent" +- ❌ "Oz conversation" → Use "conversation" +- ❌ "Ozzies" → Use "agents", "instances", or "subagents" +- ❌ "Deploying an Oz" → Use "Deploying an agent" +- ❌ "The Oz Agent" → Use "the agent" or "the Warp Agent" +- ❌ "Oz is running" → Use "An agent is running" or "A run is in progress" - ❌ "AI agents" → Use "agents" (the "AI" prefix is redundant) +- ❌ "Ambient Agents" / "ambient agents" → Use "Cloud Agents" / "cloud agents" ("ambient" is no longer a product term; acceptable only in code identifiers like `AmbientAgentConfig`) ## Platform terms diff --git a/.agents/rules/oz-style-guidelines.md b/.agents/rules/oz-style-guidelines.md index 561ab244..99675b24 100644 --- a/.agents/rules/oz-style-guidelines.md +++ b/.agents/rules/oz-style-guidelines.md @@ -34,46 +34,52 @@ When writing about Warp products or features, tie back to at least one of these ## Oz Terminology and Capitalization -### Core Oz Terms +### Core Terms - **Oz** - Warp's programmable platform for running and coordinating agents at scale -- **Oz agent** - A combination of agent instructions (skill or prompt), trigger (cron, webhook, manual), environment (local, cloud), profile, and host. Can be local or cloud, interactive or ambient -- **Oz cloud agent (general)** - An Oz agent running in the cloud, from a trigger, schedule, or started from someone's local machine -- **Oz subagent** - A child Oz agent created by a parent Oz agent to parallelize or delegate work -- **Oz run** - A single execution lifecycle of an Oz agent, including actions, outputs, and logs. Always ambient and cloud-based -- **Oz conversation** - An interactive execution lifecycle within Warp terminal, regardless of whether it's local or in the cloud -- **Environment** - The execution context for an Oz agent, including repo access, dependencies, secrets, compute, and runtime configuration +- **Warp Agent** - Warp's built-in agent harness. Use "Warp Agent" when specifically referring to the built-in harness, especially when contrasting with third-party agents (Claude Code, Codex, etc.) +- **agent** - A combination of agent instructions (skill or prompt), trigger (cron, webhook, manual), environment (local, cloud), profile, and host. Can be local or cloud. Use lowercase "agent" in most contexts. +- **cloud agent** - An agent running in the cloud, from a trigger, schedule, or started from someone's local machine +- **subagent** - A child agent created by a parent agent to parallelize or delegate work +- **Oz run** - A single execution lifecycle of an agent, including actions, outputs, and logs. Always cloud-based +- **conversation** - An interactive execution lifecycle within Warp terminal, regardless of whether it's local or in the cloud +- **Environment** - The execution context for an agent, including repo access, dependencies, secrets, compute, and runtime configuration - **Oz dashboard** - The app surface to manage all Oz runs, unified across the Warp app and web -- **Oz web app** - The web app for configuring Oz agents and managing runs +- **Oz web app** - The web app for configuring agents and managing runs ### Capitalization Rules **Cloud agents:** -- **Product** (capitalized): "Oz Cloud Agent" or "Oz Cloud Agents" when referring to Warp's specific product feature - - "Oz Cloud Agents send you session sharing links" - - "Launch an Oz Cloud Agent from the CLI" +- **Product** (capitalized): "Cloud Agent" or "Cloud Agents" when referring to Warp's specific product feature + - "Cloud Agents send you session sharing links" + - "Launch a Cloud Agent from the CLI" - **Concept** (lowercase): "cloud agent" or "cloud agents" when referring to the general concept - "Running cloud agents lets you escape the limits of your local machine" - "The cloud agent architecture enables scalability" **Other terms:** - Use "agents" not "AI agents" (redundant) +- Use "agent" not "Oz agent" (deprecated); use "Warp Agent" only when referring to the built-in harness - "Skills" not "skills" (capitalized) - "AGENTS.md" not "agents.md" (all caps) ### Terms to Avoid ❌ **Don't use:** -- "Ozzies" → Use "Oz agents", "instances", or "Oz subagents" -- "Deploying an Oz" → Use "Deploying an Oz agent" -- "The Oz Agent" → Use "An Oz agent" or "A parent Oz agent" -- "Oz is running" → Use "An Oz agent is running" or "A run is in progress" +- "Oz agent" / "Oz agents" → Use "agent" / "agents" (or "Warp Agent" / "Warp Agents" when referring to the built-in harness) +- "Oz cloud agent" → Use "cloud agent" +- "Oz subagent" → Use "subagent" +- "Oz conversation" → Use "conversation" +- "Ozzies" → Use "agents", "instances", or "subagents" +- "Deploying an Oz" → Use "Deploying an agent" +- "The Oz Agent" → Use "the agent" or "the Warp Agent" +- "Oz is running" → Use "An agent is running" or "A run is in progress" - "AI agents" → Use "agents" - "Warp's terminal" → Use "Warp" or "Warp terminal" ### Important Context About Oz -**All agents in Warp are Oz agents**, whether they are running in the cloud or running locally. +Oz is Warp's programmable platform for running and coordinating agents at scale, whether they are running in the cloud or running locally. Oz exists to take agent workflows beyond a single prompt or a single laptop, making them scalable, autonomous, collaborative, and auditable. diff --git a/.agents/skills/answer_question/SKILL.md b/.agents/skills/answer_question/SKILL.md index 1029e017..e7a17577 100644 --- a/.agents/skills/answer_question/SKILL.md +++ b/.agents/skills/answer_question/SKILL.md @@ -49,7 +49,7 @@ Both repos are indexed for `codebase_semantic_search`. Use `grep` for exact symb - Be direct and matter-of-fact. Answer the question, don't summarize the docs. - Be comprehensive — cover what the user needs to fully understand the answer — but don't pad with tangential information. -- Use Warp's standard terminology from `AGENTS.md` and the full glossary in `.warp/references/terminology.md`. Key rules: capitalize feature names (Agent, Agent Mode, Warp Drive, Codebase Context), use "Oz agent" not "Ozzie" or "the Oz Agent", use "credits" not "AI credits." +- Use Warp's standard terminology from `AGENTS.md` and the full glossary in `.warp/references/terminology.md`. Key rules: capitalize feature names (Agent, Agent Mode, Warp Drive, Codebase Context), use "agent" (generic) or "Warp Agent" (built-in harness) not "Oz agent" or "Ozzie", use "credits" not "AI credits." - If the docs do not cover the topic, say so honestly. Do not guess or fabricate information. ### 4. Generate doc links diff --git a/.agents/skills/missing_docs/references/feature_surface_map.md b/.agents/skills/missing_docs/references/feature_surface_map.md index ccf0eb02..7698faca 100644 --- a/.agents/skills/missing_docs/references/feature_surface_map.md +++ b/.agents/skills/missing_docs/references/feature_surface_map.md @@ -8,7 +8,7 @@ Lines starting with `#` are comments. Blank lines are ignored. # Maintenance: when a new GA feature flag ships, add a mapping here. # Run `python3 .warp/skills/missing_docs/scripts/audit_docs.py` to find unmapped flags. -# This audit is also run as a recurring scheduled Oz agent to catch drift. +# This audit is also run as a recurring scheduled cloud agent to catch drift. ## Feature flags -> doc pages diff --git a/.agents/skills/missing_docs/references/stale_terms.md b/.agents/skills/missing_docs/references/stale_terms.md index 555a2b3e..d6756ca1 100644 --- a/.agents/skills/missing_docs/references/stale_terms.md +++ b/.agents/skills/missing_docs/references/stale_terms.md @@ -25,10 +25,17 @@ mac os -> Use 'macOS' ## Deprecated terminology -ozzies -> Use 'Oz agents', 'instances', or 'Oz subagents' -warp agent -> Use 'Agent' or 'Oz agent' depending on context -warp agents -> Use 'Agents' or 'Oz agents' depending on context +ambient agent -> Use 'cloud agent' — 'ambient' is no longer a product term +ambient agents -> Use 'cloud agents' — 'ambient' is no longer a product term +ozzies -> Use 'agents', 'instances', or 'subagents' +oz agent -> Use 'agent' or 'Warp Agent' depending on context +oz agents -> Use 'agents' or 'Warp Agents' depending on context +oz cloud agent -> Use 'cloud agent' +oz cloud agents -> Use 'cloud agents' +oz subagent -> Use 'subagent' +oz subagents -> Use 'subagents' +oz conversation -> Use 'conversation' agent-mode -> Use 'Agent Mode' (two words, no hyphen) -deploying an oz -> Use 'Deploying an Oz agent' -the oz agent -> Use 'An Oz agent' or 'A parent Oz agent' -oz is running -> Use 'An Oz agent is running' or 'A run is in progress' +deploying an oz -> Use 'Deploying an agent' +the oz agent -> Use 'the agent' or 'the Warp Agent' +oz is running -> Use 'An agent is running' or 'A run is in progress' diff --git a/.agents/skills/style_lint/SKILL.md b/.agents/skills/style_lint/SKILL.md index f2550d94..188c2a84 100644 --- a/.agents/skills/style_lint/SKILL.md +++ b/.agents/skills/style_lint/SKILL.md @@ -52,7 +52,7 @@ python3 .warp/skills/style_lint/style_lint.py --all --fix --create-pr ### Terminology checks - **Product name casing**: "Warp Terminal" (→ "Warp"), "agent mode" (→ "Agent Mode"), "warp drive" (→ "Warp Drive"), "codebase context" (→ "Codebase Context"), "agent management panel" (→ "Agent Management Panel") -- **Oz terms to avoid**: "Ozzies", "Deploying an Oz", "The Oz Agent", "Oz is running", "AI agents" +- **Oz terms to avoid**: "Oz agent", "Oz cloud agent", "Oz subagent", "Oz conversation", "Ozzies", "Deploying an Oz", "The Oz Agent", "Oz is running", "AI agents" - **Deprecated terminology**: "whitelist" (→ "allowlist"), "blacklist"/"blocklist" (→ "denylist") - **External product names**: "Github" (→ "GitHub"), "github actions" (→ "GitHub Actions"), "MacOS" (→ "macOS"), "A.I." (→ "AI") - **Unrecognized terms** (warning): Bolded terms that look like product names but aren't in `terminology.md`. Flags candidates for glossary addition — not errors, just suggestions. @@ -65,7 +65,7 @@ When run with `--fix`: ## Relationship to validate_ui_refs -This skill checks broader formatting and terminology. The `validate_ui_refs` skill validates UI paths and Command Palette names against the warp-internal codebase. They complement each other with no overlap. Both can run in scheduled Oz agent workflows. +This skill checks broader formatting and terminology. The `validate_ui_refs` skill validates UI paths and Command Palette names against the warp-internal codebase. They complement each other with no overlap. Both can run in scheduled cloud agent workflows. ## Dependencies @@ -73,7 +73,7 @@ Requires Python 3.7+. Optional: `requests` (for Slack notifications), `gh` CLI ( ## Cloud agent / scheduling -For scheduled Oz cloud agent runs: +For scheduled cloud agent runs: 1. Configure the environment with the docs repo 2. Set the `SLACK_BOT_TOKEN` secret in the environment (for `--slack-notify`) 3. Run: `python3 .warp/skills/style_lint/style_lint.py --all --fix --create-pr --slack-notify` diff --git a/.agents/skills/style_lint/style_lint.py b/.agents/skills/style_lint/style_lint.py index 414f62e7..644ef86b 100644 --- a/.agents/skills/style_lint/style_lint.py +++ b/.agents/skills/style_lint/style_lint.py @@ -35,7 +35,7 @@ # Feature names that are correctly Title Case (exceptions to sentence-case rule) PROPER_FEATURE_NAMES = { "Admin Panel", "Agent Management Panel", "Agent Mode", "Agent Profiles", - "Ambient Agents", "Auto-detection Mode", + "Auto-detection Mode", "Cloud Agents", "Codebase Context", "Code Review", "Command Palette", "Global Rules", "Oz CLI", "Oz Platform", "Project Rules", "Slash Commands", "Terminal Mode", "Universal Input", "Warp Drive", @@ -73,11 +73,16 @@ # Oz terms to avoid (case-insensitive patterns) OZ_TERMS_TO_AVOID = [ - (r"\bOzzies\b", "Use 'Oz agents', 'instances', or 'Oz subagents'"), - (r"\bDeploying an Oz\b", "Use 'Deploying an Oz agent'"), - (r"\bThe Oz Agent\b", "Use 'An Oz agent' or 'A parent Oz agent'"), - (r"\bOz is running\b", "Use 'An Oz agent is running' or 'A run is in progress'"), + (r"\bOzzies\b", "Use 'agents', 'instances', or 'subagents'"), + (r"\bDeploying an Oz\b", "Use 'Deploying an agent'"), + (r"\bThe Oz Agent\b", "Use 'the agent' or 'the Warp Agent'"), + (r"\bOz is running\b", "Use 'An agent is running' or 'A run is in progress'"), (r"\bAI agents?\b", "Use 'agents' (the 'AI' prefix is redundant)"), + (r"\bOz cloud agents?\b", "Use 'cloud agent(s)'"), + (r"\bOz subagents?\b", "Use 'subagent(s)'"), + (r"\bOz conversation\b", "Use 'conversation'"), + (r"\bOz agents?\b", "Use 'agent(s)' or 'Warp Agent(s)' depending on context"), + (r"\b[Aa]mbient [Aa]gents?\b", "Use 'cloud agent(s)' — 'ambient' is no longer a product term"), ] # Action verbs that precede UI elements (should be bold, not backtick) @@ -389,13 +394,23 @@ def check_product_casing(lines: List[str], filepath: str) -> List[Issue]: def check_oz_terms(lines: List[str], filepath: str) -> List[Issue]: - """Check for Oz terms to avoid.""" + """Check for Oz terms to avoid. + + Skips fenced code blocks and strips inline code (backtick-wrapped text) + so that legitimate CLI commands like `oz agent run` are not flagged. + """ issues = [] + in_code_block = False for i, line in enumerate(lines, 1): - if line.strip().startswith("```") or line.strip().startswith("`"): + if line.strip().startswith("```"): + in_code_block = not in_code_block + continue + if in_code_block: continue + # Strip inline code spans so `oz agent run` is not matched + prose_line = re.sub(r"`[^`]+`", "", line) for pattern, suggestion in OZ_TERMS_TO_AVOID: - for m in re.finditer(pattern, line, re.IGNORECASE): + for m in re.finditer(pattern, prose_line, re.IGNORECASE): issues.append(Issue( filepath, i, "oz-term", f"Avoid \"{m.group(0)}\" → {suggestion}", diff --git a/.agents/skills/sync-error-docs/references/error-page-template.md b/.agents/skills/sync-error-docs/references/error-page-template.md index a9210d6b..6d9067b0 100644 --- a/.agents/skills/sync-error-docs/references/error-page-template.md +++ b/.agents/skills/sync-error-docs/references/error-page-template.md @@ -60,7 +60,7 @@ This error is returned when: ## Related -* [Oz Agent API & SDK](https://docs.warp.dev/reference/api-and-sdk/agent) — API reference +* [Agent API & SDK](https://docs.warp.dev/reference/api-and-sdk/agent) — API reference * [Cloud Agents Overview](https://docs.warp.dev/agent-platform/cloud-agents/overview) — How cloud agents work ``` diff --git a/.agents/skills/validate_ui_refs/SKILL.md b/.agents/skills/validate_ui_refs/SKILL.md index 8b76f2b4..4b1ce868 100644 --- a/.agents/skills/validate_ui_refs/SKILL.md +++ b/.agents/skills/validate_ui_refs/SKILL.md @@ -135,7 +135,7 @@ The `--slack-notify` flag posts a summary to the configured Slack channel when u ### Intended behavior for scheduled runs -When this skill is configured as a scheduled Oz agent, Slack notifications should alert the team in two cases: +When this skill is configured as a scheduled cloud agent, Slack notifications should alert the team in two cases: 1. **Auto-fixes applied** — the script found and corrected issues, and created a PR. The notification should include the PR link so the team can review and merge. 2. **Unfixed issues remain** — some issues could not be auto-corrected (e.g., a renamed or removed section) and require manual attention. The notification should list these for triage. @@ -162,7 +162,7 @@ python3 .warp/skills/validate_ui_refs/validate_ui_refs.py --all --slack-notify ## Cloud Agent / Scheduling -For scheduled Oz cloud agent runs: +For scheduled cloud agent runs: 1. Configure the environment with the docs repo 2. Keep `valid_paths.json` up-to-date by running `--refresh-valid-paths` as a pre-step (requires `warp-internal` in the environment) diff --git a/.agents/templates/faq.md b/.agents/templates/faq.md index 73f36bd0..a1e32ac4 100644 --- a/.agents/templates/faq.md +++ b/.agents/templates/faq.md @@ -1,7 +1,7 @@ --- description: >- [1-2 sentences: what topic area these FAQs cover. - Example: "Answers to common questions about Oz cloud agents, billing, and environments."] + Example: "Answers to common questions about cloud agents, billing, and environments."] --- # [Title — sentence case. Title convention: "[Feature] FAQs" or "Frequently asked questions"] diff --git a/.agents/templates/quickstart.md b/.agents/templates/quickstart.md index 9adac6c0..1cb9d362 100644 --- a/.agents/templates/quickstart.md +++ b/.agents/templates/quickstart.md @@ -1,7 +1,7 @@ --- description: >- [1-2 sentences: what the reader will accomplish + time estimate. - Example: "Learn how to run your first Oz cloud agent in ~10 minutes."] + Example: "Learn how to run your first cloud agent in ~10 minutes."] --- # [Descriptive title — sentence case. Title convention: "[Feature] quickstart" or "Quickstart for [product]". Do NOT use a bare "Quickstart" — include the feature name.] diff --git a/.agents/templates/troubleshooting.md b/.agents/templates/troubleshooting.md index 561c3948..ea91da9e 100644 --- a/.agents/templates/troubleshooting.md +++ b/.agents/templates/troubleshooting.md @@ -1,7 +1,7 @@ --- description: >- [1-2 sentences describing common issues covered on this page. - Example: "Solutions for common issues with Oz cloud agents, environments, and integrations."] + Example: "Solutions for common issues with cloud agents, environments, and integrations."] --- # [Title — sentence case. Title convention: "Troubleshooting [feature]" or "Known issues with [feature]"] diff --git a/.github/workflows/respond-to-comment.yml b/.github/workflows/respond-to-comment.yml deleted file mode 100644 index 4d87a86c..00000000 --- a/.github/workflows/respond-to-comment.yml +++ /dev/null @@ -1,249 +0,0 @@ -name: Respond to Comment -on: - issue_comment: - types: - - created - pull_request_review_comment: - types: - - created -jobs: - respond: - runs-on: ubuntu-latest - if: | - contains(github.event.comment.body,'@oz-agent') && - ( - github.event_name == 'pull_request_review_comment' || - (github.event_name == 'issue_comment' && github.event.issue.pull_request) - ) && - github.actor != 'github-actions[bot]' - permissions: - contents: write - pull-requests: write - issues: write - steps: - - name: Check author permissions - uses: actions/github-script@v7 - with: - github-token: ${{ github.token }} - script: | - const { data } = await github.rest.repos.getCollaboratorPermissionLevel({ - owner: context.repo.owner, - repo: context.repo.repo, - username: context.payload.comment.user.login, - }); - if (!['admin', 'write'].includes(data.permission)) { - core.setFailed(`Comment author @${context.payload.comment.user.login} lacks write access (has '${data.permission}')`); - } - - name: Checkout Action - uses: actions/checkout@v4 - - name: Acknowledge Comment - env: - GH_TOKEN: ${{ github.token }} - run: | - COMMENT_ID="${{ github.event.comment.id }}" - REACTION="eyes" - - if [ "${{ github.event_name }}" == "pull_request_review_comment" ]; then - gh api \ - --method POST \ - -H "Accept: application/vnd.github+json" \ - -H "X-GitHub-Api-Version: 2022-11-28" \ - /repos/${{ github.repository }}/pulls/comments/$COMMENT_ID/reactions \ - -f content="$REACTION" - else - gh api \ - --method POST \ - -H "Accept: application/vnd.github+json" \ - -H "X-GitHub-Api-Version: 2022-11-28" \ - /repos/${{ github.repository }}/issues/comments/$COMMENT_ID/reactions \ - -f content="$REACTION" - fi - - name: Checkout PR - env: - GH_TOKEN: ${{ github.token }} - run: | - PR_NUMBER="${{ github.event.issue.number }}" - if [ -z "$PR_NUMBER" ]; then - PR_NUMBER="${{ github.event.pull_request.number }}" - fi - - echo "Checking out PR #$PR_NUMBER" - gh pr checkout "$PR_NUMBER" - - name: Construct Prompt - id: prompt - uses: actions/github-script@v7 - with: - github-token: ${{ github.token }} - script: | - const { owner, repo } = context.repo; - let prNumber; - if (context.eventName === 'issue_comment') { - prNumber = context.payload.issue.number; - } else { - prNumber = context.payload.pull_request.number; - } - - // Fetch PR details to provide full context - const { data: pr } = await github.rest.pulls.get({ - owner, - repo, - pull_number: prNumber, - }); - - // Get the list of files changed in the PR - const { data: files } = await github.rest.pulls.listFiles({ - owner, - repo, - pull_number: prNumber, - }); - - const fileList = files.map(f => f.filename).join(', '); - - const commentBody = context.payload.comment.body; - const author = context.payload.comment.user.login; - - let prompt = `You are an expert software engineer and the Oz Agent. - You are responding to a specific request on a Pull Request. This may involve answering questions, providing explanations, or implementing code changes. - - **Context**: - - **PR Title**: ${pr.title} - - **PR Description**: ${pr.body || 'No description provided.'} - - **Changed Files**: ${fileList} - - **User Request**: "${commentBody}" (from user @${author}) - `; - - if (context.eventName === 'pull_request_review_comment') { - const path = context.payload.comment.path; - const line = context.payload.comment.line; - const diffHunk = context.payload.comment.diff_hunk; - prompt += ` - - **Location**: File '${path}' at line ${line}. - - **Diff Context**: - \`\`\`diff - ${diffHunk} - \`\`\` - `; - prompt += ` - **Instructions**: - 1. Read the file at '${path}' to understand the full context around the line. - `; - } else { - prompt += ` - **Instructions**: - 1. Focus your analysis on the changed files (${fileList}) unless the request explicitly mentions other files. - `; - } - - prompt += `2. Determine if the user is asking a question or requesting code changes. - 3. If asking a question: Answer it based on your analysis of the code and context. - 4. If requesting code changes: Implement them carefully, ensuring correctness and following existing style. - 5. Do not output code diffs in your final message; only provide a clear explanation of what you did or answered. - 6. Format your response in Markdown. - 7. Your output will be posted as a reply to the user. - 8. Do not attempt to stage or commit changes manually. This happens automatically after you complete your response. - `; - - core.setOutput('prompt', prompt); - - name: Run Oz Agent - uses: warpdotdev/oz-agent-action@v1 - env: - GH_TOKEN: ${{ github.token }} - id: agent - with: - prompt: ${{ steps.prompt.outputs.prompt }} - warp_api_key: ${{ secrets.WARP_API_KEY }} - profile: '' - output_format: json - model: '' - name: '' - mcp: '' - - name: Commit and Push Changes - if: success() - env: - GH_TOKEN: ${{ github.token }} - run: | - git config user.name "Oz Agent" - git config user.email "agent@warp.dev" - - if [[ -n $(git status --porcelain) ]]; then - git add . - git commit -m "Oz Agent: Address comment" - git push - else - echo "No changes to commit." - fi - - name: Reply to Comment - if: success() - uses: actions/github-script@v7 - env: - AGENT_OUTPUT: ${{ steps.agent.outputs.agent_output }} - with: - github-token: ${{ github.token }} - script: | - const raw = process.env.AGENT_OUTPUT || ''; - - // Walk JSONL lines and capture the last agent text message, if any. - let lastText = ''; - for (const line of raw.split('\n')) { - const trimmed = line.trim(); - if (!trimmed) continue; - try { - const obj = JSON.parse(trimmed); - if (obj.type === 'agent' && typeof obj.text === 'string') { - lastText = obj.text; - } - } catch (e) { - // Ignore non-JSON lines - } - } - - const content = (lastText || raw || '').trim(); - if (!content) { - core.info('No agent output to reply with.'); - return; - } - - const body = `@${context.payload.comment.user.login}: ${content}`; - const { owner, repo } = context.repo; - - if (context.eventName === 'pull_request_review_comment') { - await github.rest.pulls.createReplyForReviewComment({ - owner, - repo, - pull_number: context.payload.pull_request.number, - comment_id: context.payload.comment.id, - body, - }); - } else { - await github.rest.issues.createComment({ - owner, - repo, - issue_number: context.payload.issue.number, - body, - }); - } - - name: Report Agent Error - if: failure() && steps.agent.outcome == 'failure' - uses: actions/github-script@v7 - with: - github-token: ${{ github.token }} - script: | - const body = `@${context.payload.comment.user.login}: ⚠️ I encountered an error while processing your request. Please check the [workflow run logs] for more details.`; - const { owner, repo } = context.repo; - - if (context.eventName === 'pull_request_review_comment') { - await github.rest.pulls.createReplyForReviewComment({ - owner, - repo, - pull_number: context.payload.pull_request.number, - comment_id: context.payload.comment.id, - body, - }); - } else { - await github.rest.issues.createComment({ - owner, - repo, - issue_number: context.payload.issue.number, - body, - }); - } diff --git a/.github/workflows/review-pr.yml b/.github/workflows/review-pr.yml deleted file mode 100644 index 772db569..00000000 --- a/.github/workflows/review-pr.yml +++ /dev/null @@ -1,196 +0,0 @@ -name: Auto PR Review - -on: - pull_request: - types: [opened, ready_for_review] - -jobs: - review_pr: - if: github.event.pull_request.head.repo.full_name == github.repository - runs-on: ubuntu-latest - permissions: - contents: read - pull-requests: write - issues: write - - steps: - - name: Checkout Repository - uses: actions/checkout@v4 - - - name: Review PR with Oz agent - uses: warpdotdev/oz-agent-action@v1 - env: - GH_TOKEN: ${{ github.token }} - with: - warp_api_key: ${{ secrets.WARP_API_KEY }} - skill: review-docs-pr - - - name: Post Review - uses: actions/github-script@v7 - if: always() - with: - script: | - const fs = require('fs'); - const { owner, repo } = context.repo; - const prNumber = context.payload.pull_request.number; - const commitSha = context.payload.pull_request.head.sha; - - try { - if (!fs.existsSync('review.json')) { - console.log('No review.json found. Skipping review posting.'); - return; - } - - const reviewContent = fs.readFileSync('review.json', 'utf8'); - - let review; - try { - review = JSON.parse(reviewContent); - } catch (parseError) { - core.warning(`Failed to parse review.json: ${parseError.message}`); - const sanitized = reviewContent.replace(/[\u0000-\u001F]+/g, ' '); - try { - review = JSON.parse(sanitized); - } catch (sanitizedError) { - core.setFailed(`Failed to parse review.json even after sanitizing: ${sanitizedError.message}`); - return; - } - } - - const decodeNewlines = (text) => { - if (typeof text !== 'string') return text; - return text.replace(/\r\n/g, '\n').replace(/\\n/g, '\n'); - }; - - const rawComments = Array.isArray(review.comments) ? review.comments : []; - - // Fetch valid file paths from the PR - const prFiles = await github.paginate( - github.rest.pulls.listFiles, - { owner, repo, pull_number: prNumber } - ); - const validPaths = new Set(prFiles.map(f => f.filename)); - - // Build a map of valid diff line numbers per file and side. - // GitHub's createReview API only accepts line numbers that appear - // in the PR diff; comments targeting other lines cause a 422. - const validLines = new Map(); // key: "path:side" -> Set of line numbers - for (const file of prFiles) { - if (!file.patch) continue; - const rightLines = new Set(); - const leftLines = new Set(); - let oldLine = 0; - let newLine = 0; - for (const raw of file.patch.split('\n')) { - const hunkHeader = raw.match(/^@@ -(?:\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/); - if (hunkHeader) { - const parts = raw.match(/^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/); - oldLine = parseInt(parts[1], 10); - newLine = parseInt(parts[2], 10); - continue; - } - if (raw.startsWith('+')) { - rightLines.add(newLine); - newLine++; - } else if (raw.startsWith('-')) { - leftLines.add(oldLine); - oldLine++; - } else { - // Context line — valid on both sides - rightLines.add(newLine); - leftLines.add(oldLine); - newLine++; - oldLine++; - } - } - validLines.set(`${file.filename}:RIGHT`, rightLines); - validLines.set(`${file.filename}:LEFT`, leftLines); - } - - const comments = []; - const displaced = []; // comments whose lines aren't in the diff - - for (const c of rawComments) { - if (!c || typeof c !== 'object') continue; - if (typeof c.body !== 'string' || !c.body.trim()) continue; - if (typeof c.path !== 'string' || !c.path.trim()) continue; - - // Normalize path - const normalizedPath = c.path.trim() - .replace(/^([ab]\/)*/, '') - .replace(/^\.\//, ''); - - if (!validPaths.has(normalizedPath)) { - console.log(`Skipping comment with invalid path: ${c.path} -> ${normalizedPath}`); - continue; - } - - const line = Number(c.line); - if (!Number.isInteger(line) || line <= 0) { - console.log('Skipping comment with invalid line:', c); - continue; - } - - let side = (c.side || 'RIGHT').toString().toUpperCase(); - if (side !== 'LEFT' && side !== 'RIGHT') { - console.log(`Invalid side '${c.side}', defaulting to RIGHT`); - side = 'RIGHT'; - } - - const body = decodeNewlines(c.body); - - // Validate that this line number exists in the diff for this file/side - const key = `${normalizedPath}:${side}`; - const lineSet = validLines.get(key); - if (!lineSet || !lineSet.has(line)) { - console.log(`Comment targets line ${line} (${side}) in ${normalizedPath} which is outside the diff — moving to summary.`); - displaced.push({ path: normalizedPath, line, side, body }); - continue; - } - - comments.push({ path: normalizedPath, line, side, body }); - } - - let summary = typeof review.summary === 'string' ? decodeNewlines(review.summary).trim() : ''; - - // Append displaced comments to the summary so feedback isn't lost - if (displaced.length > 0) { - const extra = displaced.map(d => - `**${d.path}** (line ${d.line}):\n${d.body}` - ).join('\n\n---\n\n'); - const header = '\n\n---\n\n**Additional comments** (targeting lines outside the diff):\n\n'; - summary = summary ? summary + header + extra : header.trimStart() + extra; - } - const hasSummary = summary.length > 0; - - if (!hasSummary && comments.length === 0) { - console.log('No valid summary or inline comments found. Skipping review posting.'); - return; - } - - const payload = { - owner, - repo, - pull_number: prNumber, - commit_id: commitSha, - event: 'COMMENT', - }; - - if (hasSummary) { - payload.body = summary; - } else { - payload.body = 'Automated review by Oz Agent'; - } - - if (comments.length > 0) { - payload.comments = comments; - } - - await github.rest.pulls.createReview(payload); - - console.log('Review posted successfully.'); - - } catch (error) { - console.error('Failed to post review:', error); - core.setFailed(`Failed to post review: ${error.message}`); - } diff --git a/AGENTS.md b/AGENTS.md index f957b6d1..53984087 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -553,7 +553,7 @@ Product feature names retain their standard capitalization. Match the exact casi - **Agent** or **Agents** (capitalized when referring to Warp's AI agents) - **Agent Mode** (not "agent mode" or "Agent-mode") - **Terminal and Agent modes** - The two distinct modes in Warp: terminal mode (for shell commands) and Agent Mode (for multi-turn agent conversations). Use "Terminal and Agent modes" on first reference; use "terminal mode" or "Agent Mode" individually in subsequent references. Do not use "agent modality" or "Agent Modality" — this was an internal name that is not user-facing. -- **Ambient Agents** (capitalized as a feature/section name; lowercase "ambient agents" only when describing the generic concept) +- **Cloud Agents** (capitalized as a product section/feature name; lowercase "cloud agents" in most contexts) - **Warp Drive** - Shared workspace for saving and organizing commands, workflows, and environment variables across your team. - **Codebase Context** - Warp indexes your Git-tracked codebase to help Agents understand your code. - **Admin Panel** - Team management surface for controlling members, roles, and billing. @@ -563,30 +563,30 @@ Product feature names retain their standard capitalization. Match the exact casi ### Oz terminology -#### Oz vs Warp -- **Warp** is the terminal and coding surface -- **Oz** is Warp's programmable agent for running and coordinating agents at scale +#### Warp Agent vs Oz +- **Warp Agent** — Warp's built-in agent harness. Use "Warp Agent" when specifically referring to the built-in harness, especially when contrasting with third-party agents (Claude Code, Codex, etc.), or when referencing the Settings label (**Settings** > **Agents** > **Warp Agent**). +- **Oz** — Warp's programmable platform for running and coordinating agents at scale - There is typically one Warp environment per user session. Oz can run many agents concurrently, across machines, repos, and teams. -#### Core Oz terms -- **Oz** - Warp's programmable agent for running and coordinating agents at scale -- **Oz agent** - A combination of agent instructions (skill or prompt), trigger (cron, webhook, manual), environment (local, cloud), profile, and host. Agents can be local or cloud, and interactive or ambient. -- **Oz cloud agent** - An Oz agent running in the cloud, from a trigger, schedule, or started from someone's local machine -- **Oz subagent** - A child Oz agent created by a parent Oz agent to parallelize or delegate work -- **Oz run** - A single execution lifecycle of an Oz agent, including actions, outputs, and logs. Always ambient and cloud-based. -- **Oz conversation** - An interactive execution lifecycle within the Warp Terminal, regardless of whether it's local or in the cloud -- **Environment** - The execution context for an Oz agent, including repo access, dependencies, secrets, compute, and runtime configuration +#### Core terms +- **agent** - A combination of agent instructions (skill or prompt), trigger (cron, webhook, manual), environment (local, cloud), profile, and host. Agents can be local or cloud. Use lowercase "agent" in most contexts; use "Warp Agent" only when referring specifically to the built-in Warp harness. +- **cloud agent** - An agent running in the cloud, from a trigger, schedule, or started from someone's local machine +- **subagent** - A child agent created by a parent agent to parallelize or delegate work +- **conversation** - An interactive execution lifecycle within the Warp Terminal, regardless of whether it's local or in the cloud +- **Oz** - Warp's programmable platform for running and coordinating agents at scale +- **Oz run** - A single execution lifecycle of an agent, including actions, outputs, and logs. Always cloud-based. +- **Environment** - The execution context for an agent, including repo access, dependencies, secrets, compute, and runtime configuration - **Oz dashboard** - The app surface to manage all Oz runs, unified across the Warp app and web -- **Oz web app** - The web app for configuring Oz agents and managing runs +- **Oz web app** - The web app for configuring agents and managing runs #### Oz CLI commands - `oz agent run` - Run a local agent - `oz agent run-cloud` - Run an adhoc cloud agent - `oz integration create` - Install integrations (Slack, Linear) - `oz environment create/list/get/update/delete` - CRUD on environments -- `oz schedule create/list/get/update/delete` - CRUD on scheduled ambient agents +- `oz schedule create/list/get/update/delete` - CRUD on scheduled cloud agents - `oz secret create/list/update/delete` - CRUD on Warp-managed secrets -- `oz run list/get` - Get info on ambient agent runs +- `oz run list/get` - Get info on cloud agent runs #### Preferred phrases - ✅ "Ask Oz to..." @@ -594,11 +594,16 @@ Product feature names retain their standard capitalization. Match the exact casi - ✅ "What would you like Oz to do?" #### Terms to avoid -- ❌ "Ozzies" → Use "Oz agents", "instances", or "Oz subagents" -- ❌ "Deploying an Oz" → Use "Deploying an Oz agent" -- ❌ "The Oz Agent" → Use "An Oz agent" or "A parent Oz agent" -- ❌ "Oz is running" → Use "An Oz agent is running" or "A run is in progress" +- ❌ "Oz agent" / "Oz agents" → Use "agent" / "agents" (or "Warp Agent" / "Warp Agents" when referring to the built-in harness) +- ❌ "Oz cloud agent" → Use "cloud agent" +- ❌ "Oz subagent" → Use "subagent" +- ❌ "Oz conversation" → Use "conversation" +- ❌ "Ozzies" → Use "agents", "instances", or "subagents" +- ❌ "Deploying an Oz" → Use "Deploying an agent" +- ❌ "The Oz Agent" → Use "the agent" or "the Warp Agent" +- ❌ "Oz is running" → Use "An agent is running" or "A run is in progress" - ❌ "AI agents" → Use "agents" (the "AI" prefix is redundant) +- ❌ "Ambient Agents" / "ambient agents" → Use "Cloud Agents" / "cloud agents" ("ambient" is no longer a product term) - ❌ "Agent Modality" or "agent modality" → Use "Terminal and Agent modes" (this was an internal name, not user-facing) ### Technical terms diff --git a/README.md b/README.md index 94963121..342f87a8 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ Read [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution flow, local se ## Agent skills -The `.warp/skills/` directory contains [Oz agent skills](https://docs.warp.dev/agent-platform/capabilities/skills) used by the Warp docs team for automated workflows, including style linting, link checking, changelog updates, and terminology syncing. The skills are included for transparency and as examples of how Oz skills can automate documentation workflows. See [`warpdotdev/oz-skills`](https://github.com/warpdotdev/oz-skills) for more examples. +The `.warp/skills/` directory contains [agent skills](https://docs.warp.dev/agent-platform/capabilities/skills) used by the Warp docs team for automated workflows, including style linting, link checking, changelog updates, and terminology syncing. The skills are included for transparency and as examples of how Oz skills can automate documentation workflows. See [`warpdotdev/oz-skills`](https://github.com/warpdotdev/oz-skills) for more examples. Some skills depend on internal Warp repositories (`warp-internal`, `warp-server`) and won't run end-to-end without access to those codebases. diff --git a/developers/agent-api-openapi.yaml b/developers/agent-api-openapi.yaml index cd2bc4b7..83f2285b 100644 --- a/developers/agent-api-openapi.yaml +++ b/developers/agent-api-openapi.yaml @@ -1,9 +1,9 @@ openapi: 3.0.0 info: - title: Oz Agent API + title: Agent API version: 1.0.0 description: | - API for creating, managing, and querying Oz cloud agent runs. + API for creating, managing, and querying cloud agent runs. These endpoints allow users to programmatically spawn agents, list runs, and retrieve detailed run information. diff --git a/package-lock.json b/package-lock.json index fc85a379..e1237593 100644 --- a/package-lock.json +++ b/package-lock.json @@ -8232,9 +8232,9 @@ "license": "MIT" }, "node_modules/devalue": { - "version": "5.7.1", - "resolved": "https://registry.npmjs.org/devalue/-/devalue-5.7.1.tgz", - "integrity": "sha512-MUbZ586EgQqdRnC4yDrlod3BEdyvE4TapGYHMW2CiaW+KkkFmWEFqBUaLltEZCGi0iFXCEjRF0OjF0DV2QHjOA==", + "version": "5.8.1", + "resolved": "https://registry.npmjs.org/devalue/-/devalue-5.8.1.tgz", + "integrity": "sha512-4CXDYRBGqN+57wVJkuXBYmpAVUSg3L6JAQa/DFqm238G73E1wuyc/JhGQJzN7vUf/CMphYau2zXbfWzDR5aTEw==", "license": "MIT" }, "node_modules/devlop": { @@ -8881,9 +8881,9 @@ "license": "BSD-3-Clause" }, "node_modules/fast-xml-builder": { - "version": "1.1.5", - "resolved": "https://registry.npmjs.org/fast-xml-builder/-/fast-xml-builder-1.1.5.tgz", - "integrity": "sha512-4TJn/8FKLeslLAH3dnohXqE3QSoxkhvaMzepOIZytwJXZO69Bfz0HBdDHzOTOon6G59Zrk6VQ2bEiv1t61rfkA==", + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/fast-xml-builder/-/fast-xml-builder-1.2.0.tgz", + "integrity": "sha512-00aAWieqff+ZJhsXA4g1g7M8k+7AYoMUUHF+/zFb5U6Uv/P0Vl4QZo84/IcufzYalLuEj9928bXN9PbbFzMF0Q==", "funding": [ { "type": "github", @@ -8892,7 +8892,8 @@ ], "license": "MIT", "dependencies": { - "path-expression-matcher": "^1.1.3" + "path-expression-matcher": "^1.5.0", + "xml-naming": "^0.1.0" } }, "node_modules/fast-xml-parser": { @@ -17292,6 +17293,21 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/xml-naming": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/xml-naming/-/xml-naming-0.1.0.tgz", + "integrity": "sha512-k8KO9hrMyNk6tUWqUfkTEZbezRRpONVOzUTnc97VnCvyj6Tf9lyUR9EDAIeiVLv56jsMcoXEwjW8Kv5yPY52lw==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "engines": { + "node": ">=16.0.0" + } + }, "node_modules/xxhash-wasm": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/xxhash-wasm/-/xxhash-wasm-1.1.0.tgz", diff --git a/scripts/generate-og-api.mjs b/scripts/generate-og-api.mjs index 984d63fc..87469db7 100644 --- a/scripts/generate-og-api.mjs +++ b/scripts/generate-og-api.mjs @@ -45,7 +45,7 @@ const svg = ` - Oz Agent API Reference + Agent API Reference Create and manage cloud agent runs, schedules, and more. diff --git a/src/content/docs/agent-platform/agent-memory/index.mdx b/src/content/docs/agent-platform/agent-memory/index.mdx index f9b5b82c..2701051d 100644 --- a/src/content/docs/agent-platform/agent-memory/index.mdx +++ b/src/content/docs/agent-platform/agent-memory/index.mdx @@ -18,8 +18,8 @@ Memory creation and retrieval are asynchronous and run in the background, so the ## 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 Oz cloud agents. -* **Both local and cloud agents** — Supports interactive local agents in Warp and background Oz cloud agents. +* **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. @@ -34,8 +34,8 @@ Memory creation and retrieval are asynchronous and run in the background, so the 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: * The local Warp Agent. -* Oz cloud agents triggered from the CLI, web app, schedules, or integrations. -* Third-party harnesses running as Oz cloud agents — Claude Code, Codex, and others as they're added. (Running third-party harnesses locally isn't supported during the research preview.) +* 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.) Memory stays bound to its owner (a user or a team), independent of which harness reads or writes. diff --git a/src/content/docs/agent-platform/capabilities/agent-notifications.mdx b/src/content/docs/agent-platform/capabilities/agent-notifications.mdx index 15f931e8..b2859487 100644 --- a/src/content/docs/agent-platform/capabilities/agent-notifications.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-notifications.mdx @@ -77,14 +77,14 @@ Desktop notifications require system permissions. If you're not receiving them, Agent notifications currently work with: -* **Oz agent** - supported out of the box. No setup required. +* **Warp Agent** - supported out of the box. No setup required. * **Claude Code** - full support via notification plugin. * **Codex** - full support via native Codex configuration. * **OpenCode** - full support via notification plugin. ## Setting up notifications -For the **Oz agent**, notifications work out of the box — no setup needed. +For the **Warp Agent**, notifications work out of the box — no setup needed. For **third-party CLI agents**, each agent requires a one-time setup. The process varies by agent: diff --git a/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx b/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx index c93c436f..d7da4531 100644 --- a/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx +++ b/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx @@ -6,6 +6,8 @@ description: >- --- import { Tabs, TabItem } from '@astrojs/starlight/components'; +Agent Profiles let you configure how Warp's agents behave in different situations, including autonomy level, base model, tool access, and command permissions. Create multiple profiles for different workflows, control which commands run automatically, and set MCP server access rules per profile. + ## Agent Profiles Agent Profiles let you configure how your Agent behaves in different situations. Each profile defines the Agent's autonomy, base models, and tool access. You can create multiple profiles and edit them directly in **Settings** > **Agents** > **Profiles**. diff --git a/src/content/docs/agent-platform/capabilities/codebase-context.mdx b/src/content/docs/agent-platform/capabilities/codebase-context.mdx index 03b7b0f2..da9351eb 100644 --- a/src/content/docs/agent-platform/capabilities/codebase-context.mdx +++ b/src/content/docs/agent-platform/capabilities/codebase-context.mdx @@ -121,7 +121,7 @@ Files excluded by ignore rules **do not** count toward your codebase's file limi ## Codebase Context in cloud agent runs -Codebase Context is available in all Oz cloud agent runs — including runs triggered from the CLI, API/SDK, integrations (Slack, Linear, GitHub Actions), and schedules — as long as Codebase Context is enabled for your account. +Codebase Context is available in all cloud agent runs — including runs triggered from the CLI, API/SDK, integrations (Slack, Linear, GitHub Actions), and schedules — as long as Codebase Context is enabled for your account. **No additional configuration is needed.** If Codebase Context is enabled, cloud agents use it automatically. diff --git a/src/content/docs/agent-platform/capabilities/full-terminal-use.mdx b/src/content/docs/agent-platform/capabilities/full-terminal-use.mdx index cd2f8659..3d655e7f 100644 --- a/src/content/docs/agent-platform/capabilities/full-terminal-use.mdx +++ b/src/content/docs/agent-platform/capabilities/full-terminal-use.mdx @@ -7,7 +7,7 @@ description: >- import { Tabs, TabItem } from '@astrojs/starlight/components'; import VideoEmbed from '@components/VideoEmbed.astro'; -Full Terminal Use lets Warp's agent operate directly inside interactive terminal applications, such as database shells, debuggers, text editors, long-running servers, and more. +Full Terminal Use lets Warp's agent operate directly inside interactive terminal applications like database shells, debuggers, text editors, and long-running servers. The agent can see the live terminal buffer, write commands, respond to prompts, and hand control back to you at any time. The agent can see the live terminal buffer (terminal state), write to the PTY to run commands, respond to prompts, and continue working inside the running process while you stay in control. diff --git a/src/content/docs/agent-platform/capabilities/index.mdx b/src/content/docs/agent-platform/capabilities/index.mdx index 242e05b5..76c6459d 100644 --- a/src/content/docs/agent-platform/capabilities/index.mdx +++ b/src/content/docs/agent-platform/capabilities/index.mdx @@ -5,9 +5,7 @@ description: >- what context they have access to, and how they execute tasks. --- -These capabilities are the foundational building blocks that define how agents operate. These include the context sources agents can access, the rules that guide their behavior, and the tools they can use. - -Understanding these capabilities helps you get the most out of agents by configuring them to match your workflows and preferences. +Agent capabilities are the core building blocks that define how Warp's agents operate, including the context sources agents can access, the rules that guide their behavior, the tools they can use, and the models they run on. Configure these capabilities to match your workflows and preferences. ## Capabilities in this section diff --git a/src/content/docs/agent-platform/capabilities/model-choice.mdx b/src/content/docs/agent-platform/capabilities/model-choice.mdx index 95e14e6c..1e8d3f21 100644 --- a/src/content/docs/agent-platform/capabilities/model-choice.mdx +++ b/src/content/docs/agent-platform/capabilities/model-choice.mdx @@ -7,6 +7,8 @@ description: >- auto-select the best model). --- +Warp lets you choose from a curated set of large language models to power your agents, or let Warp auto-select the best model for each task. Models from OpenAI, Anthropic, Google, and open source providers are available, with configurable reasoning levels and per-profile defaults. + ## Available models Warp lets you choose from a curated set of Large Language Models (LLMs) to power your Agentic Development Environment. @@ -80,7 +82,6 @@ Warp also supports leading open source models hosted via Fireworks AI, so you ca | Model | `model_id` | | --- | --- | -| GLM 5 | `glm-5-fireworks` | | GLM 5.1 | `glm-5.1-fireworks` | | Kimi K2.5 | `kimi-k25-fireworks` | | Kimi K2.6 | `kimi-k26-fireworks` | diff --git a/src/content/docs/agent-platform/capabilities/slash-commands.mdx b/src/content/docs/agent-platform/capabilities/slash-commands.mdx index e3a2d51d..3f0920c4 100644 --- a/src/content/docs/agent-platform/capabilities/slash-commands.mdx +++ b/src/content/docs/agent-platform/capabilities/slash-commands.mdx @@ -5,7 +5,7 @@ description: >- built-in actions or saved prompts without leaving the input field. --- -When using Agent Mode or Auto-Detection Mode, typing `/` in the input field opens the Slash Commands menu. +Slash Commands are quick actions and saved prompts you can invoke by typing `/` in Agent Mode or Auto-Detection Mode. They provide instant access to built-in actions like starting conversations, creating environments, switching models, and running saved prompts from Warp Drive.
![Slash Commands menu](../../../../assets/agent-platform/slash-commands-menu.png) diff --git a/src/content/docs/agent-platform/capabilities/task-lists.mdx b/src/content/docs/agent-platform/capabilities/task-lists.mdx index 06c69128..effdbfb4 100644 --- a/src/content/docs/agent-platform/capabilities/task-lists.mdx +++ b/src/content/docs/agent-platform/capabilities/task-lists.mdx @@ -6,9 +6,7 @@ description: >- time. --- -The Agent can automatically break down complex requests into clear, trackable steps in the form of a task list with to-do items.\ -\ -When you make a sufficiently complex request that requires multiple actions, the Agent will automatically create a list of steps, execute them in order, and track progress from start to finish. There’s no need to adjust settings or enable a special mode—the Agent detects and creates task lists automatically. +Task Lists let Warp's agent automatically break down complex requests into clear, trackable steps. When a request requires multiple actions, the agent creates a structured list, executes each step in order, and tracks progress in real time. No configuration is needed—the agent detects and creates task lists automatically.
![An example of a task list in progress.](../../../../assets/agent-platform/in-progress-tasklist.png) diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx index 29f1d839..902e84c1 100644 --- a/src/content/docs/agent-platform/cloud-agents/agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -8,7 +8,7 @@ sidebar: label: "Agent identities" --- -An **agent identity** is a team-scoped identity that can own and execute Oz cloud agent runs. Every Warp team starts with a single default agent identity. Creating additional agent identities lets you separate workflows, scope credentials, and attribute automated runs to a specific bot account instead of a person. +An **agent identity** is a team-scoped identity that can own and execute cloud agent runs. Every Warp team starts with a single default agent identity. Creating additional agent identities lets you separate workflows, scope credentials, and attribute automated runs to a specific bot account instead of a person. Agent identities are useful when you want to: @@ -18,7 +18,7 @@ Agent identities are useful when you want to: ## How agent identities work -Each team has one default agent identity that runs receive automatically when no specific identity is chosen. You can create additional agent identities on top of that default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities. +Each team has one default agent identity. Headless runs (such as team API key runs that don't specify an identity) execute under this default. User-triggered runs default to running as the calling user — surfaced as **Quick run** in the web app — unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities. You can attach the following configuration to an agent identity: @@ -81,7 +81,7 @@ There are two ways to run a cloud agent as a specific agent identity: * **Authenticate with a key bound to the identity** - Every run started with that key executes as the bound agent identity. This is the typical path for CI pipelines and scheduled work. * **Pass `agent_identity_uid` on `POST /agent/runs`** - For one-off runs, send the agent identity's `uid` in the request body. The field is only valid for team-owned runs. -When neither path is used, runs execute under the default identity. +When neither path is used, headless runs (team API key runs without an identity) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user — surfaced as **Quick run** in the web app. ## Where agent identities appear in the product 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 ecb3542d..c83a9623 100644 --- a/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx +++ b/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx @@ -11,7 +11,7 @@ Teams adopt cloud agents in a few repeatable ways. This page outlines the most c #### Quick mental model -Oz cloud agent setups usually have four moving parts: +Cloud agent setups usually have four moving parts: 1. **Trigger**: something happens (CI step, webhook, cron, Slack mention). 2. **Orchestration**: something decides what to run and tracks it (Oz orchestrator, GitHub Actions, your internal system). @@ -83,7 +83,7 @@ Use this when you want Oz to run agent workloads on Warp-managed infrastructure, * **First-party integrations (Slack, Linear, etc.)** that create tasks automatically from external events. * **Scheduled agents** for recurring work (cron-like automation). * **Custom triggers** from your own systems using Warp’s API/SDK. -* **On-demand cloud jobs** using CLI commands like oz agent run-cloud. +* **On-demand cloud jobs** using CLI commands like `oz agent run-cloud`. #### Example recipe: daily dead-code cleanup @@ -103,7 +103,7 @@ Use this when you want Oz to run agent workloads on Warp-managed infrastructure, If a task is naturally divisible: -* Launch multiple cloud agents via oz agent run-cloud, each with: +* 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. diff --git a/src/content/docs/agent-platform/cloud-agents/environments.mdx b/src/content/docs/agent-platform/cloud-agents/environments.mdx index a36a971f..ee398826 100644 --- a/src/content/docs/agent-platform/cloud-agents/environments.mdx +++ b/src/content/docs/agent-platform/cloud-agents/environments.mdx @@ -66,7 +66,7 @@ Components in the execution flow: 6. **Outputs** – The run produces PRs, messages, reports, or transcripts :::note -**Local agent** runs (using `oz agent run`) don't require an environment. These runs use your current machine's setup. Environments are required for **automated platform** runs like Oz cloud agents and integrations +**Local agent** runs (using `oz agent run`) don't require an environment. These runs use your current machine's setup. Environments are required for **automated platform** runs like cloud agents and integrations ::: ### Hosts and environments diff --git a/src/content/docs/agent-platform/cloud-agents/faqs.mdx b/src/content/docs/agent-platform/cloud-agents/faqs.mdx index 265a84f7..3d367628 100644 --- a/src/content/docs/agent-platform/cloud-agents/faqs.mdx +++ b/src/content/docs/agent-platform/cloud-agents/faqs.mdx @@ -47,7 +47,7 @@ If you're not happy with where it landed, you can take over to finish the task. ### Do cloud agents have access to Codebase Context and indexing? -Yes. [Codebase Context](/agent-platform/capabilities/codebase-context/) is enabled for all Oz cloud agent runs, as long as Codebase Context is enabled for your account. This includes runs triggered from the CLI, API/SDK, integrations (Slack, Linear, GitHub Actions), and schedules. No additional configuration is needed — if Codebase Context is enabled, cloud agents use it automatically. +Yes. [Codebase Context](/agent-platform/capabilities/codebase-context/) is enabled for all cloud agent runs, as long as Codebase Context is enabled for your account. This includes runs triggered from the CLI, API/SDK, integrations (Slack, Linear, GitHub Actions), and schedules. No additional configuration is needed — if Codebase Context is enabled, cloud agents use it automatically. ### Can I access a shell inside a cloud agent environment? Are there limitations (Docker, Playwright, etc.)? diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx index 91020cb4..b7e00642 100644 --- a/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx @@ -1,7 +1,7 @@ --- title: Harnesses in Oz description: >- - Run Claude Code or Codex as Oz cloud agents. Both inherit the same triggers, + Run Claude Code or Codex as cloud agents. Both inherit the same triggers, environments, secrets, and observability as Warp Agent. sidebar: label: "Overview" diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/azure-devops.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/azure-devops.mdx index a76169d5..4ea16bc1 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/azure-devops.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/azure-devops.mdx @@ -3,11 +3,11 @@ title: Azure DevOps integration sidebar: label: "Azure DevOps" description: >- - Connect Oz cloud agents to Azure DevOps repos using personal access tokens + Connect cloud agents to Azure DevOps repos using personal access tokens and Warp-managed secrets. --- -Oz cloud agents work with any Git repository, including those hosted on Azure DevOps. A native Azure DevOps integration is not yet available, but you can grant agents access to your repositories using a personal access token and Warp-managed secrets. Once configured, your environment works with any Oz trigger—Slack, Linear, schedules, or the CLI. +Cloud agents work with any Git repository, including those hosted on Azure DevOps. A native Azure DevOps integration is not yet available, but you can grant agents access to your repositories using a personal access token and Warp-managed secrets. Once configured, your environment works with any Oz trigger—Slack, Linear, schedules, or the CLI. This page explains how to generate an Azure DevOps personal access token, store it securely, and configure a cloud agent environment that clones your repository at runtime. diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/bitbucket.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/bitbucket.mdx index 300f4d19..2f02af4d 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/bitbucket.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/bitbucket.mdx @@ -3,11 +3,11 @@ title: Bitbucket integration sidebar: label: "Bitbucket" description: >- - Connect Oz cloud agents to Bitbucket repos using access tokens and + Connect cloud agents to Bitbucket repos using access tokens and Warp-managed secrets. --- -Oz cloud agents work with any Git repository, including those hosted on Bitbucket. Unlike GitHub, Bitbucket does not have a native Warp integration, but you can grant agents access to your Bitbucket repositories using an access token and Warp-managed secrets. Once configured, your environment works with any Oz trigger—Slack, Linear, schedules, or the CLI. +Cloud agents work with any Git repository, including those hosted on Bitbucket. Unlike GitHub, Bitbucket does not have a native Warp integration, but you can grant agents access to your Bitbucket repositories using an access token and Warp-managed secrets. Once configured, your environment works with any Oz trigger—Slack, Linear, schedules, or the CLI. This page explains how to generate a Bitbucket access token, store it securely, and configure a cloud agent environment that clones your repository at runtime. diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/cloud-providers.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/cloud-providers.mdx index b3c99cef..f19a2840 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/cloud-providers.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/cloud-providers.mdx @@ -1,16 +1,12 @@ --- title: Cloud Providers (Preview) description: >- - Connect Oz cloud agents to your AWS and GCP services. + Connect cloud agents to your AWS and GCP services. sidebar: label: "AWS, GCP, and other cloud providers" --- -Oz cloud agents can securely access cloud providers using short-lived OpenID Connect credentials. - -This page explains how to configure a cloud agent environment to automatically authenticate to your -cloud provider. Oz has built-in support for AWS and GCP, and can work with any provider that -supports OIDC tokens. +Cloud agents can securely access AWS, GCP, and other cloud providers using short-lived OpenID Connect (OIDC) credentials. Configure your cloud agent environment to automatically authenticate to your cloud provider without storing long-lived keys, using Warp's built-in OIDC federation support. --- @@ -119,7 +115,7 @@ To allow multiple specific principals, use a list of subjects: ... ``` -4. Click **Next** and add permissions policies. These policies determine what Oz agents can access +4. Click **Next** and add permissions policies. These policies determine what agents can access in your AWS account. 5. Click **Next** and enter a role name and optional description. 6. Click **Create role**, then open the role and note down the role ARN. This will be of the form `arn:aws:iam:::role/`. @@ -128,7 +124,7 @@ To allow multiple specific principals, use a list of subjects: ### Step 3: Enable AWS federation in your cloud agent environment -Finally, configure the Oz cloud agent environment to use your new AWS role. +Finally, configure the cloud agent environment to use your new AWS role. 1. Open the Oz web app at [https://oz.warp.dev](https://oz.warp.dev). 2. Create or edit an environment. See [Environments](/agent-platform/cloud-agents/oz-web-app/#environments) for instructions. @@ -139,7 +135,7 @@ Finally, configure the Oz cloud agent environment to use your new AWS role. Currently, AWS federation can only be configured in the Oz web app, not the CLI. ::: -Oz agents running in this environment will now automatically assume the configured role when using +Agents running in this environment will now automatically assume the configured role when using the `aws` CLI or a compatible SDK. :::note @@ -191,16 +187,16 @@ Replace `` with the UID of your Warp team. This is the last component panel URL is `https://app.warp.dev/admin/abc123def456`, your team UID would be `abc123def456`. :::caution -If you do not set an attribute condition, then _any_ Oz agent will be able to use your Workload -Identity Federation provider, even if they do not belong to your team. +If you do not set an attribute condition, then _any cloud agent_ will be able to use your Workload +Identity Federation provider, even if it does not belong to your team. ::: ### Step 2: Configure IAM policies -You will need to configure IAM policies in GCP that allow Oz agents in the Workload Identity +You will need to configure IAM policies in GCP that allow agents in the Workload Identity Federation pool access to resources. -To give all Oz agents on your team read-only access to all Compute Engine resources in a project, +To give all agents on your team read-only access to all Compute Engine resources in a project, for example, you would run: ```bash @@ -214,7 +210,7 @@ for the full syntax supported. ### Step 3: Enable Workload Identity Federation in your cloud agent environment -Finally, configure the Oz cloud agent environment to use your Workload Identity Federation provider. +Finally, configure the cloud agent environment to use your Workload Identity Federation provider. 1. Open the Oz web app at [https://oz.warp.dev](https://oz.warp.dev). 2. Create or edit an environment. See [Environments](/agent-platform/cloud-agents/oz-web-app/#environments) for instructions. @@ -225,7 +221,7 @@ Finally, configure the Oz cloud agent environment to use your Workload Identity Currently, Workload Identity Federation can only be configured in the Oz web app, not the CLI. ::: -Oz agents running in this environment will now automatically configure +Agents running in this environment will now automatically configure [Application Default Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials) to use the configured pool. Both the `GOOGLE_APPLICATION_CREDENTIALS` and `CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE` environment variables are set, so both the `gcloud` CLI and official Google SDKs will use the Oz @@ -246,7 +242,7 @@ oz federate issue-token --audience your-provider.com --output-format json ``` Optionally, add `--duration ` to customize the token validity. This cannot exceed the -maximum runtime of an Oz agent. +maximum runtime of an agent. You may then exchange this token for provider-specific credentials. @@ -262,7 +258,7 @@ such as `https://iam.googleapis.com/projects//locations/global/w ### Subject (`sub`) -The `sub` claim is set to the identity that an Oz agent is executing as. This will either be a +The `sub` claim is set to the identity that an agent is executing as. This will either be a Warp user ID or an autogenerated account ID for team-scoped agent runs. By default, the `sub` claim uses the format `:`: @@ -313,7 +309,7 @@ list only ever contains a single value. ### Oz run -The following claims are derived from an Oz agent run: +The following claims are derived from an agent run: * `run_id`: the unique identifier for the individual run. This is not suitable for configuring access, but is useful to log for debugging. @@ -324,7 +320,7 @@ The following claims are derived from an Oz agent run: ### Example token -The following OIDC token references an Oz agent running as a specific Warp user: +The following OIDC token references an agent running as a specific Warp user: ```json // JWT Header diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/demo-issue-triage-bot.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/demo-issue-triage-bot.mdx index 53d009b1..1fa8e695 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/demo-issue-triage-bot.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/demo-issue-triage-bot.mdx @@ -8,6 +8,8 @@ sidebar: --- import VideoEmbed from '@components/VideoEmbed.astro'; +This demo shows how to trigger Warp's coding agent from a GitHub Action to automate bug report handling. The agent evaluates whether a report is actionable, requests missing details when needed, and escalates directly into a draft pull request when the issue is ready for a fix. + :::note diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx index 2b89bbdb..9bf7f2d7 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx @@ -1,12 +1,12 @@ --- title: GitHub Actions description: >- - Run Oz agents in GitHub Actions to automate code review, issue triage, and + Run agents in GitHub Actions to automate code review, issue triage, and CI fixes. --- import VideoEmbed from '@components/VideoEmbed.astro'; -Run Oz agents directly in your GitHub Actions workflows using `oz-agent-action`. The agent integrates seamlessly into your CI pipeline, automating tasks like code review, issue triage, bug fixing, and maintenance using your repository context and GitHub permissions. This page covers how the integration works, how to set it up, and common automation patterns for development teams. +Run agents directly in your GitHub Actions workflows using `oz-agent-action`. The agent integrates seamlessly into your CI pipeline, automating tasks like code review, issue triage, bug fixing, and maintenance using your repository context and GitHub permissions. This page covers how the integration works, how to set it up, and common automation patterns for development teams. :::note **Getting started?** See the [GitHub Actions quickstart](/agent-platform/cloud-agents/integrations/quickstart-github-actions/) to set up your first workflow, or visit the [oz-agent-action repository](https://github.com/warpdotdev/oz-agent-action) for detailed setup instructions and ready-to-use workflow templates. @@ -29,7 +29,7 @@ In this demo The `oz-agent-action` is a GitHub Action that wraps the Oz CLI and: -* Runs an Oz agent inside an Actions job +* Runs an agent inside an Actions job * Caches package installation for faster builds * Captures the agent's output for use in subsequent workflow steps * Lets you pass workflow context, event data, and previous step outputs into the agent prompt @@ -39,7 +39,7 @@ The `oz-agent-action` is a GitHub Action that wraps the Oz CLI and: ### Requirements -To use Oz agents in GitHub Actions, you need: +To use agents in GitHub Actions, you need: * A [**Warp API Key**](/reference/cli/#generating-api-keys) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp * Workflow permissions that match your intended actions (for example, `pull-requests: write` if the agent should commit or comment on PRs) — the agent performs actions on your behalf using the GitHub token available to the workflow @@ -49,7 +49,7 @@ To use Oz agents in GitHub Actions, you need: ### Using Skills -Skills provide reusable instructions for Oz agents. You can use pre-built skills from the [oz-skills repository](https://github.com/warpdotdev/oz-skills) or create custom [skills](/agent-platform/capabilities/skills/) for your specific workflows. Skills can also be deployed as [standalone agents](/agent-platform/capabilities/skills/#skills-as-agents) to run on a schedule or in response to events. +Skills provide reusable instructions for agents. You can use pre-built skills from the [oz-skills repository](https://github.com/warpdotdev/oz-skills) or create custom [skills](/agent-platform/capabilities/skills/) for your specific workflows. Skills can also be deployed as [standalone agents](/agent-platform/capabilities/skills/#skills-as-agents) to run on a schedule or in response to events. #### How to use skills diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/gitlab.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/gitlab.mdx index aa6fc21b..6f9dcc65 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/gitlab.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/gitlab.mdx @@ -3,11 +3,11 @@ title: GitLab integration sidebar: label: "GitLab" description: >- - Connect Oz cloud agents to GitLab repos using personal access tokens and + Connect cloud agents to GitLab repos using personal access tokens and Warp-managed secrets. --- -Oz cloud agents work with any Git repository, including those hosted on GitLab. Unlike GitHub, GitLab does not have a native Warp integration, but you can grant agents access to your GitLab repositories using a personal access token and Warp-managed secrets. Once configured, your environment works with any Oz trigger—Slack, Linear, schedules, or the CLI. +Cloud agents work with any Git repository, including those hosted on GitLab. Unlike GitHub, GitLab does not have a native Warp integration, but you can grant agents access to your GitLab repositories using a personal access token and Warp-managed secrets. Once configured, your environment works with any Oz trigger—Slack, Linear, schedules, or the CLI. This page explains how to generate a GitLab personal access token, store it securely, and configure a cloud agent environment that clones your repository at runtime. diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx index ecd2f177..3f112fdf 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx @@ -3,7 +3,7 @@ title: Linear integration sidebar: label: "Linear" description: >- - Automate Linear issues with Oz agents that run code in the cloud and create + Automate Linear issues with agents that run code in the cloud and create pull requests on your behalf. --- import VideoEmbed from '@components/VideoEmbed.astro'; diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx index 82e28bb3..4d2ebc38 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart-github-actions.mdx @@ -1,13 +1,13 @@ --- title: GitHub Actions quickstart description: >- - Set up your first Oz agent in GitHub Actions in ~10 minutes. Run agents as + Set up your first agent in GitHub Actions in ~10 minutes. Run agents as workflow steps to automate code review and issue triage. sidebar: label: "Quickstart" --- -Add Oz agents to your GitHub Actions workflows with [`oz-agent-action`](https://github.com/warpdotdev/oz-agent-action). This quickstart walks you through setting up your first GitHub Actions integration: a PR review workflow that automatically analyzes pull requests and posts inline review comments. +Add agents to your GitHub Actions workflows with [`oz-agent-action`](https://github.com/warpdotdev/oz-agent-action). This quickstart walks you through setting up your first GitHub Actions integration: a PR review workflow that automatically analyzes pull requests and posts inline review comments. --- @@ -30,7 +30,7 @@ Store your Warp API key as a GitHub Actions secret so workflows can authenticate ## 2. Create the workflow file -This workflow triggers an Oz agent whenever a PR is opened or marked ready for review. The agent reviews the diff and posts inline comments. +This workflow triggers an agent whenever a PR is opened or marked ready for review. The agent reviews the diff and posts inline comments. Create `.github/workflows/oz-pr-review.yml` in your repository with the following content: diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx index b411e5f2..37c0ea76 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx @@ -1,7 +1,7 @@ --- title: Integrations quickstart description: >- - Trigger your first Oz agent from Slack in ~15 minutes and get results + Trigger your first agent from Slack in ~15 minutes and get results in-thread. sidebar: label: "Quickstart" @@ -18,7 +18,7 @@ Oz integrations let you trigger cloud agents directly from the tools your team a ## Prerequisites * **Eligible plan** - The Slack integration requires a Warp team on Build, Max, or Business plan with at least 20 credits available. See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/). -* **An Oz cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have one yet, follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/) or run `/create-environment` in Warp. +* **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have one yet, follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/) or run `/create-environment` in Warp. * **GitHub authorization** - Warp needs access to your repos to clone code and open PRs. You'll be prompted to authorize the Warp GitHub app when you first create the integration. --- @@ -77,5 +77,5 @@ When the task is complete, Oz posts a summary back to the original Slack thread. ## Next steps * **Customize agent behavior** - Use a [skill](/agent-platform/cloud-agents/skills-as-agents/) as the base prompt for your integration to give Oz consistent, reusable instructions across every run. -* **Trigger agents programmatically** - Use the [API & SDK](/reference/api-and-sdk/) to build custom automations and integrations on top of Oz agents. +* **Trigger agents programmatically** - Use the [API & SDK](/reference/api-and-sdk/) to build custom automations and integrations on top of agents. * **Read the full Slack reference** - [Slack](/agent-platform/cloud-agents/integrations/slack/) covers identity mapping, team access, monitoring runs, troubleshooting, and uninstall instructions. diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx index f724666f..b37d510b 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx @@ -3,10 +3,12 @@ title: Slack integration sidebar: label: "Slack" description: >- - Trigger Oz agents from Slack to run cloud tasks, track progress, and create + Trigger agents from Slack to run cloud tasks, track progress, and create pull requests. --- +The Slack integration lets your team trigger cloud agents directly from Slack conversations. Tag @Oz in a message or DM the bot to start a cloud agent that clones your repos, works through the task, posts progress updates, and opens pull requests back into the same thread. + ### Overview The Slack integration lets your team trigger agents directly from conversations in Slack. When you tag **@Oz** in a message or DM the bot, Warp will start an agent in the cloud, clone the repositories defined in your environment, and begin working through the task with full context from your codebase and the Slack thread. diff --git a/src/content/docs/agent-platform/cloud-agents/overview.mdx b/src/content/docs/agent-platform/cloud-agents/overview.mdx index 243f4119..4c35494b 100644 --- a/src/content/docs/agent-platform/cloud-agents/overview.mdx +++ b/src/content/docs/agent-platform/cloud-agents/overview.mdx @@ -8,7 +8,7 @@ sidebar: --- import VideoEmbed from '@components/VideoEmbed.astro'; -Oz Cloud Agents are **cloud-connected**, **background agents** that run on the [Oz Platform](/agent-platform/cloud-agents/platform/). +Cloud agents are autonomous, background agents that run on Warp's cloud infrastructure or your own, triggered by system events, schedules, or integrations like Slack and GitHub. They execute tasks with full observability — every run is tracked, auditable, and shareable across your team. **New to cloud agents?** Start with the [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/) to run your first cloud agent in ~10 minutes. @@ -147,7 +147,7 @@ If your credit balance reaches zero, cloud agent runs will not be able to execut * [Harnesses](/agent-platform/cloud-agents/harnesses/) — pick between Warp Agent, Claude Code, and Codex for any cloud agent run. * [Agent identities](/agent-platform/cloud-agents/agents/) — team-scoped bot accounts that own and execute cloud agent runs. * [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/) — run agents based on reusable skill definitions from the CLI, web app, API, or on a schedule. -* [Oz CLI](/reference/cli/) — shows how to run Oz agents in non-interactive mode from CI, scripts, or remote machines, including auth and common commands. +* [Oz CLI](/reference/cli/) — shows how to run agents in non-interactive mode from CI, scripts, or remote machines, including auth and common commands. * [Environments](/agent-platform/cloud-agents/environments/) — explains how environments provide the runtime context (repo, image, startup commands) for agent tasks. * [Oz API and SDK](/reference/api-and-sdk/) — documents the REST API for creating, querying, and monitoring agent tasks programmatically. * [Agent Secrets](/agent-platform/cloud-agents/secrets/) — covers how to store, scope, and inject credentials into agent runs safely. 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 1f1e4bd4..6d29a549 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 @@ -47,7 +47,7 @@ When you first sign in to the Oz web app, you'll see a guided onboarding flow th The onboarding asks "What brings you to Oz?" and offers three paths: * **Create an agent automation** — Walks you through setting up a scheduled agent, integration-triggered agent, or other automation -* **Run Oz Cloud Agents in Warp** — Opens the Warp desktop app (or takes you to the download page) to run cloud agents interactively +* **Run Cloud Agents in Warp** — Opens the Warp desktop app (or takes you to the download page) to run cloud agents interactively * **Build an app that uses agents** — Links to the [Oz Platform](/agent-platform/cloud-agents/platform/) docs for using the CLI, SDK, or API You can skip onboarding at any time to go directly to the Runs page. diff --git a/src/content/docs/agent-platform/cloud-agents/platform.mdx b/src/content/docs/agent-platform/cloud-agents/platform.mdx index 34c188b2..7b378be3 100644 --- a/src/content/docs/agent-platform/cloud-agents/platform.mdx +++ b/src/content/docs/agent-platform/cloud-agents/platform.mdx @@ -46,7 +46,7 @@ In practice: **triggers create tasks; tasks execute on a host (optionally in an ### Oz CLI -The [Oz CLI](/reference/cli/) is the **headless interface** for running Oz agents in non-interactive mode. It's commonly used in CI, scripts, and server environments where there is no interactive UI. For interactive workflows, use the [agent](/agent-platform/local-agents/overview/) embedded in Warp's desktop app. +The [Oz CLI](/reference/cli/) is the **headless interface** for running agents in non-interactive mode. It's commonly used in CI, scripts, and server environments where there is no interactive UI. For interactive workflows, use the [agent](/agent-platform/local-agents/overview/) embedded in Warp's desktop app. A key property of the CLI is that it is **cloud-connected**. Even when an agent is started on a local machine or in CI, it reports progress to Warp’s servers. This enables team visibility, session sharing (where supported), and programmatic tracking through the API. @@ -142,7 +142,7 @@ The Oz [Agent API](/reference/api-and-sdk/) is the HTTP interface to the Oz Plat * Monitor execution by listing tasks and tracking state transitions over time (for example: `QUEUED` → `INPROGRESS` → `SUCCEEDED/FAILED`). * Inspect results and provenance by fetching a task’s full details, including the original prompt, creator/source metadata, session link, and resolved agent configuration. -**Oz Agent SDKs** +**Oz SDKs** Oz provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDKs](https://github.com/warpdotdev/oz-sdk-typescript) that wrap the Oz API with: @@ -217,7 +217,7 @@ Examples of context extracted by first-party integrations: #### Custom integrations -With custom integrations, you own the webhook and event-handling logic. Your system receives an event, applies any filtering or enrichment you need, and then calls the Oz API (directly or via an SDK) to create a task. The resulting task is still a full Oz agent run — observable, manageable, and auditable like any other. +With custom integrations, you own the webhook and event-handling logic. Your system receives an event, applies any filtering or enrichment you need, and then calls the Oz API (directly or via an SDK) to create a task. The resulting task is still a full cloud agent run — observable, manageable, and auditable like any other. Custom integrations are a good fit when: diff --git a/src/content/docs/agent-platform/cloud-agents/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/quickstart.mdx index 19d1b643..7cd15eb8 100644 --- a/src/content/docs/agent-platform/cloud-agents/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/quickstart.mdx @@ -1,14 +1,14 @@ --- title: Cloud agents quickstart description: >- - Learn how to run your first Oz cloud agent in ~10 minutes. Cloud agents run + Learn how to run your first cloud agent in ~10 minutes. Cloud agents run in remote environments, enabling automation, scheduling, and team collaboration. sidebar: label: "Quickstart" --- -**Oz cloud agents** run in a remote environment and can be triggered from events, schedules, integrations, or manually. This enables scaling agents off your laptop, automating development tasks, and building apps on top of agents. Oz handles the orchestration, execution, and observability. +**Cloud agents** run in a remote environment and can be triggered from events, schedules, integrations, or manually. This enables scaling agents off your laptop, automating development tasks, and building apps on top of agents. Oz handles the orchestration, execution, and observability. Cloud agents can run interactively (where you steer them in real-time) or autonomously (as background tasks). Each run creates a persistent session that your team can inspect, share, and query through the Warp app, the CLI, web app, or API. @@ -35,7 +35,7 @@ New to Warp? You'll get credits to try cloud agents. You need at least 20 credit --- -## Running your first Oz cloud agent +## Running your first cloud agent _~10 minutes • Recommended for all users_ @@ -142,7 +142,7 @@ oz schedule create \ Integrations require a team on Build, Max, or Business plan. ::: -### Build automations and apps on top of Oz agents +### Build automations and apps on top of agents Use the [Oz API & SDK](/reference/api-and-sdk/) to trigger agents programmatically from your own systems and workflows. diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx index 453ca100..5272fe77 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx @@ -1,19 +1,19 @@ --- title: Self-hosting overview description: >- - Run Oz cloud agents on your own infrastructure. Choose between a managed + Run cloud agents on your own infrastructure. Choose between a managed worker daemon orchestrated by Oz or unmanaged CLI-based execution you control. --- -Self-hosting lets your team run Oz cloud agent workloads on your own infrastructure instead of Warp-managed servers. You control the execution environment, compute resources, and network access. Repositories are cloned and stored only on your machines, and agents can reach services behind your VPN or firewall. +Self-hosting lets your team run cloud agent workloads on your own infrastructure instead of Warp-managed servers. You control the execution environment, compute resources, and network access. Repositories are cloned and stored only on your machines, and agents can reach services behind your VPN or firewall. **New to self-hosting?** Start with the [Self-hosting quickstart](/agent-platform/cloud-agents/self-hosting/quickstart/) to get a managed worker running on Docker in under 10 minutes. **Want a CLI-only path with no Docker requirement?** Jump straight to the [Unmanaged quickstart](/agent-platform/cloud-agents/self-hosting/unmanaged/#unmanaged-quickstart) to run `oz agent run` directly on any host. :::note -**Enterprise feature**: Self-hosted Oz agents are available exclusively to teams on an Enterprise plan. To enable self-hosting for your team, [contact sales](https://warp.dev/contact-sales). +**Enterprise feature**: Self-hosted agents are available exclusively to teams on an Enterprise plan. To enable self-hosting for your team, [contact sales](https://warp.dev/contact-sales). ::: ## Managed vs unmanaged @@ -115,7 +115,7 @@ You're responsible for executing `oz agent run` on your infrastructure — simil ## Routing runs to self-hosted workers -This section applies to **all managed backends** (Docker, Kubernetes, and Direct). Once a worker is connected, route Oz cloud agent runs to it by specifying the `--host` flag (or equivalent) with your worker ID. The `--host` value must match the `--worker-id` of a connected worker exactly. +This section applies to **all managed backends** (Docker, Kubernetes, and Direct). Once a worker is connected, route cloud agent runs to it by specifying the `--host` flag (or equivalent) with your worker ID. The `--host` value must match the `--worker-id` of a connected worker exactly. :::note Unmanaged runs don't need routing — you invoke `oz agent run` directly on the host where you want the agent to execute. Routing is only relevant for managed workers. diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx index d96bb44c..14a27eb3 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/quickstart.mdx @@ -7,7 +7,7 @@ sidebar: label: "Quickstart" --- -Run your first Oz cloud agent on your own infrastructure in ~10 minutes using the managed architecture with the Docker backend — the default and fastest path to self-hosting. +Run your first cloud agent on your own infrastructure in ~10 minutes using the managed architecture with the Docker backend — the default and fastest path to self-hosting. :::note This quickstart sets up the [managed architecture](/agent-platform/cloud-agents/self-hosting/#managed-architecture), where Oz orchestrates the agent and your worker provides the compute. **Prefer a CLI-only path with no Docker requirement?** Jump to the [Unmanaged quickstart](/agent-platform/cloud-agents/self-hosting/unmanaged/#unmanaged-quickstart) to run `oz agent run` directly on any host. diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/security-and-networking.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/security-and-networking.mdx index 6ada0785..8533c7cd 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/security-and-networking.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/security-and-networking.mdx @@ -34,7 +34,7 @@ While repositories are cloned and stored only on your infrastructure, code conte ## Network requirements -Self-hosted Oz agents **do not require any network ingress**. They require outbound (egress) access to the following services: +Self-hosted agents **do not require any network ingress**. They require outbound (egress) access to the following services: **Warp's backend (all architectures):** diff --git a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx index 84a2a11f..a912561f 100644 --- a/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx +++ b/src/content/docs/agent-platform/cloud-agents/self-hosting/unmanaged.mdx @@ -1,7 +1,7 @@ --- title: Unmanaged architecture description: >- - Run Oz agents in your existing CI, Kubernetes, or dev environments using + Run agents in your existing CI, Kubernetes, or dev environments using the oz agent run CLI with Warp tracking and observability. sidebar: label: "Unmanaged" @@ -72,7 +72,7 @@ The `--share` flag can be repeated to combine multiple sharing targets. If you a Warp maintains the [`warpdotdev/oz-agent-action`](https://github.com/warpdotdev/oz-agent-action) action for running agents in GitHub Actions. The action wraps `oz agent run` and is a drop-in for CI workflows: ```yaml -- name: Run Oz agent +- name: Run agent uses: warpdotdev/oz-agent-action@v1 # wraps `oz agent run` under the hood with: prompt: "Review the code changes on this branch" diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx index 3d676612..93bde902 100644 --- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx +++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx @@ -102,13 +102,13 @@ This ensures runs are scoped to what the user is allowed to see and modify, and ## Team GitHub authorization -By default, Oz cloud agents authenticate with GitHub using the personal token of the user who triggered the run. Team GitHub authorization gives you an alternative: authenticate with the **Oz by Warp** GitHub App instead, so agents can clone repositories and open pull requests without relying on any individual's token. +By default, cloud agents authenticate with GitHub using the personal token of the user who triggered the run. Team GitHub authorization gives you an alternative: authenticate with the **Oz by Warp** GitHub App instead, so agents can clone repositories and open pull requests without relying on any individual's token. This is useful for fully automated workflows that use a [team API key](/reference/cli/api-keys/), like CI/CD pipelines, scheduled agents, and SDK-triggered runs, where you want code changes attributed to the GitHub App rather than a specific person. ### How it works -When an Oz agent task is initiated with a team API key, there is no individual user to authenticate on behalf of. Instead, Warp uses tokens issued by the **Oz by Warp** GitHub App installation to authenticate directly with GitHub. +When an agent task is initiated with a team API key, there is no individual user to authenticate on behalf of. Instead, Warp uses tokens issued by the **Oz by Warp** GitHub App installation to authenticate directly with GitHub. The GitHub App token gives the agent access to the repositories included in the app installation — it can clone repos, create branches, push commits, and open pull requests. During installation, you choose whether the app can access **all repositories** or only **selected repositories** in your GitHub organization, and this controls what team API key runs can access. @@ -140,7 +140,7 @@ There are two places you may encounter this installation flow: ### How this relates to environments -An [environment](/agent-platform/cloud-agents/environments/) is a template for an Oz cloud agent's sandbox — it defines the Docker image, repos, and setup commands, but it does not carry its own GitHub permissions. The same environment can be used by different users or by team API key runs, and each will authenticate to GitHub independently. +An [environment](/agent-platform/cloud-agents/environments/) is a template for a cloud agent's sandbox — it defines the Docker image, repos, and setup commands, but it does not carry its own GitHub permissions. The same environment can be used by different users or by team API key runs, and each will authenticate to GitHub independently. The environment configuration and the **Enabled GitHub Orgs** setting in the Admin Panel serve different purposes: diff --git a/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart.mdx index 21946c90..279b7067 100644 --- a/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart.mdx @@ -1,14 +1,14 @@ --- title: Scheduled Agents quickstart description: >- - Schedule an Oz cloud agent to run recurring tasks automatically — issue + Schedule a cloud agent to run recurring tasks automatically — issue triage, dependency checks, code cleanup, and more. sidebar: label: "Quickstart" --- import VideoEmbed from '@components/VideoEmbed.astro'; -Scheduled agents are Oz cloud agents that run on a recurring cron schedule, handling recurring tasks automatically without manual triggers. This guide walks you through setting up an agent that triages your GitHub bug reports every week, checks whether each issue has enough detail to investigate, and posts follow-up comments when information is missing. You'll use a prebundled skill and the Oz web app; no CLI or custom code required. +Scheduled agents are cloud agents that run on a recurring cron schedule, handling recurring tasks automatically without manual triggers. This guide walks you through setting up an agent that triages your GitHub bug reports every week, checks whether each issue has enough detail to investigate, and posts follow-up comments when information is missing. You'll use a prebundled skill and the Oz web app; no CLI or custom code required. Watch this short demo of creating and testing a scheduled agent: @@ -18,7 +18,7 @@ Watch this short demo of creating and testing a scheduled agent: ## Prerequisites * **A Warp account on an eligible plan** - Build, Max, or Business, with credits available. See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/). -* **An Oz cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have one, follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/) to create one first. +* **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have one, follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/) to create one first. --- diff --git a/src/content/docs/agent-platform/getting-started/agents-in-warp.mdx b/src/content/docs/agent-platform/getting-started/agents-in-warp.mdx index 81548d30..9a97d156 100644 --- a/src/content/docs/agent-platform/getting-started/agents-in-warp.mdx +++ b/src/content/docs/agent-platform/getting-started/agents-in-warp.mdx @@ -1,18 +1,20 @@ --- title: Agents in Warp description: >- - Warp's Oz agents are capable collaborators that help you write code, debug + Warp's agents are capable collaborators that help you write code, debug issues, and complete terminal workflows, all from natural language prompts. --- import VideoEmbed from '@components/VideoEmbed.astro'; +Warp's agents help you write code, debug issues, and complete terminal workflows from natural language prompts. They operate with full context from your codebase, Warp Drive, and connected tools while you control their autonomy, permissions, and model choices. + -Warp includes Oz agents. These coding agents are designed to help you build, test, deploy, and debug while keeping you in control. Describe what you want to do in natural language (_you can even use your voice_), and Oz will take action using your environment, codebase, and saved context. +Warp includes powerful coding agents designed to help you build, test, deploy, and debug while keeping you in control. Describe what you want to do in natural language (_you can even use your voice_), and the agent will take action using your environment, codebase, and saved context. -## What Oz agents can do +## What agents can do -Oz agents understand your codebase and can execute tasks autonomously while keeping you in control: +Agents understand your codebase and can execute tasks autonomously while keeping you in control: * **Write and edit code** - Create new files, refactor existing code, or make changes across multiple files in your codebase * **Debug and fix errors** - Analyze stack traces, interpret error output, and apply fixes @@ -66,7 +68,7 @@ For more details, see [Agent Profiles & Permissions](/agent-platform/capabilitie ## Managing agents -You can run multiple Oz agents simultaneously in Warp. All active agents—both local conversations and cloud agent runs—are tracked in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). +You can run multiple agents simultaneously in Warp. All active agents—both local conversations and cloud agent runs—are tracked in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). Agents notify you when they need input, such as permission to run a command or approval to apply a code diff. This lets you focus on other work, knowing you'll be alerted when your attention is required. @@ -76,7 +78,7 @@ To access conversations across devices, share them with teammates, or restore pa ## Context and knowledge -Oz agents work best when they understand your codebase and workflows. Warp provides several ways to give agents the context they need: +Agents work best when they understand your codebase and workflows. Warp provides several ways to give agents the context they need: * [**Codebase Context**](/agent-platform/capabilities/codebase-context/) - Warp indexes your Git-tracked files so agents can search and understand your code * [**Rules**](/agent-platform/capabilities/rules/) - Define global and project-level guidelines that shape agent behavior @@ -88,7 +90,7 @@ Oz agents work best when they understand your codebase and workflows. Warp provi ## Third-Party CLI Agents -In addition to Warp's built-in Oz agent, Warp provides first-class support for third-party CLI coding agents like Claude Code, Codex, and OpenCode. Run any supported agent inside Warp and get rich input, code review, agent notifications, vertical tabs with agent metadata, and more. +In addition to Warp's built-in agent, Warp provides first-class support for third-party CLI coding agents like Claude Code, Codex, and OpenCode. Run any supported agent inside Warp and get rich input, code review, agent notifications, vertical tabs with agent metadata, and more. → [Learn about Third-Party CLI Agents](/agent-platform/cli-agents/overview/) @@ -96,7 +98,7 @@ In addition to Warp's built-in Oz agent, Warp provides first-class support for t ## From local to cloud -The same Oz agent capabilities that power interactive conversations in Warp also run in the cloud. Cloud agents can: +The same agent capabilities that power interactive conversations in Warp also run in the cloud. Cloud agents can: * React to events from Slack, Linear, or GitHub * Run on schedules for recurring tasks like dependency updates diff --git a/src/content/docs/agent-platform/getting-started/faqs.mdx b/src/content/docs/agent-platform/getting-started/faqs.mdx index 5c237f00..a400fed2 100644 --- a/src/content/docs/agent-platform/getting-started/faqs.mdx +++ b/src/content/docs/agent-platform/getting-started/faqs.mdx @@ -7,6 +7,8 @@ description: >- models, privacy practices, credit limits, billing, and usage guidelines. --- +Answers to frequently asked questions about Warp's agents, including supported models, data privacy, credit limits, billing, and common error messages. For billing-specific questions, see the pricing FAQs. + ## General ### What data is sent and/or stored when using Agents in Warp? diff --git a/src/content/docs/agent-platform/index.mdx b/src/content/docs/agent-platform/index.mdx index 0580760f..ee66a21e 100644 --- a/src/content/docs/agent-platform/index.mdx +++ b/src/content/docs/agent-platform/index.mdx @@ -5,7 +5,7 @@ description: >- and autonomous agents for development workflows. --- -Warp includes **Oz**, the orchestration platform for cloud agents. While Warp provides the terminal and coding surface you work in day-to-day, Oz is the underlying orchestration layer that makes running agents at scale possible. +Warp includes **Oz**, the orchestration platform that powers all of Warp's agents. Oz runs interactive agents locally inside Warp for real-time coding assistance and deploys autonomous agents in the cloud for background automation, event-driven workflows, and parallel execution across repos and teams. Warp's client is open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE-AGPL), so the editor and terminal that host your agents are fully auditable. See [Contributing to Warp](/support-and-community/community/contributing/) for the source and contribution flow. @@ -22,9 +22,9 @@ Oz is fully programmable—launch agents manually or build custom logic around t ## Key capabilities -* [**Local Agents**](/agent-platform/local-agents/overview/) - Interactive Oz agents embedded in Warp. Use natural language to write code, debug issues, run commands, and automate development tasks with full terminal access. +* [**Local Agents**](/agent-platform/local-agents/overview/) - Interactive agents embedded in Warp. Use natural language to write code, debug issues, run commands, and automate development tasks with full terminal access. * [**Third-Party CLI Agents**](/agent-platform/cli-agents/overview/) - Use Claude Code, Codex, OpenCode, and other CLI coding agents in Warp with rich input, notifications, code review, and remote session control. -* [**Oz Cloud Agents**](/agent-platform/cloud-agents/overview/) - Autonomous Oz agents that run in the background in response to system events, schedules, or integrations. +* [**Cloud Agents**](/agent-platform/cloud-agents/overview/) - Autonomous agents that run in the background in response to system events, schedules, or integrations. * [**Integrations**](/agent-platform/cloud-agents/integrations/) - Connect external system events to autonomous agent execution. Use [Slack](/agent-platform/cloud-agents/integrations/slack/), [Linear](/agent-platform/cloud-agents/integrations/linear/), [GitHub Actions](/agent-platform/cloud-agents/integrations/github-actions/), and other integrations to trigger agents in the cloud. * [**Oz Platform**](/agent-platform/cloud-agents/platform/) - The underlying infrastructure that powers Oz, including the CLI, API/SDK, orchestration layer, environments, secrets, and management/observability. @@ -32,7 +32,7 @@ Oz is fully programmable—launch agents manually or build custom logic around t ## Getting started -* [**Agents in Warp**](/agent-platform/getting-started/agents-in-warp/) - Start using Oz agents interactively in Warp +* [**Agents in Warp**](/agent-platform/getting-started/agents-in-warp/) - Start using agents interactively in Warp * [**Oz web app**](https://oz.warp.dev) - Create runs, manage schedules, browse skills, and configure integrations * [**Oz CLI**](/reference/cli/) - Run agents from the command line, in CI, or on remote machines * [**Oz API & SDK**](/reference/api-and-sdk/) - Programmatically create and monitor agent runs diff --git a/src/content/docs/agent-platform/local-agents/active-ai.mdx b/src/content/docs/agent-platform/local-agents/active-ai.mdx index 63f82f24..5bb6f8be 100644 --- a/src/content/docs/agent-platform/local-agents/active-ai.mdx +++ b/src/content/docs/agent-platform/local-agents/active-ai.mdx @@ -5,6 +5,8 @@ description: >- on your command line errors, inputs, and outputs. --- +Active AI Recommendations proactively suggest fixes and next actions based on your terminal errors, inputs, and outputs. Features include Prompt Suggestions that activate Agent Mode, Next Command predictions from your shell history, and Suggested Code Diffs that automatically surface fixes for command-line errors. + :::note Active AI features can be disabled in **Settings** > **Agents** > **Warp Agent** with the Active AI toggle. ::: diff --git a/src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx index fbe910c3..75e40d8e 100644 --- a/src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx +++ b/src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx @@ -6,6 +6,8 @@ description: >- --- import { Tabs, TabItem } from '@astrojs/starlight/components'; +Attach terminal output blocks to your agent prompts so the agent can understand errors, commands, and outputs from your current or previous sessions. Blocks can be attached with keyboard shortcuts, mouse clicks, or automatically within agent conversations. + ## Attaching blocks as context Warp’s Agent can use blocks from your Agent conversations as context to better understand your queries and generate more relevant responses. diff --git a/src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx index 50e775fc..6e7adfde 100644 --- a/src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx +++ b/src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx @@ -5,6 +5,8 @@ description: >- can use visual context when generating responses. --- +Attach screenshots, diagrams, or other images directly to agent prompts so the agent can use visual context when generating responses. Warp supports drag-and-drop, copy-paste, and file upload for up to 5 images per request across all supported models. + ## **Attaching images as context** To provide visual context, you can attach images directly to an agent prompt. This is useful for including screenshots, diagrams, or other visual references alongside your query. diff --git a/src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx index 91c7cbff..bb2f82ba 100644 --- a/src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx +++ b/src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx @@ -5,6 +5,8 @@ description: >- context for your Agent prompts. --- +Attach text selections or diff hunks directly from Warp's code editor or Code Review panel as context for agent prompts. Select code, press a keyboard shortcut, and Warp inserts the file path, line numbers, and content into your prompt automatically. + ### Attaching selections from Warp's native code editor When you have Warp’s [native code editor](/code/code-editor/) open beside a regular pane, you can easily attach specific lines of code as context: diff --git a/src/content/docs/agent-platform/local-agents/agent-context/urls-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/urls-as-context.mdx index c416ed2d..25ae2fef 100644 --- a/src/content/docs/agent-platform/local-agents/agent-context/urls-as-context.mdx +++ b/src/content/docs/agent-platform/local-agents/agent-context/urls-as-context.mdx @@ -5,6 +5,8 @@ description: >- content. --- +Attach a public URL to any agent prompt to provide page content as context. Warp scrapes the page and surfaces the extracted text directly to the model, giving the agent access to documentation, references, or any publicly accessible web content. + ## Referencing websites via URLs You can attach a public URL to any prompt to provide page content as context. Warp will scrape the page and surface the extracted text directly to the model. diff --git a/src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx index c2b67403..32777665 100644 --- a/src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx +++ b/src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx @@ -6,6 +6,8 @@ description: >- --- import VideoEmbed from '@components/VideoEmbed.astro'; +Use the @ symbol in agent prompts to reference files, folders, code symbols, Warp Drive objects, and blocks from other sessions as context. The @ menu searches your entire Git repository from the project root and works immediately without codebase indexing. + ## How the @ context menu works You can attach specific files, folders, code symbols, Warp Drive objects, and blocks from other sessions as context to a prompt using the @ symbol. When you’re inside a **Git repository**, typing @ opens a context menu that allows you to search for and select files or directories to include. diff --git a/src/content/docs/agent-platform/local-agents/code-diffs.mdx b/src/content/docs/agent-platform/local-agents/code-diffs.mdx index c2ca0fb3..e8abece9 100644 --- a/src/content/docs/agent-platform/local-agents/code-diffs.mdx +++ b/src/content/docs/agent-platform/local-agents/code-diffs.mdx @@ -8,6 +8,8 @@ description: >- --- import VideoEmbed from '@components/VideoEmbed.astro'; +When Warp's agent generates code changes, they appear as visual diffs in a built-in editor. Review proposed changes line by line, refine them with natural language, make manual edits, or accept them to apply the modifications to your files. + ## Reviewing code diffs During an Agent Conversation, Warp can generate code diffs that open directly in a built-in diff editor. diff --git a/src/content/docs/agent-platform/local-agents/generate.mdx b/src/content/docs/agent-platform/local-agents/generate.mdx index 55cf5000..93be673f 100644 --- a/src/content/docs/agent-platform/local-agents/generate.mdx +++ b/src/content/docs/agent-platform/local-agents/generate.mdx @@ -8,6 +8,8 @@ description: >- import { Tabs, TabItem } from '@astrojs/starlight/components'; import VideoEmbed from '@components/VideoEmbed.astro'; +Generate (Legacy) turns natural language queries into precise terminal commands or contextual suggestions inside interactive CLI tools. Type `#` in the command line to describe what you want, and Warp generates the matching command in real time. + ## What is Generate? Generate helps turn natural language queries into precise commands as terminal input or contextual suggestions inside interactive commands and programs, whether you're using psql, gdb, git, mysql, or any other CLI tool. diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx index 9aa4a052..6438f547 100644 --- a/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx +++ b/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx @@ -7,6 +7,8 @@ description: >- import { Tabs, TabItem } from '@astrojs/starlight/components'; import VideoEmbed from '@components/VideoEmbed.astro'; +Agent conversations in Warp are multi-turn interactions tied to terminal sessions. Continue previous threads with follow-ups, manage conversation history, attach context from blocks and files, and run multiple conversations simultaneously across windows, tabs, or panes. + ## Conversations with Warp's Agent Conceptually, a conversation is a sequence of AI queries and blocks. Conversations are tied to sessions and you can run multiple Agent Mode conversations simultaneously in different windows, tabs, or panes. diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx index d7386c6c..fa693766 100644 --- a/src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx +++ b/src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx @@ -6,7 +6,7 @@ description: >- --- import VideoEmbed from '@components/VideoEmbed.astro'; -Warp provides two distinct modes: a clean terminal for commands, and a dedicated conversation view for multi-turn conversations with [Oz, Warp's agent](/agent-platform/local-agents/interacting-with-agents/). +Warp provides two distinct modes: a clean terminal for running shell commands, and a dedicated conversation view for multi-turn interactions with Oz, Warp's agent. Terminal mode keeps the interface minimal by default, while Agent Mode surfaces full controls for model selection, voice input, image attachments, and conversation management. @@ -17,7 +17,7 @@ Warp provides two distinct modes: a clean terminal for commands, and a dedicated Before diving in, here are two key concepts: * **Terminal session** - Your shell environment where you run commands. This is the default mode when you open Warp—a clean, traditional terminal input. -* **Oz agent conversation** - A multi-turn interaction with Oz. Conversations maintain context across exchanges and have their own dedicated view with richer controls. +* **Agent conversation** - A multi-turn interaction with Oz. Conversations maintain context across exchanges and have their own dedicated view with richer controls. Terminal and Agent modes make switching between these two contexts seamless while keeping them visually distinct. @@ -67,7 +67,7 @@ If you disable the message bar while auto-detection is enabled, you won't see th The shortcuts shown on this page use macOS keybindings. For Windows and Linux shortcuts, see [Keyboard Shortcuts](/getting-started/keyboard-shortcuts/). ::: -### Oz agent conversation view (expanded UI) +### Agent conversation view (expanded UI) * A dedicated conversation view with richer agent controls including model select, voice input, image attachments, and conversation management. * Familiar "charms" (current directory, git branch, diff view entry point, etc.) are still available. @@ -111,7 +111,7 @@ This separation keeps your terminal view clean while preserving full context wit #### Cloud agent conversations -In addition to local agent conversations, you can start **Oz cloud agent conversations** that run in an isolated cloud environment. Cloud agents are useful for: +In addition to local agent conversations, you can start **cloud agent conversations** that run in an isolated cloud environment. Cloud agents are useful for: * Running parallel agents across multiple tasks * Running agents remotely on hosted computers (offloading compute from your local machine) @@ -124,7 +124,7 @@ Cloud agent conversations have a few differences from local conversations: * **Environment selector** - Choose which [Warp Environment](/agent-platform/cloud-agents/environments/) to run in * **Credits indicator** - Shows your remaining cloud agent credits -* **Different zero state** - The conversation header indicates "New Oz cloud agent conversation" +* **Different zero state** - The conversation header indicates "New cloud agent conversation" Cloud agent conversations are always stored in the cloud. For more details on accessing and sharing cloud conversations, see [Cloud-synced Conversations](/agent-platform/local-agents/cloud-conversations/). @@ -189,7 +189,7 @@ Auto-detection is enabled by default for new Warp users. For users who had Warp ### How to enter a conversation -There are several ways to start or enter an Oz agent conversation: +There are several ways to start or enter an agent conversation: #### A) Use the `/agent` or `/new` slash command @@ -311,7 +311,7 @@ If you prefer to type natural language at any point in a terminal session and ha ### Step 1 — Set new tabs to open in agent view -By default, new tabs and panes open in terminal mode. To launch directly into an Oz agent conversation instead: +By default, new tabs and panes open in terminal mode. To launch directly into an agent conversation instead: 1. Go to **Settings** > **Features** > **General**. 2. Change **Default mode for new sessions** to **Agent**. diff --git a/src/content/docs/agent-platform/local-agents/interactive-code-review.mdx b/src/content/docs/agent-platform/local-agents/interactive-code-review.mdx index b568d9f7..05837456 100644 --- a/src/content/docs/agent-platform/local-agents/interactive-code-review.mdx +++ b/src/content/docs/agent-platform/local-agents/interactive-code-review.mdx @@ -6,6 +6,8 @@ description: >- --- import VideoEmbed from '@components/VideoEmbed.astro'; +Interactive Code Review lets you review agent-generated code, leave inline comments on specific lines, batch your feedback, and send all requested changes to the agent in a single pass. It works with Warp's native agent and supported third-party CLI agents like Claude Code and Codex. + ### Overview Interactive Code Review lets you review, annotate, and refine code generated by any supported agent, whether that's Warp's native Agent or a third-party CLI agent running in Warp. Instead of relying on an AI to review another AI's output, Warp keeps the developer in control. diff --git a/src/content/docs/agent-platform/local-agents/overview.mdx b/src/content/docs/agent-platform/local-agents/overview.mdx index 2764ed64..c1cf191f 100644 --- a/src/content/docs/agent-platform/local-agents/overview.mdx +++ b/src/content/docs/agent-platform/local-agents/overview.mdx @@ -6,9 +6,11 @@ description: >- Environment. --- +Warp's local agents are interactive agents embedded directly in the terminal that help you write code, debug issues, run commands, and automate development tasks using natural language. Agents operate with full context from your codebase, Warp Drive, and connected tools, while you stay in control of every action. + ## AI in Warp -Warp includes intelligent Oz agents designed to help you build, test, deploy, and debug while keeping you in control. Interactive agent conversations in Warp can look up commands, execute tasks, fix bugs, and adapt to your workflows. You can manage agent behavior directly, with full context from your Warp Drive and your team. +Warp includes intelligent agents designed to help you build, test, deploy, and debug while keeping you in control. Interactive agent conversations in Warp can look up commands, execute tasks, fix bugs, and adapt to your workflows. You can manage agent behavior directly, with full context from your Warp Drive and your team. :::note Warp's AI features can be globally disabled in **Settings** > **Agents** > **Warp Agent** with the AI toggle.\ diff --git a/src/content/docs/agent-platform/local-agents/session-sharing.mdx b/src/content/docs/agent-platform/local-agents/session-sharing.mdx index 7982c6dd..b052f651 100644 --- a/src/content/docs/agent-platform/local-agents/session-sharing.mdx +++ b/src/content/docs/agent-platform/local-agents/session-sharing.mdx @@ -24,7 +24,7 @@ When you share an agent session, Warp publishes it to the cloud and generates a ## Sharing a session -1. Start or open an agent session in Warp. The agent can be an Oz agent, a third-party coding agent, or any interactive agent running in your terminal. +1. Start or open an agent session in Warp. The agent can be Warp's built-in agent, a third-party coding agent, or any interactive agent running in your terminal. 2. Open the share action from any of these entry points: * **Command Palette** - Search for "Share session" * **Pane header** - Click the overflow menu in the pane header diff --git a/src/content/docs/changelog/2026.mdx b/src/content/docs/changelog/2026.mdx index 2e07e788..fcefed2f 100644 --- a/src/content/docs/changelog/2026.mdx +++ b/src/content/docs/changelog/2026.mdx @@ -390,7 +390,7 @@ Submit bugs and feature requests on our [GitHub board!](https://github.com/warpd * \[macOS] Right-clicking on text files in Finder allows you to open in Warp's code editor. * Send code review comments, attach diff hunks as context, and send substrings as context (`cmd L`) to 3rd party CLI tools such as Claude Code, Codex, Opencode, etc. -* Oz agents can now ask users clarifying questions during Agent Mode interactions. +* Agents can now ask users clarifying questions during Agent Mode interactions. * Warp's agent now suggests followups when it is done. **Improvements** @@ -401,7 +401,7 @@ Submit bugs and feature requests on our [GitHub board!](https://github.com/warpd * Added "Sign up" option to the settings gear menu for non-logged-in users. * MCP config files edited by the agent now show an 'Open config' button in the code diff header, making it easy to jump directly to the config file. * Added `/skills` support in CLI agent rich input for browsing and invoking agent-specific skills. -* Sandboxed Oz agents now have dedicated autonomy settings, instead of inheriting the team-level defaults. +* Sandboxed agents now have dedicated autonomy settings, instead of inheriting the team-level defaults. * Updated settings info icon tooltips to clarify they open documentation. * Improved quality and latency of prompt suggestions and suggested code diffs. * Cloud agents can now accept images and file attachments as context. @@ -430,7 +430,7 @@ Submit bugs and feature requests on our [GitHub board!](https://github.com/warpd * Fixed Oz session sharing failing behind HTTP proxies on port 80. * The `OZ_RUN_ID` environment variable is now available inside agent terminal sessions, set to the current task ID. * Improved error messages when agent session sharing fails, removing repetitive text and providing clearer guidance. -* Oz agents can now ask users clarifying questions during Agent Mode interactions. +* Agents can now ask users clarifying questions during Agent Mode interactions. ### 2026.03.25 (v0.2026.03.25.08.24) @@ -579,12 +579,12 @@ Submit bugs and feature requests on our [GitHub board!](https://github.com/warpd * Fixed "open file" button in code review diff view not working when the pane is maximized. * Fixed git metadata background operations after a terminal is closed. * Mobile soft keyboard will now work for LRCs. -* Oz agents now report more detailed information about session-sharing failures. +* Agents now report more detailed information about session-sharing failures. **Oz updates** -* Oz agent tasks now report structured error codes to the server, enabling better error tracking and retryability handling. -* Fixed Oz cloud agent not waiting for automatic error retry on network failures. +* Agent tasks now report structured error codes to the server, enabling better error tracking and retryability handling. +* Fixed cloud agent not waiting for automatic error retry on network failures. * Added support for passing arguments to skill invocations (`$ARGUMENTS`, `$N`) and for including user queries with the invocation. ### 2026.02.25 (v0.2026.02.25.08.24) @@ -657,7 +657,7 @@ Oz is Warp's orchestration platform for cloud agents: launch parallel agents, au [Read the launch post →](https://www.warp.dev/blog/oz-orchestration-platform-cloud-agents) -#### Oz Cloud Agents +#### Cloud Agents * **Run Cloud Agents from anywhere with built-in tracking** — start agents from Warp or via the CLI, triggers, or schedules. Every run is auditable and steerable. [Cloud Agents docs →](https://docs.warp.dev/agent-platform/cloud-agents/overview) * **Cloud environments for consistent execution** — configure Docker-based environments (unlimited repos + setup commands) and run agents in isolated cloud sandboxes. [Environments docs →](https://docs.warp.dev/agent-platform/cloud-agents/environments) diff --git a/src/content/docs/code/code-editor/code-editor-vim-keybindings.mdx b/src/content/docs/code/code-editor/code-editor-vim-keybindings.mdx index cd5c6379..75226cf1 100644 --- a/src/content/docs/code/code-editor/code-editor-vim-keybindings.mdx +++ b/src/content/docs/code/code-editor/code-editor-vim-keybindings.mdx @@ -7,6 +7,8 @@ sidebar: label: "Code editor Vim keybindings" --- +Warp's built-in code editor supports native Vim keybindings for keyboard-driven navigation and editing. Enable Vim mode to use familiar motions, text objects, visual mode, registers, and editing commands directly in Warp without switching to an external editor. + ## About Vim keybindings The Vi family of programs (including Vim and Neovim) are modal text editors that allow for keyboard-driven text editing. Vi-style keybindings are especially popular among developers for their speed and precision in navigating and manipulating code. Warp’s [code editor](/code/code-editor/) now includes native support for Vim keybindings (also known as Vim mode), offering a familiar editing experience directly within your coding workflows. diff --git a/src/content/docs/code/code-editor/file-tree.mdx b/src/content/docs/code/code-editor/file-tree.mdx index a6ab1345..2a870704 100644 --- a/src/content/docs/code/code-editor/file-tree.mdx +++ b/src/content/docs/code/code-editor/file-tree.mdx @@ -5,6 +5,8 @@ description: >- context menu actions. --- +The File Tree is Warp's built-in project explorer for browsing, opening, and managing files alongside your terminal. It automatically reflects your project structure and supports context menu actions like attaching files as agent context, copying paths, and creating new files. + ![Warp's native file tree showing the project's file and folder structure in the left panel.](../../../../assets/terminal/filetree-main.png) Warp includes a **native file tree** that makes it easy to explore and manage project files. The file tree is available whenever in any directory and it automatically reflects your project structure as files are added, removed, or changed. diff --git a/src/content/docs/code/code-editor/find-and-replace.mdx b/src/content/docs/code/code-editor/find-and-replace.mdx index 073695fb..5b52870c 100644 --- a/src/content/docs/code/code-editor/find-and-replace.mdx +++ b/src/content/docs/code/code-editor/find-and-replace.mdx @@ -8,6 +8,8 @@ sidebar: --- import DemoVideo from '@components/DemoVideo.astro'; +Warp's code editor includes built-in find and replace with support for regex, case sensitivity, and smart case preservation. Search across a file, jump between matches, and replace text with automatic casing adjustments for PascalCase, camelCase, and hyphenated patterns. + ## Find Press `CMD-F` on macOS or `CTRL-SHIFT-F` on Windows and Linux to open the find menu. As you type, all matches in the file are highlighted, and the match closest to your cursor is selected. diff --git a/src/content/docs/code/code-review.mdx b/src/content/docs/code/code-review.mdx index f532917d..f411412e 100644 --- a/src/content/docs/code/code-review.mdx +++ b/src/content/docs/code/code-review.mdx @@ -7,6 +7,8 @@ description: >- import DemoVideo from '@components/DemoVideo.astro'; import VideoEmbed from '@components/VideoEmbed.astro'; +The Code Review panel lets you inspect, edit, and manage Git diffs directly inside Warp. Review uncommitted changes or compare branches, attach diffs as context for agents, revert specific hunks, and leave inline comments that agents can act on in real time. + ## Overview When you are working locally in a Git repository with uncommitted changes, the **Code Review panel** lets you inspect, edit, and manage code changes directly inside Warp. It integrates with Git and Warp's Agents, giving you the ability to: diff --git a/src/content/docs/code/overview.mdx b/src/content/docs/code/overview.mdx index a5abd773..3e2b7787 100644 --- a/src/content/docs/code/overview.mdx +++ b/src/content/docs/code/overview.mdx @@ -6,6 +6,8 @@ description: >- --- import VideoEmbed from '@components/VideoEmbed.astro'; +Warp's coding features help you go from prompt to production. They combine a dedicated coding agent — consistently ranked among the top on SWE-bench Verified — with a native code editor, inline diff review, codebase context, and project-level rules for accurate, context-aware code generation. + :::note On macOS and Linux SSH sessions, Warp's [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) brings the file tree, native file reads, and native code diffs to remote hosts. See [Feature support over SSH](/code/ssh-feature-support/) for the current support matrix. ::: diff --git a/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx b/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx index 43009fae..37dc72dc 100644 --- a/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx +++ b/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx @@ -29,7 +29,7 @@ Warp's cloud agent infrastructure has four key components: ## Warp-hosted (SaaS) -Warp-hosted is the default deployment model. Oz agents run on Warp-managed infrastructure with no setup required from your team. +Warp-hosted is the default deployment model. Agents run on Warp-managed infrastructure with no setup required from your team. ### How it works diff --git a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx index 326b7314..e81d7032 100644 --- a/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx +++ b/src/content/docs/enterprise/enterprise-features/bring-your-own-llm.mdx @@ -12,7 +12,7 @@ This gives you control over cloud spend and model hosting, without changing how :::caution BYOLLM currently supports **AWS Bedrock** only. Coming soon: Azure Foundry and Google Vertex support. -BYOLLM applies to interactive Oz agents in the terminal. Oz cloud agents do not yet support BYOLLM routing. +BYOLLM applies to interactive agents in the terminal. Cloud agents do not yet support BYOLLM routing. ::: :::note @@ -35,7 +35,7 @@ Here's the high-level flow: 1. **Admin configures routing** - Your team admin sets routing policies in Warp's admin settings (e.g., "Route Claude Sonnet 4.5 through AWS Bedrock; disable direct Anthropic API"). 2. **Team members authenticate** - Each team member authenticates to AWS locally using the AWS CLI (`aws login`). -3. **Warp routes requests** - When a team member uses an interactive Oz agent in the terminal, Warp uses their short-lived session credentials to authenticate requests to your configured AWS Bedrock API endpoint. +3. **Warp routes requests** - When a team member uses an interactive agent in the terminal, Warp uses their short-lived session credentials to authenticate requests to your configured AWS Bedrock API endpoint. 4. **Inference executes in your cloud** - The model runs in your AWS account. Responses return to the Warp client. ### Credential lifecycle diff --git a/src/content/docs/enterprise/getting-started/getting-started-developers.mdx b/src/content/docs/enterprise/getting-started/getting-started-developers.mdx index 66ba2fe1..1e5ac983 100644 --- a/src/content/docs/enterprise/getting-started/getting-started-developers.mdx +++ b/src/content/docs/enterprise/getting-started/getting-started-developers.mdx @@ -7,10 +7,10 @@ description: >- This guide helps developers get up and running with their team in Warp. You'll learn how to download Warp, log in with your organization's SSO, and configure key features like Codebase Context, Warp Drive, and Agent Profiles to accelerate your work across the entire SDLC (all while staying in your terminal). -When you use agents in Warp, you're using **Oz agents**. Oz is Warp's programmable agent for running and coordinating agents at scale, whether they run locally on your machine or in the cloud. Oz provides the orchestration, tracking, and control plane that makes scaling agent workflows seamless. +When you use agents in Warp, you're working with **Warp's built-in agents**. Oz is Warp's programmable agent for running and coordinating agents at scale, whether they run locally on your machine or in the cloud. Oz provides the orchestration, tracking, and control plane that makes scaling agent workflows seamless. :::note -New to Warp Enterprise? Try the [Enterprise quickstart](/enterprise/getting-started/quickstart/) for a 10-minute walkthrough of SSO login, Warp setup, and running your first Oz agent. +New to Warp Enterprise? Try the [Enterprise quickstart](/enterprise/getting-started/quickstart/) for a 10-minute walkthrough of SSO login, Warp setup, and running your first agent. ::: ## Step 1: Download and install Warp @@ -121,13 +121,13 @@ Once codebase indexing is enabled, you can index individual repositories: During indexing, your code is sent to Warp's servers for processing where embeddings are created and stored. The code itself is not saved—only the embeddings are persisted. This allows agents to understand your codebase structure and context without storing your actual source code. :::note -For Oz cloud agents: Code snippets may be stored as part of conversation records when agents create or modify files, since diffs are preserved in the conversation history. +For cloud agents: Code snippets may be stored as part of conversation records when agents create or modify files, since diffs are preserved in the conversation history. ::: ### Agent Profiles {/* Warp also supports third-party CLI agents (Claude Code, Codex, Copilot), so we say "built-in" rather than "every." */} -Agent Profiles let you configure how Warp's built-in Oz agents behave. Profiles give you direct control over model selection, autonomy, tools, and permissions for your agent workflows. +Agent Profiles let you configure how Warp's built-in agents behave. Profiles give you direct control over model selection, autonomy, tools, and permissions for your agent workflows. **Creating an Agent Profile:** @@ -232,7 +232,7 @@ Warp keeps you in your terminal with agent help across the entire SDLC: **Testing** * "Write unit tests for this function following our existing patterns" * "Run the test suite and explain what failed" -* Configure Oz cloud agents to run test suites and validate coverage on PRs in the background +* Configure cloud agents to run test suites and validate coverage on PRs in the background ### Learning resources @@ -251,7 +251,7 @@ For common login, SSO, and access issues, see the [Enterprise FAQ](/enterprise/g Now that you're set up: -* **Explore agent capabilities** - Learn about [agents in Warp](/agent-platform/local-agents/overview/) and [Oz cloud agents](/agent-platform/cloud-agents/overview/) +* **Explore agent capabilities** - Learn about [agents in Warp](/agent-platform/local-agents/overview/) and [cloud agents](/agent-platform/cloud-agents/overview/) * **Contribute to team knowledge** - Add useful Workflows, Prompts, and Rules to your team's Warp Drive to compound productivity gains across your team * **Stay updated** - Check the [Warp changelog](/changelog/) for new features diff --git a/src/content/docs/enterprise/getting-started/getting-started-enterprise.mdx b/src/content/docs/enterprise/getting-started/getting-started-enterprise.mdx index 478d07b8..9ce05e1d 100644 --- a/src/content/docs/enterprise/getting-started/getting-started-enterprise.mdx +++ b/src/content/docs/enterprise/getting-started/getting-started-enterprise.mdx @@ -113,7 +113,7 @@ Alternatively, visit [app.warp.dev/admin](https://app.warp.dev/admin) directly. * **AI** - Configure general and AI autonomy settings for your team * **Models** - Configure which models are available to your team and AWS Bedrock * **Code** - Enable Codebase Context for your team -* **Platform** - Configure Oz cloud agent settings +* **Platform** - Configure cloud agent settings * **Privacy** - Configure user-generated content data collection, cloud conversation storage, and enterprise secret redaction * **Sharing** - Configure direct link sharing and "anyone with link" sharing permissions @@ -163,7 +163,7 @@ Once your team is set up: * **Agent Profiles** - Configure default [Agent Profiles](/agent-platform/capabilities/agent-profiles-permissions/) for different types of work to give teams appropriate autonomy and control * **BYOLLM** - Set up [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) to route inference through your cloud infrastructure for data locality and cost control * **Monitor usage** - Review usage analytics in the Admin Panel to track adoption and measure engineering productivity gains -* **Self-hosting** - Run Oz agents on your own infrastructure to control where agents run and keep repository clones on your own machines. See [Self-Hosting](/agent-platform/cloud-agents/self-hosting/) for setup instructions +* **Self-hosting** - Run agents on your own infrastructure to control where agents run and keep repository clones on your own machines. See [Self-Hosting](/agent-platform/cloud-agents/self-hosting/) for setup instructions ## Troubleshooting diff --git a/src/content/docs/enterprise/getting-started/quickstart.mdx b/src/content/docs/enterprise/getting-started/quickstart.mdx index 963e162c..2dcfc351 100644 --- a/src/content/docs/enterprise/getting-started/quickstart.mdx +++ b/src/content/docs/enterprise/getting-started/quickstart.mdx @@ -2,12 +2,12 @@ title: Enterprise quickstart description: >- Get up and running with Warp Enterprise in under 10 minutes. Log in, set up - your terminal, and run your first Oz agent. + your terminal, and run your first agent. sidebar: label: "Quickstart" --- -This quickstart walks you through the essentials: logging in via SSO, setting up Warp, and running your first Oz agent. You can complete this in under 10 minutes. +This quickstart walks you through the essentials: logging in via SSO, setting up Warp, and running your first agent. You can complete this in under 10 minutes. ## Step 1: Log in via SSO @@ -32,20 +32,20 @@ If you have an existing Warp account from before your organization enabled SSO, 3. Launch Warp and log in with SSO (Step 1). 4. Verify you see your team name in **Settings** > **Teams**. -## Step 3: Configure and run your first Oz agent +## Step 3: Configure and run your first agent -When you use agents in Warp, you're using **Oz agents**. Oz is Warp's programmable agent for running and coordinating agents at scale, whether they run locally on your machine or in the cloud. +When you use agents in Warp, you're working with **Warp's built-in agents**. Oz is Warp's programmable agent for running and coordinating agents at scale, whether they run locally on your machine or in the cloud. ### Index your codebase 1. Navigate to a Git repository in Warp. 2. Warp automatically detects the repo and begins indexing. 3. Optionally, run `/init` to manually trigger indexing or re-indexing after significant code changes. -4. Once indexed, Oz agents understand your code structure, patterns, and conventions. +4. Once indexed, agents understand your code structure, patterns, and conventions. -### Run your first Oz agent locally +### Run your first agent locally -Start an Oz conversation right in the terminal. Try the following prompt: +Start a conversation right in the terminal. Try the following prompt: ``` Explain the architecture of this project @@ -60,9 +60,9 @@ Oz reads your codebase, understands its structure, and responds with a context-a * **Explore** - "What patterns does this repo use for error handling?" * **Plan** - Use `/plan` to have Oz create a structured task plan for complex features -## Step 4: Run an Oz cloud agent +## Step 4: Run a cloud agent -Oz cloud agents run in the cloud for background work, unlimited parallelization, and long-running tasks. +Cloud agents run in the cloud for background work, unlimited parallelization, and long-running tasks. ### Create an environment @@ -88,10 +88,10 @@ Once your environment is ready, use the following command to launch a cloud agen oz agent run-cloud --env my-env --prompt "Review the open PRs in this repo" ``` -Monitor and steer Oz cloud agents from the Oz dashboard or directly in Warp. +Monitor and steer cloud agents from the Oz dashboard or directly in Warp. ## Next steps * **Set up key features** - Follow the full [Getting started for developers](/enterprise/getting-started/getting-started-developers/) guide to configure Codebase Context, Warp Drive, MCP integrations, and Agent Profiles. -* **Explore Oz cloud agents** - Learn about [Oz cloud agents](/agent-platform/cloud-agents/overview/) for background automation and parallel workflows. +* **Explore cloud agents** - Learn about [cloud agents](/agent-platform/cloud-agents/overview/) for background automation and parallel workflows. * **Learn more** - Visit [Warp Guides](/guides/) for video tutorials and end-to-end workflows. diff --git a/src/content/docs/enterprise/index.mdx b/src/content/docs/enterprise/index.mdx index 2b7aa966..458c0d82 100644 --- a/src/content/docs/enterprise/index.mdx +++ b/src/content/docs/enterprise/index.mdx @@ -40,11 +40,11 @@ Warp Enterprise serves three primary audiences: * **Warp Drive team workspace** - Share Workflows, Notebooks, Prompts, Plans, Rules, and Environment Variables across your team * **Codebase Context** - Team-level code indexing helps agents understand your repositories and generate accurate, context-aware responses * **MCP integrations** - Connect to your team's tools (Linear, Sentry, Figma, GitHub, and more) for context-aware agent responses -* **Session sharing** - Collaborate on terminal sessions and Oz conversations with shareable links +* **Session sharing** - Collaborate on terminal sessions and conversations with shareable links -### Oz agent capabilities +### Agent capabilities * **State-of-the-art agents** - Multi-model agents with full terminal access, code editing, and autonomous task execution -* **Oz cloud agents** - Run agents in the cloud for unlimited parallelization, background automation, and long-running workflows. Perfect for PR reviews, scheduled tasks, and distributed work across multiple repositories +* **Cloud agents** - Run agents in the cloud for unlimited parallelization, background automation, and long-running workflows. Perfect for PR reviews, scheduled tasks, and distributed work across multiple repositories * **Integrated control plane** - Launch, orchestrate, and manage local, cloud, and autonomous agents from a unified interface. Track all agent activity across your team from the Oz dashboard * **Agent Profiles** - Customize agent behavior, models, autonomy levels, and permissions * **Rules and guardrails** - Enforce coding standards, tech stack preferences, and security practices through team-wide or project-specific rules diff --git a/src/content/docs/enterprise/security-and-compliance/security-overview.mdx b/src/content/docs/enterprise/security-and-compliance/security-overview.mdx index 82febd95..b5101594 100644 --- a/src/content/docs/enterprise/security-and-compliance/security-overview.mdx +++ b/src/content/docs/enterprise/security-and-compliance/security-overview.mdx @@ -119,7 +119,7 @@ Warp's operational security practices — including access controls, monitoring, ### Self-hosted deployments -Enterprise teams can self-host Oz cloud agent execution to control where agents run and keep repositories on their own infrastructure. +Enterprise teams can self-host cloud agent execution to control where agents run and keep repositories on their own infrastructure. Self-hosted deployments use a split architecture: * **Execution plane (customer-hosted)** - Repository clones, build artifacts, runtime secrets, and container filesystem state stay on your infrastructure @@ -158,7 +158,7 @@ Security-relevant controls include: * **Sharing** - Restrict or permit direct link sharing and "anyone with link" sharing permissions * **AI** - Configure AI autonomy settings and general agent behavior for the team * **Models** - Control which LLM models are available to team members, including AWS Bedrock -* **Platform** - Configure Oz cloud agent access and settings +* **Platform** - Configure cloud agent access and settings ## Security features for developers diff --git a/src/content/docs/enterprise/support-and-resources/billing.mdx b/src/content/docs/enterprise/support-and-resources/billing.mdx index 5d4bb48e..b9f91462 100644 --- a/src/content/docs/enterprise/support-and-resources/billing.mdx +++ b/src/content/docs/enterprise/support-and-resources/billing.mdx @@ -11,7 +11,7 @@ This page covers general information about credits, cloud agent costs, and BYOLL ## Credits -Warp uses a credit-based billing model. Any interaction with Oz agents consumes credits based on the complexity of the task, the model used, and the amount of context processed. +Warp uses a credit-based billing model. Any interaction with agents consumes credits based on the complexity of the task, the model used, and the amount of context processed. ### How credits work @@ -31,7 +31,7 @@ Credit allocations vary by contract. Contact your account manager for details on ## Cloud agent billing -Oz cloud agents consume AI credits for inference, compute credits for the sandbox they run in, and platform credits for the orchestration layer. See [Credits](/support-and-community/plans-and-billing/credits/) for the full breakdown of how each credit type is metered. +Cloud agents consume AI credits for inference, compute credits for the sandbox they run in, and platform credits for the orchestration layer. See [Credits](/support-and-community/plans-and-billing/credits/) for the full breakdown of how each credit type is metered. ### How credits are consumed @@ -65,7 +65,7 @@ Administrators can configure monthly spending limits and receive alerts to preve Enterprise administrators can set monthly spending limits across the following four categories: -* **Cloud spending limit** - Cap monthly spend on Oz cloud agent usage. +* **Cloud spending limit** - Cap monthly spend on cloud agent usage. * **Local spending limit** - Cap monthly spend on local agent usage in the Warp app. * **Total spending limit** - Cap combined monthly spend across both cloud and local agents. * **Per-user spending limit** - Cap monthly spend for any individual user. Set a default that applies to all users, or configure limits on a per-user basis for predictable individual spend. diff --git a/src/content/docs/enterprise/team-management/admin-panel.mdx b/src/content/docs/enterprise/team-management/admin-panel.mdx index be62cc25..a6dd8d75 100644 --- a/src/content/docs/enterprise/team-management/admin-panel.mdx +++ b/src/content/docs/enterprise/team-management/admin-panel.mdx @@ -102,7 +102,7 @@ The features available in the Admin Panel scale with your Warp plan: * **Full admin control** - Configure all available settings * **Enterprise secret redaction** - Custom regex patterns for secrets * **BYOLLM** - Route inference through your cloud infrastructure -* **Self-hosting cloud agent workers** - Deploy Oz cloud agent workers on your own infrastructure +* **Self-hosting cloud agent workers** - Deploy cloud agent workers on your own infrastructure * **Advanced compliance** - SOC 2, HIPAA, and custom data handling agreements * **Priority support** - Dedicated Slack/Teams channels @@ -248,11 +248,11 @@ For organizations with sensitive internal processes, disable "Anyone with link" ### Platform settings -Configure Oz cloud agent settings for your team, including GitHub authorization for automated workflows. +Configure cloud agent settings for your team, including GitHub authorization for automated workflows. **Enabled GitHub Orgs** -The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations, enabling Oz cloud agents initiated with a [team API key](/reference/cli/api-keys/) to clone repositories and open pull requests using the Oz by Warp GitHub App. +The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations, enabling cloud agents initiated with a [team API key](/reference/cli/api-keys/) to clone repositories and open pull requests using the Oz by Warp GitHub App. To configure: diff --git a/src/content/docs/enterprise/team-management/roles-and-permissions.mdx b/src/content/docs/enterprise/team-management/roles-and-permissions.mdx index df5bd074..3481d097 100644 --- a/src/content/docs/enterprise/team-management/roles-and-permissions.mdx +++ b/src/content/docs/enterprise/team-management/roles-and-permissions.mdx @@ -44,7 +44,7 @@ Team Admins cannot demote or modify the Team Owner role. ### What members can do -* **Use agents** - Run Oz agents locally and in the cloud within the policies admins define. +* **Use agents** - Run agents locally and in the cloud within the policies admins define. * **Access team resources** - Use shared Workflows, Notebooks, Prompts, Rules, and Environment Variables in Warp Drive. * **Configure personal settings** - Adjust settings where admins have selected "Respect User Setting." * **Share sessions** - Collaborate via session sharing (if enabled by admins). diff --git a/src/content/docs/getting-started/supported-shells.mdx b/src/content/docs/getting-started/supported-shells.mdx index 7b0d9ed1..45ba8e84 100644 --- a/src/content/docs/getting-started/supported-shells.mdx +++ b/src/content/docs/getting-started/supported-shells.mdx @@ -7,6 +7,8 @@ sidebar: label: "Supported shells" --- +Warp supports bash, zsh, fish, and PowerShell (pwsh) across macOS, Windows, and Linux, loading your login shell by default. You can change the default shell per-session, customize each shell's configuration files and environment variables, and install additional shells like fish or PowerShell on macOS. + ## Warp default shell Warp tries to load your login shell by default. Currently, Warp supports bash, fish, zsh, and PowerShell (pwsh). If your login shell is set to something else (e.g. Nushell) Warp will show a banner indicating it's not supported and load the default shells listed below: diff --git a/src/content/docs/guides/configuration/how-to-set-up-self-serve-data-analytics-with-skills.mdx b/src/content/docs/guides/configuration/how-to-set-up-self-serve-data-analytics-with-skills.mdx index d9d78fe2..d3e7bcdd 100644 --- a/src/content/docs/guides/configuration/how-to-set-up-self-serve-data-analytics-with-skills.mdx +++ b/src/content/docs/guides/configuration/how-to-set-up-self-serve-data-analytics-with-skills.mdx @@ -19,7 +19,7 @@ Self-serve data analytics means anyone on your team can ask a data question and ## Walkthrough video -In this 40-minute livestream, Warp's data team demonstrates the workflow end-to-end, including the two Skills you'll install below and a third pattern (running the same Skills from Slack via an Oz cloud agent). Feel free to skip ahead if you prefer to follow the written steps. +In this 40-minute livestream, Warp's data team demonstrates the workflow end-to-end, including the two Skills you'll install below and a third pattern (running the same Skills from Slack via a cloud agent). Feel free to skip ahead if you prefer to follow the written steps. @@ -176,7 +176,7 @@ The `analysis-artifacts` Skill is largely stack-agnostic. It structures outputs, You installed two community Skills, customized the model index for your warehouse, and ran both a simple lookup and a full deep-dive analysis. -**Extend to Slack.** Wire the same two Skills into an Oz cloud agent configured with your dbt repo, and your teammates can ask data questions by @-mentioning Oz in a Slack channel, without opening a terminal. The Agent clones the repo, picks up the Skills from `.agents/skills/`, and replies in-thread. See the [Slack integration docs](https://docs.warp.dev/agent-platform/cloud-agents/integrations/slack/) and [Skills as Agents](https://docs.warp.dev/agent-platform/cloud-agents/skills-as-agents/) for setup. +**Extend to Slack.** Wire the same two Skills into a cloud agent configured with your dbt repo, and your teammates can ask data questions by @-mentioning Oz in a Slack channel, without opening a terminal. The agent clones the repo, picks up the Skills from `.agents/skills/`, and replies in-thread. See the [Slack integration docs](https://docs.warp.dev/agent-platform/cloud-agents/integrations/slack/) and [Skills as Agents](https://docs.warp.dev/agent-platform/cloud-agents/skills-as-agents/) for setup. Explore related guides and features: diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 3ffaf9b3..9e489ea2 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -8,7 +8,7 @@ sidebar: --- import VideoEmbed from '@components/VideoEmbed.astro'; -Warp is an [open source](https://github.com/warpdotdev/warp) **Agentic Development Environment**, a modern terminal combined with powerful agents that help you build, test, deploy, and debug code. Warp's AI is powered by **Oz**, the orchestration platform for cloud agents. +Warp is an [open source](https://github.com/warpdotdev/warp) **Agentic Development Environment** that combines a modern, high-performance terminal with powerful agents to help you build, test, deploy, and debug code. Warp's agents are powered by **Oz**, the orchestration platform for running agents locally or in the cloud at scale.
![Warp, the Agentic Development Environment: Warp (a modern terminal built for coding with agents) and Oz (the orchestration platform for cloud agents)](../../assets/terminal/warp-oz-welcome.png) @@ -53,7 +53,7 @@ Local agents keep you in control. You can review changes, steer the agent mid-ta ### Cloud agents -Oz Cloud Agents run in the background on Warp's infrastructure (or your own) for automation at scale. +Cloud agents run in the background on Warp's infrastructure (or your own) for automation at scale. * **Triggers**: React to events from Slack, Linear, GitHub, or custom webhooks * **Schedules**: Run recurring tasks like dependency updates or dead code removal diff --git a/src/content/docs/knowledge-and-collaboration/admin-panel.mdx b/src/content/docs/knowledge-and-collaboration/admin-panel.mdx index 8c23a899..1c69a162 100644 --- a/src/content/docs/knowledge-and-collaboration/admin-panel.mdx +++ b/src/content/docs/knowledge-and-collaboration/admin-panel.mdx @@ -5,6 +5,8 @@ description: >- settings enforced across all team members. --- +The Admin Panel gives team administrators centralized control over organization-wide Warp settings, including agent autonomy, privacy controls, billing limits, codebase indexing, and sharing policies. Settings configured in the Admin Panel are enforced across all team members and override individual preferences. + ## What is the Admin Panel? The [Admin Panel](https://app.warp.dev/admin/) provides team administrators with centralized control over organization-wide settings in Warp. It allows you to manage workspace settings that are enforced across all members of your team. diff --git a/src/content/docs/knowledge-and-collaboration/teams.mdx b/src/content/docs/knowledge-and-collaboration/teams.mdx index 3602f8e9..7c3f8f76 100644 --- a/src/content/docs/knowledge-and-collaboration/teams.mdx +++ b/src/content/docs/knowledge-and-collaboration/teams.mdx @@ -5,6 +5,8 @@ description: >- --- import VideoEmbed from '@components/VideoEmbed.astro'; +A Warp team is a group of users who collaborate through a shared workspace in Warp Drive. Teams share Workflows, Notebooks, Prompts, Rules, and Environment Variables, with role-based permissions for admins and members. Each Warp user can belong to one team at a time. + ## What is a team? A team is a group of Warp users who can collaborate on the command line together. Warp teams can share a dedicated workspace in Warp Drive. [Learn about pricing](https://www.warp.dev/pricing) and see our [Pricing FAQ](/support-and-community/plans-and-billing/pricing-faqs/). diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/agent-mode-context.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/agent-mode-context.mdx index 79e885f9..247cc7f3 100644 --- a/src/content/docs/knowledge-and-collaboration/warp-drive/agent-mode-context.mdx +++ b/src/content/docs/knowledge-and-collaboration/warp-drive/agent-mode-context.mdx @@ -7,7 +7,7 @@ sidebar: label: "Agent Mode context" --- -[Agent Mode](/agent-platform/local-agents/interacting-with-agents/) can leverage your [Warp Drive](/knowledge-and-collaboration/warp-drive/) contents to tailor responses to your personal and team developer workflows and environments. +Warp's agents automatically pull context from your Warp Drive contents, including Workflows, Notebooks, Environment Variables, Rules, and MCP Servers, to generate responses tailored to your personal and team developer workflows. Referenced objects appear as citations in the conversation. ## Objects used as context diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/environment-variables.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/environment-variables.mdx index c4f893e9..fcfdcf98 100644 --- a/src/content/docs/knowledge-and-collaboration/warp-drive/environment-variables.mdx +++ b/src/content/docs/knowledge-and-collaboration/warp-drive/environment-variables.mdx @@ -4,6 +4,8 @@ description: >- Save or sync environment variables to load into your terminal sessions. --- +Environment Variables in Warp Drive let you save, sync, and load environment variables into your terminal sessions with a click. Support for both static values and dynamic secrets from external managers like 1Password, LastPass, and Hashicorp Vault keeps credentials secure and out of source code. + ## What are environment variables in Warp? Environment variables in Warp are similar to .env files, except you can: diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx index 8ac2546a..690c3bc9 100644 --- a/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx +++ b/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx @@ -8,6 +8,8 @@ description: >- import { Tabs, TabItem } from '@astrojs/starlight/components'; import VideoEmbed from '@components/VideoEmbed.astro'; +Warp Drive is a built-in workspace for saving and sharing Workflows, Notebooks, Prompts, and Environment Variables across your team. All objects sync in real time, so you and your team always have access to the latest versions, whether you're working locally or collaborating across an organization. + ## What is Warp Drive? All objects stored in Warp Drive sync immediately as they’re updated, so you and your team will always have access to the latest versions. diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx index 8259d964..cd1428b9 100644 --- a/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx +++ b/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx @@ -7,6 +7,8 @@ sidebar: --- import { Tabs, TabItem } from '@astrojs/starlight/components'; +Notebooks are interactive, runnable documents in Warp Drive that combine markdown text with executable shell command blocks. Use them for onboarding playbooks, debugging runbooks, and development workflows that teammates can search, share, and execute directly from the terminal. + ### What is a Notebook? Notebooks are runnable documentation consisting of markdown text and list elements, code blocks, and runnable shell snippets that can be automatically executed in your terminal session. Notebooks are searchable and accessible through the [Command Palette](/terminal/command-palette/) so you can access and run your documentation without ever leaving the terminal. You can also export Notebooks in .md format at any time. diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/prompts.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/prompts.mdx index 59119a24..b4fd44d4 100644 --- a/src/content/docs/knowledge-and-collaboration/warp-drive/prompts.mdx +++ b/src/content/docs/knowledge-and-collaboration/warp-drive/prompts.mdx @@ -7,6 +7,8 @@ sidebar: --- import VideoEmbed from '@components/VideoEmbed.astro'; +Prompts are parameterized natural language queries you can save in Warp Drive and reuse with agents. Name a prompt, add arguments for dynamic values, and execute it from the Command Palette or Warp Drive to repeat complex agent workflows without retyping. + ## What is a prompt? A prompt is a parameterized natural language query you can name and save in Warp to use with [Agent Mode](/agent-platform/local-agents/interacting-with-agents/). diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/web.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/web.mdx index 420a2892..be8f38b7 100644 --- a/src/content/docs/knowledge-and-collaboration/warp-drive/web.mdx +++ b/src/content/docs/knowledge-and-collaboration/warp-drive/web.mdx @@ -5,6 +5,8 @@ description: >- screen device, including mobile phones, tablets, and touch-enabled laptops. --- +Warp Drive on the Web lets you view and edit Warp Drive objects and shared sessions directly in any browser, including mobile devices and tablets. Access Workflows, Notebooks, Prompts, and session transcripts from anywhere without installing the Warp desktop app. + ## What is Warp on the web? Warp Drive on the Web lets you view and edit your Warp Drive objects and shared sessions directly in the browser, on any device. diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx index baf7b737..307d1a40 100644 --- a/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx +++ b/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx @@ -9,6 +9,8 @@ sidebar: import DemoVideo from '@components/DemoVideo.astro'; import VideoEmbed from '@components/VideoEmbed.astro'; +Workflows are parameterized commands you can name, save, and share in Warp Drive. Define arguments with default values, add descriptions for search, and execute workflows from the Command Palette or Warp Drive to run frequently used commands without retyping them. + ## What is a workflow? A workflow is a parameterized command you can name and save in Warp with descriptions and arguments. Workflows are searchable and easily accessed from the [Command Palette](/terminal/command-palette/) so you can find and execute them without switching contexts. @@ -19,7 +21,7 @@ You can create a new workflow from various entry points in Warp: * From Warp Drive, + > New workflow * Using Block Actions, Save as Workflow -* From Oz agent results, Save as Workflow +* From agent results, Save as Workflow * From the [Command Palette](/terminal/command-palette/), Create a New Personal Workflow Any of these entry points will open the workflow editor where you can: @@ -81,7 +83,7 @@ Once a workflow has been created, you can edit it at any time, as long as you ha #### AI Autofill -Workflows also have the option to use an [Oz agent](/agent-platform/local-agents/overview/) to automatically generate a title, descriptions, or parameters. +Workflows also have the option to use an [agent](/agent-platform/local-agents/overview/) to automatically generate a title, descriptions, or parameters. * Create or edit a Workflow, in the edit view you should see the option to AutoFill. * Warp will fill in the fields based on the Workflow you're creating. diff --git a/src/content/docs/quickstart.mdx b/src/content/docs/quickstart.mdx index 92755569..c23cbb73 100644 --- a/src/content/docs/quickstart.mdx +++ b/src/content/docs/quickstart.mdx @@ -6,7 +6,7 @@ description: >- --- import { Tabs, TabItem } from '@astrojs/starlight/components'; -This guide walks you through installing Warp, trying the terminal features you'll use every day, and firing off your first agent prompt. After completing the steps in this guide, you'll have a working Warp setup and a clear picture of how terminal commands and agents work together. +Get up and running with Warp in about 10 minutes. Install the app, run your first commands using Blocks and the modern text editor, and start an agent conversation to write code, debug issues, or explore your codebase, all from natural language prompts inside the terminal. --- @@ -116,5 +116,5 @@ Now that you have the basics, check out the features that make Warp a full devel * **[Customizing Warp](/getting-started/quickstart/customizing-warp/)** — Pick a theme, configure your prompt, choose your AI model, and import keybindings from another terminal. * **[Codebase Context](/agent-platform/capabilities/codebase-context/)** — Index your Git repositories so agents understand your code and give context-aware answers across large, multi-repo systems. -* **[Oz cloud agents](/agent-platform/cloud-agents/overview/)** — Run agents in the background for PR review, issue triage, dependency updates, and other tasks that don't need your immediate attention. +* **[Cloud agents](/agent-platform/cloud-agents/overview/)** — Run agents in the background for PR review, issue triage, dependency updates, and other tasks that don't need your immediate attention. * **[Keyboard shortcuts](/getting-started/keyboard-shortcuts/)** — The full shortcut reference for power users. diff --git a/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx b/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx index 776b2da1..1eb31e6f 100644 --- a/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx +++ b/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx @@ -1,7 +1,7 @@ --- title: "Demo: Sentry monitoring with SDK" description: >- - Build a Sentry webhook handler that triggers Oz agents to investigate errors + Build a Sentry webhook handler that triggers agents to investigate errors and create draft PRs. --- import VideoEmbed from '@components/VideoEmbed.astro'; diff --git a/src/content/docs/reference/api-and-sdk/index.mdx b/src/content/docs/reference/api-and-sdk/index.mdx index 045ca861..152d8643 100644 --- a/src/content/docs/reference/api-and-sdk/index.mdx +++ b/src/content/docs/reference/api-and-sdk/index.mdx @@ -8,6 +8,8 @@ description: >- --- import VideoEmbed from '@components/VideoEmbed.astro'; +The Oz API and SDKs let you create, monitor, and inspect cloud agent runs programmatically. Use the REST API from any HTTP client, or the official Python and TypeScript SDKs for typed requests, built-in retries, and structured error handling. The SDKs are ideal for CI pipelines, internal tools, and custom integrations. + ### Oz API The Oz API lets you create and inspect [Cloud Agent](/agent-platform/cloud-agents/overview/) runs over HTTP from any system (CI, cron, backend services, internal tools), without requiring the Warp desktop app. @@ -24,7 +26,7 @@ This page is a high-level overview.\ For full API endpoint details, please refer to the [**Agents API Reference**](/api)**.** For schema definitions, see the SDK repos: [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) and [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript). ::: -### Oz Agent SDK +### Oz SDK Oz provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs that wrap the Oz API with: @@ -126,7 +128,7 @@ The API shares a set of reusable models across endpoints. Detailed JSON schemas, --- -## Oz Agent SDKs +## Oz SDKs ### Python SDK diff --git a/src/content/docs/reference/cli/agent-profiles.mdx b/src/content/docs/reference/cli/agent-profiles.mdx index 575f3e45..91dc9787 100644 --- a/src/content/docs/reference/cli/agent-profiles.mdx +++ b/src/content/docs/reference/cli/agent-profiles.mdx @@ -7,6 +7,8 @@ sidebar: label: "Agent Profiles" --- +Agent profiles control what the agent can do, how it behaves, and where it can act when running from the Oz CLI. Create profiles in the Warp app to configure file access, command execution, MCP server usage, model selection, and directory permissions, then reference them by ID in CLI commands. + Agent profiles control three things: * **What the agent can do** — file access, command execution, and MCP server usage diff --git a/src/content/docs/reference/cli/federate.mdx b/src/content/docs/reference/cli/federate.mdx index fe638baa..ecfcc9da 100644 --- a/src/content/docs/reference/cli/federate.mdx +++ b/src/content/docs/reference/cli/federate.mdx @@ -1,7 +1,7 @@ --- title: Federated identity tokens description: >- - Issue short-lived OIDC identity tokens from a running Oz agent so it can + Issue short-lived OIDC identity tokens from a running agent so it can authenticate to cloud providers without long-lived credentials. sidebar: label: "Federated identity" @@ -9,7 +9,7 @@ sidebar: `oz federate` issues short-lived OIDC identity tokens for the agent that's currently running. Use these tokens to authenticate to cloud providers (AWS, GCP, Azure, and other OIDC-aware systems) without baking long-lived credentials into your environment. -This command can only be called from inside a running Oz agent session — typically as part of a [skill](/agent-platform/capabilities/skills/), a tool, or a script the agent executes while a run is in progress. +This command can only be called from inside a running agent session — typically as part of a [skill](/agent-platform/capabilities/skills/), a tool, or a script the agent executes while a run is in progress. ## When to use federation diff --git a/src/content/docs/reference/cli/index.mdx b/src/content/docs/reference/cli/index.mdx index 816674cf..86022205 100644 --- a/src/content/docs/reference/cli/index.mdx +++ b/src/content/docs/reference/cli/index.mdx @@ -7,6 +7,8 @@ description: >- --- import { Tabs, TabItem } from '@astrojs/starlight/components'; +The Oz CLI is the command-line tool for running and managing Warp's cloud agents from any terminal, script, or CI pipeline. Use it to start agents locally or in the cloud, connect MCP servers, configure integrations, and authenticate without requiring the Warp desktop app. + :::note **`warp-cli` is deprecated and has been replaced by `oz`.** If you have `warp-cli` installed, it will auto-update to `oz`. All the same commands are available, just replace `warp-cli` with `oz` in your scripts and workflows. ::: diff --git a/src/content/docs/reference/cli/troubleshooting.mdx b/src/content/docs/reference/cli/troubleshooting.mdx index 81658beb..025b9d80 100644 --- a/src/content/docs/reference/cli/troubleshooting.mdx +++ b/src/content/docs/reference/cli/troubleshooting.mdx @@ -5,6 +5,8 @@ description: >- failures, environments, GitHub access, and Docker image issues. --- +Solutions for common Oz CLI errors, including authentication issues, agent failures, environment configuration, GitHub access problems, and Docker image compatibility. Use `oz help` for built-in documentation on any command. + ## Getting help The CLI includes built-in documentation for all commands: diff --git a/src/content/docs/reference/cli/warp-drive.mdx b/src/content/docs/reference/cli/warp-drive.mdx index 3311a9eb..3cda4c1c 100644 --- a/src/content/docs/reference/cli/warp-drive.mdx +++ b/src/content/docs/reference/cli/warp-drive.mdx @@ -7,6 +7,8 @@ sidebar: label: "Warp Drive Context" --- +Reference saved Warp Drive objects in Oz CLI commands to reuse prompts, notebooks, workflows, and rules as agent context. Pass a saved prompt ID with `--saved-prompt` or inline Warp Drive references using ``, ``, or `` syntax. + ## Reusing saved prompts When you find prompts that work well, save them in [Warp Drive](/knowledge-and-collaboration/warp-drive/) to reuse across sessions, share with teammates, and integrate into automated workflows. For more information, see [Prompts](/knowledge-and-collaboration/warp-drive/prompts/). diff --git a/src/content/docs/reference/index.mdx b/src/content/docs/reference/index.mdx index 360872bd..4acfd0f2 100644 --- a/src/content/docs/reference/index.mdx +++ b/src/content/docs/reference/index.mdx @@ -4,7 +4,7 @@ description: >- Technical reference documentation for the Oz CLI, API, and SDK. --- -This section covers the programmatic interfaces for running and managing Oz agents in CI pipelines, scripts, backend services, and custom tooling. +Technical reference documentation for the Oz CLI, API, and SDKs. Use these programmatic interfaces to run and manage agents from CI pipelines, scripts, backend services, and custom tooling without requiring the Warp desktop app. ## CLI @@ -15,7 +15,7 @@ The [Oz CLI](/reference/cli/) lets you run and configure agents from any environ - [MCP Servers](/reference/cli/mcp-servers/) - Pass MCP server configuration to agent runs using the `--mcp` flag, by UUID, inline JSON, or file path. - [Skills](/reference/cli/skills/) - Run agents from reusable instruction sets stored in your repositories using the `--skill` flag. - [Warp Drive Context](/reference/cli/warp-drive/) - Reference saved prompts, notebooks, workflows, and rules from Warp Drive directly in CLI agent commands. -- [Integration Setup](/reference/cli/integration-setup/) - Configure environments and connect external tools like Slack and Linear so you can trigger Oz agents from outside the terminal. +- [Integration Setup](/reference/cli/integration-setup/) - Configure environments and connect external tools like Slack and Linear so you can trigger agents from outside the terminal. - [Troubleshooting](/reference/cli/troubleshooting/) - Find solutions to common CLI errors, including authentication issues, agent failures, environment problems, and Docker image issues. ## API & SDK diff --git a/src/content/docs/support-and-community/community/open-source-partnership.mdx b/src/content/docs/support-and-community/community/open-source-partnership.mdx index 077761a3..8694c0a5 100644 --- a/src/content/docs/support-and-community/community/open-source-partnership.mdx +++ b/src/content/docs/support-and-community/community/open-source-partnership.mdx @@ -1,21 +1,21 @@ --- title: Oz Open Source Partnership description: >- - Warp supports high-impact open source projects with free Oz agent credits + Warp supports high-impact open source projects with free agent credits through the Oz Open Source Partnership program. --- -Warp is committed to supporting the open source community. Through the Oz Open Source Partnership program, we offer free Oz agent usage credits to high-impact open source projects, helping maintainers and contributors accelerate their development workflows. +Warp is committed to supporting the open source community. Through the Oz Open Source Partnership program, we offer free agent usage credits to high-impact open source projects, helping maintainers and contributors accelerate their development workflows. ## What you get -* **Free Oz credits** - Receive complimentary credits to run Oz agents on your open source project -* **Oz agent access** - Use cloud agents to automate tasks like code review, bug triage, documentation, and more across your repositories -* **Ongoing support** - Warp partners with accepted projects to ensure they get the most value from Oz agents +* **Free Oz credits** - Receive complimentary credits to run agents on your open source project +* **Agent access** - Use cloud agents to automate tasks like code review, bug triage, documentation, and more across your repositories +* **Ongoing support** - Warp partners with accepted projects to ensure they get the most value from agents ## Who can apply -The Oz Open Source Partnership program is designed for actively maintained, high-impact open source projects. When reviewing applications, we consider factors like community size, project activity, and the potential impact of Oz agents on your workflow. +The Oz Open Source Partnership program is designed for actively maintained, high-impact open source projects. When reviewing applications, we consider factors like community size, project activity, and the potential impact of agents on your workflow. :::note Have questions about the program? Reach out to us at [support@warp.dev](mailto:support@warp.dev). @@ -26,5 +26,5 @@ Have questions about the program? Reach out to us at [support@warp.dev](mailto:s Tell us about your open source project by filling out the [application form](https://tally.so/r/LZWxqG). We'll review your submission and follow up with next steps. :::note -The Oz Open Source Partnership program provides free Oz agent credits for open source projects. This is separate from Warp's open source client — the Warp client is published under AGPL v3 at [`warpdotdev/warp`](https://github.com/warpdotdev/warp); see [Contributing to Warp](/support-and-community/community/contributing/). For sponsorship opportunities for your project, reach out to [partnerships@warp.dev](mailto:partnerships@warp.dev). +The Oz Open Source Partnership program provides free agent credits for open source projects. This is separate from Warp's open source client — the Warp client is published under AGPL v3 at [`warpdotdev/warp`](https://github.com/warpdotdev/warp); see [Contributing to Warp](/support-and-community/community/contributing/). For sponsorship opportunities for your project, reach out to [partnerships@warp.dev](mailto:partnerships@warp.dev). ::: diff --git a/src/content/docs/support-and-community/index.mdx b/src/content/docs/support-and-community/index.mdx index 36217137..c58f94b9 100644 --- a/src/content/docs/support-and-community/index.mdx +++ b/src/content/docs/support-and-community/index.mdx @@ -43,7 +43,7 @@ We host [live events](https://luma.com/warpdotdev) year-round — product demos, * [**Warp Preview**](/support-and-community/community/warp-preview-and-alpha-program/) — Try experimental features before anyone else. Your feedback directly shapes what ships. * [**Refer a Friend**](/support-and-community/community/refer-a-friend/) — Send Warp to a developer you think would love it. Earn themes, swag, and gift cards. -* [**Oz Open Source Partnership**](/support-and-community/community/open-source-partnership/) — Free Oz agent credits for high-impact open source projects. +* [**Oz Open Source Partnership**](/support-and-community/community/open-source-partnership/) — Free agent credits for high-impact open source projects. :::note **Ambassador program** diff --git a/src/content/docs/support-and-community/plans-and-billing/bring-your-own-api-key.mdx b/src/content/docs/support-and-community/plans-and-billing/bring-your-own-api-key.mdx index 48f6354d..b3c95398 100644 --- a/src/content/docs/support-and-community/plans-and-billing/bring-your-own-api-key.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/bring-your-own-api-key.mdx @@ -26,7 +26,7 @@ When you add your own model API keys in Warp, those keys are stored **locally on Warp uses these API keys to directly route your agent requests to the model provider you've configured. :::caution -BYOK does not apply to [Oz Cloud Agents](/agent-platform/cloud-agents/overview/). Because your API keys are stored locally on your device, they are not available to cloud-hosted agent runs. Cloud agent runs always consume [Warp credits](/support-and-community/plans-and-billing/credits/). +BYOK does not apply to [Cloud Agents](/agent-platform/cloud-agents/overview/). Because your API keys are stored locally on your device, they are not available to cloud-hosted agent runs. Cloud agent runs always consume [Warp credits](/support-and-community/plans-and-billing/credits/). ::: When a model is selected using your own key: @@ -81,7 +81,7 @@ Some AI-powered features are not affected by BYOK and are included as part of Wa | ----------------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------------- | | [Active AI Recommendations](/agent-platform/local-agents/active-ai/) | No | Always included with Build and higher plans. | | [Codebase Context](/agent-platform/capabilities/codebase-context/) | Yes | Uses Warp's AI infrastructure and consumes credits. | -| [Oz Cloud Agents](/agent-platform/cloud-agents/overview/) | Yes | BYOK keys are stored locally and not available to cloud-hosted runs. | +| [Cloud Agents](/agent-platform/cloud-agents/overview/) | Yes | BYOK keys are stored locally and not available to cloud-hosted runs. | These features will continue to function normally regardless of whether you’ve configured BYOK. diff --git a/src/content/docs/support-and-community/plans-and-billing/index.mdx b/src/content/docs/support-and-community/plans-and-billing/index.mdx index ae1490f1..692b4fc9 100644 --- a/src/content/docs/support-and-community/plans-and-billing/index.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/index.mdx @@ -5,7 +5,7 @@ description: >- billing settings. --- -Warp offers flexible plans designed for individual developers, teams, and enterprises. Learn about pricing, credits, and billing options. +Warp offers flexible plans for individual developers, teams, and enterprises, with credits powering all agent features. Choose from plan-included credits, add-on credit purchases, automatic reloads, or bring-your-own API keys. Compare plans, manage billing, and track credit usage from your account settings. * [**Plans & Pricing**](/support-and-community/plans-and-billing/plans-pricing-refunds/) - Compare plans, pricing tiers, and refund policies * [**Credits**](/support-and-community/plans-and-billing/credits/) - How credits are used and calculated across AI features diff --git a/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx b/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx index c70d85a2..3509ceb4 100644 --- a/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx @@ -27,7 +27,7 @@ The three buckets are independent and a single run can consume from more than on ## How platform credits are measured -Platform credits accrue while an Oz agent is actively working on a task — from when the task starts running to when it finishes, fails, or is cancelled. Idle time, time spent waiting on user input, and time before the task starts don't accrue platform credits. +Platform credits accrue while an agent is actively working on a task — from when the task starts running to when it finishes, fails, or is cancelled. Idle time, time spent waiting on user input, and time before the task starts don't accrue platform credits. See [warp.dev/pricing](https://warp.dev/pricing) for current rates. @@ -37,7 +37,7 @@ Whether platform credits apply depends on where the agent runs and who's paying ### Uses platform credits -* **Cloud agents on any plan** use platform credits for every cloud agent run, regardless of which agent runs the task (Warp Agent, Claude Code, Codex, or Gemini), inference source (Warp-managed, BYOK, or BYOLLM), or compute source (Warp-hosted or self-hosted workers). Warp's platform infrastructure coordinates every cloud agent run. +* **Cloud agents on any plan** use platform credits for every cloud agent run, regardless of which agent runs the task (Warp Agent, Claude Code, or Codex), inference source (Warp-managed, BYOK, or BYOLLM), or compute source (Warp-hosted or self-hosted workers). Warp's platform infrastructure coordinates every cloud agent run. * **Local agents on Business or Enterprise with customer-supplied inference** use platform credits when the local agent run uses [BYOK](/support-and-community/plans-and-billing/bring-your-own-api-key/) or BYOLLM via Amazon Bedrock or Google Vertex. Warp isn't paying for the model call, but Warp's platform infrastructure is still running the local agent. BYOK and customer-supplied inference are subject to plan-size eligibility — see the callout above. ### Doesn't use platform credits diff --git a/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx b/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx index 2ee0d98d..df8c3815 100644 --- a/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx @@ -162,7 +162,7 @@ Warp doesn’t currently offer discounts for students or non-profits. We recomme For open source teams, two paths are available: -* The [Oz Open Source Partnership](/support-and-community/community/open-source-partnership/) program offers free Oz agent credits to high-impact open source projects. +* The [Oz Open Source Partnership](/support-and-community/community/open-source-partnership/) program offers free agent credits to high-impact open source projects. * Warp's client itself is open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE-AGPL), so you can build, run, and contribute to it directly. See [Contributing to Warp](/support-and-community/community/contributing/) for the flow. ### Where is Warp Drive data for my team stored? diff --git a/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx b/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx index e27cdac8..92edb5ce 100644 --- a/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx +++ b/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx @@ -23,7 +23,7 @@ To enable Blocks over SSH, Warp uses an SSH Wrapper function; navigate to settin ### Online features don't work -There is a known issue that can occur that causes online features to break ([Oz agent](/agent-platform/local-agents/overview/), [Generate](/agent-platform/local-agents/overview/), [Block Sharing](/terminal/blocks/block-sharing/), [Refer a Friend](/support-and-community/community/refer-a-friend/) ). This is due to the login token going stale, typically due to a password change, and can be resolved by the following steps: +There is a known issue that can occur that causes online features to break ([Agent](/agent-platform/local-agents/overview/), [Generate](/agent-platform/local-agents/overview/), [Block Sharing](/terminal/blocks/block-sharing/), [Refer a Friend](/support-and-community/community/refer-a-friend/) ). This is due to the login token going stale, typically due to a password change, and can be resolved by the following steps: diff --git a/src/content/docs/support-and-community/troubleshooting-and-support/using-warp-offline.mdx b/src/content/docs/support-and-community/troubleshooting-and-support/using-warp-offline.mdx index 3a071c24..b4672966 100644 --- a/src/content/docs/support-and-community/troubleshooting-and-support/using-warp-offline.mdx +++ b/src/content/docs/support-and-community/troubleshooting-and-support/using-warp-offline.mdx @@ -17,7 +17,7 @@ Warp is "Offline" when you aren't connected to the internet, or if you're blocki Warp’s cloud-based features which require an internet connection will not work in offline mode. Those features include: * [Warp Drive](/knowledge-and-collaboration/warp-drive/#using-warp-drive-offline) (Some files may be read-only in offline mode) -* [Oz agent](/agent-platform/local-agents/overview/) +* [Agent](/agent-platform/local-agents/overview/) * [Agent Mode](/agent-platform/local-agents/interacting-with-agents/) * [Generate](/agent-platform/local-agents/overview/) * [AI Autofill](/knowledge-and-collaboration/warp-drive/workflows/#warp-ai-autofill) diff --git a/src/content/docs/terminal/blocks/index.mdx b/src/content/docs/terminal/blocks/index.mdx index 501e8cdf..f339991f 100644 --- a/src/content/docs/terminal/blocks/index.mdx +++ b/src/content/docs/terminal/blocks/index.mdx @@ -5,6 +5,8 @@ description: >- --- import VideoEmbed from '@components/VideoEmbed.astro'; +Blocks are Warp's fundamental unit for organizing terminal output. Every command and its output is grouped into a single Block that you can copy, search, filter, bookmark, share, and navigate independently — replacing the endless scroll of traditional terminals with structured, actionable output. + ## What are Blocks? Blocks enable us to easily: diff --git a/src/content/docs/terminal/command-palette.mdx b/src/content/docs/terminal/command-palette.mdx index 0dbfd508..7dc3999d 100644 --- a/src/content/docs/terminal/command-palette.mdx +++ b/src/content/docs/terminal/command-palette.mdx @@ -7,6 +7,8 @@ description: >- import { Tabs, TabItem } from '@astrojs/starlight/components'; import VideoEmbed from '@components/VideoEmbed.astro'; +The Command Palette is Warp's global search interface for quickly finding and launching Workflows, Notebooks, Prompts, keyboard shortcuts, file searches, settings, and other actions. Open it with a keyboard shortcut, then type or filter results by type to find exactly what you need. +
![Command Palette Panel](../../../assets/terminal/command-palette-panel.png)
Command Palette Panel.
diff --git a/src/content/docs/terminal/editor/index.mdx b/src/content/docs/terminal/editor/index.mdx index 9649b964..07d7dd78 100644 --- a/src/content/docs/terminal/editor/index.mdx +++ b/src/content/docs/terminal/editor/index.mdx @@ -7,6 +7,8 @@ description: >- import { Tabs, TabItem } from '@astrojs/starlight/components'; import VideoEmbed from '@components/VideoEmbed.astro'; +Warp's input editor works like a modern IDE text editor, with cursor movement, click-to-place, multi-line editing, copy-paste, word selection, and soft wrapping built in. Unlike traditional terminals, you can edit commands the same way you edit code — no memorizing shell-specific shortcuts required. + :::note Text Editor Input also works for [SSH sessions](/terminal/warpify/ssh/). ::: diff --git a/src/content/docs/terminal/input/classic-input.mdx b/src/content/docs/terminal/input/classic-input.mdx index 35195998..bdc1bd6e 100644 --- a/src/content/docs/terminal/input/classic-input.mdx +++ b/src/content/docs/terminal/input/classic-input.mdx @@ -29,22 +29,22 @@ You can enter Agent Mode in a few ways: - * Type any natural language, like a task or a question, in the terminal input. Warp will recognize natural language with a local auto-detection feature and prepare to send your query to an Oz agent. + * Type any natural language, like a task or a question, in the terminal input. Warp will recognize natural language with a local auto-detection feature and prepare to send your query to an agent. * Use the keyboard shortcut `⌘+I` to toggle into Agent Mode, or type `*+Space`. * Click the “AI” sparkles icon in the menu bar, and this will open a new terminal pane that starts in Agent Mode. - * From a block you want to ask an Oz agent about, you can click the sparkles icon in the toolbelt, or click on its block context menu item "Attach block(s) to AI query". + * From a block you want to ask an agent about, you can click the sparkles icon in the toolbelt, or click on its block context menu item "Attach block(s) to AI query". - * Type any natural language, like a task or a question, in the terminal input. Warp will recognize natural language with a local auto-detection feature and prepare to send your query to an Oz agent. + * Type any natural language, like a task or a question, in the terminal input. Warp will recognize natural language with a local auto-detection feature and prepare to send your query to an agent. * Use the keyboard shortcut `Ctrl+I` to toggle into Agent Mode, or type `*+Space`. * Click the "AI" sparkles icon in the menu bar, and this will open a new terminal pane that starts in Agent Mode. - * From a block you want to ask an Oz agent about, you can click the sparkles icon in the toolbelt, or click on its block context menu item "Attach block(s) to AI query". + * From a block you want to ask an agent about, you can click the sparkles icon in the toolbelt, or click on its block context menu item "Attach block(s) to AI query". - * Type any natural language, like a task or a question, in the terminal input. Warp will recognize natural language with a local auto-detection feature and prepare to send your query to an Oz agent. + * Type any natural language, like a task or a question, in the terminal input. Warp will recognize natural language with a local auto-detection feature and prepare to send your query to an agent. * Use the keyboard shortcut `Ctrl+I` to toggle into Agent Mode, or type `*+Space`. * Click the "AI" sparkles icon in the menu bar, and this will open a new terminal pane that starts in Agent Mode. - * From a block you want to ask an Oz agent about, you can click the sparkles icon in the toolbelt, or click on its block context menu item "Attach block(s) to AI query". + * From a block you want to ask an agent about, you can click the sparkles icon in the toolbelt, or click on its block context menu item "Attach block(s) to AI query". diff --git a/src/content/docs/terminal/sessions/index.mdx b/src/content/docs/terminal/sessions/index.mdx index 746c27b9..0a66f04a 100644 --- a/src/content/docs/terminal/sessions/index.mdx +++ b/src/content/docs/terminal/sessions/index.mdx @@ -7,6 +7,8 @@ description: >- import DemoVideo from '@components/DemoVideo.astro'; import VideoEmbed from '@components/VideoEmbed.astro'; +Warp sessions let you navigate between terminal sessions and automatically restore your workspace when you relaunch the app. Session Navigation helps you quickly switch between active sessions, while Session Restoration preserves your windows, tabs, and panes across restarts. + 1. [Session Navigation](/terminal/sessions/session-navigation/) enables you to easily navigate to any session in Warp. 2. [Session Restoration](/terminal/sessions/session-restoration/) automatically restores the window and tabs from your previous session. diff --git a/src/content/docs/terminal/windows/vertical-tabs.mdx b/src/content/docs/terminal/windows/vertical-tabs.mdx index 2137af19..dcee474a 100644 --- a/src/content/docs/terminal/windows/vertical-tabs.mdx +++ b/src/content/docs/terminal/windows/vertical-tabs.mdx @@ -33,7 +33,7 @@ Vertical tabs are especially useful when running multiple coding agents side by ### Tab management * **Search, drag and drop, and renaming** - Filter panes by title, directory, or branch; reorder tabs or move panes between tabs by dragging; double-click a tab to rename it inline. -* **New tab menu** - Create agent tabs, terminal tabs, Oz cloud agent sessions, worktree configs, and [Tab Configs](/terminal/windows/tab-configs/) from a unified **+** menu. +* **New tab menu** - Create agent tabs, terminal tabs, cloud agent sessions, worktree configs, and [Tab Configs](/terminal/windows/tab-configs/) from a unified **+** menu. ## Enabling vertical tabs @@ -141,7 +141,7 @@ Click the **+** button in the control bar to open the new tab menu. The menu inc * **Agent** - Open a new agent tab. * **Terminal** - Open a new terminal tab. -* **Oz cloud agent** - Open a new Oz cloud agent session tab. +* **Cloud agent** - Open a new cloud agent session tab. * **Tab Configs** - Any [Tab Configs](/terminal/windows/tab-configs/) you've created appear as menu items for one-click setup. * **New worktree config** - Create a new worktree-based Tab Config. * **New tab config** - Create a new Tab Config from a starter template. diff --git a/src/pages/api.astro b/src/pages/api.astro index dc0f183d..e4fc84cf 100644 --- a/src/pages/api.astro +++ b/src/pages/api.astro @@ -2,7 +2,7 @@ // Standalone Scalar API reference — not embedded in Starlight. // Accessible at docs.warp.dev/api // Spec lives at `developers/agent-api-openapi.yaml`, synced from the -// upstream Oz Agent API source. Re-sync that file when the API changes +// upstream Agent API source. Re-sync that file when the API changes // and this page picks it up at the next build. // // Note on `set:html={specJson}` below: the injected value is JSON.stringify() @@ -27,24 +27,24 @@ const specJson = JSON.stringify(specObject); - Oz Agent API Reference | Warp - + Agent API Reference | Warp + - - + + - + - - + + {/* PushFeedback CSS + JS are NOT loaded here — the lazy loader inside @@ -218,8 +218,8 @@ const specJson = JSON.stringify(specObject); // doesn't show a fake "interactive" affordance (per scalar/scalar#5079). defaultOpenAllTags: true, metaData: { - title: 'Oz Agent API Reference', - description: 'Interactive API reference for the Oz Agent API.', + title: 'Agent API Reference', + description: 'Interactive API reference for the Agent API.', }, // --------------------------------------------------------------- // Scalar consumes `customCss` as a runtime string, so we can't From 86340d33bb8a24c1e00e0df39a02bc59573b43f9 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Tue, 19 May 2026 00:12:19 -0700 Subject: [PATCH 10/10] Move Memory (Research Preview) to bottom of Agents tab sidebar (#103) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Memory was sitting in the #2 slot, right after 'Getting started' and above 'Warp Agents'. Reorder so the research-preview section sits at the bottom of the Agents tab (after 'Oz Cloud Agents & Orchestration'), matching the visual hierarchy of stable → preview content. Co-authored-by: Oz --- src/sidebar.ts | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/sidebar.ts b/src/sidebar.ts index 523d2b68..cabd7404 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -246,12 +246,6 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ 'agent-platform/getting-started/faqs', ], }, - { - label: 'Memory (Research Preview)', - items: [ - { slug: 'agent-platform/agent-memory', label: 'Agent Memory' }, - ], - }, { label: 'Warp Agents', items: [ @@ -405,6 +399,12 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'agent-platform/cloud-agents/faqs', label: 'Cloud agent FAQs' }, ], }, + { + label: 'Memory (Research Preview)', + items: [ + { slug: 'agent-platform/agent-memory', label: 'Agent Memory' }, + ], + }, ], }, {