Why consequential actions ring

Some actions have effects the user should own: a refund, a saved setting, a cancelled order. The assistant can be wrong about which order, or about whether the user meant it. For these, the library offers two shapes, and neither lets the assistant act alone.

Ringing: the user presses

A consequential action rings. The assistant points at the element: it is scrolled into view, ringed, and labeled with what pressing does. Then the assistant tells the user it is ready. The user presses it, or does not.

This keeps the effect in the user’s hand and in the page’s own UI. The user sees the real button, in its real state, next to the data it acts on. Nothing new to trust appears: no summary of what the assistant thinks it is about to do. If the button is disabled or gone, the ring does not happen, and the assistant hears why.

The ring leaves when the user dismisses it or acts. It does not block the page.

Confirming: the user approves

Some actions are fine to press once the user agrees, but awkward to find on the page. consequential="confirm" asks in the panel instead. The card names the action, and the user approves or denies. On approval the library presses the element itself.

The pause is assistant-ui’s human(), which lives in the browser. The backend sees an ordinary tool call whose result arrives late. A denial is a plain answer, not an error: “The user declined … That is final: leave it unless they ask for it again.” The instructions tell the assistant the decline is final, so it does not ask again in the same breath.

Before pressing, the library checks the element again. The card may have waited while the row left or the button turned disabled.

Choosing between them

Ring when the user should see the effect in place before it happens, like a refund on the order’s own page. Confirm when the conversation already holds enough context and the press itself is the routine part, like cancelling an order the user just named.

Tools have no element to point at, so a consequential tool always confirms.

Why not let the backend gate it

Server-side approval gates exist, but they ask about a tool call, not about a thing on the page. Ringing needs the page. Confirming needs the row the assistant picked from a grouped action. Both live where the action does, in the browser, and both work with no backend change.