Usher Pro

Usher vs Usher Pro

• Usher: Usher answers, takes users to the right page, and runs your app’s own tools. Every key has it.
• Usher Pro Pro: Usher Pro does all of that, and can also do the task on the page itself: fill in forms, pick dates and options, and finish workflows. Voqal turns it on per key.

Same install. Usher Pro is a switch on your key, not a package. Your code is identical either way. To turn it on, email team@voqal.ai with the key. It applies from each user’s next session.

How they work together:

• If one of your app’s tools fits the request, the assistant uses it. This is the fastest and most reliable path.
• With Usher Pro, when no tool fits, it does the task on the page, the way the user would.
• Without Usher Pro, it takes the user to the right page and tells them how to finish.

What it does

Usher Pro works on the page the user is on. It reads the page’s controls, decides the next step (type into a field, pick an option, choose a date, click a button), takes that step the way a person would, and then reads the page again. It repeats this until the task is done. If the task is on another page, the assistant takes the user there first.

A task stops in one of three ways. It finishes. The user stops it. Or it reaches a step it shouldn’t take without the user, or can’t take at all. Every task also has a step limit and a time limit, so it can’t run on and on.

Turning it on

Usher Pro is enabled on your key by Voqal. To turn it on, email team@voqal.ai with your key. You don’t install a different package or change any code. The same @voqal/usher-react (0.1.0-beta.5 or later) and the same <Usher voqalKey> pick it up from the user’s next session. Keys without Usher Pro behave exactly as before.

How do I know if I have Pro?

There is no prop or flag in your code to read. Voqal tells you when it turns Usher Pro on for a key. To check it yourself:

• Ask the assistant. On a page with a form, say “fill in the name field with Test”. With Usher Pro it types it in. Without it, it tells you how to do it yourself.
• From code, during a live session, call ref.current.operate(goal). On a key without Usher Pro it resolves to { kind: "refused", reason: "unknown_tool" } and does nothing. With Usher Pro it really runs the task, so use a harmless goal on a test page.

Confirmation and stopping

• A card before anything consequential. Before Usher Pro clicks a button that submits, confirms, books, pays, saves, updates, sends, approves, transfers, deletes, removes, revokes or cancels, it pauses and shows a card above the orb: “Confirm before I continue. Next step: Save changes.” The click happens only when the user taps Do it. With Not now, nothing is clicked, and the assistant says the last step is theirs.
• Stop means stop. If the user says or types “stop”, “cancel” or “never mind”, the task ends right away, even while a card is showing. A sentence that only contains one of those words, like “cancel my subscription”, is a new request, not a stop.
• One task at a time. A new request replaces the one in progress. The old task stops before the new one touches the page.

What it never touches

These are never sent to the decision service, so it can’t choose them. They are checked again right before every action, in case the page changed in the meantime.

• Password fields, and any field your page marks for a password or a one-time code.
• Payment card fields: the card number, security code and expiry (by their autocomplete hints, names, or labels).
• Hidden inputs and file uploads.
• Links and forms that would leave your app’s origin.
• The assistant’s own orb, chat panel and confirmation card.
• Anything you mark with data-usher-operate="off" (below).

Usher Pro acts as the signed-in user, in their browser. It can only do what that user could do with their own clicks. Your server-side permission checks still apply to every request it causes.

Keeping it away from parts of your app

Mark a control, or a section that wraps many, with data-usher-operate="off". Usher Pro won’t see it and won’t act on it. The assistant can still talk about that part of the page and point the user to it.

// One control<input name="internal-notes" data-usher-operate="off" />// A whole section: nothing inside it is seen or touched<section data-usher-operate="off">  <WireTransferForm /></section>

Good candidates: bank and payout details you would rather users type themselves, money movement, account deletion, and admin-only areas.

What leaves the browser

To decide each step, Usher Pro sends Voqal a description of the controls the user can currently see: each control’s label, role and current value, plus the page’s visible text (both cut down in size), and the steps taken so far. Voqal processes this with its AI model providers to choose the next step. Off-limits controls are never included. The page description isn’t stored: Voqal’s service logs only ids, counts and timings for each step. If conversation logging is on, the conversation log records the task the way it records any tool call: the request, and the outcome with the labels of the fields that were set. Say in your privacy notice that an AI assistant may read the current page to complete tasks.

See What leaves the browser for everything else a session sends.

When it can’t finish

When it can’t finish, Usher Pro tells the user what it did, names the field that’s still open using the page’s own label, and says how to finish. If the decision service is slow, unavailable, or switched off, the session carries on and the assistant guides the user instead, as plain Usher does.

Starting a task from code

UsherHandle.operate(goal) runs a task the same way as a spoken request, with the same confirmation card. It needs a live session on a key with Usher Pro. Without one, it returns a refusal and does nothing.

const usher = useRef<UsherHandle>(null);// Runs the same way as when the user asks out loud.const action = await usher.current?.operate("Change the payout account holder to Harbor Payments LLC and save it");// action.kind === "operated": action.status is done | partial | blocked | declined | stopped,// and action.message is the line the assistant says about it.

Usher Pro adds the diagnostics events operate:start, operate:step, operate:end, operate:confirm and operate:failed. They carry counts and timings, never page content. See Support & diagnostics.