AI Modes

The ARCY SDK exposes a floating assistant that operates in three explicit modes. Users switch between them using a tab bar inside the chat panel.

Modes

Chat mode

The user asks where something is or requests general help. ARCY responds with a text message and may include a link to the relevant page inside the chat. That is the full scope of Chat mode. No element highlighting, navigation, or actions occur. Conversation history is preserved when the chat panel is closed and restored when it reopens.

The chat bar auto-expands vertically up to five rows as the user types. If the user manually resizes the bar taller, the row limit increases proportionally. Vertical resizing is available in Chat mode only.

Teach mode

The user asks how to do something. ARCY generates an ordered, step-by-step coachmark walkthrough that highlights real UI elements on the page. No text answer appears in the chat bar. Instead, a floating coachmark card appears anchored to each relevant element in sequence.

Each coachmark shows:

• A title for the session
• The current step message
• Step counter (e.g., 2 / 5)
• Back, Next, and Done navigation controls

The user moves through steps at their own pace. When a step specifies an anchorId, the target element receives a pulsing glow highlight and is scrolled into view automatically if off-screen. The highlight follows pointer events through to the element so the user can interact with it normally. If the element cannot be found (e.g. it was removed), the step still displays in the tooltip without a highlight.

The tooltip can be repositioned by dragging its header. Once dragged, the tooltip stays at the chosen position for all subsequent steps. Before the first drag, it centers on screen. The tooltip is automatically clamped within the viewport on drag end and window resize.

Minimize and restore

Clicking the X button on the tooltip minimizes it to a small circular floating icon instead of ending the session. The icon appears at the tooltip's last position and shows the current step counter (e.g. "3/7"). The icon is draggable with the same viewport clamping rules as the full tooltip.

Clicking the minimized icon restores the full tooltip at the icon's current position and resumes the teach flow from the same step. When minimized, the element highlight is removed. When restored, the highlight reappears on the current step's element.

The "Done" button on the last step still fully ends the session. To end a session mid-flow, the user must restore the tooltip and navigate to the last step.

Cross-route persistence

Tooltip state (position, minimize state, step index, drag flag) is persisted to sessionStorage alongside other SDK UI state. When a teach step triggers a route change that causes a full page reload, the tooltip (or minimized icon) reappears at the persisted position and step after the page loads.

In Teach mode, the chat bar can only be resized horizontally. Vertical resize is disabled.

When the teach session starts, the chat bar closes automatically so it does not visually conflict with the coachmark. When the session ends, the chat bar reopens so the user can ask a follow-up question.

Agent mode

The user tells ARCY what to do. ARCY creates an action plan and executes the steps on the user's behalf using the constrained action model (click, focus, fill, navigate). No arbitrary DOM manipulation occurs.

While ARCY is planning, a toast notification appears at the bottom-right of the screen with a loading indicator. When planning finishes, ARCY shows the full plan in the chat panel for review before anything runs. The user can approve or cancel. Execution only begins after explicit approval.

Agent mode has two sub-modes controlled by a toggle in the chat panel:

Ask (default): After the user approves the overall plan, ARCY shows a coachmark before each individual step explaining what it is about to do and why. The user can allow, skip, or cancel each step.

Auto: After the user approves the overall plan, ARCY executes all steps sequentially and shows progress in the panel. No per-step confirmation is required.

When all steps finish, a success toast confirms completion and auto-dismisses after 4 seconds. If a step fails, an error toast appears and the user can dismiss it to reset the agent state. Step state is preserved across page navigations so multi-page plans continue correctly after a route change.

Step-level confirmations (Human in the Loop)

In both Ask and Auto modes, certain steps pause automatically and require explicit confirmation before ARCY proceeds. This happens when:

• The action cannot be undone. ARCY shows "This action cannot be undone" and requires the user to click Confirm.
• The step was marked for confirmation by the AI. For consequential but reversible actions such as submitting a form, sending an invite, or publishing content, ARCY shows "This step requires your confirmation." The user must click Confirm to proceed.
• The target element cannot be found. ARCY shows "Could not find this element." The user can allow the attempt anyway or skip the step.
• The target element is currently unavailable. ARCY shows "This element is currently unavailable" (for example, a button that is disabled or obscured). The user can allow the attempt or skip.

In all four cases, the user can cancel the entire plan using the X button on the coachmark. Steps that require confirmation show a Confirm button instead of Allow; steps where skipping is meaningful show both Confirm and Skip.

In Agent mode, the chat bar can only be resized horizontally. Vertical resize is disabled.

Anchoring elements for agent actions

For ARCY to interact with an element in Agent mode, the element must have a data-arcy attribute set to a stable, descriptive ID.

<button data-arcy="invite-member-btn">Invite member</button>
<input data-arcy="email-input" type="email" />

ARCY uses the anchor IDs you have instrumented to construct its action plan. Elements without data-arcy cannot be targeted. See the data-arcy reference for placement guidance.

Proactive intervention

Intervention is a background mode that monitors user behavior and offers help when ARCY detects a struggle signal, such as repeated clicking in the same area, extended inactivity, or form abandonment.

Intervention is enabled by default. Users can turn it off in the ARCY settings panel.

When a struggle signal fires, ARCY sends a silent query and, if it produces a relevant teach response, shows a small prompt in the bottom-right corner of the screen. The user can tap "Show me" to open the teach walkthrough or dismiss the prompt.

No query is sent while the chat panel is open or when the session has not been established.

User control

Users can toggle proactive help from the ARCY settings panel inside the widget. The toggle is labeled "Proactive help."

Interaction history

The ARCY settings panel includes a History section that lists recent interactions across all three modes. Each entry shows:

• The mode used (Chat, Teach, or Agent)
• The first message or query the user sent
• How long ago the interaction started
• For Chat mode: how many messages were exchanged

History is stored in localStorage and persists across page reloads within the same browser. It is scoped to this browser only and is never sent to ARCY servers. Users can clear the full history from the settings panel at any time.

A new Chat interaction is recorded when the user sends the first message of a fresh conversation. Subsequent messages in the same conversation increment the message count of that entry. Teach and Agent interactions are recorded on every query because each one starts a new session.

Supported action types

Agent mode executes these action types only. No other DOM operations are performed.

Destructive actions (delete, remove, drop) are never included in agent plans. If a user asks for a destructive action, ARCY responds with a teach walkthrough instead.