From c010e49aa24c4e37407079a48b09a61970407167 Mon Sep 17 00:00:00 2001 From: Joseph Schorr Date: Wed, 30 Sep 2026 11:55:34 -0400 Subject: [PATCH 1/2] docs: give each example-agent demo its own page; put demos on the landing page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split the combined "Five agent demos" page into one page per agent (codebot, hubspot-companies, reviewbot, pm-bot, Agent Builder), each with the narrated clip, what the demo shows, and the controls at work. On the landing page, embed the reviewbot demo in the hero below the install terminal and the Agent Builder demo in its section — both resolved from the docs media manifest, no autoplay since the clips are narrated. --- site/app/(landing)/Landing.tsx | 31 +++++++++++++ site/app/(landing)/landing.css | 36 +++++++++++++++ site/content/docs/codebot.mdx | 41 +++++++++++++++++ site/content/docs/example-agent-builder.mdx | 32 ++++++++++++++ site/content/docs/example-agents.mdx | 49 --------------------- site/content/docs/hubspot-companies.mdx | 38 ++++++++++++++++ site/content/docs/pm-bot.mdx | 38 ++++++++++++++++ site/content/docs/reviewbot.mdx | 40 +++++++++++++++++ 8 files changed, 256 insertions(+), 49 deletions(-) create mode 100644 site/content/docs/codebot.mdx create mode 100644 site/content/docs/example-agent-builder.mdx delete mode 100644 site/content/docs/example-agents.mdx create mode 100644 site/content/docs/hubspot-companies.mdx create mode 100644 site/content/docs/pm-bot.mdx create mode 100644 site/content/docs/reviewbot.mdx diff --git a/site/app/(landing)/Landing.tsx b/site/app/(landing)/Landing.tsx index 392e7af..b295026 100644 --- a/site/app/(landing)/Landing.tsx +++ b/site/app/(landing)/Landing.tsx @@ -10,6 +10,7 @@ import { Wordmark } from "@/components/Wordmark"; import { SiteFooter } from "@/components/SiteFooter"; import { DiscordIcon, GitHubIcon } from "@/components/BrandIcons"; import { DISCORD_URL } from "@/lib/site"; +import { getAsset } from "@/lib/manifest"; import { OWASP, coverageSummary } from "./owasp"; const REPO = "https://github.com/authzed/openagentprimitives"; @@ -428,6 +429,23 @@ function InstallTerminal() { ); } +/* A narrated demo clip, resolved from the docs media manifest. The narration + * is the point, so there is no autoplay: it starts on a click, unmuted, from + * its poster frame. */ +function DemoClip({ name, caption }: { name: string; caption: ReactNode }) { + const asset = getAsset(name); + if (!asset || (!asset.webm && !asset.mp4)) return null; + return ( +
+ +
{caption}
+
+ ); +} + function SectionHead({ kicker, children, @@ -508,6 +526,15 @@ export function Landing() {
+ + Watch one: reviewbot reviews a + pull request read-only and records a Check Run. + + } + />
@@ -634,6 +661,10 @@ export function Landing() { ))} +
Read the Agent Builder guide diff --git a/site/app/(landing)/landing.css b/site/app/(landing)/landing.css index 97dfc0e..211aac1 100644 --- a/site/app/(landing)/landing.css +++ b/site/app/(landing)/landing.css @@ -538,6 +538,42 @@ body:has(.lp) { color: var(--lp-term-muted); } +/* ---------------------------------------------------------------- clips --- */ + +/* Narrated demo clips, framed like the terminal. Posters carry the frame; + the narration means no autoplay, so the video waits for a click. */ +.lp-clip { + margin: 0; +} + +.lp-hero-aside .lp-clip { + margin-top: 16px; +} + +.lp-section .lp-clip { + margin-top: 40px; + max-width: 860px; +} + +.lp-clip video { + display: block; + width: 100%; + border: 1px solid var(--lp-line); + border-radius: var(--lp-radius); + background: var(--lp-term-bg); +} + +.lp-clip figcaption { + margin-top: 8px; + font-size: 13px; + line-height: 1.6; + color: var(--lp-muted); +} + +.lp-clip figcaption a { + color: var(--lp-link); +} + /* ---------------------------------------------------------------- slabs --- */ /* Cells fused into one slab by a 1px gap over a line-colored ground, so diff --git a/site/content/docs/codebot.mdx b/site/content/docs/codebot.mdx new file mode 100644 index 0000000..45e1616 --- /dev/null +++ b/site/content/docs/codebot.mdx @@ -0,0 +1,41 @@ +export const meta = { + title: 'codebot', + section: 'Guides', + group: 'Example agents', + order: 70, + description: 'A passthrough coding agent that plans, gets one scoped approval, and opens a pull request as the person who asked.', +} + +# codebot + +
+ codebot is a coding agent that clones a repository, makes the change with the requester's own + Claude Code subscription, commits as the requester, and opens a pull request. It runs in + passthrough identity mode, so the platform never holds the person's credentials — they are + injected into the sandbox at session start and discarded with it. +
+ + + +## What the demo shows + +Jordan asks codebot to fix a flaky test in `acme/widget`. The agent proposes a plan, and a single +approval covers both the plan and the repository it names — the approval is slotted to +`acme/widget`, so the steps inside the plan run without prompting again, ending in an opened pull +request. When Jordan then asks for work in a different repository, the slotted approval does not +stretch to cover it: a fresh approval is required. + +The demo is a scripted Slack simulation; its people, companies, repositories, and results are +fictional. + +## The controls at work + +- [Plan gating](/docs/plan-gating) — a person approves the plan once, and every later action is + checked against it. +- [Passthrough identity](/docs/passthrough-vs-agent) — the work runs as Jordan, under Jordan's own + GitHub and Anthropic credentials, which the platform never stores server-side. + +The bundle is in the repository at +[`examples/codebot`](https://github.com/authzed/openagentprimitives/tree/main/examples/codebot), +packaged as a `.oap` agent container you can lint and install with +[`oap agent`](/docs/packaging-oap). diff --git a/site/content/docs/example-agent-builder.mdx b/site/content/docs/example-agent-builder.mdx new file mode 100644 index 0000000..da71922 --- /dev/null +++ b/site/content/docs/example-agent-builder.mdx @@ -0,0 +1,32 @@ +export const meta = { + title: 'Agent Builder', + section: 'Guides', + group: 'Example agents', + order: 78, + description: 'One build in the real web UI: describe an agent, answer its questions, approve the stage, test it live, and keep the draft.', +} + +# Agent Builder + +
+ Agent Builder is an OAP agent that creates other agents. In the real web UI, a person describes a + new limerick agent in plain language; the builder asks questions one at a time, gets a stage + approval, builds a draft, lets the person test it live on the page, and offers an + admin-reviewed install. +
+ + + +## What the demo shows + +Unlike the other example-agent demos, this is footage of the real product, end to end: one +description, a few questions, one approval per stage, a live test of the draft in an embedded +session, and a saved draft the person keeps. Installing it for real records a request for a +platform administrator; nothing runs until they approve it. + +## Where to go next + +- [Agent Builder](/docs/agent-builder) — what the builder is, how it's turned on, and the controls + it follows. +- [Your first custom agent](/docs/agent-builder-first-agent) — this same build walked through + stage by stage, with the page as the guide. diff --git a/site/content/docs/example-agents.mdx b/site/content/docs/example-agents.mdx deleted file mode 100644 index d5d92f4..0000000 --- a/site/content/docs/example-agents.mdx +++ /dev/null @@ -1,49 +0,0 @@ -export const meta = { - title: 'Five agent demos', - section: 'Guides', - group: 'Example agents', - order: 70, - description: 'See codebot, HubSpot CRM, reviewbot, and pm-bot in scripted Slack demos, followed by the Agent Builder in the real web UI.', -} - -# Five agent demos - -
- Four short Slack simulations show how the example agents behave. Their people, companies, repos, - issues, and results are fictional. The final video is footage of the real Agent Builder web UI. -
- -## codebot - -Jordan asks codebot to fix a flaky test in `acme/widget`. The agent proposes a plan, waits for one scoped -approval, then opens a PR. A request to work in a different repo needs a fresh approval. - - - -## HubSpot CRM - -A scheduled digest highlights companies that passed the fit threshold. When Sam asks for Circldot's contacts, -the agent routes the request to the company's owner and shares the contacts only after approval. - - - -## reviewbot - -A pull-request update starts a read-only review. reviewbot shows its findings and a report reference in Slack, then concludes -a Check Run on the reviewed commit. It does not modify the repository or post PR comments. - - - -## pm-bot - -The product-manager example reads its granted GitHub repos and linked Linear issues, then groups work by -product goal. Its summary recommends a next step without changing either service. - - - -## Agent Builder - -In the real web UI, a person describes a new limerick agent in plain language. The builder asks questions, -gets stage approval, builds a draft, lets the person test it, and offers an admin-reviewed install. - - diff --git a/site/content/docs/hubspot-companies.mdx b/site/content/docs/hubspot-companies.mdx new file mode 100644 index 0000000..15a85cb --- /dev/null +++ b/site/content/docs/hubspot-companies.mdx @@ -0,0 +1,38 @@ +export const meta = { + title: 'hubspot-companies', + section: 'Guides', + group: 'Example agents', + order: 72, + description: 'A read-only HubSpot CRM reporter: a scheduled company digest, with private contacts gated behind the owner of the data.', +} + +# hubspot-companies + +
+ hubspot-companies is a read-only HubSpot CRM reporting agent. On a schedule it reports the + companies created inside a window that cleared a minimum fit score, mentioning each company's + assigned owner in the channel. Contacts on a named company are gated behind an owner-approval + flow — the person who owns the record decides, not whoever asked. +
+ + + +## What the demo shows + +A scheduled digest highlights the companies that passed the fit threshold. When Sam asks for +Circldot's contacts, the agent does not answer Sam directly: the approval routes to Circldot's +owner, Jordan, who sees what would be shared, with whom, and why. Only after Jordan approves does +the agent return the contacts to Sam. + +The demo is a scripted Slack simulation; its people, companies, and results are fictional. + +## The controls at work + +- [Triggers](/docs/triggers) — the digest is a scheduled run, not a person typing. +- [Shared permissions](/docs/shared-permissions) — the approval routes to the data's owner, and + the data is shared only after that owner says yes. + +The bundle is in the repository at +[`examples/hubspot-companies`](https://github.com/authzed/openagentprimitives/tree/main/examples/hubspot-companies), +packaged as a `.oap` agent container you can lint and install with +[`oap agent`](/docs/packaging-oap). diff --git a/site/content/docs/pm-bot.mdx b/site/content/docs/pm-bot.mdx new file mode 100644 index 0000000..07a6475 --- /dev/null +++ b/site/content/docs/pm-bot.mdx @@ -0,0 +1,38 @@ +export const meta = { + title: 'pm-bot', + section: 'Guides', + group: 'Example agents', + order: 76, + description: 'A read-only product-manager agent that reports how GitHub and Linear work in flight aligns with product goals.', +} + +# pm-bot + +
+ pm-bot is a read-only product-manager agent. It reads the GitHub repositories it was granted and + the Linear issues in the linked workspace, then reports how the work in flight aligns with stated + product goals. It never writes to either system. +
+ + + +## What the demo shows + +pm-bot reads its granted repositories and linked issues, groups the work in flight by product +goal, and posts a summary that recommends a next step — without changing anything in GitHub or +Linear. + +The demo is a scripted Slack simulation; its people, repositories, issues, and results are +fictional. + +## The controls at work + +- Which repositories the agent may read is an install question, answered by the administrator who + installs it — not something the agent discovers at runtime. +- [Safe tools](/docs/safe-tools) — read-only is a property of the tool contracts the session is + offered, checked on every call. + +The bundle is in the repository at +[`examples/pm-agent`](https://github.com/authzed/openagentprimitives/tree/main/examples/pm-agent), +packaged as a `.oap` agent container you can lint and install with +[`oap agent`](/docs/packaging-oap). diff --git a/site/content/docs/reviewbot.mdx b/site/content/docs/reviewbot.mdx new file mode 100644 index 0000000..3a65f78 --- /dev/null +++ b/site/content/docs/reviewbot.mdx @@ -0,0 +1,40 @@ +export const meta = { + title: 'reviewbot', + section: 'Guides', + group: 'Example agents', + order: 74, + description: 'An automated pull-request reviewer: triggered by a webhook, read-only by construction, concluded as a GitHub Check Run.', +} + +# reviewbot + +
+ reviewbot is an automated GitHub pull-request reviewer. A push to a pull request arrives as a + signed webhook — no human starts the session — so the agent clones the diff read-only, drives an + inner Claude Code through its bundled review skills, delivers the summary to Slack, and records + the outcome as a GitHub Check Run on the pull request's head commit. It never writes to a + repository and never comments on a pull request. +
+ + + +## What the demo shows + +A pull-request update starts a read-only review. reviewbot posts its findings and a report +reference in Slack, then concludes a Check Run on the reviewed commit. Nothing in the run can +modify the repository or post PR comments — the write simply isn't among the tools the session is +offered. + +The demo is a scripted Slack simulation; its people, repositories, and results are fictional. + +## The controls at work + +- [Triggers](/docs/triggers) — the session starts from a signed webhook, with HMAC verification + and event filtering enforced by the platform. +- [Safe tools](/docs/safe-tools) — the read-only boundary is declared in the tool contracts and + enforced per call, not entrusted to the model or to a narrow upstream token. + +The bundle is in the repository at +[`examples/reviewbot`](https://github.com/authzed/openagentprimitives/tree/main/examples/reviewbot), +packaged as a `.oap` agent container you can lint and install with +[`oap agent`](/docs/packaging-oap). From 6114b4dcf4a40834f8afafc7905b8411fd8227fa Mon Sep 17 00:00:00 2001 From: Joseph Schorr Date: Wed, 30 Sep 2026 11:58:43 -0400 Subject: [PATCH 2/2] docs: add the oap agent install command to each example-agent page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Each bundle page closes with an Install it section: the lint + install commands from the bundle's README and a line on what the install asks. The Agent Builder page is unchanged — it ships built in, with no bundle to install. --- site/content/docs/codebot.mdx | 14 ++++++++++++-- site/content/docs/hubspot-companies.mdx | 14 ++++++++++++-- site/content/docs/pm-bot.mdx | 14 ++++++++++++-- site/content/docs/reviewbot.mdx | 14 ++++++++++++-- 4 files changed, 48 insertions(+), 8 deletions(-) diff --git a/site/content/docs/codebot.mdx b/site/content/docs/codebot.mdx index 45e1616..451e3fd 100644 --- a/site/content/docs/codebot.mdx +++ b/site/content/docs/codebot.mdx @@ -35,7 +35,17 @@ fictional. - [Passthrough identity](/docs/passthrough-vs-agent) — the work runs as Jordan, under Jordan's own GitHub and Anthropic credentials, which the platform never stores server-side. +## Install it + The bundle is in the repository at [`examples/codebot`](https://github.com/authzed/openagentprimitives/tree/main/examples/codebot), -packaged as a `.oap` agent container you can lint and install with -[`oap agent`](/docs/packaging-oap). +packaged as a [`.oap` agent container](/docs/packaging-oap): + +```bash +oap agent lint examples/codebot +oap agent install examples/codebot --namespace default +``` + +The install prompts one question — which language toolchains the coding sandbox +should get. After install, each user links their own GitHub and Anthropic +credentials once via the identity portal. diff --git a/site/content/docs/hubspot-companies.mdx b/site/content/docs/hubspot-companies.mdx index 15a85cb..cbb117a 100644 --- a/site/content/docs/hubspot-companies.mdx +++ b/site/content/docs/hubspot-companies.mdx @@ -32,7 +32,17 @@ The demo is a scripted Slack simulation; its people, companies, and results are - [Shared permissions](/docs/shared-permissions) — the approval routes to the data's owner, and the data is shared only after that owner says yes. +## Install it + The bundle is in the repository at [`examples/hubspot-companies`](https://github.com/authzed/openagentprimitives/tree/main/examples/hubspot-companies), -packaged as a `.oap` agent container you can lint and install with -[`oap agent`](/docs/packaging-oap). +packaged as a [`.oap` agent container](/docs/packaging-oap): + +```bash +oap agent lint examples/hubspot-companies +oap agent install examples/hubspot-companies --namespace default +``` + +The install applies the bundled manifests, then drives each required channel's +wizard. The HubSpot OAuth credential is minted separately by the identity setup +flow described in the bundle's README. diff --git a/site/content/docs/pm-bot.mdx b/site/content/docs/pm-bot.mdx index 07a6475..9fdfb64 100644 --- a/site/content/docs/pm-bot.mdx +++ b/site/content/docs/pm-bot.mdx @@ -32,7 +32,17 @@ fictional. - [Safe tools](/docs/safe-tools) — read-only is a property of the tool contracts the session is offered, checked on every call. +## Install it + The bundle is in the repository at [`examples/pm-agent`](https://github.com/authzed/openagentprimitives/tree/main/examples/pm-agent), -packaged as a `.oap` agent container you can lint and install with -[`oap agent`](/docs/packaging-oap). +packaged as a [`.oap` agent container](/docs/packaging-oap): + +```bash +oap agent lint examples/pm-agent +oap agent install examples/pm-agent --namespace default +``` + +The install asks its two questions — which repositories the agent may read, and +the read-only GitHub PAT it authenticates with. It applies no privileged +resources, so it is safe to install into a shared namespace. diff --git a/site/content/docs/reviewbot.mdx b/site/content/docs/reviewbot.mdx index 3a65f78..26ad1ab 100644 --- a/site/content/docs/reviewbot.mdx +++ b/site/content/docs/reviewbot.mdx @@ -34,7 +34,17 @@ The demo is a scripted Slack simulation; its people, repositories, and results a - [Safe tools](/docs/safe-tools) — the read-only boundary is declared in the tool contracts and enforced per call, not entrusted to the model or to a narrow upstream token. +## Install it + The bundle is in the repository at [`examples/reviewbot`](https://github.com/authzed/openagentprimitives/tree/main/examples/reviewbot), -packaged as a `.oap` agent container you can lint and install with -[`oap agent`](/docs/packaging-oap). +packaged as a [`.oap` agent container](/docs/packaging-oap): + +```bash +oap agent lint examples/reviewbot +oap agent install examples/reviewbot --namespace default +``` + +The install prompts for reviewbot's own Anthropic API key when its Secret is +absent, and runs the GitHub channel wizard. See the bundle's README for the +prerequisites, including the Claude toolchain image its sandbox runs.