Merge branch 'hyc/orchestration-launch' into hyc/orch/handoff

Author: hongyi-chen

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:<uid>`, 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.

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)
 

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
 
-<table><thead><tr><th width="150">Page</th><th width="120">Path</th><th>What you can do</th></tr></thead><tbody><tr><td><strong>Dashboard</strong></td><td><code>/dashboard</code></td><td>Quick actions, suggested agents, recent agents, and featured reads</td></tr><tr><td><strong>Runs</strong></td><td><code>/runs</code></td><td>View all runs, filter by status/source/creator, start new runs, inspect transcripts</td></tr><tr><td><strong>Agents</strong></td><td><code>/agents</code></td><td>Browse skills from your environments, view suggested skills, dispatch skills as agents</td></tr><tr><td><strong>Schedules</strong></td><td><code>/schedules</code></td><td>Create scheduled agents, pause/enable schedules, view run history</td></tr><tr><td><strong>Environments</strong></td><td><code>/environments</code></td><td>Create and manage environments with repos, Docker images, and setup commands</td></tr><tr><td><strong>Integrations</strong></td><td><code>/integrations</code></td><td>Connect Slack and Linear to trigger agents from external tools</td></tr></tbody></table>
+<table><thead><tr><th width="150">Page</th><th width="120">Path</th><th>What you can do</th></tr></thead><tbody><tr><td><strong>Dashboard</strong></td><td><code>/dashboard</code></td><td>Quick actions, suggested agents, recent agents, and featured reads</td></tr><tr><td><strong>Runs</strong></td><td><code>/runs</code></td><td>View all runs, filter by status/source/creator, start new runs, inspect transcripts</td></tr><tr><td><strong>Agents</strong></td><td><code>/agents</code></td><td>Browse skills from your environments, manage agent identities, dispatch skills as agents</td></tr><tr><td><strong>Schedules</strong></td><td><code>/schedules</code></td><td>Create scheduled agents, pause/enable schedules, view run history</td></tr><tr><td><strong>Environments</strong></td><td><code>/environments</code></td><td>Create and manage environments with repos, Docker images, and setup commands</td></tr><tr><td><strong>Secrets</strong></td><td><code>/secrets</code></td><td>Create and manage Warp-managed secrets for cloud agent runs</td></tr><tr><td><strong>Integrations</strong></td><td><code>/integrations</code></td><td>Connect Slack and Linear to trigger agents from external tools</td></tr></tbody></table>
 
 <figure>
 ![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.
 
 <figure>
 ![Creating a new agent skill in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-new-agent.png)
-<figcaption>Creating a new agent skill in the Oz web app.</figcaption>
+<figcaption>Creating a new skill in the Oz web app.</figcaption>
 </figure>
 
+### 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