Agent Prompt

For development, import AgentPrompt from @servicetitan/anvil2-ai-kit. For design, find it in the AI Kit Web Component Library file.

Options

The Agent Prompt supports single-select and multi-select modes, a free-text option, and multi-step flows.

Selection Modes

Each mode drives a different selection interaction. Single-select uses radio semantics; multi-select uses checkbox semantics.

Single Select

Each option row acts as a radio — selecting one deselects all others. The selected row is outlined to confirm the choice.

Multi Select

Each row carries a checkbox, and any number of options can be selected. The resolved answer is the set of checked values.

Free Text

The “Something else…” free-text row renders when onOtherChange is wired. In single-select, the row is mutually exclusive with the option rows — typing deselects any chosen option, and selecting a row retains but subordinates the typed text. In multi-select, the typed value is an independent addition to the selection.

Multi-step

Passing a step object switches the action row to a Back/Next/Send stepper and shows the current step count in the header. The first step shows only Next; middle steps show both Back and Next; the last step shows Back and Send.

Behavior

The primary action is always enabled — attempting to send with nothing selected surfaces an inline error rather than disabling the button.

Visual States

The prompt renders in an empty (no selection), selected, and disabled state. The disabled state dims the options and action row but keeps the close button active so the user can always dismiss.

Location

The Agent Prompt occupies the same position as the Prompt Bar — replacing it for the duration of the question. Once the user sends an answer, the Prompt Bar returns.

Empty Answer Error

When the user presses Send or Next without selecting an option or entering free text, an error message appears beneath the options. Selecting any option or typing in the free-text field clears the error immediately.

Usage Guidelines

When to Use

Use the Agent Prompt when:

Clarifying questions – The agent needs an answer from the user before it continues.
Structured answers – The user answers by choosing one option or several options from a set.
Multi-part questions – The agent needs answers to several questions in sequence. Use the multi-step flow to move through them with Back, Next, and Send.

When not to use

Avoid using the Agent Prompt for:

Open-ended requests – When the agent has no set of options to offer, let the user reply in the Prompt Bar.
Optional follow-ups – Use Suggestions to offer quick follow-up prompts beneath an agent response when the agent does not need an answer to continue.

Keyboard Interaction

Users can navigate and operate the Agent Prompt using standard keyboard controls.

Key	Description
Tab	Moves focus through the option group, free-text field, and buttons
Arrow Up / Down	Navigates between options in single-select mode
Space	Checks or unchecks the focused option in multi-select mode
Enter	Activates the focused button (Send, Next, Back, or Close)

Code

Implementation
AgentPrompt Props
AgentPromptOption

Common Examples

To use the AgentPrompt, pass a question, an options array, controlled value / onChange, and a required onClose handler. The close button is always shown and remains available while the prompt is disabled.

import { AgentPrompt } from "@servicetitan/anvil2-ai-kit";

function ExampleComponent() {
  const [value, setValue] = useState<string | null>(null);

  return (
    <AgentPrompt
      question="How should I proceed?"
      options={[
        { value: "a", label: "Choice A" },
        { value: "b", label: "Choice B" },
      ]}
      value={value}
      onChange={setValue}
      onSend={(answer) => send(answer)}
      onClose={() => dismiss()}
    />
  );
}

Selection mode

Single-select is the default. Each row is the control; the selected row is outlined. Set selectionMode="multi" for checkbox semantics and a string[] value.

Free text

Wiring onOtherChange shows the “Something else…” row. In single-select, free text is mutually exclusive with a selected row; the text is retained if the user switches back. In multi-select, free text is independent and is appended to the selected values on send.Pass allowOther={false} to hide the row even when a handler exists. Pass true without onOtherChange only in development as a misconfiguration.

Multi-step

Pass step={{ current, total }} to replace the single Send with a stepper. Wire onNext to advance; without it, Next validates but does not move. onBack is never validated.

Empty answer

Send and Next stay enabled. Submitting with no selection and no free text shows the empty-answer error instead of calling onSend or onNext.onSend and onNext receive a resolved answer: the selected option in single-select, or the checked values with non-empty free text appended in multi-select. Free-text strings pass through verbatim.

Internationalization

AgentPrompt owns these localized strings:

ai-kit.agentPrompt.close
ai-kit.agentPrompt.otherPlaceholder
ai-kit.agentPrompt.send
ai-kit.agentPrompt.back
ai-kit.agentPrompt.next
ai-kit.agentPrompt.emptyError
ai-kit.agentPrompt.step

Localize question and option labels before passing them. Override otherPlaceholder or emptyErrorMessage on the component, or mount AiKitIntlProvider inside CartoTheme. step receives {current} and {total}.

React Accessibility

The question labels the options group through aria-labelledby.
Single-select uses radio semantics. Multi-select uses checkbox semantics.
headingLevel sets the question’s heading tag independently of visual size.
Close remains available while disabled is true.

<AgentPrompt
  question="How should I proceed?"
  options={options}
  value={value}
  onChange={setValue}
  onSend={send}
  onClose={dismiss}
/>

`AgentPrompt` Props

The AgentPrompt accepts the following props. It is a discriminated union on selectionMode. value and onChange match that mode.

(value: string | null) => void | (value: string[]) => void

required

Fired when the selection changes. Signature matches selectionMode.

() => void

required

Fired when the close button is pressed. Always required.

AgentPromptOption[]

required

Selectable options, rendered in order.

string

required

Question shown in the header and used as the options group’s accessible name.

string | null | string[]

required

Controlled selection. string | null in single-select; string[] in multi-select.

boolean

Whether to show the free-text row. Defaults to whether onOtherChange is provided.

string

Class merged onto the root element.

boolean

Disables the prompt. Close remains available.

string

Override for the localized empty-answer error.

"h2" | "h3" | "h4" | "h5" | "h6"

default:"h2"

Semantic heading level for the question.

() => void

Fired when Back is pressed. Never validated.

(answer: string | null) => void | (answer: string[]) => void

Fired when Next commits a valid answer. Required for the stepper to advance.

(value: string) => void

Fired on every free-text edit. Wiring it shows the row by default.

(answer: string | null) => void | (answer: string[]) => void

Fired when Send commits a valid answer. Receives the resolved answer.

string

Placeholder for the free-text row. Defaults to the localized “Something else…”.

string

Controlled free-text value.

"single" | "multi"

default:"single"

Selection semantics. Co-varies with value and onChange.

{ current: number; total: number }

Multi-step position. Omit for a single Send action.

const option: AgentPromptOption = {
  value: "choc",
  label: "Chocolate",
};

`AgentPromptOption`

ReactNode

required

Display content for the option.

string

required

Stable identity used as the selection value and React key.

boolean

Disables this option while leaving the rest interactive.

Concepts & Guidelines

Anvil2

Resources

Agent Prompt - Web

Options

Selection Modes

Single Select

Multi Select

Free Text

Multi-step

Behavior

Visual States

Location

Empty Answer Error

Usage Guidelines

When to Use

When not to use

Keyboard Interaction

Code

Common Examples

Selection mode

Free text

Multi-step

Empty answer

Internationalization

React Accessibility

`AgentPrompt` Props

`AgentPromptOption`

​Options

​Selection Modes

​Single Select

​Multi Select

​Free Text

​Multi-step

​Behavior

​Visual States

​Location

​Empty Answer Error

​Usage Guidelines

​When to Use

​When not to use

​Keyboard Interaction

​Code

​Common Examples

​Selection mode

​Free text

​Multi-step

​Empty answer

​Internationalization

​React Accessibility

​AgentPrompt Props

​AgentPromptOption

Options

Selection Modes

Single Select

Multi Select

Free Text

Multi-step

Behavior

Visual States

Location

Empty Answer Error

Usage Guidelines

When to Use

When not to use

Keyboard Interaction

Code

Common Examples

Selection mode

Free text

Multi-step

Empty answer

Internationalization

React Accessibility

`AgentPrompt` Props

`AgentPromptOption`