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-check

In 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:

tsx
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 or aria-label, or aria-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 own aria-label, and a dialog keepMounted so 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 inside data-agent-hidden if agents shouldn't use it.

Warnings, which don't:

  • unconfirmed: a button whose label starts with a word like Delete, Pay or Deploy has no data-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:

ts
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:

tsx
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, or aria-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 an onclick) 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.

ts
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):

bash
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.

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.
  • unconfirmed reads a button's words, so it can't know what a button with other words does.
  • Reading a page, unseen goes 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-hidden on 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 with data-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-label of a ui-tabs-list, a ui-scroll-area-viewport or a ui-slider-thumb on ui-tabs, ui-scroll-area or ui-slider too.