Agent readiness check
Check whether an agent can use a page: every control named, each name finding one control, none it can't see, with a score. In a test, in Playwright, or from the command line.
An agent uses a page by finding each control by its name. agent-check checks a page the
way the agent sees it, and scores it: the share of controls an agent can find by a name of
their own. On a UI SDK app it asks the agent bridge itself, in any framework UI SDK serves.
On any other site it reads the page's accessibility tree, as browser agents do. Try both on
the Agents page: the live check, with and without three mistakes in a
form, and a bookmarklet that checks any page you're on. For a public page, paste its link
into the checker.
pnpm dlx shadcn@latest add @uiset/agent-checkIn a test
expectAgentReady checks the page and throws, with every problem, when the score is under
minScore (100) or an error is found. Use the bridge your app creates:
import { render } from "@testing-library/react"
import { createAgent } from "@ui-sdk/react/agent"
import { test } from "vitest"
import { expectAgentReady } from "@/components/ui/agent-check/check"
import { ProjectSettings } from "./project-settings"
const agent = createAgent()
test("an agent can find every control on the settings page", async () => {
render(<ProjectSettings />)
await expectAgentReady(agent)
})
checkAgentReadiness(agent) returns the report instead, and formatAgentReadiness(report)
writes it as text. root (an element or a CSS selector) limits where it looks for controls
agents can't see; the bridge always reports the whole page.
What it checks
Errors, which lower the score:
unnamed: a component the bridge lists has no name, so no step can find it. Give it a label part oraria-label, oraria-hidden="true"if it's decoration.ambiguous: a name finds more than one component, so a step by that name fails. A name matches every name holding its words: "Region" finds "Revenue by region". Give each a name with a word the others lack. A closed tooltip, menu or dialog takes its trigger's name: give a tooltip its ownaria-label, and a dialogkeepMountedso its title names it.unseen: a control a person can reach (a native button or field, or an ARIA widget, that Tab reaches) isn't a UI SDK component, so agents can't see it. Use the UI SDK part for it, or put it insidedata-agent-hiddenif agents shouldn't use it.
Warnings, which don't:
unconfirmed: a button whose label starts with a word like Delete, Pay or Deploy has nodata-agent-confirm. Add one saying what it does, if a person should approve it.overflow: the page has more than 100 components, so an agent's snapshot shows 100 and it must query for the rest. Fewer components per view (tabs, pages, collapsed sections) let it see the whole view at once.
Names are checked with the bridge's own search (query), so they match the way a step's do.
Components no step targets, with no actions, like avatars, may share a name. A control is
UI SDK's when it has data-slot, which UI SDK puts on every element it binds; inner parts a
component drives itself, out of the Tab order inside it (a grid's row checkboxes), aren't
counted.
The score counts the components the bridge lists and the controls it can't see; errors lower
it and warnings don't. Accept a problem you've decided to keep with ignore, and it counts as
fine:
await expectAgentReady(agent, { ignore: (problem) => problem.kind === "unseen" && problem.control.includes("Legacy export") })
Any page, without a bridge
checkPageReadiness reads the page itself: every button, link, field and widget the
accessibility tree has, with the name a browser gives it. It needs nothing from the page, so
it checks a site built with anything. expectPageReady is its test helper:
import { render } from "@testing-library/react"
import { test } from "vitest"
import { expectPageReady } from "@/components/ui/agent-check/page"
import { Checkout } from "./checkout"
test("an agent reading the checkout page can tell every control apart", () => {
render(<Checkout />)
expectPageReady()
})
Errors, which lower the score:
unnamed: a control with no name. Give it visible text, a label, oraria-label.ambiguous: controls of one kind sharing a name, like three "Edit" buttons in a table, or two "Read more" links that go to different places. Radios, tabs, options and menu items only need a name of their own within their group, so every question can have its "Yes".unseen: something that looks clickable (a pointer cursor starts on it, or it has anonclick) but isn't a button or link, so an agent reading the page sees no control there. An interactive grid's cells, rows and headers, like a calendar's days, are what agents see there; they aren't reported, or scored, since a data grid's cells repeat each other's text.
Names follow the browser's rules closely but not completely: aria-labelledby, aria-label,
a label, the text inside (images by their alt, icons by their title, hidden parts left
out), then title or placeholder. root and ignore work as they do with the bridge, and
elements: true adds each problem's elements to the report.
On a page, with Playwright
checkPage runs the check on a real page. On a UI SDK page it reaches the bridge as the
browser's agent would: through the tools the app registers with WebMCP (registerTools),
once captureAgentTools has run before the page loads, or through a global you name. On any
other page it reads the page. mode: "bridge" requires a bridge, and mode: "page" reads the
page even where there is one.
import { expect, test } from "@playwright/test"
import { captureAgentTools, checkPage } from "@/components/ui/agent-check/playwright"
import { formatAgentReadiness } from "@/components/ui/agent-check/check"
test("settings is agent-ready", async ({ page }) => {
await captureAgentTools(page)
await page.goto("/settings")
const report = await checkPage(page) // or checkPage(page, { agent: "agent" }) for window.agent
expect(report.score, formatAgentReadiness(report)).toBe(100)
})
From the command line
cli.ts checks pages by URL in Chromium, any site or yours on localhost, and exits 1 when
one scores under --min-score (100):
npx tsx components/ui/agent-check/cli.ts http://localhost:3000 /settings /billing
Paths after the first URL are read against it. It uses a page's UI SDK bridge when it finds
one within a few seconds, and reads the page when not; --mode bridge or --mode page
chooses. --agent <global> names the bridge's global when the app doesn't register WebMCP
tools, --root <selector> limits where it looks, --channel chrome uses installed Chrome
instead of Playwright's Chromium, and --json prints the reports as JSON.
Paste a link
uiset.dev/check runs the same check on any public page: paste its link, and it
loads the page in a browser and shows the report. A link to the report
(uiset.dev/check?url=example.com) checks the page again when it opens, and each address's
report is kept for ten minutes. It loads public pages only: an address on a private network,
or anything a page or its redirects reach there, isn't loaded. It skips images, video and
fonts, which don't change what an agent finds, and stops a page that takes over 45 seconds.
For a page on localhost or behind a sign-in, use the bookmarklet.
The bookmarklet
The Agents page has a bookmarklet: drag it to your bookmarks bar and click it on any page,
including yours on localhost and pages you're signed in to. It asks the page's bridge when
it finds one at window.agent, reads the page when not, and draws the report over the page:
choose a problem to outline its elements. It runs in your browser, so nothing leaves it.
In your own app, showAgentReadiness() from @/components/ui/agent-check/overlay draws the
same report, with your bridge if you pass it ({ agent }).
Limits
- A snapshot lists 100 components and a query returns 100 at most. Past 100 components of one kind, the check says how many it couldn't read.
- An exact name doesn't win over a longer one in UI SDK today (vercel-labs/ui#612), so "Region" beside "Revenue by region" is reported, as a step by "Region" fails.
unconfirmedreads a button's words, so it can't know what a button with other words does.- Reading a page,
unseengoes by what looks clickable: a click handler added from script on an element with no pointer cursor isn't found. Frames from other sites and closed shadow roots aren't read.
Fixes that come up often
- A tooltip that repeats its trigger's name. A closed tooltip takes its trigger's name
(vercel-labs/ui#604), so the name finds two
components. Put
data-agent-hiddenon its content: agents read the trigger's name, and people and screen readers are unaffected. - A field or menu that repeats a component's action. A grid's search field holds the
grid's name ("Search orders" beside "Orders"). When the component offers the same action
(
filter), hide the field from agents withdata-agent-hidden; they use the action. - A row's controls. Give each a verb of its own ("Open Launch plan", "More for Launch plan"), so none is the bare title that finds both.
- Web Components named on an inner part. The web bridge reads a component's name from
its root element: put the
aria-labelof aui-tabs-list, aui-scroll-area-viewportor aui-slider-thumbonui-tabs,ui-scroll-areaorui-slidertoo.