Agent Prompt – 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.

AI Kit

Agent Experience

Agent Prompt – Code

Common Examples

Selection mode

Free text

Multi-step

Empty answer

Internationalization

React Accessibility

`AgentPrompt` Props

`AgentPromptOption`

​Common Examples

​Selection mode

​Free text

​Multi-step

​Empty answer

​Internationalization

​React Accessibility

​AgentPrompt Props

​AgentPromptOption

Common Examples

Selection mode

Free text

Multi-step

Empty answer

Internationalization

React Accessibility

`AgentPrompt` Props

`AgentPromptOption`