docs(agent-platform): add agent identities page and expand secrets + web-UI coverage

[hongyi-chen]

Summary

Dedicated docs PR for agent identities (named agents) under cloud agents. Separate from the five in-flight orchestration-launch PRs, targeting the same gating branch hyc/orchestration-launch.

The PR adds one new page covering what a named agent is, plan limits, attached configuration (description, managed secrets, skills), CRUD via the public REST API, API keys bound to a specific identity, running as a named agent, and where named agents surface across the product. It also reconciles a handful of existing pages so service-account and automation references forward-link to the new page without renaming "service account" everywhere it appears.

New page

• src/content/docs/agent-platform/cloud-agents/agents.mdx — Named agents reference. Title: Named agents. Sidebar label: Named agents. Covers: what a named agent is, default vs. additional identities, plan limits per plan name (Free / Build / Business / Enterprise), attached description / managed secrets / skills, create / list / update / delete via REST (with a pointer to the OpenAPI page at /api), generating an API key bound to an identity, running as a specific identity (key binding or agent_identity_uid on POST /agent/runs), and where identities surface (Agents page, Agent picker, Run filters, Admin Panel). Caveats: team-scoped, user must be on exactly one team, over-plan-limit identities are visible but unusable.

Edited pages

• src/content/docs/agent-platform/cloud-agents/secrets.mdx — Adds a forward link to the new agents page in the team-secrets recommendation and a brief note that secrets can be attached directly to a named agent. Keeps "service account" intact where it refers to external systems (Metabase, GCP, etc.).
• src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx — Pattern 1 setup checklist: A service account (recommended for automation) → A named agent (recommended for automation) with a link to the new agents page.
• src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx — Reconciles the two meanings of the /agents URL by splitting the Agents section into clearly-separated Skills and Named agents subsections, with a forward link to the new agents page for the full reference. Renames the in-page "Creating new agents" → "Creating new skills" so the skills/named-agents distinction is unambiguous within the page. Adds a Named agents entry to the related-resources footer.
• src/content/docs/reference/cli/index.mdx — Leaves the literal oz whoami output text intact (user or service account ID) and adds a one-line note that a service-account principal is a named agent on your team, linking forward to the new agents page.
• src/content/docs/reference/cli/federate.mdx — Keeps the literal service_account:my-sa-id example in the subject-template components reference and adds a one-line cross-reference to the new agents page.

Out of scope

• No changes to src/sidebar.ts, vercel.json, top-level landing pages, or any files owned by the five in-flight launch PRs (harnesses/*, orchestration/*, handoff/*, agent-memory/*, platform-credits.mdx, multi-agent-edited files, cli-agents/* multi-harness files). The sidebar entry for the new page will be added in a separate follow-up.

Validation

• python3 .agents/skills/style_lint/style_lint.py — Run directly against the 6 changed files: 0 issues.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only — Run directly against the 6 changed files: 92 internal links checked, 0 broken.

Open questions for product / PM

• Feature-flag posture for launch. The endpoints are gated behind the agent_identities_api flag per spec (PRODUCT.md). Are we shipping the docs page in lockstep with the flag flip, or should I add a brief "Available to teams on the orchestration launch wave" preamble?
• x-internal: true. Today the /agent/identities endpoints are public in warp-server/public_api/openapi.yaml (not x-internal), so the page references the OpenAPI page at /api for full request/response shapes. Confirm this is the intent at launch — if any of these endpoints will flip to x-internal: true before launch, I'll need to reframe the "Managing named agents" section.
• Plan limits. The spec lists Free=1, Build=inherits Free (1), Business=5, Enterprise=unlimited. I've documented these by plan name. Confirm these match launch reality; if Business or Enterprise change, the Plan limits section needs an update.
• Sidebar entry. I deliberately did not touch src/sidebar.ts per the hard rules. Should a sidebar entry be added before merge, or do you want this PR to land as a hidden page that's only reachable via the cross-links until the broader navigation lands?

Artifacts

• Conversation: https://staging.warp.dev/conversation/e0139d85-cb2f-4f70-a508-cdd3e8f7d621

Co-Authored-By: Oz oz-agent@warp.dev

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Error		May 16, 2026 11:10pm

[oz-for-oss]

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR adds a new named agents reference page and cross-links it from related cloud agent, secrets, and CLI docs. The structure is useful, but several changed lines currently document API/UI behavior that conflicts with the generated API reference or with other new text in the same PR.

Concerns

• The named agents page advertises create/update fields and a retrieve endpoint that are not present in the generated public API reference.
• The page gives conflicting guidance on whether the fallback/Quick run identity is the default named agent or the calling user.
• The web app page promises default model/harness/default configuration on named agents, but the new reference and API schema do not document those fields.

Verdict

Found: 0 critical, 4 important, 0 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

⚠️ [IMPORTANT] This documents fields the published API schema does not expose: CreateAgentRequest and UpdateAgentRequest currently only include name, and AgentResponse only returns uid, name, available, and created_at. Either sync the API schema/server support in this PR or remove description, secrets, and skills from the endpoint docs.

[oz-for-oss]

⚠️ [IMPORTANT] GET /agent/identities/{uid} is not present in the API reference; that path currently only defines PUT and DELETE, so readers will look for a getAgent operation that does not exist. Add the operation to the public spec or remove this Retrieve bullet.

[oz-for-oss]

⚠️ [IMPORTANT] This contradicts the Agent picker docs below and in oz-web-app.mdx, which say Quick run runs as the calling user. Resolve whether the fallback is the default named agent or the user's identity before publishing.

[oz-for-oss]

⚠️ [IMPORTANT] The named-agents reference and public API schema do not document default model/harness/default configuration on an agent identity. Remove these fields here or add them consistently to the reference/API docs if the product supports them.

[hongyi-chen]

Revision pass pushed (2b7552a). Summary of what changed since the initial commit:

Terminology

• Retitled the new page to Agent identities (sentence case, sidebar label) and replaced every "named agent" / "named agents" / "named agent identities" across the six in-scope files with agent identity / agent identities. Where copy referenced the literal UI label (the Agents page in the Oz web app, the Agent dropdown), the immediate UI prose keeps that label and surrounding copy uses "agent identity."
• Updated cross-references in secrets.mdx, deployment-patterns.mdx, oz-web-app.mdx, reference/cli/index.mdx, and reference/cli/federate.mdx. The literal oz whoami and oz federate issue-token output stays intact; both pages now include a one-line note tying service_account: principals to agent identities, linking to agents.mdx.

agents.mdx

• Removed the Free / Build / Business / Enterprise plan-limit table. Replaced with a single sentence pointing to warp.dev/pricing while preserving the conceptual points (default identity is always available, additional identities count against the plan limit, over-limit identities remain visible but unusable).
• Added a Service accounts and agent identities subsection that maps service_account:<uid> principals (in oz whoami, oz federate issue-token) to agent identities.
• Added a Supporting multiple agent identities paragraph covering when a team should create more than the default (CI runner, on-call automation, scheduled jobs) and the scoping benefits (least-credential, attributable audit trails, isolated rotation).

secrets.mdx

• New Creating secrets in the Oz web app walkthrough for the Add secret side pane (Name → Value → Description → Scope), placed alongside the existing oz secret CLI section.
• New Scoping secrets to environments and runs section covering:
  • Environment-level scoping — secrets attached to a cloud environment are the only ones contributed from that environment.
  • Run-level scoping — default (inherit all in-scope), explicit name list (only those), and empty list (opt out of all secret injection). Run-level scoping is exposed on the run config in the public REST API; cross-links to the Oz API & SDK reference rather than quoting the schema.
• Note framing the three layers (identity, environment, run) as a broader access-scoping model.

oz-web-app.mdx

• Added a Secrets row (/secrets) to the quick-reference table.
• Reframed the Agents-page disambiguation to use "agent identity."
• Added a step-by-step walkthrough of the New agent side pane: name, description, prompt, skills, base harness, base model, harness auth secret, secrets, and memory stores. Cross-links back to agents.mdx for the conceptual reference.

Files touched (all in scope)

• src/content/docs/agent-platform/cloud-agents/agents.mdx
• src/content/docs/agent-platform/cloud-agents/secrets.mdx
• src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx
• src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx
• src/content/docs/reference/cli/index.mdx
• src/content/docs/reference/cli/federate.mdx

src/sidebar.ts, vercel.json, top-level landing pages, and files owned by other workstreams are untouched.

Validation

• python3 .agents/skills/style_lint/style_lint.py --changed → 0 issues.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only → 318 files, 2417 internal links, 0 broken.
• git grep 'named agent' → no matches.

Open questions for product / PM

1. Run-level secret scoping launch status. Is the field shipping at launch, or staying behind OzSecretScopingEnabled()? Current copy describes it as available on the public REST API run config and links to the OpenAPI page; happy to add a launch caveat if it's flagged-off at GA.
2. Environment-level secret scoping launch status. The copy assumes the environment form's secret selector is visible to all customers; confirm whether that's true at launch or still gated behind a flag/cohort.
3. Web-UI secret creation gating. The walkthrough describes the public /secrets Add-secret side pane without caveats — confirm there are no gating concerns (browser-side encryption, access roles, etc.) that should be called out.
4. Agent creation UI fields. The New agent walkthrough lists name, description, prompt, skills, base harness, base model, harness auth secret, secrets, and memory stores. Memory stores are currently dogfood-gated in the client; should I drop that bullet (or mark the section conditional) for the public docs at GA?
5. Plan-limit page. Plan-limit specifics now live at warp.dev/pricing. Confirm that page is the canonical location and includes agent-identity limits at GA, otherwise we'll need a different forward-link target.