Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agents.candu.ai/llms.txt

Use this file to discover all available pages before exploring further.

Wizards are not limited to free-text chat. They can show structured UI when the user needs to choose, provide details, review generated content, confirm an action, or copy output. Think of these as interaction patterns. The wizard decides when a pattern is useful, then renders the right UI for that moment.

Choose

Use chips, single-choice lists, or multi-choice lists when the answer shape is known.

Collect

Use forms when the wizard needs structured fields such as emails, URLs, numbers, dropdowns, or longer notes.

Review

Use editable reviews, summaries, and confirmations before important actions run.

​
Pattern Reference

PatternUse when the wizard needs to…Underlying primitive
ChipsOffer a few short choicesshowChips
Single choiceHave the user choose exactly one optionshowSelectCards
Multiple choiceHave the user choose more than one optionshowSelectCards
FormCollect structured fieldsshowShortForm
Editable reviewLet the user amend generated contentshowRefineAndConfirm
Read-only summaryRecap values before a final stepshowSummary
Code blockShow copyable text, JSON, or codeshowCode
Action confirmationAsk the user to approve a confirmation-required actionSystem-generated
In most wizard instructions, describe the pattern you want rather than the raw tool call. For example: “Show chips for Activation, Education, and Expansion” is usually better than pasting a full JSON schema into a stage booster.

​
Sequencing UI

A wizard can show more than one structured UI surface in sequence. This is useful when a task has several distinct questions or review moments. For example, a gifting wizard might:
  1. Show a single-choice list of gift options.
  2. Show a form for recipient details.
  3. Show an editable review of the message.
  4. Show a final confirmation before sending.
The user experiences this as a guided flow: question 1 of 3, question 2 of 3, review, confirm. The wizard can still carry context forward between each step. Use sequential UI when:
  • Each question has a different shape.
  • Later questions depend on earlier answers.
  • You want the user to review generated content before the final action.
  • A required field appears only after a lookup or policy check.
Avoid combining everything into one large form when the user needs to make a meaningful choice first.

​
Chips

Use chips for a few short choices that do not need descriptions. Good examples:
  • Yes / no
  • Shorter / warmer / more professional
  • Retry / skip / cancel
  • Activation / Education / Expansion
Tell the wizard: 
Show chips for the goal: Activation, Education, Expansion.
Best practices:
  • Keep labels short.
  • Use chips for 2-8 options.
  • Do not use chips when options need descriptions or images.
  • For risky choices, use a list or review screen instead.

​
Single Choice

Use single choice when the user should pick exactly one option from a small set. Good examples:
  • Pick a segment to test
  • Choose one matching contact
  • Select an invoice type
  • Choose a troubleshooting path
  • Confirm which existing project the user meant
Single-choice options rendered as vertical cards
Tell the wizard: 
Show a single-choice list of matching segments. Use the segment name as the label and include a short description of the criteria when available.
Best practices:
  • Keep the list short.
  • Put the most likely option first.
  • Include descriptions when labels alone could be ambiguous.
  • Use explicit radio-style selection when the choice should not submit on first tap.
  • Use an additional option for escape hatches such as “Other”, “None of the above”, or “Add new”.
  • For long lists with very short labels, chips can still work. Otherwise use a searchable form dropdown.

​
Multiple Choice

Use multiple choice when the user can select more than one option before submitting. Good examples:
  • Select locations to enable
  • Pick checklist items to include
  • Choose fields to map
  • Select actions to add to a wizard
Multiple-choice options rendered with checkbox affordances
Tell the wizard: 
Show a multiple-choice list of locations. Let the user select one or more, then continue.
Best practices:
  • Use multiple choice only when more than one answer is valid.
  • Keep option labels scannable.
  • Use descriptions when the consequence of each choice is not obvious.
  • Use an additional option for escape hatches such as “Other”, “None of the above”, or “Add new”.
  • For long lists with very short labels, chips can still work. Otherwise use a searchable multi-select dropdown.

​
Forms

Use forms when the wizard needs structured input from the user. Good examples:
  • Email address
  • Name and occasion
  • URL to test
  • Endpoint path and method
  • Campaign name, owner email, and message notes
  • Dropdown selection from a larger list
Form collecting launch details
Tell the wizard: 
Show a form to collect campaign name, owner email, and message notes. Campaign name and owner email are required. Message notes can be a longer text field.
Best practices:
  • Ask for related fields together instead of one turn at a time.
  • Use email fields for email addresses.
  • Use number fields for numeric inputs.
  • Use textarea fields for prose.
  • Use code fields when the user needs to provide JSON, YAML, markdown, or configuration.
  • Use searchable dropdowns for long known lists.
  • Label fields by what the user should enter, not by what the system will do with it.

​
Editable Review

Use editable review when the wizard has generated content and the user should inspect or amend it before continuing. Good examples:
  • Review an email draft
  • Edit generated instructions
  • Confirm a message before sending
  • Tune an action description before saving
  • Review a generated prompt before opening an editor
Tell the wizard: 
Draft the message, then show an editable review screen. Let the user revise the message before continuing. Do not send until the user confirms.
Best practices:
  • Use editable review after generation, not for initial data collection.
  • Prefill the fields with the generated content.
  • Wait for explicit confirmation before running the next write action.
  • Do not auto-advance after a tone or content rewrite.

​
Read-Only Summary

Use a read-only summary when the user needs to review final values but should not edit them in that surface. Good examples:
  • Gift name, recipient, and total cost
  • Invoice client, line items, and total
  • Segment name and criteria
  • URL rule before updating a placement
  • Quote details before submission
Tell the wizard: 
Before creating the segment, show a read-only summary with the segment name, criteria, and matched user count if available.
Best practices:
  • Include the values that matter for user trust.
  • Do not show every internal field.
  • Use editable review instead if the user should change values directly.
  • Pair summaries with confirmation-required actions for creates, updates, deletes, sends, or submissions.

​
Code Blocks

Use code blocks when the wizard needs to return copyable text, JSON, API details, or code. Good examples:
  • Installation snippet
  • JSON schema
  • cURL request
  • Agent instruction block
  • Markdown template
Tell the wizard: 
Show the generated JSON schema as a copyable code block.
Best practices:
  • Use code blocks for output the user should copy elsewhere.
  • Use a form with a code field when collecting code from the user.
  • Keep generated code self-contained.

​
Action Confirmation

Action confirmation appears automatically when an action uses a confirmation-required execution policy. Use this for actions that create, update, delete, send, submit, approve, or trigger an external effect. The user sees what will happen before anything changes.
Confirmation-required action review screen
Tell the wizard: 
After the user reviews the summary, call the confirmation-required action. If the user declines, explain that nothing changed and ask how they want to adjust.
Best practices:
  • Use Automatic for safe read actions.
  • Use Confirm required for writes or external effects.
  • Treat a declined confirmation as a valid user choice.
  • Do not hide risky changes in chat text.

​
Runtime Mapping

Most authors should describe the UI pattern they want. The runtime maps those patterns to primitives.
PatternPrimitiveNotes
ChipsshowChipsCompact pill choices. No descriptions or thumbnails.
Single choiceshowSelectCardsSet multiSelect: false. Use showSelectAffordance: true when the user should explicitly submit instead of tapping once.
Multiple choiceshowSelectCardsSet multiSelect: true. Use showSelectAffordance: true to show checkbox affordances.
FormshowShortFormSupports text, email, number, textarea, code, dropdown, searchable dropdown, and multi-select dropdown fields.
Editable reviewshowRefineAndConfirmUses the same field types as forms, but is for reviewing generated content.
Read-only summaryshowSummarySupports label-value pairs. Values can be strings or string arrays.
Code blockshowCodeRead-only copyable text or code.
Action confirmationSystem-generatedAppears when an action has Confirm required.
For long option lists, prefer a searchable dropdown in a form over a long card list.

​
Advanced Details

Use these details when writing low-level agent instructions or debugging a wizard runtime issue.
showSelectCards powers both single-choice and multiple-choice card lists.
BehaviorSettings
Immediate single choicemultiSelect: false, showSelectAffordance: false
Radio-style single choicemultiSelect: false, showSelectAffordance: true
Plain multiple choicemultiSelect: true, showSelectAffordance: false
Checkbox-style multiple choicemultiSelect: true, showSelectAffordance: true
Thumbnail gridpresentation: "gridCards"
verticalCards is the default presentation. Use gridCards only when every option has assetUrl; otherwise the UI falls back to verticalCards.
Card options support optional description, assetUrl, prefix, and selected fields.Use prefix only with verticalCards. If you use it, all options should use the same prefix type: number, text, or icon. Do not mix prefix types or add a prefix to only some options.Use selected: true when re-showing a choice and you want an option to start selected. Put selected options at the start of the options array, keeping stable order within selected and unselected groups.Use additionalOption for escape hatches such as “Other”, “None of the above”, or “Add new”. Do not use it for free-text; collect free text with a form.
Forms support:
  • Single-line text
  • Email
  • Number
  • Textarea
  • Code
  • Dropdown
  • Searchable dropdown
  • Multi-select dropdown
Form fields are required by default unless marked optional.
progressStage advances to the next wizard step after the current step’s completion criteria are satisfied.dismissModal closes the wizard when it is running inside a modal shell. It is context-specific and should only be used after the task is complete or the user has been navigated to the next place.
showCode is read-only. Use it for generated output the user should copy.To collect code from the user, show a form with a code field instead.

​
Common Mistakes

The model already receives the runtime tool definitions. In most cases, tell the wizard which pattern to use and what content to show, rather than duplicating the full schema in the booster.
A wizard can only use the actions and UI patterns available in its current step. When you design or revise a step, check that the step has access to the data it needs and that the intended interaction pattern is supported there.
Tables are useful in docs, but they are usually a poor format for stage boosters. For agent instructions, prefer direct prose that keeps related conditions in the same sentence, such as “Return up to 12 gift options ranked best first, with the most relevant options first.” Use line breaks sparingly when the relationship between ideas matters; a blank line can make two related instructions feel unrelated.
If the wizard needs the user to pick a known segment, contact, location, status, or action, use a list, chips, or dropdown. Free text creates unnecessary ambiguity.
Cards are best for short, meaningful choices. If the list is long, use a searchable dropdown.
If the wizard generated the content and the user is reviewing it, use editable review. Forms are for collecting input. Review screens are for confirming or amending generated output.
If the user is reviewing final values before a write action, use a read-only summary. If they need to change values, take them back to the previous collection or review step.
Only progress when the step’s completion criteria are satisfied. If the wizard advances early, tighten the criteria or adjust the stage booster.

​
Design Principle

The best wizard does not feel like a chatbot with occasional forms. It feels like a guided product workflow that uses conversation only where conversation is the right interface. Use chat for intent, explanation, and recovery. Use structured UI for choices, forms, review, confirmation, and completion.