Agent Actions on the Website
Prepare target markup and enable the agent's website element actions.
Actions and Limits
After an explicit user request, the agent can call one of eight types:
| Type | Result | Limit |
|---|---|---|
highlight | Highlights the target. | Does not open a hidden panel automatically. |
scroll_to | Scrolls to the target. | Does not open a hidden panel automatically. |
focus | Moves focus to an element. | The target must support focus. |
click | Clicks a button, link, or another available HTMLElement. | Disabled targets are blocked; the site must confirm dangerous consequences. |
fill | Fills a text-like input, textarea, or contenteditable. | Password, card, and other sensitive fields are blocked. |
clear | Clears an input, textarea, select, or contenteditable. | The target must support clearing. |
select | Selects an option in an HTML select or a custom control with combobox/listbox markup. | The option must be unambiguous and available. An arbitrary button without the select contract is not supported. |
toggle | Changes a checkbox, radio, or role="switch" element. | It does not apply to arbitrary buttons. |
An action uses an exact data-ai-context-id, not fuzzy label matching. Supply either one target or a chain of up to 12 targets, never both. A chain supports only highlight and scroll_to: the widget finds the furthest available step and continues the guide after a DOM change or visitor click.
When the same key occurs more than once, the target needs a complete entity_type and entity_id pair. Otherwise, the ambiguous action is blocked.
If no exact element is found or several elements match equally, the agent does not choose one at random and explains the route in words.
Multiple tabs and dialog history
Only the widget instance that sent the request runs the automatic action. When one dialog is open in several tabs, the command does not run on every page at once. Opening history or reloading the page does not run old actions again.
To see a highlight again, select Show on page in the action card. This replay runs on the current page, where the target element must be available. It does not change the stored result of the original execution. A slow response alone does not invalidate the command while the request belongs to this open widget.
How to Read the Result
While an action runs, the widget shows a card with its target, state, and execution details.
Final states:
- completed — the page confirmed execution;
- not found — the element is not on the current screen;
- blocked — the action cannot be performed automatically;
- error — the action failed.
The interface may show an intermediate execution state, but only success, not_found, blocked, and failed are final results. Do not treat the action as complete until the card shows success.
Diagnostics
If element selection or an action does not work:
- Check that “Element selection” is enabled in widget settings.
- Make sure the page loads the current widget code.
- Check that the element has readable text,
data-ai-label, ordata-ai-context-id. - Do not reuse one
data-ai-context-idfor several elements without adata-ai-entity-type/data-ai-entity-idpair. - For a hidden target, check its standard trigger relationship or
data-ai-reveals-context-id. - To find an instruction, check that the key matches in the element and Markdown; add
data-ai-kb-queryif necessary. - For a “not found” state, make sure the user is on the right page and the element has already rendered.
What to Add Next
Markup on this page is enough for ordinary highlighting and DOM actions. If an agent response must run a separate site business operation, such as opening an order through your router or preparing payment, use a custom action. To edit field text with a review step before application, use inline edits.