This guide walks through building a wizard from scratch: planning the flow, configuring steps, writing instructions for the AI, and placing the wizard in your product.
If you haven't yet, start with What is a wizard? for context on what wizards do and when to use them.
Plan the flow first
The best wizards solve one specific user problem. Before opening the configurator, sketch out the flow on paper or in a doc.
A useful planning prompt: "Where in our product do users regularly get stuck, and what would 'completing this task' actually look like for them?" Common examples: troubleshooting why content isn't showing, creating a segment, setting up onboarding, validating a placement.
For each step you're imagining, jot down:
The question the wizard should ask
The data the AI needs to fetch
The actions the AI might need to take
What "done" looks like at this step
A rough outline is enough. You'll refine it once you're in the configurator.
Single-step or multi-step?
Use a single-step wizard when the task is focused and the user just needs help completing one thing in one conversation. Use a multi-step wizard when the workflow has a real sequence — gather information, take action, validate — and different stages need different guidance.
Rule of thumb: a multi-step wizard guides a process; a single-step wizard helps with a task.
Confirm the actions exist
Before building, check that the actions your wizard needs are registered. Go to Actions → All Actions and confirm the agent will be able to do whatever the wizard requires — fetch data, check state, create or update records.
If actions are missing, register them first. Your engineering team can define new endpoints and connect them, or you can use Candu's discovery tools to scan your codebase or watch live API calls to generate draft actions for review.
A wizard can only do what its available actions allow, so this step gates everything else.
For a full walkthrough of identifying, creating, and testing actions — including what to ask engineering for, read Set up actions for your wizard.
Create the wizard
Go to Actions → Agents → New agent.
Slug
The unique identifier for your wizard. Use lowercase words separated by hyphens — create-segment-wizard, diagnose-content-not-showing. The slug is stable and used in code, so choose carefully.
Agent title
What users see at the top of the wizard. Make it task-oriented: "Why isn't this showing?", "Create a new segment", "Set up your onboarding flow."
Configure each step
Each wizard step has the same set of fields. Here's what each one does and how to use it.
Step title
The heading shown inside the wizard. Reflects what's happening at this point in the flow. "Let's figure out why this isn't showing", "Who should be seeing this?"
Goal description
The opening line shown before the user types anything. Keep it short. "What content would you like to troubleshoot?"
Input placeholder
Hint text in the input field. Guides the user toward the kind of input you want. "Enter the content ID."
Stage booster
This is the instruction set for the AI at this step. Write it like you're briefing a smart teammate who's joining mid-meeting.
A strong booster has four parts:
Context — what the agent already knows
Guidance — what to do, in what order
Constraints — what to avoid
Formatting — how to respond
Here's a worked example for a "why isn't this showing" wizard:
Context: You have the contentId from the previous step. The segment list has already been fetched.
Guidance: Check whether the selected segment includes this user. If it doesn't, explain why clearly. If it does, move to the next check.
Constraints: Don't guess. Don't suggest fixes until all the checks are complete.
Formatting: Keep replies short. Ask one question at a time. Don't use markdown. The labels are for your reference — paste the booster into the configurator as one passage. The four-part structure is the discipline; the prose is what the AI sees.
Always handle edge cases. Tell the AI explicitly what to do if context is missing, an API returns no results, an action fails, or the user gives an incomplete answer. The biggest source of wizard problems is the unhappy path.
Completion criteria
What "done" looks like at this step. Describe a state, not a click or a system event.
Good: "User has selected a segment and confirmed the page to test", "A segment has been created, or the user has chosen to skip."
Less good: "User clicks the Continue button."
Actions
Pick only the actions this step actually needs. Each step exposes the AI to a different subset — including actions the step doesn't need increases the chance the AI calls the wrong one.
Two rules:
Include every action the step might legitimately need
Remove write actions once they're no longer relevant in later steps
On governance: every action has a policy. Automatic lets the AI run the action immediately. Confirm required pauses the AI and asks the user to confirm before firing. Use Automatic for reads. Use Confirm required for anything that creates, updates, or deletes data.
Place the wizard in your product
Once the wizard is built, save and publish it. Then go to Content in Candu to place it where users will encounter it.
Add the Wizard component to your content. Paste in the wizard's slug so the content knows which wizard to load.
Where you place a wizard depends on the experience you want:
Inline — embedded directly in a page
Overlay — opens over the page when triggered
Attached to an element — anchored to a specific button or section
Behind a launcher — opens from a button, banner, or floating bubble
Pass context when useful
Some wizards work best when they open with context already available. A "why isn't this showing" wizard launched from a specific content page can open with the content ID pre-filled, so the user doesn't have to provide it.
Always include a fallback in the booster for when that context isn't passed: "First check whether the content ID is available. If not, ask the user to provide it before continuing."
Test before you ship
Work through every step manually before rolling out. Check:
The flow feels clear
The right actions are available at each step
The booster gives the AI enough direction
Completion criteria trigger at the right time
The wizard handles missing data, empty results, and unexpected answers
Test more than the happy path. Most issues appear when something is missing or off-script.
Common mistakes
A few things that tend to go wrong with first wizards:
Trying to do too much in one wizard. A wizard that handles four workflows is worse than four wizards that handle one each.
Vague boosters. "Help the user create a segment" gives the AI almost nothing. Be specific and direct.
Completion criteria that describe clicks instead of outcomes. The AI doesn't know about your buttons; it knows about state.
No fallback for missing context. If your wizard depends on data from another step or the launch point, always include a fallback path.
Curious how wizards work under the hood? Our developer documentation on wizards covers the config schema, runtime model, and the relationship between actions, stage boosters, and completion criteria.
Next
Once your wizard is live, read Monitor, test, and improve your wizard to learn how to review conversations, inspect actions, and refine the experience over time.