Skip to main content
An agent-ready app is one whose buttons, links, fields and menus carry plain names that the HelpAlive agent can read: their visible text or their accessible names. This page is for developers and designers who want the agent to work well in their app. There is nothing to install or tag. The same habits that help screen-reader users help the agent.

​
Agent-ready apps at a glance

  • The agent reads the page as structured text, not as a picture. It takes no screenshots.
  • For each control it reads the kind of control, its name, its state, and the text around it.
  • You add no data attributes, selectors or ids for HelpAlive.
  • Clear names, labeled fields, native elements and errors shown as text all help the agent.
  • When the agent meets something it can’t read, such as a <canvas> or a frame from another site, it hands the task back to the user.

​
How the agent reads your page

The agent reads the page as structured text, not as a picture. It takes no screenshots. For each button, link, field and menu, it reads:
  • what kind of control it is, such as a button, a link, a text field or a checkbox;
  • its name, which refers to the visible text, or the accessible name from a <label>, aria-label, aria-labelledby, alt or title;
  • its state, such as checked, disabled, selected or expanded, and the value a field shows, except in password fields;
  • the headings, section titles, notices and error messages around it.
Hidden elements are left out. Open shadow DOM, and frames from your own origin, are read like the rest of the page. You add no data attributes, selectors or ids for HelpAlive, because the agent works with the page as your users see it.

​
Prerequisites

​
How to make your app agent-ready

1

Give every control a name

An icon-only button needs a name a screen reader would announce. Add aria-label, or visually hidden text.
2

Tie each field to its label

Use <label for>, or wrap the field in its label. A placeholder alone is not enough, because it disappears once the user types, and it reads as a hint, not a name.
3

Use plain, distinct words

Prefer “Invite teammate” to “Go”. When a list repeats the same button on every row, the row’s own text tells them apart.
4

Use native elements or the right role

A <button>, <select> or <input type="checkbox"> says what it is. If you build your own, give it the matching role and states, as accessible component libraries already do.
5

Show errors as text

Write validation errors as text near the field, or link them with aria-describedby. The agent reads them, as a user would.

​
What the agent can’t read

The agent hands the task back to the user when it meets something it can’t read or shouldn’t do:
  • drawings in a <canvas>, and other content drawn as pixels;
  • content inside a frame from another site;
  • controls with no name it can find;
  • file uploads, phone codes, passwords, downloads, system dialogs and other apps.
Safety and hand-backs lists the rest.

​
Check it works

  1. Run your browser’s accessibility checker, or a tool such as Lighthouse, on a busy page. Fix controls flagged as having no name.
  2. Open the agent in your app and ask it to do a task on that page. Watch where it hands back to you.

​
Why does the agent stop and ask the user to take over?

The agent stops because it reached a control it couldn’t name or read. Find the step where it stopped, and give that control a visible label or an aria-label.

​
Why does the agent pick the wrong one of several similar buttons?

The agent picks the wrong button because the buttons share a name. Make each name specific, for example “Edit billing address” and “Edit shipping address”.

​
Next

How HelpAlive works

From the question to the task.

Assists

Does the steps, or shows how.

Safety and hand-backs

What it always hands back.
Last modified on October 11, 2026